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 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 =for podview <img src="data:base64">
118 R0lGODdhAQABAIAAAAAAAAAAACwAAAAAAQABAIAAAAAAAAACAkQBADs=
119 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 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 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 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 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 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 Topics contained in "{topics}" array, each is an array with indices of
155 "T_XXX" constants:
156 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 Styles
165 "::styles" property provides access to the styles, applied to different
166 pod text parts. These styles are:
167 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 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 In addition to styles, Prima::PodView defined "colormap" entries for
184 "STYLE_LINK" , "STYLE_CODE", and "STYLE_VERBATIM":
185 COLOR_LINK_FOREGROUND
187 COLOR_LINK_BACKGROUND
188 COLOR_CODE_FOREGROUND
189 COLOR_CODE_BACKGROUND
190 The default colors in the styles are mapped into these entries.
192 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 If the page is loaded successfully, depending on "::topicView" property
200 value, either "select_topic" or "select_text_offset" method is called.
201 The family of file and link access functions consists of the following
203 methods:
204 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 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 load_bookmark BOOKMARK
214 Loads a bookmark string, prepared by make_bookmark function. Used
215 internally.
216 load_content CONTENT
218 Loads content into the viewer. Returns "undef" is there is no POD
219 context, 1 otherwise.
220 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 The 'up' string returns a bookmark to the upper level of the
228 manpage.
229 The 'next' and 'prev' return a bookmark to the next or the previous
231 topics in a manpage.
232 If the location cannot be stored or defined, "undef" is returned.
234 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 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 NewPage
246 Called after new content is loaded
247perl v5.38.0 2023-07-21 Prima::PodView(3)