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 content loading functions:

open_read %OPTIONS

Clears the current content and enters the reading mode. In this mode the content can be appended by calling read that pushes the raw POD content to the parser.

read TEXT

Supplies TEXT string to the parser. Manages basic indentation, but the main formatting is performed inside add and add_formatted

Must be called only within open_read/close_read brackets

add TEXT, STYLE, INDENT

Formats TEXT string of a given STYLE ( one of "STYLE_XXX" constants) with INDENT space.

Must be called only within open_read/close_read brackets.

add_formatted FORMAT, TEXT

Adds a pre-formatted TEXT with a given FORMAT, supplied by "=begin" or "=for" POD directives. Prima::PodView understands 'text' and 'podview' FORMATs; the latter format is for Prima::PodView itself and contains small number of commands, aimed at inclusion of images into the document.

The 'podview' commands are:

close_read

Closes the reading mode and starts the text rendering by calling "format". Returns "undef" if there is no POD context, 1 otherwise.

Rendering¶

The rendering is started by "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.

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

        M_INDENT       - the block X-axis indent
        M_TEXT_OFFSET  - same as BLK_TEXT_OFFSET
        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 to the full text blocks, wrapped and pushed into TextView-provided storage. In parallel, links and the corresponding event rectangles are calculated on this stage.

Topics¶

Prima::PodView provides the "::topicView" property, which governs whether the man page is viewed by topics or as a whole. When it is viewed as topics, "{modelRange}" array selects the model blocks that include the topic. Thus, having a single model loaded, text blocks change dynamically.

Topics contained in "{topics}" array, each is an array with indices of "T_XXX" constants:

        T_MODEL_START - beginning of topic
        T_MODEL_END   - length of a topic
        T_DESCRIPTION - topic name
        T_STYLE       - STYLE_XXX constant
        T_ITEM_DEPTH  - depth of =item recursion
        T_LINK_OFFSET - offset in links array, started in the topic

Styles¶

"::styles" property provides access to the styles, applied to different pod text parts. These styles are:

        STYLE_CODE     - style for C<>
        STYLE_TEXT     - normal text
        STYLE_HEAD_1   - =head1
        STYLE_HEAD_2   - =head2
        STYLE_HEAD_3   - =head3
        STYLE_HEAD_4   - =head4
        STYLE_ITEM     - =item
        STYLE_LINK     - style for L<> text
        STYLE_VERBATIM - style for pre-formatted text

Each style is a hash with the following keys: "fontId", "fontSize", "fontStyle", "color", "backColor", fully analogous to the tb::BLK_DATA_XXX options. This functionality provides another layer of accessibility to the pod formatter.

In addition to styles, Prima::PodView defined "colormap" entries for "STYLE_LINK" , "STYLE_CODE", and "STYLE_VERBATIM":

        COLOR_LINK_FOREGROUND
        COLOR_LINK_BACKGROUND
        COLOR_CODE_FOREGROUND
        COLOR_CODE_BACKGROUND

The default colors in the styles are mapped into these entries.

Link and navigation methods¶

Prima::PodView provides a hand-icon mouse pointer highlight for the link entries and as an interactive part, the link documents or topics are loaded when the user presses the mouse button on the link. Prima::Widget::Link is used for the link mechanics implementation.

If the page is loaded successfully, depending on "::topicView" property value, either "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 a manpage, if it can be found in the PATH or perl installation directories. If unsuccessful, displays an error.

load_link LINK

LINK is a text in format of perlpod "L<>" link: "manpage/section". Loads the manpage, if necessary, and selects the section.

load_bookmark BOOKMARK

Loads a bookmark string, prepared by make_bookmark function. Used internally.

load_content CONTENT

Loads content into the viewer. Returns "undef" is there is no POD context, 1 otherwise.

make_bookmark [ WHERE ]

Combines the information about the currently viewing manpage, 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 '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 a manpage.

If the location cannot be stored or defined, "undef" is returned.

Events¶

Bookmark BOOKMARK

When a new topic is navigated to by the user, this event is triggered with the current topic to have it eventually stored in bookmarks or history.

Link LINK_REF, BUTTON, MOD, X, Y

When the user clicks on a link, this event is called with the link address, mouse button, modificator keys, and coordinates.

NewPage

Called after new content is loaded