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 <http://developer.gnome.org/doc/API/2.0/gtk/GtkTextView.html>.

        L<Glib::Object>
        +--- L<Gtk2::Object>
             +--- L<Gtk2::Widget>
                  +--- L<Gtk2::Editable>
                       +--- L<Gtk2::TextView>
                            +--- L<Gtk2::PodViewer>

        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 CW$name.

        $name = 'SYNOPSIS';

        $view->jump_to($name);

this scrolls the PodViewer window to the selected mark.

        $viewer->load($document);

Loads a given document. CW$document can be a perldoc name (eg., CW'perlvar'), a module (eg. CW'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 CWperlvar in the current directory.

The CWload() 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 CWperldoc -f [function].

        $viewer->load_string($string);

This method renders the POD data in the CW$string variable.

        $parser = $view->parser;

returns the CWGtk2::PodViewer::Parser object used to render the POD data.

Gtk2::PodViewer inherits all of Gtk2::TextView's signals, and has the following:

        $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.

        $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.

        $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.

CWpodviewer 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 <http://jodrell.net/projects/podbrowser>.

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 <http://gtk2-perl.sf.net/>.

•

Pod::Parser

•

IO::Scalar

Gtk2::PodViewer::Parser, which is part of the Gtk2::PodViewer distribution, also requires Locale::gettext.

•

Gtk2 or <http://gtk2-perl.sf.net/>

•

<http://developer.gnome.org/doc/API/2.0/gtk/GtkTextView.html>

•

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.