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 <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 $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 <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 ([email protected]). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.