trusty (3) Prima::PodView.3.gz
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.