/ 
Wx-Perl-PodBrowser-6
River stage zero No dependents
/ Wx::Perl::PodRichText

NAME

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

SYNOPSIS

use Wx::Perl::PodRichText;
my $podtext = Wx::Perl::PodRichText->new;
$podtext->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

This is a Wx::RichTextCtrl displaying formatted POD documents either from .pod or .pm files or parsed from a string or file handle.

See Wx::Perl::PodBrowser for a whole 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 the left indent feature so text paragraphs flow nicely within =over etc.

  • =item bullet points use the RichText bullet paragraphs, and numbered =item use numbered paragraphs likewise. In Wx circa 2.8.12 big numbers seem to display with the text overlapping, but that would be a Wx matter, and for small numbers it's fine.

  • Verbatim paragraphs are done in wxFONTFAMILY_TELETYPE and wxRichTextLineBreakChar for each newline. 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 target.

    The current code has an EVT_TEXT_URL() handler following to target POD and 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 text is done with latin-1 0xA0 non-breaking spaces. RichText obeys them when word wrapping.

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

$podtext = Wx::Perl::PodRichText->new($parent)
$podtext = 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 let wxWidgets choose an ID number.

$podtext->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
guess      => $str

section  => $string
line     => $integer     line number

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

$podtext->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 or line is a position within the document. They can be given alone to move in the currently displayed document.

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

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

$podtext->reload ()

Re-read the current module or filename source.

$bool = $podtext->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 give the part parsed so far.

@strings = $podtext->get_heading_list ()

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

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

Return the character position of $section, starting from 0 as per SetInsertionPoint() etc. $section is a heading or item as described above for section of goto_pod(). If there is no $section then return undef.

BUGS

Wx::wxTE_AUTO_URL is turned on attempting to pick up unlinked URLs, but it doesn't seem to have any effect circa Wx 2.8.12 under Gtk. Is that option only for the plain Wx::TextCtrl? Could search and linkize apparent URLs manually, though perhaps that's best left to L<> markup in the source POD anyway.

As of wxWidgets circa 2.8.12 if new() called without a $parent gets a segfault. 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 etc argument checking?

SEE ALSO

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

HOME PAGE

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

LICENSE

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