Kevin Ryde > Wx-Perl-PodBrowser > Wx::Perl::PodRichText

Download:
Wx-Perl-PodBrowser-14.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

Open  0
View/Report Bugs
Module Version: 14   Source  

NAME ^

Wx::Perl::PodRichText -- POD in a RichTextCtrl

SYNOPSIS ^

 use Wx::Perl::PodRichText;
 my $podtextwidget = Wx::Perl::PodRichText->new;
 $podtextwidget->goto_pod (module => 'Foo::Bar');

CLASS HIERARCHY ^

Wx::Perl::PodBrowser is a subclass of Wx::RichTextCtrl.

    Wx::Object
      Wx::EvtHandler
        Wx::Validator
          Wx::Control
            Wx::TextCtrlBase
              Wx::RichTextCtrl
                 Wx::Perl::PodRichText

DESCRIPTION ^

Wx::Perl::PodBrowser is a Wx::RichTextCtrl subclass for read-only display of formatted POD documents. The POD can be from .pod or .pm files or parsed from a string or file handle.

See Wx::Perl::PodBrowser for a whole toplevel browser window.

Details

The initial widget SetSize() is a sensible size for POD, currently about 80 columns by 30 lines of the default font. A parent widget can make it bigger or smaller as desired.

The POD to text conversion tries to use RichText features.

The display is reckoned as text so POD =begin text sections are included in the display. Other =begin types are ignored.

Reading a large POD file is slow. The work is done piece-wise from the event loop to keep the rest of the application running, but expect noticeable lag.

FUNCTIONS ^

$podtextwidget = Wx::Perl::PodRichText->new($parent)
$podtextwidget = Wx::Perl::PodRichText->new($parent,$id)

Create and return a new PodRichText widget in $parent. If $id is not given then wxID_ANY is used to have wxWidgets choose an ID number.

$podtextwidget->goto_pod (key => value, ...)

Go to a specified POD module, filename, section etc. The key/value options are

    module     => $str      module etc in @INC
    filename   => $str      file name
    filehandle => $fh
    string     => $str      POD marked-up text
    guess      => $str      module or filename

    section     => $string
    line        => $integer     line number
    heading_num => $n           heading number

The target POD document is given by one of module, filename, etc. module is sought with Pod::Find in the usual @INC path. string is POD in a string.

    $podtextwidget->goto_pod (module => "perlpodspec");

guess tries a module or filename. It's intended for command line or similar loose input to let the user enter either module or filename.

Optional section, line or heading_num is a position within the document. They can be given alone to move in the currently displayed document.

    # move within current display
    $podtextwidget->goto_pod (section => "DESCRIPTION");

section is a heading per =head or a item per =item. The first word from an =item works too, as is common for the POD formatters and helps cross-references to perlfunc and similar.

heading_num goes to a heading numbered consecutively starting from 0 for the first =head, as per the get_heading_list(). Going by number ensures any heading can be reached even when names might be duplicated.

$podtextwidget->reload ()

Re-read the current module or filename source.

$bool = $podtextwidget->can_reload ()

Return true if the current POD is from a module or filename source and therefore suitable for a reload().

Content Methods

POD is parsed progressively under a timer and the following methods return information only on as much as parsed so far.

@strings = $podtextwidget->get_heading_list ()

Return a list of the =head headings in the displayed document.

$charpos = $podtextwidget->get_section_position ($section)

Return the character position of $section. The position is per SetInsertionPoint() etc so 0 is the start of the document. $section is a heading or item as described above for the section option of goto_pod(). If there is no such $section then return undef.

BUGS ^

As of wxWidgets circa 2.8.12 calling new() without a $parent segfaults. This is the same as Wx::RichTextCtrl->new() called without a parent. Is it good enough to let Wx::RichTextCtrl->new() do any necessary undef argument checking?

SEE ALSO ^

Wx, Wx::Perl::PodBrowser, Pod::Find

HOME PAGE ^

http://user42.tuxfamily.org/wx-perl-podbrowser/index.html

LICENSE ^

Copyright 2012, 2013 Kevin Ryde

Wx-Perl-PodBrowser is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Wx-Perl-PodBrowser is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Wx-Perl-PodBrowser. If not, see http://www.gnu.org/licenses/.

syntax highlighting: