Wx::Perl::PodRichText -- POD in a RichTextCtrl
use Wx::Perl::PodRichText; my $podtextwidget = Wx::Perl::PodRichText->new; $podtextwidget->goto_pod (module => 'Foo::Bar');
Wx::Perl::PodBrowser is a subclass of
Wx::Object Wx::EvtHandler Wx::Validator Wx::Control Wx::TextCtrlBase Wx::RichTextCtrl Wx::Perl::PodRichText
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.
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.
=itembullet points are Text bullet paragraphs and numbered
=itemare 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.
wxRichTextLineBreakCharfor 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.
$podtextwidget = Wx::Perl::PodRichText->new($parent)
$podtextwidget = Wx::Perl::PodRichText->new($parent,$id)
Create and return a new PodRichText widget in
$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 is sought with Pod::Find in the usual
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.
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.
Re-read the current
$bool = $podtextwidget->can_reload ()
Return true if the current POD is from a
filename source and therefore suitable for a
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
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?
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/.