/ 
Prima-1.71
River stage two • 17 direct dependents • 19 total dependents
/ Prima::PodView

NAME

Prima::PodView - POD browser widget

SYNOPSIS

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;

DESCRIPTION

Prima::PodView contains a formatter ( in terms of perlpod ) and a viewer of the POD content. It heavily employs its ascendant class Prima::TextView, and is in turn the base class for the toolkit's default help viewer Prima::HelpViewer.

USAGE

The package consists of 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 following content-loading functions:

open_read %OPTIONS

Clears the current content and enters the reading mode. In this mode, the content can be appended by repeatedly calling the read method that pushes the raw POD content to the parser.

read TEXT

Supplies the TEXT string to the parser. Parses basic indentation, but the main formatting is performed inside add and add_formatted.

Must be called only within the open_read/close_read brackets

add TEXT, STYLE, INDENT

Formats the TEXT string of a given STYLE ( one of the STYLE_XXX constants) with the INDENT space.

Must be called only within the open_read/close_read brackets.

add_formatted FORMAT, TEXT

Adds a pre-formatted TEXT with a given FORMAT, supplied by the =begin or =for POD directives. Prima::PodView understands 'text' and 'podview' FORMATs; the latter format is for Prima::PodView itself and contains a small number of commands for rendering images in documents.

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 canceled. It is used in conjunction with the following command, img, to allow a POD manpage to 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 scaling is required, width and height options can be set. If the image is a multiframe image, the frame index can be set by the frame option. A special cut option, if set to a true value, activates the cut behavior if ( and only if ) the image load operation is unsuccessful. This makes 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 will be selected.

If src is omitted, the image is retrieved from the images array, from the index frame.

It is also possible to embed images in the pod, by using a special src tag for base64-encoded images. The format should preferably be GIF, as this is Prima default format, or BMP for very small images, as it is supported without third-party libraries:

=for podview <img src="data:base64">
R0lGODdhAQABAIAAAAAAAAAAACwAAAAAAQABAIAAAAAAAAACAkQBADs=
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 the 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 on a document model, generated by the open_read/close_read session. The model is a set of the 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 into text blocks, wrapped, and pushed into the TextView-provided storage. In parallel, links and the corresponding event rectangles are calculated at this stage.

Topics

Prima::PodView provides the ::topicView property, which manages whether the man page is viewed by topics or as a whole. When a page is in the single topic mode, the {modelRange} array selects the model blocks that include the topic to be displayed. That way the model stays the same while text blocks inside the widget can be changed.

Topics reside in the {topics} array, where each is an array with the following indices of the T_XXX constants:

T_MODEL_START - start of topic
T_MODEL_END   - end of a topic
T_DESCRIPTION - topic name
T_STYLE       - STYLE_XXX constant
T_ITEM_DEPTH  - depth of =item recursion
T_LINK_OFFSET - offset in the links array

Styles

The ::styles property provides access to the styles, applied to different pod text parts. These styles are:

STYLE_CODE     - style for 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
STYLE_VERBATIM - style for pre-formatted text

Each style is a hash with the following keys: fontId, fontSize, fontStyle, color, and 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 defines colormap entries for STYLE_LINK , STYLE_CODE, and STYLE_VERBATIM:

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 the hand-icon mouse pointer that highlights links. Also, the link documents or topics are loaded in the widget when the user presses the mouse button on the link. Prima::Widget::Link is used for the implementation of the link mechanics.

If the page is loaded successfully, depending on the ::topicView property value, either the 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 the manpage if it can be found in the PATH or perl installation directories. If unsuccessful, displays an error.

LINK is a text in the format of perlpod L<> link: "manpage/section". Loads the manpage, if necessary, and selects the section.

load_bookmark BOOKMARK

Loads the bookmark string prepared by the make_bookmark function. Used internally.

load_content CONTENT

Loads content into the viewer. Returns undef if there is no POD context, 1 otherwise.

make_bookmark [ WHERE ]

Combines the information about the currently viewing page source, 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 the '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 the manpage.

If the location cannot be stored or defined, undef is returned.

Events

Bookmark BOOKMARK

When a new topic is navigated by the user, this event is triggered with the current topic to have it eventually stored in the bookmarks or user history.

When the user clicks on a link, this event is called with the link address, mouse button, modification keys, and coordinates.

NewPage

Called after new content is loaded