Man Linux: Main Page and Category List

NAME

       Prima::PodView - POD browser widget

SYNOPSIS

               use Prima qw(Application);
               use Prima::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 viewer
       of POD content. It heavily employs its ascendant class Prima::TextView,
       and is in turn base for the toolkit’s default help viewer
       Prima::HelpViewer.

USAGE

       The package consists of the several logically separated parts. These
       include file locating and loading, formatting and navigation.

   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
           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:

           cut Example:

                       =for podview <cut>

                       =for text just text-formatter info

                               ....
                               text-only info
                               ...

                       =for podview </cut>

               The <cut<gt> clause skips all POD input until cancelled.  It is
               used in conjunction with the following command, img, to allow a
               POD manpage provide both graphic (’podview’, ’html’, etc ) and
               text ( ’text’ ) content.

           img src="SRC" [width="WIDTH"] [height="HEIGHT"] [cut="CUT"]
           [frame="FRAME"]
               An image inclusion command, where src is a relative or an
               absolute path to an image file. In case if scaling is required,
               "width" and "height" options can be set. When the image is a
               multiframe image, the frame index can be set by "frame" option.
               Special "cut" option, if set to a true value, activates the cut
               behavior if ( and only if ) the image load operation was
               unsuccessful.  This make possible simultaneous use of ’podview’
               and ’text’ :

                       =for podview <img src="graphic.gif" cut=1 >

                       =begin text

                       y     .
                       |  .
                       |.
                       +----- x

                       =end text

                       =for podview </cut>

               In the example above ’graphic.gif’ will be shown if it can be
               found and loaded, otherwise the poor-man-drawings would be
               selected.

       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 pre-formatted text and C<>
               STYLE_TEXT   - normal text
               STYLE_HEAD_1 - =head1
               STYLE_HEAD_2 - =head2
               STYLE_ITEM   - =item
               STYLE_LINK   - style for L<> 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" and "STYLE_CODE":

               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. The
       mechanics below that is as follows. "{contents}" of event rectangles, (
       see Prima::TextView ) is responsible for distinguishing whether a mouse
       is inside a link or not.  When the link is activated, "link_click" is
       called, which, in turn, calls "load_link" method. 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.