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::RichTextCtrl.
Wx::Perl::PodBrowser
Wx::RichTextCtrl
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 file handle or a string.
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.
SetSize()
The POD to text conversion tries to use RichText features.
Indentation uses left indent so text paragraphs flow within =over etc.
=over
=item bullet points are RichText bullet paragraphs. Numbered =item are RichText numbered paragraphs.
=item
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 problem and small numbers are not affected.
Verbatim paragraphs are in wxFONTFAMILY_TELETYPE and wxRichTextLineBreakChar for newline line breaks. Wraparound is avoided by a large negative right indent.
wxFONTFAMILY_TELETYPE
wxRichTextLineBreakChar
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 likewise with a pod:// pseudo-URL. Is pod: L a good idea? It won't be usable by anything else, but the attribute is a handy place to hold the link destination.
L<>
pod://
pod:
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.
EVT_TEXT_URL()
Wx::LaunchDefaultBrowser()
S<> non-breaking text uses 0xA0 non-breaking spaces to prevent word wrapping. But Wx will still break a non-breaking run which is wider than the widget width, rather than letting it disappear off the right edge.
S<>
The display is reckoned as text so POD =begin text sections are included in the display. Other =begin types are ignored. All =for are ignored.
=begin text
=begin
=for
Reading a large POD file is slow. The work is done piece-wise from the event loop so the rest of the application runs, 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 $parent. If $id is not given then wxID_ANY is used to have wxWidgets choose an ID number.
$parent
$id
wxID_ANY
$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.
module
filename
@INC
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.
guess
Optional section, line or heading_num is a position within the document. They can be given alone to move in the currently displayed document.
section
line
heading_num
# 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.
=head
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.
get_heading_list()
$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().
reload()
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.
Markup in the headings is not included in the return, just the plain text (with E<> escapes as characters, and S<> non-breaking spaces as 0xA0).
E<>
$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.
$section
SetInsertionPoint()
goto_pod()
undef
If there are multiple headings or items with the same name then the return is the first one of them.
As of wxWidgets circa 2.8.12 calling new() without a $parent causes 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 argument checking?
new()
Wx::RichTextCtrl->new()
Wx, Wx::Perl::PodBrowser, Pod::Find
http://user42.tuxfamily.org/wx-perl-podbrowser/index.html
Copyright 2012, 2013, 2014, 2017 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/.
To install Wx::Perl::PodBrowser, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Wx::Perl::PodBrowser
CPAN shell
perl -MCPAN -e shell install Wx::Perl::PodBrowser
For more information on module installation, please visit the detailed CPAN module installation guide.