view release on metacpan or  search on metacpan

lib/Tk/HyperlinkButton.pm  view on Meta::CPAN

package Tk::HyperlinkButton;

use 5.016003;
use strict;
use warnings;
use Browser::Open qw/ open_browser /;

use Tk;
use Tk::widgets qw/ Button /;
use base qw/ Tk::Derived Tk::Button /;

Construct Tk::Widget 'HyperlinkButton';

our $VERSION = '0.02';

=head1 NAME

Tk::HyperlinkButton - Create a clickable hyperlink button to open a web browser

=head1 SYNOPSIS

  use Tk::HyperlinkButton;
  
  my $mw = MainWindow->new();
  
  my $link_text = 'metacpan.org';
  my $link_target = 'http://www.metacpan.org';
  my $link_callback = sub{ print "your callback here\n"; };
  
  my $hyperlink_widget = $mw->HyperlinkButton(
      -text => $link_text,
      -target => $link_target,
      -command => $link_callback,
  );
  
  $hyperlink_widget->pack;
  
  $mw->MainLoop;

=head1 DESCRIPTION

Tk::Hyperlink is an adjusted L<Tk::Button> widget to display a hyperlink.
The hyperlink will be displayed with blue foreground color by default and highlighted on mouse over.
The look and feel resembles a Label (no borders by default).

A custom callback can be provided the same way as for other buttons (using the option C<-command>).
The callback will be executed when the hyperlink is clicked.
The default callback will open the system's default web browser and navigate to the URL provided by the option C<target>.
If C<target> is not defined, the URL will be what you define by the option C<-text>.

The widget is indented to only represent the hyperlink.
The intended use case is actually to have some kind of L<Tk::Label>-like widget that is a clickable hyperlink.

Text in front or after the hyperlink should be created with other means (e.g. L<Tk::Label> or L<Tk::Text>).

=head1 WIDGET-SPECIFIC OPTIONS

=head2 target

Sets the address for the hyperlink. If target is not given, C<-text> will be used as target automatically.

Using C<-text> and C<-target> in combination, you can get a clickable hyperlink that open a web browser with the address defined in C<-target>, but that displays a different text as defined in C<-text>. 
Basically, that's what you have in HTML as well.

=head2 command

A callback that will be executed when the hyperlink is clicked. Optional.
By default, clicking the hyperlink will open the system's default browser and navigate to the URL (cf. C<-target>).

=head1 WIDGET METHODS