--- name: "Gtk2::PodViewer" section: "3pm" platform: "linux" package: "libgtk2-podviewer-perl" version: "0.09-2" release: "Debian 3.1 (Sarge)" platforms: ["linux"] url: "https://new.carta.tech/Gtk2::PodViewer" --- # Gtk2::PodViewer(3pm) Gtk2::PodViewer - a Gtk2 widget for displaying Plain old Documentation (POD). ``` use Gtk2 -init; use Gtk2::PodViewer; ``` ``` my $viewer = Gtk2::PodViewer->new; ``` ``` $viewer->load('/path/to/file.pod'); # load a file $viewer->load('IO::Scalar'); # load a module $viewer->load('perlvar'); # load a perldoc $viewer->load('bless'); # load a function ``` ``` $viewer->show; # see, it's a widget! ``` ``` my $window = Gtk2::Window->new; $window->add($viewer); ``` ``` $window->show; ``` ``` Gtk2->main; ``` Gtk2::PodViewer is a widget for rendering Perl POD documents. It is based on the Gtk2::TextView widget and uses Pod::Parser for manipulating POD data. Gtk2::PodViewer widgets inherit all the methods and properties of Gtk2::TextView widgets. Full information about text buffers can be found in the Gtk+ documentation at \. ``` L +--- L +--- L +--- L +--- L +--- L ``` ``` my $view = Gtk2::PodViewer->new; ``` creates and returns a new Gtk2::PodViewer widget. ``` $viewer->clear; ``` This clears the viewer's buffer and resets the iter. You should never need to use this method since the loader methods (see "Document Loaders" below) will do it for you. ``` @marks = $view->get_marks; ``` This returns an array of section headers. So for example, a POD document of the form ``` =pod ``` ``` =head1 NAME ``` ``` =head1 SYNOPSIS ``` ``` =cut ``` would result in ``` @marks = ('NAME', 'SYNOPSIS'); ``` You can then use the contents of this array to create a document index. ``` $name = 'SYNOPSIS'; ``` ``` $mark = $view->get_mark($name); ``` returns the GtkTextMark object referred to by `$name`. ``` $name = 'SYNOPSIS'; ``` ``` $view->jump_to($name); ``` this scrolls the PodViewer window to the selected mark. ``` $viewer->load($document); ``` Loads a given document. `$document` can be a perldoc name (eg., `'perlvar'`), a module (eg. `'IO::Scalar'`), a filename or the name of a Perl builtin function from perlfunc. Documents are searched for in that order, that is, the perlvar document will be loaded before a file called `"perlvar"` in the current directory. The `"load()"` method is a wrapper to a number of specialised document loaders. You can call one of these loaders directly to override the order in which Gtk2::PodViewer searches for documents: ``` $viewer->load_perldoc($perldoc); ``` loads a perldoc file, or returns undef on failure. ``` $viewer->load_module($module); ``` loads POD from a module file, or returns undef on failure. ``` $viewer->load_file($file); ``` loads POD from a file, or returns undef on failure. ``` $viewer->load_function($function); ``` This method scans the perlfunc POD document for the documentation for a given function. The algorithm for this is lifted from the Pod::Perldoc module, so it should work identically to `"perldoc -f [function]"`. ``` $viewer->load_string($string); ``` This method renders the POD data in the `$string` variable. ``` $parser = $view->parser; ``` returns the `"Gtk2::PodViewer::Parser"` object used to render the POD data. Gtk2::PodViewer inherits all of Gtk2::TextView's signals, and has the following:\ **The 'link\_clicked' signal** ``` $viewer->signal_connect('link_clicked', \&clicked); ``` ``` sub clicked { my ($viewer, $link_text) = @_; print "user clicked on '$link_text'\n"; } ``` Emitted when the user clicks on a hyperlink within the POD. This may be a section title, a document name, or a URL. The receiving function will be giving two arguments: a reference to the Gtk2::PodViewer object, and a scalar containing the link text.\ **The 'link\_enter' signal** ``` $viewer->signal_connect('link_enter', \&enter); ``` ``` sub enter { my ($viewer, $link_text) = @_; print "user moused over '$link_text'\n"; } ``` Emitted when the user moves the mouse pointer over a hyperlink within the POD. This may be a section title, a document name, or a URL. The receiving function will be giving two arguments: a reference to the Gtk2::PodViewer object, and a scalar containing the link text.\ **The 'link\_leave' signal** ``` $viewer->signal_connect('link_leave', \&leave); ``` ``` sub clicked { my $viewer = shift; print "user moused out\n"; } ``` Emitted when the user moves the mouse pointer out from a hyperlink within the POD. `"podviewer"` is installed with Gtk2::PodViewer. It is a simple Pod viewing program. It is pretty minimal, but does do the job quite well. Those looking for a more feature-complete documentation browser should try PodBrowser, available from \. Gtk2::PodViewer is a work in progress. All comments, complaints, offers of help and patches are welcomed. We currently know about these issues: When rendering long documents the UI freezes for too long. Some strangeness with Unicode. Gtk2 (obviously). The most recent version will be from \. Pod::Parser IO::Scalar Gtk2::PodViewer::Parser, which is part of the Gtk2::PodViewer distribution, also requires Locale::gettext. Gtk2 or \ \ Gtk2::PodViewer::Parser Gavin Brown, Torsten Schoenfeld and Scott Arrington. (c) 2004 Gavin Brown (gavin.brown@uk.com). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.