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 Documenta‐
7       tion (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 manipulat‐
35       ing 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 <http://devel‐
40       oper.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 Load‐
60       ers" 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 (oth‐
72       erwise, Gtk2::Ex::PodViewer will create a new database for itself). If
73       you want to tell Gtk2::Ex::PodViewer to create a new document database
74       (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 docu‐
81       ment 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., 'perl‐
112       var'), a module (eg. 'IO::Scalar'), a filename or the name of a Perl
113       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
142       The following document loads are now deprecated, and are now just wrap‐
143       per of the "load_doc" method:
144
145               $viewer->load_perldoc($perldoc);
146               $viewer->load_module($module);
147
148               $parser = $view->parser;
149
150       returns the "Gtk2::Ex::PodViewer::Parser" object used to render the POD
151       data.
152

SIGNALS

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

Getting and Setting Font preferences

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

THE podviewer PROGRAM

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

BUGS AND TASKS

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

PREREQUISITES

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

AUTHORS

267       Gavin Brown, Torsten Schoenfeld and Scott Arrington.
268

COPYRIGHT

270       (c) 2003-2005 Gavin Brown (gavin.brown@uk.com). All rights reserved.
271       This program is free software; you can redistribute it and/or modify it
272       under the same terms as Perl itself.
273
274
275
276perl v5.8.8                       2006-07-11            Gtk2::Ex::PodViewer(3)