|
Prima::PodView - POD browser widget |
Prima::PodView - POD browser widget
Prima::PodView contains a formatter ( in terms of the perlpod manpage ) and viewer of POD content. It heavily employs its ascendant class the Prima::TextView manpage, and is in turn base for the toolkit's default help viewer the Prima::HelpViewer manpage.
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:
Must be called only within open_read/close_read brackets
STYLE_XXX constants) with
INDENT space.
Must be called only within open_read/close_read brackets.
=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:
=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.
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.
format.
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 the Prima::TextView manpage, 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.
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 indeces 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 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.
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 the Prima::TextView manpage )
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:
L<> link: ``manpage/section''.
Loads the manpage, if necessary, and selects the section.
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.
|
Prima::PodView - POD browser widget |