NAME

NB: This module used to be called Gtk2::PodViewer. That module is now a stub that points to this module.

SYNOPSIS

        use Gtk2 -init;
        use Gtk2::Ex::PodViewer;

        my $viewer = Gtk2::Ex::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;

DESCRIPTION

Gtk2::Ex::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>.

OBJECT HIERARCHY

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

CONSTRUCTOR

        my $view = Gtk2::Ex::PodViewer->new;

creates and returns a new Gtk2::Ex::PodViewer widget.

ADDITIONAL METHODS

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

        my $db = $viewer->get_db;

This method returns a hashref that contains the POD document database used internally by Gtk2::Ex::PodViewer. If you want to improve startup performance, you can cache this database using a module like "Storable". To load a cached database into a viewer object, call

        $viewer->set_db($db);

before making a call to any of the document loader methods below (otherwise, Gtk2::Ex::PodViewer will create a new database for itself). If you want to tell Gtk2::Ex::PodViewer to create a new document database (for example, after a new module has been installed), use

        $viewer->reinitialize_db;

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

DOCUMENT LOADERS

        $viewer->load_doc($perldoc);

loads a perldoc file or Perl module documentation, or 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.

        $viewer->load_perldoc($perldoc);
        $viewer->load_module($module);

        $parser = $view->parser;

SIGNALS

        $viewer->signal_connect('link_clicked', \&clicked);

        sub clicked {
                my ($viewer, $link_text) = @_;
                print "user clicked on '$link_text'\n";
        }

        $viewer->signal_connect('link_enter', \&enter);

        sub enter {
                my ($viewer, $link_text) = @_;
                print "user moused over '$link_text'\n";
        }

        $viewer->signal_connect('link_leave', \&leave);

        sub clicked {
                my $viewer = shift;
                print "user moused out\n";
        }

Getting and Setting Font preferences

        $viewer->modify_font(Gtk2::Pango::FontDescription->from_string($FONT_NAME);

To modify the appearance of the various elements of the page, you need to extract the Gtk2::TextTag from the viewer's buffer:

        my $tag = $viewer->get_buffer->get_tag_table->lookup('monospace');
        $tag->set('font' => $FONT_NAME);

The tags used by Gtk2::Ex::PodViewer are:

"bold"

Used to format bold text.

"italic"

Used to format italic text.

"head1" ... "head4"

Used to format headers.

"monospace"

Used to format preformatted text.

"typewriter"

Used to format inline preformatted text.

"link"

Used to format hyperlinks.

THE podviewer PROGRAM

BUGS AND TASKS

We currently know about these issues:

• When rendering long documents the UI freezes for too long.
• Some strangeness with Unicode.

PREREQUISITES

• Gtk2 (obviously). The most recent version will be from <http://gtk2-perl.sf.net/>.
• Pod::Parser
• IO::Scalar
• Pod::Simple::Search

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

SEE ALSO

• Gtk2 or <http://gtk2-perl.sf.net/>
• <http://developer.gnome.org/doc/API/2.0/gtk/GtkTextView.html>
• Gtk2::Ex::PodViewer::Parser

AUTHORS

COPYRIGHT