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 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 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 In addition to styles, Prima::PodView defined "colormap" entries for
174 "STYLE_LINK" and "STYLE_CODE":
175 COLOR_LINK_FOREGROUND
177 COLOR_LINK_BACKGROUND
178 COLOR_CODE_FOREGROUND
179 COLOR_CODE_BACKGROUND
180 The default colors in the styles are mapped into these entries.
182 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 The family of file and link access functions consists of the following
195 methods:
196 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 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 load_bookmark BOOKMARK
206 Loads a bookmark string, prepared by make_bookmark function. Used
207 internally.
208 load_content CONTENT
210 Loads content into the viewer. Returns "undef" is there is no POD
211 context, 1 otherwise.
212 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 The 'up' string returns a bookmark to the upper level of the
220 manpage.
221 The 'next' and 'prev' return a bookmark to the next or the previous
223 topics in a manpage.
224 If the location cannot be stored or defined, "undef" is returned.
226 Events
228 Bookmark BOOKMARK
229 When a new topic is navigated to by the user, this event is
230 triggered with the current topic to have it eventually stored in
231 bookmarks or history.
232 Link LINK_REF, BUTTON, MOD, X, Y
234 When the user clicks on a link, this event is called with the link
235 address, mouse button, modificator keys, and coordinates.
236 NewPage
238 Called after new content is loaded
239perl v5.32.0 2020-07-28 Prima::PodView(3)