The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Prima-1.67
River stage two • 17 direct dependents • 19 total dependents
43 ++
/ Prima::Widget::Link

NAME

Prima::Widget::Link - routines for interactive links

DESCRIPTION

The class can be used in widgets that need to feature links, i e a highlighted rectangle, usually of text. When the user moves mouse or click on a link, depending on the link type, various action can be executed. A "tooltip" link type can display a hint with (rich) text, and a "hyperlink" link can open a browser or pod viewer. The programmer can also customize these actions.

SYNOPSIS

  use Prima qw(Label Application);

  my $main_window = Prima::MainWindow->new( size => [400, 100] );
  $main_window->insert( Label =>
    centered => 1,
    text   => \ "L<tip://$0/ttt|tip>, L<pod://Prima/|podviewer>, L<http://google.com/|browser>, L<id|custom>",
    onLink => sub { print "$_[2]\n" },
  );
  run Prima;

  =pod

  =head1 ttt

  this is a tooltip

  =for podview <img src="data:base64">
  R0lGODdhFgAVAIAAAAAAAP///ywAAAAAFgAVAIAAAAD///8CLIyPqcutsKALQKI6qT11R69lWDJm
  5omm6jqBjucycEx+bVOSNNf1+/NjCREFADs=

Link types

Link types can be set with the url syntax. There are four recognized link types that behave differently.

Tooltips

These are not really links in the strict sense, as clicking on them doesn't cause any action, however when the user hovers mouse over a tooltip, the module loads the pod content from the url, and displays it as a hint.

The idea behind this feature is to collect all tootip cards in a pod section, and referencing them in a text like in the example code in SYNOPSIS above.

Syntax: L<tip://FILEPATH_OR_MODULE/SECTION> or L<tip://FILEPATH_OR_MODULE> where FILEPATH_OR_MODULE can refer either to a file (path with slashes/backslashes) or a perl module (with ::s ).

Tooltip text, when selected, is underscored by a dashed line, vs all other link types that draw solid line.

Pod sections

These links both diplay a pod section preview, like the toolkip, but also open a pod viewer with the referred section when clicked on.

Syntax: L<pod://FILEPATH_OR_MODULE/SECTION> or L<pod://FILEPATH_OR_MODULE> where FILEPATH_OR_MODULE can refer either to a file (path with slashes/backslashes) or a perl module (with ::s ).

Links with schemes ftp://, http://, and https:// open a browser when clicked on.

All other urls, not matched by either scheme above, are expected to be handled programmatically. The preview, if any is handled by the LinkPreview event, and click by Link event.

See Events below.

Usage

Since Prima::Widget::Link is not a widget by itself but a collection of routines in a class, an object of such class should be instantiated programmatically and attached to a widget that needs to display links, an owner widget.

The owner needs to call mouse and paint methods from inside its on_mousedown etc relevant events. The owner might also want to overload link events, see below.

Markup

Prima::Drawable::Markup understands the L<..|..> command, which is, unlike perlpod, is formatted with its arguments reversed, to stay consistent with the other markup commands (i e it is L<http://google.com|search>, not L<search|http://google.com> .

The simple way to incorporate rich text in both widget and link handler is to use Prima::Drawable::Markup to handle the markup parsing, and use the resulting object from the same class both for widget drawing and for the link reactions. One just needs to add markup = $markup_object > to Prima::Widget::Link-new() >.

API

Properties

rectangles

Contains array of rectangles in arbitrary coordinates that could be used to map screen coordinates to a url. Filled automatically.

references

An array of URLs

Methods

To be used when the link object is not bound to a markup object and link rectangle recalculation is needed due to formatting change, f ex widget size, font size etc. %DEFAULTS is sent internally to tb::block_walk that might need eventual default parameters.

Scans BLOCKS and add monotonically increasing LINK_ID to new link rectanges. Return new LINK_ID.

clear_positions

Clears the content of rectangles

id2rectangles ID

Returns rectangles mapped to a link id. There can be more than 1 rectangle bound to a single link ID since link text could be, f ex, wrapped.

open_podview URL

Opens a pod viewer with the URL

open_browser URL

Opens a web browser with the URL

reset_positions_markup BLOCKS, %DEFAULTS

To be used when the link object is bound to a markup object and link rectangle recalculation is needed due to formatting change, f ex widget size, font size etc. %DEFAULTS is sent internally to tb::block_walk that might need eventual default parameters.

Events

All events are send to the owner, not to the link object itself, however the SELF parameter is sent and contains the link object.

Send to the owner, if any, from within on_mousedown event, to indicate that a link as pressed on.

LinkPreview SELF, URL_REF

Send to the owner, if any, from within on_mousemove event. The owner might want to fill URL_REF with (rich) text that will be displayed as a link preview

LinkAdjustRect SELF, RECT_REF

Since the owner might implement a scrollable view, or any other view that has a coordinate system that is no necessary consistent with the rectangles stored in the link object, this event will be called when a link rectangle needs to be mapped to the owner coordinates.

AUTHOR

Dmitry Karasik, <dmitry@karasik.eu.org>.

SEE ALSO

Prima, Prima::Drawable::Markup, Prima::Label, Prima::PodView