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               It is also possible to embed images in the pod, by using
112               special "src" tag and base64-encoded images. The format should
113               preferrably be GIF, as this is Prima default format, or BMP for
114               very small images, as it is supported without third party
115               libraries:
116
117                       =for podview <img src="data:base64">
118                       R0lGODdhAQABAIAAAAAAAAAAACwAAAAAAQABAIAAAAAAAAACAkQBADs=
119
120       close_read
121           Closes the reading mode and starts the text rendering by calling
122           "format".  Returns "undef" if there is no POD context, 1 otherwise.
123
124   Rendering
125       The rendering is started by "format" call, which returns ( almost )
126       immediately, initiating the mechanism of delayed rendering, which is
127       often time-consuming.  "format"'s only parameter KEEP_OFFSET is a
128       boolean flag, which, if set to 1, remembers the current location on a
129       page, and when the rendered text approaches the location, scrolls the
130       document automatically.
131
132       The rendering is based an a document model, generated by
133       open_read/close_read session.  The model is a set of same text blocks
134       defined by Prima::TextView, except that the header length is only three
135       integers:
136
137               M_INDENT       - the block X-axis indent
138               M_TEXT_OFFSET  - same as BLK_TEXT_OFFSET
139               M_FONT_ID      - 0 or 1, because PodView's fontPalette contains only two fonts -
140                                variable ( 0 ) and fixed ( 1 ).
141
142       The actual rendering is performed in "format_chunks", where model
143       blocks are transformed to the full text blocks, wrapped and pushed into
144       TextView-provided storage. In parallel, links and the corresponding
145       event rectangles are calculated on this stage.
146
147   Topics
148       Prima::PodView provides the "::topicView" property, which governs
149       whether the man page is viewed by topics or as a whole. When it is
150       viewed as topics, "{modelRange}" array selects the model blocks that
151       include the topic.  Thus, having a single model loaded, text blocks
152       change dynamically.
153
154       Topics contained in "{topics}" array, each is an array with indices of
155       "T_XXX" constants:
156
157               T_MODEL_START - beginning of topic
158               T_MODEL_END   - length of a topic
159               T_DESCRIPTION - topic name
160               T_STYLE       - STYLE_XXX constant
161               T_ITEM_DEPTH  - depth of =item recursion
162               T_LINK_OFFSET - offset in links array, started in the topic
163
164   Styles
165       "::styles" property provides access to the styles, applied to different
166       pod text parts. These styles are:
167
168               STYLE_CODE     - style for C<>
169               STYLE_TEXT     - normal text
170               STYLE_HEAD_1   - =head1
171               STYLE_HEAD_2   - =head2
172               STYLE_HEAD_3   - =head3
173               STYLE_HEAD_4   - =head4
174               STYLE_ITEM     - =item
175               STYLE_LINK     - style for L<> text
176               STYLE_VERBATIM - style for pre-formatted text
177
178       Each style is a hash with the following keys: "fontId", "fontSize",
179       "fontStyle", "color", "backColor", fully analogous to the
180       tb::BLK_DATA_XXX options.  This functionality provides another layer of
181       accessibility to the pod formatter.
182
183       In addition to styles, Prima::PodView defined "colormap" entries for
184       "STYLE_LINK" , "STYLE_CODE", and "STYLE_VERBATIM":
185
186               COLOR_LINK_FOREGROUND
187               COLOR_LINK_BACKGROUND
188               COLOR_CODE_FOREGROUND
189               COLOR_CODE_BACKGROUND
190
191       The default colors in the styles are mapped into these entries.
192
193   Link and navigation methods
194       Prima::PodView provides a hand-icon mouse pointer highlight for the
195       link entries and as an interactive part, the link documents or topics
196       are loaded when the user presses the mouse button on the link.
197       Prima::Widget::Link is used for the link mechanics implementation.
198
199       If the page is loaded successfully, depending on "::topicView" property
200       value, either "select_topic" or "select_text_offset" method is called.
201
202       The family of file and link access functions consists of the following
203       methods:
204
205       load_file MANPAGE
206           Loads a manpage, if it can be found in the PATH or perl
207           installation directories.  If unsuccessful, displays an error.
208
209       load_link LINK
210           LINK is a text in format of perlpod "L<>" link: "manpage/section".
211           Loads the manpage, if necessary, and selects the section.
212
213       load_bookmark BOOKMARK
214           Loads a bookmark string, prepared by make_bookmark function.  Used
215           internally.
216
217       load_content CONTENT
218           Loads content into the viewer. Returns "undef" is there is no POD
219           context, 1 otherwise.
220
221       make_bookmark [ WHERE ]
222           Combines the information about the currently viewing manpage, topic
223           and text offset into a storable string. WHERE, an optional string
224           parameter, can be either omitted, in such case the current settings
225           are used, or be one of 'up', 'next' or 'prev' strings.
226
227           The 'up' string returns a bookmark to the upper level of the
228           manpage.
229
230           The 'next' and 'prev' return a bookmark to the next or the previous
231           topics in a manpage.
232
233           If the location cannot be stored or defined, "undef" is returned.
234
235   Events
236       Bookmark BOOKMARK
237           When a new topic is navigated to by the user, this event is
238           triggered with the current topic to have it eventually stored in
239           bookmarks or history.
240
241       Link LINK_REF, BUTTON, MOD, X, Y
242           When the user clicks on a link, this event is called with the link
243           address, mouse button, modificator keys, and coordinates.
244
245       NewPage
246           Called after new content is loaded
247
248
249
250perl v5.36.0                      2023-03-20                 Prima::PodView(3)
Impressum