1Prima::PodView(3) User Contributed Perl Documentation Prima::PodView(3)
2
6 Prima::PodView - POD browser widget
7
9 use Prima qw(Application PodView);
10 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 run Prima;
20
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
28 The package consists of the several logically separated parts. These
29 include file locating and loading, formatting and navigation.
30 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 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 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 Must be called only within open_read/close_read brackets
47 add TEXT, STYLE, INDENT
49 Formats TEXT string of a given STYLE ( one of "STYLE_XXX"
50 constants) with INDENT space.
51 Must be called only within open_read/close_read brackets.
53 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 The 'podview' commands are:
62 cut Example:
64 =for podview <cut>
66 =for text just text-formatter info
68 ....
70 text-only info
71 ...
72 =for podview </cut>
74 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 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 =for podview <img src="graphic.gif" cut=1 >
92 =begin text
94 y .
96 | .
97 |.
98 +----- x
99 =end text
101 =for podview </cut>
103 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 If "src" is omitted, image is retrieved from "images" array,
109 from the index "frame".
110 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 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 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 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 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 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 Topics contained in "{topics}" array, each is an array with indices of
146 "T_XXX" constants:
147 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 Styles
156 "::styles" property provides access to the styles, applied to different
157 pod text parts. These styles are:
158 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 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 In addition to styles, Prima::PodView defined "colormap" entries for
175 "STYLE_LINK" , "STYLE_CODE", and "STYLE_VERBATIM":
176 COLOR_LINK_FOREGROUND
178 COLOR_LINK_BACKGROUND
179 COLOR_CODE_FOREGROUND
180 COLOR_CODE_BACKGROUND
181 The default colors in the styles are mapped into these entries.
183 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 The family of file and link access functions consists of the following
196 methods:
197 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 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 load_bookmark BOOKMARK
207 Loads a bookmark string, prepared by make_bookmark function. Used
208 internally.
209 load_content CONTENT
211 Loads content into the viewer. Returns "undef" is there is no POD
212 context, 1 otherwise.
213 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 The 'up' string returns a bookmark to the upper level of the
221 manpage.
222 The 'next' and 'prev' return a bookmark to the next or the previous
224 topics in a manpage.
225 If the location cannot be stored or defined, "undef" is returned.
227 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 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 NewPage
239 Called after new content is loaded
240perl v5.36.0 2022-07-22 Prima::PodView(3)