/ 
Prima-1.75
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-> new;
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

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:

pod::M_INDENT       - the block X-axis indent
pod::M_TEXT_OFFSET  - same as BLK_TEXT_OFFSET
pod::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.

Styles

In addition to styles provided by Prima::Drawable::Pod, Prima::PodView defines colorMap entries for pod::STYLE_LINK , pod::STYLE_CODE, and pod::STYLE_VERBATIM:

COLOR_LINK_FOREGROUND
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

SEE ALSO

Prima::Drawable::Pod, Prima::TextView