Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

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

A TextView widget with hyper links
https://github.com/rsrchboy/gtk2-ex-hypertextview

Last synced: 3 months ago
JSON representation

A TextView widget with hyper links

Awesome Lists containing this project

README 

        
=pod



=head1 NAME



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



=head1 VERSION



version 0.201



=head1 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;



=head1 DESCRIPTION



Gtk2::Ex::HyperTextView is a widget for rendering documents containing

hyperlinks. It is based on the L widget and provides a widget

that can be used by itself, or subclassed (e.g.

L.



Gtk2::Ex::HyperTextView widgets inherit all the methods and properties of

L widgets. Full information about text buffers can be found

in the Gtk+ documentation at

L.



=head1 OBJECT HIERARCHY



    L

    +--- L

         +--- L

              +--- L

                   +--- L

                        +--- L



=head1 CONSTRUCTOR



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



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



=head1 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 L 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 C. 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 C<$name>.



    $name = 'SYNOPSIS';



    $view->jump_to($name);



this scrolls the HyperTextView window to the selected mark.



    $viewer->load($document);



Loads a given document. C<$document> can be a perldoc name (eg., C<'perlvar'>), a module (eg. C<'IO::Scalar'>), a filename or the name of a Perl builtin function from L. Documents are searched for in that order, that is, the L document will be loaded before a file called C in the current directory.



=head1 DOCUMENT LOADERS



The C 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 C<$string> variable.



    $parser = $view->parser;



returns the C object used to render the POD data.



=head1 SIGNALS



Gtk2::Ex::HyperTextView inherits all of Gtk2::TextView's signals, and has the following:



=head2 The C<'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.



=head2 The C<'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.



=head2 The C<'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. 



=head1 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 L 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:



=over



=item C



Used to format bold text.



=item C



Used to format italic text.



=item C ... C



Used to format headers.



=item C



Used to format preformatted text.



=item C



Used to format inline preformatted text.



=item C



Used to format hyperlinks.



=back



=head1 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:



=over



=item *



When rendering long documents the UI freezes for too long.



=item *



Some strangeness with Unicode.



=back



=head1 PREREQUISITES



=over



=item *



L (obviously). The most recent version will be from L.



=item *



L



=item *



L



=item *



L



=back



L, which is part of the L distribution, also requires L.



=head1 SEE ALSO



=over



=item *



L or L



=item *



L



=item *



L,

L, L,

L.



=back



=head1 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



=head1 RATIONALE



This work is a "restatement" of the L package.  It's been

altered such that the link-aware subclass of L is contained in

its own base class (L_, such that Pod (and other)

viewers can in turn descend from the base class.



=head1 AUTHORS



This package is largely a restatement/realignment of the code and

documentation contained in the L 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.



=head1 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 ([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.



=head1 AUTHOR



Chris Weyl 



=head1 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