Prima::PodView(3)

💅 Prima::PodView(3) — User Contributed Perl Documentation 💅

okay so bestie, welcome to the Prima::PodView(3) page. it's giving POD browser widget energy, and we're gonna keep every detail intact while making it make sense. iykyk ✨

✨ NAME ✨

Prima::PodView — POD browser widget. that's it, that's the name section, but it's iconic 💅

🌸 SYNOPSIS 🌸

here's the whole vibe in code, exactly as it appears — no cap:

               use Prima qw(Application PodView);

               my $window = Prima::MainWindow-> create;
               my $podview = $window-> insert( 'Prima::PodView',
                       pack => { fill => 'both', expand => 1 }
               );
               $podview-> open_read;
               $podview-> read("=head1 NAME\n\nI'm also a pod!\n\n");
               $podview-> close_read;

               run Prima;

💖 DESCRIPTION 💖

Prima::PodView contains a formatter (in terms of perlpod) and a viewer of the POD content. It heavily employs its ascendant class Prima::TextView, and is in turn the base class for the toolkit's default help viewer Prima::HelpViewer. full stack POD realness 🌈

🎀 USAGE 🎀

The package consists of several logically separated parts. These include file locating and loading, formatting, and navigation. lowkey a whole little ecosystem 🫶

🧚 Content methods 🧚

The basic access to the content is not bound to the file system. The POD content can be supplied without any file to the viewer. Indeed, the file loading routine load_file is a mere wrapper to the following content-loading functions:

• open_read %OPTIONS — Clears the current content and enters the reading mode. In this mode, the content can be appended by repeatedly calling the read method that pushes the raw POD content to the parser. reading mode activate 📖
• read TEXT — Supplies the TEXT string to the parser. Parses basic indentation, but the main formatting is performed inside add and add_formatted. Must be called only within the open_read/close_read brackets. no solo read runs, bestie 🚫
• close_read — Closes the reading mode and starts the text rendering by calling format. Returns undef if there is no POD context, 1 otherwise. bye bye reading mode 👋

🦋 Rendering 🦋

The rendering is started by the format call which returns almost immediately, initiating the mechanism of delayed rendering, which is often time-consuming. format's only parameter KEEP_OFFSET is a boolean flag, which, if set to 1, remembers the current location on a page, and when the rendered text approaches the location, scrolls the document automatically. set it to 1 and it remembers where you were 🧠

The rendering is based on a document model, generated by the open_read/close_read session. The model is a set of the same text blocks defined by Prima::TextView, except that the header length is only three integers:

pod::M_INDENT       - the block X-axis indent
pod::M_TEXT_OFFSET  - same as BLK_TEXT_OFFSET
pod::M_FONT_ID      - 0 or 1, because PodView's fontPalette contains only two fonts -
                 variable ( 0 ) and fixed ( 1 ).

The actual rendering is performed in format_chunks, where model blocks are transformed into text blocks, wrapped, and pushed into the TextView-provided storage. In parallel, links and the corresponding event rectangles are calculated at this stage. format_chunks is doing the most 💅

⭐ Topics ⭐

Prima::PodView provides the ::topicView property, which manages whether the man page is viewed by topics or as a whole. When a page is in the single topic mode, the {modelRange} array selects the model blocks that include the topic to be displayed. That way the model stays the same while text blocks inside the widget can be changed. model stays, text blocks shift — it's giving efficient ✨

🌈 Styles 🌈

In addition to styles provided by Prima::Drawable::Pod, Prima::PodView defines colorMap entries for pod::STYLE_LINK, pod::STYLE_CODE, and pod::STYLE_VERBATIM:

COLOR_LINK_FOREGROUND
COLOR_CODE_FOREGROUND
COLOR_CODE_BACKGROUND

The default colors in the styles are mapped into these entries. colorMap girlies rise 🎨

💅 Link and navigation methods 💅

Prima::PodView provides the hand-icon mouse pointer that highlights links. Also, the link documents or topics are loaded in the widget when the user presses the mouse button on the link. Prima::Widget::Link is used for the implementation of the link mechanics. hand cursor says click me 👆

If the page is loaded successfully, depending on the ::topicView property value, either the select_topic or select_text_offset method is called.

The family of file and link access functions consists of the following methods:

• load_file MANPAGE — Loads the manpage if it can be found in the PATH or perl installation directories. If unsuccessful, displays an error. if it's not found, error time 😭
• load_link LINK — LINK is a text in the format of perlpod L<> link: manpage/section. Loads the manpage, if necessary, and selects the section. link go brrr 🦋
• load_bookmark BOOKMARK — Loads the bookmark string prepared by the make_bookmark function. Used internally.
• load_content CONTENT — Loads content into the viewer. Returns undef if there is no POD context, 1 otherwise.
• make_bookmark [ WHERE ] — Combines the information about the currently viewing page source, topic, and text offset, into a storable string. WHERE, an optional string parameter, can be either omitted, in such case the current settings are used, or be one of the 'up', 'next', or 'prev' strings.
  • The 'up' string returns a bookmark to the upper level of the manpage.
  • The 'next' and 'prev' return a bookmark to the next or the previous topics in the manpage.
  • If the location cannot be stored or defined, undef is returned. bookmark said no 🙈

🔥 Events 🔥

• Bookmark BOOKMARK — When a new topic is navigated by the user, this event is triggered with the current topic to have it eventually stored in the bookmarks or user history. history girlies stay winning 💜
• Link LINK_REF, BUTTON, MOD, X, Y — When the user clicks on a link, this event is called with the link address, mouse button, modification keys, and coordinates. click event unlocked 🔗
• NewPage — Called after new content is loaded. new page, new me ✨

👑 SEE ALSO 👑

• Prima::Drawable::Pod
• Prima::Drawable::TextView

mwah 💋 — source/version: perl v5.42.0, date: 2024-08-20. now go browse some POD, bestie 🫶🎀