NAME

Win32::GUI::HyperLink - A Win32::GUI Hyperlink control

SYNOPSIS

Win32::GUI::HyperLink is a Win32::GUI::Label that acts as a clickable hyperlink. By default it has a 'hand' Cursor, is drawn in blue text rather than black and the text is dynamically underlined when the mouse moves over the text. The Label can be clicked to launch a hyperlink, and supports onMouseIn and onMouseOut events to allow (for example) the link url to be displayed while the mouse is over the link.

    use Win32::GUI::HyperLink;

    my $hyperlink = Win32::GUI::HyperLink->new($parent_window, %options);

    my $hyperlink = $parent_window->AddHyperLink(%options);

    $url = $hyperlink->Url();

    $hyperlink->Url($url);

    $hyperlink->Launch();

Win32::GUI::HyperLink is a sub-class of Win32::GUI::Label, and so supports all the options and methods of Win32::GUI::Label. See the Win32::GUI::Label documentation for further information. Anywhere that behaviour differs is highlighted below.

See the HyperLinkDemo.pl script for examples of using the functionality. This demo script can be found in the .../Win32/GUI/demos/HyperLink directory beneath the installation directory.

METHODS

new

  $hyperlink = Win32::GUI::HyperLink->new($parent, %options);

  $hyperlink = $window->AddHyperLink(%options);

Takes any options that Win32::GUI::Label does with the following changes:

-url

The Link to launch. e.g. -url => "http://www.perl.com/", If not supplied will default to -text.

-onMouseIn

A code reference to call when the mouse moves over the link text. Do not rely on this being available if your script is run on a machine that has early versions of Win32::GUI or does not have Win32::API available. See "REQUIRES" for further information.

-onMouseOut

A code reference to call when the mouse moves off the link text. Do not rely on this being available if your script is run on a machine that has early versions of Win32::GUI or does not have Win32::API available. See "REQUIRES" for further information.

-underline

Controls how the text behaves as the mouse moves over and off the link text. Possible values are: 0 Text is not underlined. 1 Text is underlined when the mouse is over the link text. This is the default. 2 Text is always underlined. On machines with early versions of Win32::GUI or without Win32::API available option 1 may be unavailable. In this case option 2 becomes the default. See "REQUIRES" for further information.

Differences to Win32::GUI::Label

If -text is not supplied, then -text defaults to -url. (If neither -url nor -text are supplied, then you have an empty label!)

-notify is always set to 1.

If a -onClick handler is supplied, then the default action of launching the link when the link is clicked is disabled. See "Launch" method for how to get this functionality from you own Click handler.

Original/Old Event Model (OEM)

Win32::GUI::HyperLink will call the subroutines main::NAME_MouseIn and main::NAME_MouseOut , if they exist, when the mouse moves over the link, and when the mouse moves out oif the link respectively, where NAME is the name of the label, set with the -name option.

Url

  $url = $hyperlink->Url();

Get the value of the current link.

  $hyperlink->Url($url);

Set the value of the current link.

Launch

  $hyperlink->Launch();

Launches the link url in the user's default browser. This method is supplied to make it easy to call the default Click functionality from your own Click Handler. If you pass a -onClick option to the constructor then the default handler is disabled. This allows you to turn off the default click behaviour by passing a reference to an empty subroutine:

  -onClick => sub {},

If you have your own Click handler, then the default behaviour can be restored by calling $self->Launch() from within your handler.

Returns 1 on Success, 0 on failure (and carps a warning), and undef if there is no link url to try to launch.

Launch() passes the value of the link url to the operating system, which launches the link in the user's default browser.

If ShellExecute is available (Win32::GUI greater than 1.0, or via Win32::API) then the link is passed to the Windows ShellExecute function. If not the link is passed to Windows start(.exe) command. In either case any valid executable program or document that has a file association should be successsfully started.

AUTHOR

Robert May, <rmay@popeslane.clara.co.uk>

Additional information may be available at http://www.robmay.me.uk/win32gui/.

REQUIRES

Win32::GUI v0.99_1 or later. The test suite passes at least as far back as V0.0.670, and the code runs without errors, but differences in the event processing loops means that the main functionality does not work. If you need this functionality with earlier versions of Win32::GUI it is suggested that you use Win32::GUI::HyperLink v0.02. If you make this code work with earlier versions of Win32::GUI, please pass your changes back to the author for inclusion.

Win32::GUI::BitmapInline, as distributed with Win32::GUI, will be used if Win32::GUI::HyperLink cannot get the system's 'hand' cursor. If Win32::GUI::BitmapInline is not available in this circumctance, then the cursor will not change when hovering over the link.

Win32::API. May be required for full functionality, depending on your version of Win32::GUI.

If you do no have this module installed then the dynamic underlining of the link as the mouse moves over it may not work, and the MouseIn/Out events may not be available.

As at Win32::GUI 1.0 this module requires access to LoadCursor, GetCapture and ShellExecute win32 API calls that are not part of the Win32::GUI distribution. API calls that are not available through Win32::GUI are accessed using Win32::API, and if it is not available, functionality will be missing:

LoadCursor: if not available then the default 'hand' cursor that is used will be one built in to Win32::GUI::HyperLink rather than the operating system's default.

GetCapture: if not available, then underlining of the link text when the mouse hovers over the link is not available, nor are the MouseIn or MouseOut events.

If you need the full functionality without using Win32::API the the current CVS HEAD revision of the code has the missing functions, and Win32::GUI::HyperLink is coded to use them if they exist in the Win32::GUI build.

COMPATABILITY

This module should be backwards compatable with all prior Win32::GUI::HyperLink releases, including the original (v0.02) release. If you find that it is not, please inform the Author.

EXAMPLES

  use strict;
  use warnings;

  use Win32::GUI 1.0;
  use Win32::GUI::HyperLink;

  # A window
  my $win = Win32::GUI::Window->new(
    -title => "HyperLink",
    -pos => [ 100, 100 ],
    -size => [ 240, 200 ],
  );

  # Simplest usage
  $win->AddHyperLink(
    -text => "http://www.perl.org/",
    -pos => [10,10],
  );

  $win->Show();
  Win32::GUI::Dialog();
  exit(0);

BUGS

See the TODO file from the disribution.

Please report any bugs or feature requests to the Author.

Bugs with the tests

All tests pass when run with 'prove'. Some interaction with 'make test' results in the following warnings, neither of which are cause for concern.

The test when neither -text nor -url are set when running 03.method-new.t against Win32::GUI v1.0 results in a warning: Use of uninitialized value in subroutine entry at C:/Perl/site/lib/Win32/GUI.pm line 597, <DATA> line 164..

99.pod-coverage.t results in the warning: Too late to run INIT block at C:/Perl/site/lib/Win32/API/Type.pm line 71.

The tests do not cover any actual GUI interaction.

ACKNOWLEDGEMENTS

Many thanks to the Win32::GUI developers at http://sourceforge.net/projects/perl-win32-gui/

There was a previous incarnation of Win32::GUI::HyperLink that was posted on win32-gui-users@lists.sourceforge.net in 2001. I am not sure of the original author but it looks like Aldo Calpini.

Some of the ideas here are taken from http://www.codeguru.com/Cpp/controls/staticctrl/article.php/c5803/

COPYRIGHT & LICENSE

Copyright 2005 Robert May, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Win32::GUI::HyperLink

perl -MCPAN -e shell
install Win32::GUI::HyperLink