Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Prima::PodView(3)     User Contributed Perl Documentation    Prima::PodView(3)

       Prima::PodView -	POD browser widget

	       use Prima qw(Application	PodView);

	       my $window = Prima::MainWindow->	create;
	       my $podview = $window-> insert( 'Prima::PodView',
		       pack => { fill => 'both', expand	=> 1 }
	       $podview-> open_read;
	       $podview-> read("=head1 NAME\n\nI'm also	a pod!\n\n");
	       $podview-> close_read;

	       run Prima;

       Prima::PodView contains a formatter ( in	terms of perlpod ) and viewer
       of POD content. It heavily employs its ascendant	class Prima::TextView,
       and is in turn base for the toolkit's default help viewer

       The package consists of the several logically separated parts. These
       include file locating and loading, formatting and navigation.

   Content methods
       The basic access	to the content is not bound to the file	system.	The
       POD content can be supplied without any file to the viewer. Indeed, the
       file loading routine "load_file"	is a mere wrapper to the content
       loading functions:

       open_read %OPTIONS
	   Clears the current content and enters the reading mode. In this
	   mode	the content can	be appended by calling read that pushes	the
	   raw POD content to the parser.

       read TEXT
	   Supplies TEXT string	to the parser. Manages basic indentation, but
	   the main formatting is performed inside add and add_formatted

	   Must	be called only within open_read/close_read brackets

       add TEXT, STYLE,	INDENT
	   Formats TEXT	string of a given STYLE	( one of "STYLE_XXX"
	   constants) with INDENT space.

	   Must	be called only within open_read/close_read brackets.

       add_formatted FORMAT, TEXT
	   Adds	a pre-formatted	TEXT with a given FORMAT, supplied by "=begin"
	   or "=for" POD directives. Prima::PodView understands	'text' and
	   'podview' FORMATs; the latter format	is for Prima::PodView itself
	   and contains	small number of	commands, aimed	at inclusion of	images
	   into	the document.

	   The 'podview' commands are:

	   cut Example:

		       =for podview <cut>

		       =for text just text-formatter info

			       text-only info

		       =for podview </cut>

	       The <cut<gt> clause skips all POD input until cancelled.	 It is
	       used in conjunction with	the following command, img, to allow a
	       POD manpage provide both	graphic	('podview', 'html', etc	) and
	       text ( 'text' ) content.

	   img [src="SRC"] [width="WIDTH"] [height="HEIGHT"] [cut="CUT"]
	       An image	inclusion command, where src is	a relative or an
	       absolute	path to	an image file. In case if scaling is required,
	       "width" and "height" options can	be set.	When the image is a
	       multiframe image, the frame index can be	set by "frame" option.
	       Special "cut" option, if	set to a true value, activates the cut
	       behavior	if ( and only if ) the image load operation was
	       unsuccessful.  This makes possible simultaneous use of
	       'podview' and 'text' :

		       =for podview <img src="graphic.gif" cut=1 >

		       =begin text

		       y     .
		       |  .
		       +----- x

		       =end text

		       =for podview </cut>

	       In the example above 'graphic.gif' will be shown	if it can be
	       found and loaded, otherwise the poor-man-drawings would be

	       If "src"	is omitted, image is retrieved from "images" array,
	       from the	index "frame".

	   Closes the reading mode and starts the text rendering by calling
	   "format".  Returns "undef" if there is no POD context, 1 otherwise.

       The rendering is	started	by "format" call, which	returns	( almost )
       immediately, initiating the mechanism of	delayed	rendering, which is
       often time-consuming.  "format"'s only parameter	KEEP_OFFSET is a
       boolean flag, which, if set to 1, remembers the current location	on a
       page, and when the rendered text	approaches the location, scrolls the
       document	automatically.

       The rendering is	based an a document model, generated by
       open_read/close_read session.  The model	is a set of same text blocks
       defined by Prima::TextView, except that the header length is only three

	       M_INDENT	      -	the block X-axis indent
	       M_TEXT_OFFSET  -	same as	BLK_TEXT_OFFSET
	       M_FONT_ID      -	0 or 1,	because	PodView's fontPalette contains only two	fonts -
				variable ( 0 ) and fixed ( 1 ).

       The actual rendering is performed in "format_chunks", where model
       blocks are transformed to the full text blocks, wrapped and pushed into
       TextView-provided storage. In parallel, links and the corresponding
       event rectangles	are calculated on this stage.

       Prima::PodView provides the "::topicView" property, which governs
       whether the man page is viewed by topics	or as a	whole. When it is
       viewed as topics, "{modelRange}"	array selects the model	blocks that
       include the topic.  Thus, having	a single model loaded, text blocks
       change dynamically.

       Topics contained	in "{topics}" array, each is an	array with indices of
       "T_XXX" constants:

	       T_MODEL_START - beginning of topic
	       T_MODEL_END   - length of a topic
	       T_DESCRIPTION - topic name
	       T_STYLE	     - STYLE_XXX constant
	       T_ITEM_DEPTH  - depth of	=item recursion
	       T_LINK_OFFSET - offset in links array, started in the topic

       "::styles" property provides access to the styles, applied to different
       pod text	parts. These styles are:

	       STYLE_CODE     -	style for C<>
	       STYLE_TEXT     -	normal text
	       STYLE_HEAD_1   -	=head1
	       STYLE_HEAD_2   -	=head2
	       STYLE_HEAD_3   -	=head3
	       STYLE_HEAD_4   -	=head4
	       STYLE_ITEM     -	=item
	       STYLE_LINK     -	style for L<> text
	       STYLE_VERBATIM -	style for pre-formatted	text

       Each style is a hash with the following keys: "fontId", "fontSize",
       "fontStyle", "color", "backColor", fully	analogous to the
       tb::BLK_DATA_XXX	options.  This functionality provides another layer of
       accessibility to	the pod	formatter.

       In addition to styles, Prima::PodView defined "colormap"	entries	for


       The default colors in the styles	are mapped into	these entries.

   Link	and navigation methods
       Prima::PodView provides a hand-icon mouse pointer highlight for the
       link entries and	as an interactive part,	the link documents or topics
       are loaded when the user	presses	the mouse button on the	link. The
       mechanics below that is as follows. "{contents}"	of event rectangles, (
       see Prima::TextView ) is	responsible for	distinguishing whether a mouse
       is inside a link	or not.	 When the link is activated, "link_click" is
       called, which, in turn, calls "load_link" method. If the	page is	loaded
       successfully, depending on "::topicView"	property value,	either
       "select_topic" or "select_text_offset" method is	called.

       The family of file and link access functions consists of	the following

       load_file MANPAGE
	   Loads a manpage, if it can be found in the PATH or perl
	   installation	directories.  If unsuccessful, displays	an error.

       load_link LINK
	   LINK	is a text in format of perlpod "L<>" link: "manpage/section".
	   Loads the manpage, if necessary, and	selects	the section.

       load_bookmark BOOKMARK
	   Loads a bookmark string, prepared by	make_bookmark function.	 Used

       load_content CONTENT
	   Loads content into the viewer. Returns "undef" is there is no POD
	   context, 1 otherwise.

       make_bookmark [ WHERE ]
	   Combines the	information about the currently	viewing	manpage, topic
	   and text offset into	a storable string. WHERE, an optional string
	   parameter, can be either omitted, in	such case the current settings
	   are used, or	be one of 'up',	'next' or 'prev' strings.

	   The 'up' string returns a bookmark to the upper level of the

	   The 'next' and 'prev' return	a bookmark to the next or the previous
	   topics in a manpage.

	   If the location cannot be stored or defined,	"undef"	is returned.

       Bookmark	BOOKMARK
	   When	a new topic is navigated to by the user, this event is
	   triggered with the current topic to have it eventually stored in
	   bookmarks or	history.

       Link LINK_REF, BUTTON, MOD, X, Y
	   When	the user clicks	on a link, this	event is called	with the link
	   address, mouse button, modificator keys, and	coordinates.

	   Called after	new content is loaded

perl v5.32.1			  2021-08-26		     Prima::PodView(3)


Want to link to this manual page? Use this URL:

home | help