/ 
Gtk2-PodViewer-0.08
/ Gtk2::PodViewer

NAME

Gtk2::PodViewer - a Gtk2 widget for displaying Plain old Documentation (POD).

SYNOPSIS

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;

DESCRIPTION

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.

OBJECT HIERARCHY

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

CONSTRUCTOR

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

creates and returns a new Gtk2::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.

@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

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.

SIGNALS

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.

THE podviewer PROGRAM

podviewer is installed with Gtk2::PodViewer. It is a simple Pod viewing program. It is pretty minimal, but does do the job quite well.

BUGS AND TASKS

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.

  • When you click on a link, the first line of text in the new document is hilighted.

PREREQUISITES

SEE ALSO

AUTHORS

Gavin Brown, Torsten Schoenfeld and Scott Arrington.

COPYRIGHT

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