1Prima::PodView(3)     User Contributed Perl Documentation    Prima::PodView(3)
2
3
4

NAME

6       Prima::PodView - POD browser widget
7

SYNOPSIS

9               use Prima qw(Application PodView);
10
11               my $window = Prima::MainWindow-> create;
12               my $podview = $window-> insert( 'Prima::PodView',
13                       pack => { fill => 'both', expand => 1 }
14               );
15               $podview-> open_read;
16               $podview-> read("=head1 NAME\n\nI'm also a pod!\n\n");
17               $podview-> close_read;
18
19               run Prima;
20

DESCRIPTION

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

USAGE

28       The package consists of the several logically separated parts. These
29       include file locating and loading, formatting and navigation.
30
31   Content methods
32       The basic access to the content is not bound to the file system. The
33       POD content can be supplied without any file to the viewer. Indeed, the
34       file loading routine "load_file" is a mere wrapper to the content
35       loading functions:
36
37       open_read %OPTIONS
38           Clears the current content and enters the reading mode. In this
39           mode the content can be appended by calling read that pushes the
40           raw POD content to the parser.
41
42       read TEXT
43           Supplies TEXT string to the parser. Manages basic indentation, but
44           the main formatting is performed inside add and add_formatted
45
46           Must be called only within open_read/close_read brackets
47
48       add TEXT, STYLE, INDENT
49           Formats TEXT string of a given STYLE ( one of "STYLE_XXX"
50           constants) with INDENT space.
51
52           Must be called only within open_read/close_read brackets.
53
54       add_formatted FORMAT, TEXT
55           Adds a pre-formatted TEXT with a given FORMAT, supplied by "=begin"
56           or "=for" POD directives. Prima::PodView understands 'text' and
57           'podview' FORMATs; the latter format is for Prima::PodView itself
58           and contains small number of commands, aimed at inclusion of images
59           into the document.
60
61           The 'podview' commands are:
62
63           cut Example:
64
65                       =for podview <cut>
66
67                       =for text just text-formatter info
68
69                               ....
70                               text-only info
71                               ...
72
73                       =for podview </cut>
74
75               The <cut<gt> clause skips all POD input until cancelled.  It is
76               used in conjunction with the following command, img, to allow a
77               POD manpage provide both graphic ('podview', 'html', etc ) and
78               text ( 'text' ) content.
79
80           img [src="SRC"] [width="WIDTH"] [height="HEIGHT"] [cut="CUT"]
81           [frame="FRAME"]
82               An image inclusion command, where src is a relative or an
83               absolute path to an image file. In case if scaling is required,
84               "width" and "height" options can be set. When the image is a
85               multiframe image, the frame index can be set by "frame" option.
86               Special "cut" option, if set to a true value, activates the cut
87               behavior if ( and only if ) the image load operation was
88               unsuccessful.  This makes possible simultaneous use of
89               'podview' and 'text' :
90
91                       =for podview <img src="graphic.gif" cut=1 >
92
93                       =begin text
94
95                       y     .
96                       |  .
97                       |.
98                       +----- x
99
100                       =end text
101
102                       =for podview </cut>
103
104               In the example above 'graphic.gif' will be shown if it can be
105               found and loaded, otherwise the poor-man-drawings would be
106               selected.
107
108               If "src" is omitted, image is retrieved from "images" array,
109               from the index "frame".
110
111       close_read
112           Closes the reading mode and starts the text rendering by calling
113           "format".  Returns "undef" if there is no POD context, 1 otherwise.
114
115   Rendering
116       The rendering is started by "format" call, which returns ( almost )
117       immediately, initiating the mechanism of delayed rendering, which is
118       often time-consuming.  "format"'s only parameter KEEP_OFFSET is a
119       boolean flag, which, if set to 1, remembers the current location on a
120       page, and when the rendered text approaches the location, scrolls the
121       document automatically.
122
123       The rendering is based an a document model, generated by
124       open_read/close_read session.  The model is a set of same text blocks
125       defined by Prima::TextView, except that the header length is only three
126       integers:
127
128               M_INDENT       - the block X-axis indent
129               M_TEXT_OFFSET  - same as BLK_TEXT_OFFSET
130               M_FONT_ID      - 0 or 1, because PodView's fontPalette contains only two fonts -
131                                variable ( 0 ) and fixed ( 1 ).
132
133       The actual rendering is performed in "format_chunks", where model
134       blocks are transformed to the full text blocks, wrapped and pushed into
135       TextView-provided storage. In parallel, links and the corresponding
136       event rectangles are calculated on this stage.
137
138   Topics
139       Prima::PodView provides the "::topicView" property, which governs
140       whether the man page is viewed by topics or as a whole. When it is
141       viewed as topics, "{modelRange}" array selects the model blocks that
142       include the topic.  Thus, having a single model loaded, text blocks
143       change dynamically.
144
145       Topics contained in "{topics}" array, each is an array with indices of
146       "T_XXX" constants:
147
148               T_MODEL_START - beginning of topic
149               T_MODEL_END   - length of a topic
150               T_DESCRIPTION - topic name
151               T_STYLE       - STYLE_XXX constant
152               T_ITEM_DEPTH  - depth of =item recursion
153               T_LINK_OFFSET - offset in links array, started in the topic
154
155   Styles
156       "::styles" property provides access to the styles, applied to different
157       pod text parts. These styles are:
158
159               STYLE_CODE   - style for pre-formatted text and C<>
160               STYLE_TEXT   - normal text
161               STYLE_HEAD_1 - =head1
162               STYLE_HEAD_2 - =head2
163               STYLE_HEAD_3 - =head3
164               STYLE_HEAD_4 - =head4
165               STYLE_ITEM   - =item
166               STYLE_LINK   - style for L<> text
167
168       Each style is a hash with the following keys: "fontId", "fontSize",
169       "fontStyle", "color", "backColor", fully analogous to the
170       tb::BLK_DATA_XXX options.  This functionality provides another layer of
171       accessibility to the pod formatter.
172
173       In addition to styles, Prima::PodView defined "colormap" entries for
174       "STYLE_LINK" and "STYLE_CODE":
175
176               COLOR_LINK_FOREGROUND
177               COLOR_LINK_BACKGROUND
178               COLOR_CODE_FOREGROUND
179               COLOR_CODE_BACKGROUND
180
181       The default colors in the styles are mapped into these entries.
182
183   Link and navigation methods
184       Prima::PodView provides a hand-icon mouse pointer highlight for the
185       link entries and as an interactive part, the link documents or topics
186       are loaded when the user presses the mouse button on the link. The
187       mechanics below that is as follows. "{contents}" of event rectangles, (
188       see Prima::TextView ) is responsible for distinguishing whether a mouse
189       is inside a link or not.  When the link is activated, "link_click" is
190       called, which, in turn, calls "load_link" method. If the page is loaded
191       successfully, depending on "::topicView" property value, either
192       "select_topic" or "select_text_offset" method is called.
193
194       The family of file and link access functions consists of the following
195       methods:
196
197       load_file MANPAGE
198           Loads a manpage, if it can be found in the PATH or perl
199           installation directories.  If unsuccessful, displays an error.
200
201       load_link LINK
202           LINK is a text in format of perlpod "L<>" link: "manpage/section".
203           Loads the manpage, if necessary, and selects the section.
204
205       load_bookmark BOOKMARK
206           Loads a bookmark string, prepared by make_bookmark function.  Used
207           internally.
208
209       load_content CONTENT
210           Loads content into the viewer. Returns "undef" is there is no POD
211           context, 1 otherwise.
212
213       make_bookmark [ WHERE ]
214           Combines the information about the currently viewing manpage, topic
215           and text offset into a storable string. WHERE, an optional string
216           parameter, can be either omitted, in such case the current settings
217           are used, or be one of 'up', 'next' or 'prev' strings.
218
219           The 'up' string returns a bookmark to the upper level of the
220           manpage.
221
222           The 'next' and 'prev' return a bookmark to the next or the previous
223           topics in a manpage.
224
225           If the location cannot be stored or defined, "undef" is returned.
226
227
228
229perl v5.30.0                      2019-08-21                 Prima::PodView(3)
Impressum