NAME

Gtk2::Ex::HyperTextView - Gtk2::TextView with links!

VERSION

version 0.201

SYNOPSIS

use Gtk2 -init;
use Gtk2::Ex::HyperTextView;

my $viewer = Gtk2::Ex::HyperTextView->new;

# ... load some content ...

$viewer->show;                # see, it's a widget!

my $window = Gtk2::Window->new;
$window->add($viewer);

$window->show;

Gtk2->main;

DESCRIPTION

Gtk2::Ex::HyperTextView is a widget for rendering documents containing hyperlinks. It is based on the Gtk2::TextView widget and provides a widget that can be used by itself, or subclassed (e.g. Gtk2::Ex::HyperTextView::Pod.

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

CONSTRUCTOR

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

creates and returns a new Gtk2::Ex::HyperTextView 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::HyperTextView. 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::HyperTextView will create a new database for itself). If you want to tell Gtk2::Ex::HyperTextView 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 HyperTextView 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::HyperTextView 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_string($string);

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

$parser = $view->parser;

returns the Gtk2::Ex::HyperTextView::Parser object used to render the POD data.

SIGNALS

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

BUGS AND TASKS

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

• Pod::Parser

• IO::Scalar

• Pod::Simple::Search

Gtk2::Ex::HyperTextView::Parser, which is part of the Gtk2::Ex::HyperTextView 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::HyperTextView::Parser, Gtk2::Ex::PodViewer, Gtk2::Ex::HyperTextView::Pod, Gtk2::Ex::HyperTextView::Markdown.

BUGS

All complex software has bugs lurking in it, and this module is no exception.

Bugs, feature requests and pull requests through GitHub are most welcome; our page and repo (same URI):

https://github.com/RsrchBoy/gtk2-ex-hypertextview

RATIONALE

This work is a "restatement" of the Gtk2::Ex::PodViewer package. It's been altered such that the link-aware subclass of Gtk2::TextView is contained in its own base class (Gtk2::Ex::HyperTextView_, such that Pod (and other) viewers can in turn descend from the base class.

AUTHORS

This package is largely a restatement/realignment of the code and documentation contained in the Gtk2::Ex::PodViewer distribution. PodViewer's authors are listed as Gavin Brown, Torsten Schoenfeld and Scott Arrington.

All errors, and the work realigning the code, have been done by Chris Weyl.

COPYRIGHT

Copyright (c) 2012 Chris Weyl. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Large chunks of code in this package are:

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

AUTHOR

Chris Weyl <cweyl@alumni.drew.edu>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2012 by Chris Weyl.

This is free software, licensed under:

The GNU Lesser General Public License, Version 2.1, February 1999