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.

• Indentation is done with left indent so text paragraphs flow nicely within =over etc.

• =item bullet points are Text bullet paragraphs and numbered =item are numbered paragraphs.

  In Wx circa 2.8.12, numbered paragraphs with big numbers seem to display with the text overlapping the number, but that should be a Wx matter and small numbers are not affected.

• Verbatim paragraphs are in wxFONTFAMILY_TELETYPE and with wxRichTextLineBreakChar for newline line breaks. Wraparound is avoided by a large negative right indent.

  Alas there's no scroll bar or visual indication of more text off to the right, but avoiding wraparound helps tables and ascii art.

• L<> links to URLs are underlined and buttonized with the "URL" style. L<> links to POD similarly but using a pod:// pseudo-URL. Is a pod: URL a good idea? It won't be usable by anything else, but the attribute is a handy place to hold the link destination.

  The current code has an EVT_TEXT_URL() handler going to target POD, or Wx::LaunchDefaultBrowser() for URLs. But that might change, as it might be better to leave that to the browser parent if some applications wanted to display only a single POD.

• S<> non-breaking uses 0xA0 non-breaking spaces to prevent word wrapping. A non-breaking run wider than the widget width is broken rather than disappearing off the right though.

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

cpanm Wx::Perl::PodBrowser

perl -MCPAN -e shell
install Wx::Perl::PodBrowser