Wx::Perl::PodRichText -- POD in a RichTextCtrl |
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::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 the Wx::Perl::PodBrowser manpage 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.
=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 inwxFONTFAMILY_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.
$podtextwidget = Wx::Perl::PodRichText->new($parent)
$podtextwidget = Wx::Perl::PodRichText->new($parent,$id)
$parent
. If $id
is not
given then wxID_ANY
is used to have wxWidgets choose an ID number.
$podtextwidget->goto_pod (key => value, ...)
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 the Pod::Find manpage 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 the perlfunc manpage 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 ()
module
or filename
source.
$bool = $podtextwidget->can_reload ()
module
or filename
source and
therefore suitable for a 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 ()
=head
headings in the displayed document.
$charpos = $podtextwidget->get_section_position ($section)
$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
.
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?
Wx, the Wx::Perl::PodBrowser manpage, the Pod::Find manpage
http://user42.tuxfamily.org/wx-perl-podbrowser/index.html
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/.
Wx::Perl::PodRichText -- POD in a RichTextCtrl |