1Prima::PodView(3) User Contributed Perl Documentation Prima::PodView(3)
2
6 Prima::PodView - POD browser widget
7
9 use Prima qw(Application);
10 use Prima::PodView;
11 my $window = Prima::MainWindow-> create;
13 my $podview = $window-> insert( 'Prima::PodView',
14 pack => { fill => 'both', expand => 1 }
15 );
16 $podview-> open_read;
17 $podview-> read("=head1 NAME\n\nI'm also a pod!\n\n");
18 $podview-> close_read;
19 run Prima;
21
23 Prima::PodView contains a formatter ( in terms of perlpod ) and viewer
24 of POD content. It heavily employs its ascendant class Prima::TextView,
25 and is in turn base for the toolkit's default help viewer
26 Prima::HelpViewer.
27
29 The package consists of the several logically separated parts. These
30 include file locating and loading, formatting and navigation.
31 Content methods
33 The basic access to the content is not bound to the file system. The
34 POD content can be supplied without any file to the viewer. Indeed, the
35 file loading routine "load_file" is a mere wrapper to the content
36 loading functions:
37 open_read %OPTIONS
39 Clears the current content and enters the reading mode. In this
40 mode the content can be appended by calling read that pushes the
41 raw POD content to the parser.
42 read TEXT
44 Supplies TEXT string to the parser. Manages basic indentation, but
45 the main formatting is performed inside add and add_formatted
46 Must be called only within open_read/close_read brackets
48 add TEXT, STYLE, INDENT
50 Formats TEXT string of a given STYLE ( one of "STYLE_XXX"
51 constants) with INDENT space.
52 Must be called only within open_read/close_read brackets.
54 add_formatted FORMAT, TEXT
56 Adds a pre-formatted TEXT with a given FORMAT, supplied by "=begin"
57 or "=for" POD directives. Prima::PodView understands 'text' and
58 'podview' FORMATs; the latter format is for Prima::PodView itself
59 and contains small number of commands, aimed at inclusion of images
60 into the document.
61 The 'podview' commands are:
63 cut Example:
65 =for podview <cut>
67 =for text just text-formatter info
69 ....
71 text-only info
72 ...
73 =for podview </cut>
75 The <cut<gt> clause skips all POD input until cancelled. It is
77 used in conjunction with the following command, img, to allow a
78 POD manpage provide both graphic ('podview', 'html', etc ) and
79 text ( 'text' ) content.
80 img [src="SRC"] [width="WIDTH"] [height="HEIGHT"] [cut="CUT"]
82 [frame="FRAME"]
83 An image inclusion command, where src is a relative or an
84 absolute path to an image file. In case if scaling is required,
85 "width" and "height" options can be set. When the image is a
86 multiframe image, the frame index can be set by "frame" option.
87 Special "cut" option, if set to a true value, activates the cut
88 behavior if ( and only if ) the image load operation was
89 unsuccessful. This makes possible simultaneous use of
90 'podview' and 'text' :
91 =for podview <img src="graphic.gif" cut=1 >
93 =begin text
95 y .
97 | .
98 |.
99 +----- x
100 =end text
102 =for podview </cut>
104 In the example above 'graphic.gif' will be shown if it can be
106 found and loaded, otherwise the poor-man-drawings would be
107 selected.
108 If "src" is omitted, image is retrieved from "images" array,
110 from the index "frame".
111 close_read
113 Closes the reading mode and starts the text rendering by calling
114 "format". Returns "undef" if there is no POD context, 1 otherwise.
115 Rendering
117 The rendering is started by "format" call, which returns ( almost )
118 immediately, initiating the mechanism of delayed rendering, which is
119 often time-consuming. "format"'s only parameter KEEP_OFFSET is a
120 boolean flag, which, if set to 1, remembers the current location on a
121 page, and when the rendered text approaches the location, scrolls the
122 document automatically.
123 The rendering is based an a document model, generated by
125 open_read/close_read session. The model is a set of same text blocks
126 defined by Prima::TextView, except that the header length is only three
127 integers:
128 M_INDENT - the block X-axis indent
130 M_TEXT_OFFSET - same as BLK_TEXT_OFFSET
131 M_FONT_ID - 0 or 1, because PodView's fontPalette contains only two fonts -
132 variable ( 0 ) and fixed ( 1 ).
133 The actual rendering is performed in "format_chunks", where model
135 blocks are transformed to the full text blocks, wrapped and pushed into
136 TextView-provided storage. In parallel, links and the corresponding
137 event rectangles are calculated on this stage.
138 Topics
140 Prima::PodView provides the "::topicView" property, which governs
141 whether the man page is viewed by topics or as a whole. When it is
142 viewed as topics, "{modelRange}" array selects the model blocks that
143 include the topic. Thus, having a single model loaded, text blocks
144 change dynamically.
145 Topics contained in "{topics}" array, each is an array with indices of
147 "T_XXX" constants:
148 T_MODEL_START - beginning of topic
150 T_MODEL_END - length of a topic
151 T_DESCRIPTION - topic name
152 T_STYLE - STYLE_XXX constant
153 T_ITEM_DEPTH - depth of =item recursion
154 T_LINK_OFFSET - offset in links array, started in the topic
155 Styles
157 "::styles" property provides access to the styles, applied to different
158 pod text parts. These styles are:
159 STYLE_CODE - style for pre-formatted text and C<>
161 STYLE_TEXT - normal text
162 STYLE_HEAD_1 - =head1
163 STYLE_HEAD_2 - =head2
164 STYLE_HEAD_3 - =head3
165 STYLE_HEAD_4 - =head4
166 STYLE_ITEM - =item
167 STYLE_LINK - style for L<> 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" and "STYLE_CODE":
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.
227perl v5.28.0 2017-05-08 Prima::PodView(3)