NAME
Win32::GUI::HyperLink - A Win32::GUI Hyperlink control
VERSION
Version 0.11
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 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 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 unless Win32::API is not available. 2 Text is always underlined. This is the default if Win32::API is not available.
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.
Win32::GUI::HyperLink uses the NEM (New Event Model) to register for events with the Win32::GUI::Label object. Hence if you want to get subroutines called by name (OEM), then you must pass -eventmodel => "both" as a parameter.
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 Win32::API is available 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 v1.0. It may work with earlier versions, but this has not been tested, and is not currently supported. It may be supported in future releases, depending on feedback. If you wish to try it with an earlier Win32::GUI version, then you will need to remove the 1.0 from the use Win32::GUI 1.0 line of the code. Please report any success or failure with earlier versions to the Author.
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 onMouseIn/Out event callbacks may not be available.
This module requires access to some win32 API calls that are not part of the current Win32::GUI distribution. Those functions that are not available through Win32::GUI are accessed using Win32::API. If Win32::API is not available, and there is not alternative fallback strategy, then some functionality may be missing. The test suite should warn if this affects you.
COMPATABILITY
This module should be backwards compatable with the prior Win32::GUI::HyperLink module (v0.02). 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
If you want to use the OEM event model, then you must currently pass -eventmodel => "both" as an option to the constructor: as Win32::GUI::HyperLink uses the NEM event model, this will be selected by default.
See the TODO file from the disribution.
Please report any bugs or feature requests to the Author.
Bugs with the tests
The test when neither -text nor -url are set results in a warning: Use of uninitialized value in subroutine entry at C:/Perl/site/lib/Win32/GUI.pm line 597, <DATA> line 164. . I can't track this down, but it does not seem to be anything to worry about.
Some interaction with the test harness results in a warning c<< Too late to run INIT block at C:/Perl/site/lib/Win32/API/Type.pm line 71. >> when running the pod-coverage tests. This does not seem to be a problem.
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.