Gtk2::Ex::PodViewer(3pm)

1Gtk2::Ex::PodViewer(3)User Contributed Perl DocumentationGtk2::Ex::PodViewer(3)
2
3
4

NAME

6       Gtk2::Ex::PodViewer - a Gtk2 widget for displaying Plain old
7       Documentation (POD).
8
9       NB: This module used to be called Gtk2::PodViewer. That module is now a
10       stub that points to this module.
11

SYNOPSIS

13               use Gtk2 -init;
14               use Gtk2::Ex::PodViewer;
15
16               my $viewer = Gtk2::Ex::PodViewer->new;
17
18               $viewer->load('/path/to/file.pod');     # load a file
19               $viewer->load('IO::Scalar');            # load a module
20               $viewer->load('perlvar');               # load a perldoc
21               $viewer->load('bless');                 # load a function
22
23               $viewer->show;                          # see, it's a widget!
24
25               my $window = Gtk2::Window->new;
26               $window->add($viewer);
27
28               $window->show;
29
30               Gtk2->main;
31

DESCRIPTION

33       Gtk2::Ex::PodViewer is a widget for rendering Perl POD documents. It is
34       based on the Gtk2::TextView widget and uses Pod::Parser for
35       manipulating POD data.
36
37       Gtk2::Ex::PodViewer widgets inherit all the methods and properties of
38       Gtk2::TextView widgets. Full information about text buffers can be
39       found in the Gtk+ documentation at
40       <http://developer.gnome.org/doc/API/2.0/gtk/GtkTextView.html>.
41

OBJECT HIERARCHY

43               L<Glib::Object>
44               +--- L<Gtk2::Object>
45                    +--- L<Gtk2::Widget>
46                         +--- L<Gtk2::Editable>
47                              +--- L<Gtk2::TextView>
48                                   +--- L<Gtk2::Ex::PodViewer>
49

CONSTRUCTOR

51               my $view = Gtk2::Ex::PodViewer->new;
52
53       creates and returns a new Gtk2::Ex::PodViewer widget.
54

ADDITIONAL METHODS

56               $viewer->clear;
57
58       This clears the viewer's buffer and resets the iter. You should never
59       need to use this method since the loader methods (see "Document
60       Loaders" below) will do it for you.
61
62               my $db = $viewer->get_db;
63
64       This method returns a hashref that contains the POD document database
65       used internally by Gtk2::Ex::PodViewer. If you want to improve startup
66       performance, you can cache this database using a module like
67       "Storable". To load a cached database into a viewer object, call
68
69               $viewer->set_db($db);
70
71       before making a call to any of the document loader methods below
72       (otherwise, Gtk2::Ex::PodViewer will create a new database for itself).
73       If you want to tell Gtk2::Ex::PodViewer to create a new document
74       database (for example, after a new module has been installed), use
75
76               $viewer->reinitialize_db;
77
78               @marks = $view->get_marks;
79
80       This returns an array of section headers. So for example, a POD
81       document of the form
82
83               =pod
84
85               =head1 NAME
86
87               =head1 SYNOPSIS
88
89               =cut
90
91       would result in
92
93               @marks = ('NAME', 'SYNOPSIS');
94
95       You can then use the contents of this array to create a document index.
96
97               $name = 'SYNOPSIS';
98
99               $mark = $view->get_mark($name);
100
101       returns the GtkTextMark object referred to by $name.
102
103               $name = 'SYNOPSIS';
104
105               $view->jump_to($name);
106
107       this scrolls the PodViewer window to the selected mark.
108
109               $viewer->load($document);
110
111       Loads a given document. $document can be a perldoc name (eg.,
112       'perlvar'), a module (eg. 'IO::Scalar'), a filename or the name of a
113       Perl builtin function from perlfunc. Documents are searched for in that
114       order, that is, the perlvar document will be loaded before a file
115       called "perlvar" in the current directory.
116

DOCUMENT LOADERS

118       The "load()" method is a wrapper to a number of specialised document
119       loaders. You can call one of these loaders directly to override the
120       order in which Gtk2::Ex::PodViewer searches for documents:
121
122               $viewer->load_doc($perldoc);
123
124       loads a perldoc file or Perl module documentation, or undef on failure.
125
126               $viewer->load_file($file);
127
128       loads POD from a file, or returns undef on failure.
129
130               $viewer->load_function($function);
131
132       This method scans the perlfunc POD document for the documentation for a
133       given function. The algorithm for this is lifted from the Pod::Perldoc
134       module, so it should work identically to "perldoc -f [function]".
135
136               $viewer->load_string($string);
137
138       This method renders the POD data in the $string variable.
139
140   DEPRECATED DOCUMENT LOADERS
141       The following document loads are now deprecated, and are now just
142       wrapper of the "load_doc" method:
143
144               $viewer->load_perldoc($perldoc);
145               $viewer->load_module($module);
146
147               $parser = $view->parser;
148
149       returns the "Gtk2::Ex::PodViewer::Parser" object used to render the POD
150       data.
151

SIGNALS

153       Gtk2::Ex::PodViewer inherits all of Gtk2::TextView's signals, and has
154       the following:
155
156   The 'link_clicked' signal
157               $viewer->signal_connect('link_clicked', \&clicked);
158
159               sub clicked {
160                       my ($viewer, $link_text) = @_;
161                       print "user clicked on '$link_text'\n";
162               }
163
164       Emitted when the user clicks on a hyperlink within the POD. This may be
165       a section title, a document name, or a URL. The receiving function will
166       be giving two arguments: a reference to the Gtk2::Ex::PodViewer object,
167       and a scalar containing the link text.
168
169   The 'link_enter' signal
170               $viewer->signal_connect('link_enter', \&enter);
171
172               sub enter {
173                       my ($viewer, $link_text) = @_;
174                       print "user moused over '$link_text'\n";
175               }
176
177       Emitted when the user moves the mouse pointer over a hyperlink within
178       the POD. This may be a section title, a document name, or a URL. The
179       receiving function will be giving two arguments: a reference to the
180       Gtk2::Ex::PodViewer object, and a scalar containing the link text.
181
182   The 'link_leave' signal
183               $viewer->signal_connect('link_leave', \&leave);
184
185               sub clicked {
186                       my $viewer = shift;
187                       print "user moused out\n";
188               }
189
190       Emitted when the user moves the mouse pointer out from a hyperlink
191       within the POD.
192

Getting and Setting Font preferences

194       You can set the font used to render text in a Gtk2::Ex::PodViewer
195       widget like so:
196
197               $viewer->modify_font(Gtk2::Pango::FontDescription->from_string($FONT_NAME);
198
199       To modify the appearance of the various elements of the page, you need
200       to extract the Gtk2::TextTag from the viewer's buffer:
201
202               my $tag = $viewer->get_buffer->get_tag_table->lookup('monospace');
203               $tag->set('font' => $FONT_NAME);
204
205       The tags used by Gtk2::Ex::PodViewer are:
206
207       "bold"
208           Used to format bold text.
209
210       "italic"
211           Used to format italic text.
212
213       "head1" ... "head4"
214           Used to format headers.
215
216       "monospace"
217           Used to format preformatted text.
218
219       "typewriter"
220           Used to format inline preformatted text.
221
222       "link"
223           Used to format hyperlinks.
224

THE podviewer PROGRAM

226       "podviewer" is installed with Gtk2::Ex::PodViewer. It is a simple Pod
227       viewing program. It is pretty minimal, but does do the job quite well.
228       Those looking for a more feature-complete documentation browser should
229       try PodBrowser, available from
230       <http://jodrell.net/projects/podbrowser>.
231

BUGS AND TASKS

233       Gtk2::Ex::PodViewer is a work in progress. All comments, complaints,
234       offers of help and patches are welcomed.
235
236       We currently know about these issues:
237
238       •   When rendering long documents the UI freezes for too long.
239
240       •   Some strangeness with Unicode.
241

PREREQUISITES

243       •   Gtk2 (obviously). The most recent version will be from
244           <http://gtk2-perl.sf.net/>.
245
246       •   Pod::Parser
247
248       •   IO::Scalar
249
250       •   Pod::Simple::Search
251
252       Gtk2::Ex::PodViewer::Parser, which is part of the Gtk2::Ex::PodViewer
253       distribution, also requires Locale::gettext.
254

AUTHORS

263       Gavin Brown, Torsten Schoenfeld and Scott Arrington.
264

COPYRIGHT

266       (c) 2003-2005 Gavin Brown (gavin.brown@uk.com). All rights reserved.
267       This program is free software; you can redistribute it and/or modify it
268       under the same terms as Perl itself.
269
270
271
272perl v5.34.0                      2022-01-21            Gtk2::Ex::PodViewer(3)