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 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               STYLE_VERBATIM - style for pre-formatted text
168
169       Each style is a hash with the following keys: "fontId", "fontSize",
170       "fontStyle", "color", "backColor", fully analogous to the
171       tb::BLK_DATA_XXX options.  This functionality provides another layer of
172       accessibility to the pod formatter.
173
174       In addition to styles, Prima::PodView defined "colormap" entries for
175       "STYLE_LINK" , "STYLE_CODE", and "STYLE_VERBATIM":
176
177               COLOR_LINK_FOREGROUND
178               COLOR_LINK_BACKGROUND
179               COLOR_CODE_FOREGROUND
180               COLOR_CODE_BACKGROUND
181
182       The default colors in the styles are mapped into these entries.
183
184   Link and navigation methods
185       Prima::PodView provides a hand-icon mouse pointer highlight for the
186       link entries and as an interactive part, the link documents or topics
187       are loaded when the user presses the mouse button on the link. The
188       mechanics below that is as follows. "{contents}" of event rectangles, (
189       see Prima::TextView ) is responsible for distinguishing whether a mouse
190       is inside a link or not.  When the link is activated, "link_click" is
191       called, which, in turn, calls "load_link" method. If the page is loaded
192       successfully, depending on "::topicView" property value, either
193       "select_topic" or "select_text_offset" method is called.
194
195       The family of file and link access functions consists of the following
196       methods:
197
198       load_file MANPAGE
199           Loads a manpage, if it can be found in the PATH or perl
200           installation directories.  If unsuccessful, displays an error.
201
202       load_link LINK
203           LINK is a text in format of perlpod "L<>" link: "manpage/section".
204           Loads the manpage, if necessary, and selects the section.
205
206       load_bookmark BOOKMARK
207           Loads a bookmark string, prepared by make_bookmark function.  Used
208           internally.
209
210       load_content CONTENT
211           Loads content into the viewer. Returns "undef" is there is no POD
212           context, 1 otherwise.
213
214       make_bookmark [ WHERE ]
215           Combines the information about the currently viewing manpage, topic
216           and text offset into a storable string. WHERE, an optional string
217           parameter, can be either omitted, in such case the current settings
218           are used, or be one of 'up', 'next' or 'prev' strings.
219
220           The 'up' string returns a bookmark to the upper level of the
221           manpage.
222
223           The 'next' and 'prev' return a bookmark to the next or the previous
224           topics in a manpage.
225
226           If the location cannot be stored or defined, "undef" is returned.
227
228   Events
229       Bookmark BOOKMARK
230           When a new topic is navigated to by the user, this event is
231           triggered with the current topic to have it eventually stored in
232           bookmarks or history.
233
234       Link LINK_REF, BUTTON, MOD, X, Y
235           When the user clicks on a link, this event is called with the link
236           address, mouse button, modificator keys, and coordinates.
237
238       NewPage
239           Called after new content is loaded
240
241
242
243perl v5.36.0                      2022-07-22                 Prima::PodView(3)
Impressum