Prima::...et::Link(3)

✨ NAME ✨

Prima::Widget::Link — routines for interactive links. That’s the whole name vibe, bestie 💖

---

🌸 DESCRIPTION 🌸

So here’s the tea: this class is for widgets that need to show links — like, actual highlighted rectangles, usually with a line of text in them. When the user moves the mouse over a link or clicks it, different actions can fire depending on the link type. A "tooltip" link can display a hint with (rich) text, and a "hyperlink" link can open a browser or a pod viewer. And if you’re the programmer, you can customize these actions too. Periodt 💅

Also hi, this page is the Prima::...et::Link(3) situation from User Contributed Perl Documentation — we’re folding that in right here at the top instead of making you read a stale header line 🫶

---

🦋 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. Four recognized link types behave differently, and they’re giving very distinct main character energy 👑

💛 Tooltips

These are not links in the strict sense, because clicking on them doesn’t cause any action. But when the user hovers the mouse over a tooltip, the module loads the pod content from the URL and displays it as a hint. Obsessed, honestly.

The idea behind this feature is to collect all tooltip cards in a pod section and reference them in the 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).

The tooltip text, when selected, is underscored by a dashed line, vs all other link types that use a solid line. Cute little differentiation moment 🎀

💜 Pod sections

These links display a pod section preview like the tooltip but also open a pod viewer with the referred section when clicked on. So they’re like tooltip’s extroverted sibling.

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).

💙 Hyperlinks

Links with schemes ftp://, http://, and https:// open a browser when clicked on. Classic internet behavior, no notes 🔥

🧡 Custom links

All other URLs, not matched by either scheme above, are expected to be handled programmatically. The preview, if any, should be handled by the LinkPreview event, and the mouse click by the 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 an owner widget that needs to display links.

The owner widget needs to call the mouse and paint methods from inside its on_mousedown etc relevant events. The owner widget class might also want to overload link events — see below how. It’s giving “you’re the main character, but the link object is your sidekick” energy ✨

---

🎀 Markup 🎀

Prima::Drawable::Markup understands the L<..|..> command, which — 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 the 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() >. Yes bestie, that’s the exact weird little incantation from the page — we keep the facts, we just add sparkle 💫

---

👑 API 👑

⭐ Properties

• rectangles — Contains an 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

• add_positions_from_blocks LINK_ID, BLOCKS, %DEFAULTS — Used when the link object is not bound to any markup object but recalculation of the visual rectangle that the link occupies is needed due to change in formatting, f ex after a change in widget size, font size, etc. %DEFAULTS is sent internally to tb::block_walk which may need eventual default parameters. Scans BLOCKS and add monotonically increasing LINK_ID to new link rectangles. 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 — Used when the link object is bound to a markup object and recalculation of the visual rectangle that the link occupies is needed due to change in formatting, f ex after a change in widget size, font size, etc. %DEFAULTS is sent internally to tb::block_walk which may need eventual default parameters.

💫 Events

All events are sent to the owner, not to the link object itself, however, the SELF parameter which contains the link object is always the first parameter. Important bestie detail 🫶

• Link SELF, URL, BUTTON, MOD — Sent to the owner, if any, from within the on_mousedown event to indicate that the link was pressed on.
• LinkPreview SELF, URL_REF — Sent to the owner, if any, from within the on_mousemove event. The owner may want to fill URL_REF with (rich) text that will be displayed as a link preview.
• LinkAdjustRect SELF, RECT_REF — Since the owner may implement a scrollable view or any other view that has a coordinate system that is not necessarily 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::Drawable::Pod

---

okay that’s the whole page bestie 💅 — this was Prima::...et::Link(3) from the perl v5.42.0 docs, dated 2024-08-20. go slay your links! 🎀✨