Prima::PodView - POD browser widget
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;
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.
The package consists of the several logically separated parts. These include file locating and loading, formatting and navigation.
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:
load_file
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.
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
Formats TEXT string of a given STYLE ( one of STYLE_XXX constants) with INDENT space.
STYLE_XXX
Must be called only within open_read/close_read brackets.
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.
=begin
=for
The 'podview' commands are:
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.
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 makes possible simultaneous use of 'podview' and 'text' :
width
height
frame
cut
=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.
If "src" is omitted, image is retrieved from images array, from the index frame.
images
Closes the reading mode and starts the text rendering by calling format. Returns undef if there is no POD context, 1 otherwise.
format
undef
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.
format_chunks
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.
::topicView
{modelRange}
Topics contained in {topics} array, each is an array with indices of T_XXX constants:
{topics}
T_XXX
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 property provides access to the styles, applied to different pod text parts. These styles are:
::styles
STYLE_CODE - style for pre-formatted text and 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
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.
fontId
fontSize
fontStyle
color
backColor
In addition to styles, Prima::PodView defined colormap entries for STYLE_LINK and STYLE_CODE:
colormap
STYLE_LINK
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.
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.
{contents}
link_click
load_link
select_topic
select_text_offset
The family of file and link access functions consists of the following methods:
Loads a manpage, if it can be found in the PATH or perl installation directories. If unsuccessful, displays an error.
LINK is a text in format of perlpod L<> link: "manpage/section". Loads the manpage, if necessary, and selects the section.
L<>
Loads a bookmark string, prepared by make_bookmark function. Used internally.
Loads content into the viewer. Returns undef is there is no POD context, 1 otherwise.
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.
To install Prima, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Prima
CPAN shell
perl -MCPAN -e shell install Prima
For more information on module installation, please visit the detailed CPAN module installation guide.