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.