1Prima::Widget::Link(3)User Contributed Perl DocumentationPrima::Widget::Link(3)
2
3
4

NAME

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

DESCRIPTION

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

SYNOPSIS

17         use Prima qw(Label Application);
18
19         my $main_window = Prima::MainWindow->new( size => [400, 100] );
20         $main_window->insert( Label =>
21           centered => 1,
22           text   => \ "L<tip://$0/ttt|tip>, L<pod://Prima/|podviewer>, L<http://google.com/|browser>, L<id|custom>",
23           onLink => sub { print "$_[2]\n" },
24         );
25         run Prima;
26
27         =pod
28
29         =head1 ttt
30
31         this is a tooltip
32
33         =for podview <img src="data:base64">
34         R0lGODdhFgAVAIAAAAAAAP///ywAAAAAFgAVAIAAAAD///8CLIyPqcutsKALQKI6qT11R69lWDJm
35         5omm6jqBjucycEx+bVOSNNf1+/NjCREFADs=
36
38       Link types can be set with the url syntax. There are four recognized
39       link types that behave differently.
40
41   Tooltips
42       These are not really links in the strict sense, as clicking on them
43       doesn't cause any action, however when the user hovers mouse over a
44       tooltip, the module loads the pod content from the url, and displays it
45       as a hint.
46
47       The idea behind this feature is to collect all tootip cards in a pod
48       section, and referencing them in a text like in the example code in
49       SYNOPSIS above.
50
51       Syntax: "L<tip://FILEPATH_OR_MODULE/SECTION>" or
52       "L<tip://FILEPATH_OR_MODULE>" where "FILEPATH_OR_MODULE" can refer
53       either to a file (path with slashes/backslashes) or a perl module (with
54       "::"s ).
55
56       Tooltip text, when selected, is underscored by a dashed line, vs all
57       other link types that draw solid line.
58
59   Pod sections
60       These links both diplay a pod section preview, like the toolkip, but
61       also open a pod viewer with the referred section when clicked on.
62
63       Syntax: "L<pod://FILEPATH_OR_MODULE/SECTION>" or
64       "L<pod://FILEPATH_OR_MODULE>" where "FILEPATH_OR_MODULE" can refer
65       either to a file (path with slashes/backslashes) or a perl module (with
66       "::"s ).
67
68   Hyperlinks
69       Links with schemes "ftp://", "http://", and "https://" open a browser
70       when clicked on.
71
72   Custom links
73       All other urls, not matched by either scheme above, are expected to be
74       handled programmatically.  The preview, if any is handled by the
75       "LinkPreview" event, and click by "Link" event.
76
77       See Events below.
78

Usage

80       Since "Prima::Widget::Link" is not a widget by itself but a collection
81       of routines in a class, an object of such class should be instantiated
82       programmatically and attached to a widget that needs to display links,
83       an owner widget.
84
85       The owner needs to call mouse and paint methods from inside its
86       "on_mousedown" etc relevant events.  The owner might also want to
87       overload link events, see below.
88

Markup

90       Prima::Drawable::Markup understands the "L<..|..>" command, which is,
91       unlike perlpod, is formatted with its arguments reversed, to stay
92       consistent with the other markup commands (i e it is
93       "L<http://google.com|search>", not "L<search|http://google.com>" .
94
95       The simple way to incorporate rich text in both widget and link handler
96       is to use "Prima::Drawable::Markup" to handle the markup parsing, and
97       use the resulting object from the same class both for widget drawing
98       and for the link reactions. One just needs to add " markup ="
99       $markup_object > to " Prima::Widget::Link-"new() >.
100

API

102   Properties
103       rectangles
104           Contains array of rectangles in arbitrary coordinates that could be
105           used to map screen coordinates to a url.  Filled automatically.
106
107       references
108           An array of URLs
109
110   Methods
111       add_positions_from_blocks LINK_ID, BLOCKS, %DEFAULTS
112           To be used when the link object is not bound to a markup object and
113           link rectangle recalculation is needed due to formatting change, f
114           ex widget size, font size etc. %DEFAULTS is sent internally to
115           "tb::block_walk" that might need eventual default parameters.
116
117           Scans BLOCKS and add monotonically increasing LINK_ID to new link
118           rectanges. Return new LINK_ID.
119
120       clear_positions
121           Clears the content of "rectangles"
122
123       id2rectangles ID
124           Returns rectangles mapped to a link id. There can be more than 1
125           rectangle bound to a single link ID since link text could be, f ex,
126           wrapped.
127
128       open_podview URL
129           Opens a pod viewer with the URL
130
131       open_browser URL
132           Opens a web browser with the URL
133
134       reset_positions_markup BLOCKS, %DEFAULTS
135           To be used when the link object is bound to a markup object and
136           link rectangle recalculation is needed due to formatting change, f
137           ex widget size, font size etc. %DEFAULTS is sent internally to
138           "tb::block_walk" that might need eventual default parameters.
139
140   Events
141       All events are send to the owner, not to the link object itself,
142       however the "SELF" parameter is sent and contains the link object.
143
144       Link SELF, URL, BUTTON, MOD
145           Send to the owner, if any, from within "on_mousedown" event, to
146           indicate that a link as pressed on.
147
148       LinkPreview SELF, URL_REF
149           Send to the owner, if any, from within "on_mousemove" event.  The
150           owner might want to fill URL_REF with (rich) text that will be
151           displayed as a link preview
152
153       LinkAdjustRect SELF, RECT_REF
154           Since the owner might implement a scrollable view, or any other
155           view that has a coordinate system that is no necessary consistent
156           with the rectangles stored in the link object, this event will be
157           called when a link rectangle needs to be mapped to the owner
158           coordinates.
159

AUTHOR

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

SEE ALSO

164       Prima, Prima::Drawable::Markup, Prima::Label, Prima::PodView
165
166
167
168perl v5.36.0                      2023-03-20            Prima::Widget::Link(3)
Impressum