--- name: "Gtk2::Ex::PodViewer" section: "3pm" platform: "linux" package: "libgtk2-ex-podviewer-perl" version: "0.18-1" release: "Debian 9 (Stretch)" platforms: ["linux"] url: "https://new.carta.tech/Gtk2::Ex::PodViewer" --- # Gtk2::Ex::PodViewer(3pm) a Gtk2 widget for displaying Plain old Documentation (POD). NB: This module used to be called Gtk2::PodViewer. That module is now a stub that points to this module. ## NAME Gtk2::Ex::PodViewer - a Gtk2 widget for displaying Plain old Documentation (POD). 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 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::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 \. ## OBJECT HIERARCHY ``` L +--- L +--- L +--- L +--- L +--- L ``` ## 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 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::Ex::PodViewer searches for documents: ``` $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. ### DEPRECATED DOCUMENT LOADERS The following document loads are now deprecated, and are now just wrapper of the `"load_doc"` method: ``` $viewer->load_perldoc($perldoc); $viewer->load_module($module); ``` ``` $parser = $view->parser; ``` returns the `"Gtk2::Ex::PodViewer::Parser"` object used to render the POD data. ## SIGNALS Gtk2::Ex::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::Ex::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::Ex::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. ## Getting and Setting Font preferences You can set the font used to render text in a Gtk2::Ex::PodViewer widget like so: ``` $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 `"podviewer"` is installed with Gtk2::Ex::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 \. ## BUGS AND TASKS Gtk2::Ex::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. ## PREREQUISITES - • Gtk2 (obviously). The most recent version will be from \. - • 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 \ - • \ - • Gtk2::Ex::PodViewer::Parser ## AUTHORS Gavin Brown, Torsten Schoenfeld and Scott Arrington. ## COPYRIGHT (c) 2003-2005 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.