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.