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

FreeBSD Manual Pages

  
 
  

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

NAME
       Prima::Outlines - tree view widgets

SYNOPSIS
	       use Prima::Outlines;

	       my $outline = Prima::StringOutline-> create(
		       items =>	[
			       [  'Simple item'	],
			       [[ 'Embedded item ']],
			       [[ 'More	embedded items', [ '#1', '#2' ]]],
		       ],
	       );
	       $outline-> expand_all;

DESCRIPTION
       The module provides a set of widget classes, designed to	display	a
       tree-like hierarchy of items. "Prima::OutlineViewer" presents a generic
       class that contains basic functionality and defines the interface for
       the descendants,	which are "Prima::StringOutline", "Prima::Outline",
       and "Prima::DirectoryOutline".

Prima::OutlineViewer
       Presents	a generic interface for	browsing the tree-like lists.  A node
       in a linked list	represents each	item.  The format of node is
       predefined, and is an anonymous array with the following	definitions of
       indices:

       #0  Item	id with	non-defined format. The	simplest implementation,
	   "Prima::StringOutline", treats the scalar as	a text string. The
	   more	complex	classes	store references to arrays or hashes here. See
	   "items" article of a	concrete class for the format of a node
	   record.

       #1  Reference to	a child	node. "undef" if there is none.

       #2  A boolean flag, which selects if the	node shown as expanded,	e.g.
	   all its immediate children are visible.

       #3  Width of an item in pixels.

       The indices above 3 should not be used, because eventual	changes	to the
       implementation of the class may use these. It should be enough item 0
       to store	any value.

       To support a custom format of node, it is sufficient to overload	the
       following notifications:	"DrawItem", "MeasureItem", "Stringify".	Since
       "DrawItem" is called for	every item, a gross method "draw_items"	can be
       overloaded instead.  See	also Prima::StringOutline and Prima::Outline.

       The class employs two addressing	methods, index-wise and	item-wise. The
       index-wise counts only the visible ( non-expanded ) items, and is
       represented by an integer index.	 The item-wise addressing cannot be
       expressed by an integer index, and the full node	structure is used as a
       reference. It is	important to use a valid reference here, since the
       class does not always perform the check if the node belongs to internal
       node list due to	the speed reasons.

       "Prima::OutlineViewer" is a descendant of "Prima::GroupScroller"	and
       "Prima::MouseScroller", so some properties and methods are not
       described here. See Prima::IntUtils for these.

       The class is not	usable directly.

   Properties
       autoHeight INTEGER
	   If set to 1,	changes	"itemHeight" automatically according to	the
	   widget font height.	If 0, does not influence anything.  When
	   "itemHeight"	is set explicitly, changes value to 0.

	   Default value: 1

       dragable	BOOLEAN
	   If 1, allows	the items to be	dragged	interactively by pressing
	   control key together	with left mouse	button.	If 0, item dragging is
	   disabled.

	   Default value: 1

       extendedSelect BOOLEAN
	   Regards the way the user selects multiple items and is only actual
	   when	"multiSelect" is 1. If 0, the user must	click each item	in
	   order to mark as selected. If 1, the	user can drag mouse or use
	   "Shift" key plus arrow keys to perform range	selection; the
	   "Control" key can be	used to	select individual items.

	   Default value: 0

       focusedItem INTEGER
	   Selects the focused item index. If -1, no item is focused.  It is
	   mostly a run-time property, however,	it can be set during the
	   widget creation stage given that the	item list is accessible	on
	   this	stage as well.

       indent INTEGER
	   Width in pixels of the indent between item levels.

	   Default value: 12

       itemHeight INTEGER
	   Selects the height of the items in pixels. Since the	outline
	   classes do not support items	with different vertical	dimensions,
	   changes to this property affect all items.

	   Default value: default font height

       items ARRAY
	   Provides access to the items	as an anonymous	array. The format of
	   items is described in the opening article ( see
	   Prima::OutlineViewer	).

	   Default value: []

       multiSelect BOOLEAN
	   If 0, the user can only select one item, and	it is reported by the
	   "focusedItem" property. If 1, the user can select more than one
	   item.  In this case,	"focusedItem"'th item is not necessarily
	   selected.  To access	selected item list, use	"selectedItems"
	   property.

	   Default value: 0

       offset INTEGER
	   Horizontal offset of	an item	list in	pixels.

       selectedItems ARRAY
	   ARRAY is an array of	integer	indices	of selected items. Note, that
	   these are the items visible on the screen only. The property
	   doesn't handle the selection	status of the collapsed	items.

	   The widget keeps the	selection status on each node, visible and
	   invisible ( e.g. the	node is	invisible if its parent	node is
	   collapsed). However,	"selectedItems"	accounts for the visible nodes
	   only; to manipulate the node	status or both visible and invisible
	   nodes, use "select_item", "unselect_item", "toggle_item" methods.

       showItemHint BOOLEAN
	   If 1, allows	activation of a	hint label when	the mouse pointer is
	   hovered above an item that does not fit horizontally	into the
	   widget inferiors. If	0, the hint is never shown.

	   See also: makehint.

	   Default value: 1

       topItem INTEGER
	   Selects the first item drawn.

   Methods
       add_selection ARRAY, FLAG
	   Sets	item indices from ARRAY	in selected or deselected state,
	   depending on	FLAG value, correspondingly 1 or 0.

	   Note, that these are	the items visible on the screen	only. The
	   method doesn't handle the selection status of the collapsed items.

	   Only	for multi-select mode.

       adjust INDEX, EXPAND
	   Performs expansion (	1 ) or collapse	( 0 ) of INDEXth item,
	   depending on	EXPAND boolean flag value.

       calibrate
	   Recalculates	the node tree and the item dimensions.	Used
	   internally.

       delete_items [ NODE = undef, OFFSET = 0,	LENGTH = undef ]
	   Deletes LENGTH children items of NODE at OFFSET.  If	NODE is
	   "undef", the	root node is assumed. If LENGTH	is "undef", all	items
	   after OFFSET	are deleted.

       delete_item NODE
	   Deletes NODE	from the item list.

       deselect_all
	   Removes selection from all items.

	   Only	for multi-select mode.

       draw_items CANVAS, PAINT_DATA
	   Called from within "Paint" notification to draw items. The default
	   behavior is to call "DrawItem" notification for every visible item.
	   PAINT_DATA is an array of arrays, where each	array consists of
	   parameters, passed to "DrawItem" notification.

	   This	method is overridden in	some descendant	classes, to increase
	   the speed of	the drawing routine.

	   See DrawItem	for PAINT_DATA parameters description.

       get_index NODE
	   Traverses all items for NODE	and finds if it	is visible.  If	it is,
	   returns two integers: the first is item index and the second	is
	   item	depth level. If	it is not visible, "-1,	undef" is returned.

       get_index_text INDEX
	   Returns text	string assigned	to INDEXth item.  Since	the class does
	   not assume the item storage organization, the text is queried via
	   "Stringify" notification.

       get_index_width INDEX
	   Returns width in pixels of INDEXth item, which is a cached result
	   of "MeasureItem" notification, stored under index #3	in node.

       get_item	INDEX
	   Returns two scalars corresponding to	INDEXth	item: node reference
	   and its depth level.	If INDEX is outside the	list boundaries, empty
	   array is returned.

       get_item_parent NODE
	   Returns two scalars,	corresponding to NODE: its parent node
	   reference and offset	of NODE	in the parent's	immediate children
	   list.

       get_item_text NODE
	   Returns text	string assigned	to NODE.  Since	the class does not
	   assume the item storage organization, the text is queried via
	   "Stringify" notification.

       get_item_width NODE
	   Returns width in pixels of INDEXth item, which is a cached result
	   of "MeasureItem" notification, stored under index #3	in node.

       expand_all [ NODE = undef ].
	   Expands all nodes under NODE. If NODE is "undef", the root node is
	   assumed. If the tree	is large, the execution	can take significant
	   amount of time.

       insert_items NODE, OFFSET, @ITEMS
	   Inserts one or more ITEMS under NODE	with OFFSET.  If NODE is
	   "undef", the	root node is assumed.

       iterate ACTION, FULL
	   Traverses the item tree and calls ACTION subroutine for each	node.
	   If FULL boolean flag	is 1, all nodes	are traversed. If 0, only the
	   expanded nodes are traversed.

	   ACTION subroutine is	called with the	following parameters:

	   #0  Node reference

	   #1  Parent node reference; if "undef", the node is the root.

	   #2  Node offset in parent item list.

	   #3  Node index.

	   #4  Node depth level. 0 means the root node.

	   #5  A boolean flag, set to 1	if the node is the last	child in
	       parent node list, set to	0 otherwise.

	   #6  Visibility index. When "iterate"	is called with "FULL = 1", the
	       index is	the item index as seen of the screen. If the item is
	       not visible, the	index is "undef".

	       When "iterate" is called	with "FULL = 1", the index is always
	       the same	as "node index".

       is_selected INDEX, ITEM
	   Returns 1 if	an item	is selected, 0 if it is	not.

	   The method can address the item either directly ( ITEM ) or by its
	   INDEX in the	screen position.

       makehint	SHOW, INDEX
	   Controls hint label upon INDEXth item. If a boolean flag SHOW is
	   set to 1, and "showItemHint"	property is 1, and the item index does
	   not fit horizontally	in the widget inferiors	then the hint label is
	   shown.  By default the label	is removed automatically as the	user
	   moves the mouse pointer away	from the item. If SHOW is set to 0,
	   the hint label is hidden immediately.

       point2item Y, [ HEIGHT ]
	   Returns index of an item that contains horizontal axis at Y in the
	   widget coordinates.	If HEIGHT is specified,	it must	be the widget
	   height; if it is not, the value is fetched by calling
	   "Prima::Widget::height".  If	the value is known, passing it to
	   "point2item"	thus achieves some speed-up.

       select_all
	   Selects all items.

	   Only	for multi-select mode.

       set_item_selected INDEX,	ITEM, FLAG
	   Sets	selection flag of an item.  If FLAG is 1, the item is
	   selected. If	0, it is deselected.

	   The method can address the item either directly ( ITEM ) or by its
	   INDEX in the	screen position. Only for multi-select mode.

       select_item INDEX, ITEM
	   Selects an item.

	   The method can address the item either directly ( ITEM ) or by its
	   INDEX in the	screen position. Only for multi-select mode.

       toggle_item INDEX, ITEM
	   Toggles selection of	an item.

	   The method can address the item either directly ( ITEM ) or by its
	   INDEX in the	screen position. Only for multi-select mode.

       unselect_item INDEX, ITEM
	   Deselects an	item.

	   The method can address the item either directly ( ITEM ) or by its
	   INDEX in the	screen position. Only for multi-select mode.

       validate_items ITEMS
	   Traverses the array of ITEMS	and puts every node to the common
	   format: cuts	scalars	above index #3,	if there are any, or adds
	   default values to a node if it contains less	than 3 scalars.

   Events
       Expand NODE, EXPAND
	   Called when NODE is expanded	( 1 ) or collapsed ( 0 ).  The EXPAND
	   boolean flag	reflects the action taken.

       DragItem	OLD_INDEX, NEW_INDEX
	   Called when the user	finishes the drag of an	item from OLD_INDEX to
	   NEW_INDEX position. The default action rearranges the item list in
	   accord with the dragging action.

       DrawItem	CANVAS,	NODE, X1, Y1, X2, Y2, INDEX, SELECTED, FOCUSED,
       PRELIGHT
	   Called when INDEXth item, contained in NODE is to be	drawn on
	   CANVAS. X1, Y1, X2, Y2 coordinated define the exterior rectangle of
	   the item in widget coordinates. SELECTED, FOCUSED, and PRELIGHT
	   boolean flags are set to 1 if the item is selected, focused,	or
	   pre-lighted,	respectively; 0	otherwise.

       MeasureItem NODE, LEVEL,	REF
	   Puts	width of NODE item in pixels into REF scalar reference.	LEVEL
	   is the node depth as	returned by "get_item" for the reference. This
	   notification	must be	called from within
	   "begin_paint_info/end_paint_info" block.

       SelectItem [[INDEX, ITEM, SELECTED], [INDEX, ITEM, SELECTED], ...]
	   Called when an item gets selected or	deselected. The	array passed
	   contains set	of arrays for each items, where	the item can be
	   defined either as integer INDEX, or directly	as ITEM, or both.  In
	   case	INDEX is undef,	the item is invisible; if ITEM is undef, then
	   the caller didn't bother to call "get_item" for the speed reasons,
	   and the received should call	this function. The SELECTED flag
	   contains the	new value of the item.

       Stringify NODE, TEXT_REF
	   Puts	text string, assigned to NODE item into	TEXT_REF scalar
	   reference.

Prima::StringOutline
       Descendant of "Prima::OutlineViewer" class, provides standard single-
       text items widget. The items can	be set by merely supplying a text as
       the first scalar	in node	array structure:

       $string_outline-> items([ 'String', [ 'Descendant' ]]);

Prima::Outline
       A variant of "Prima::StringOutline", with the only difference that the
       text is stored not in the first scalar in a node	but as a first scalar
       in an anonymous array, which in turn is the first node scalar. The
       class does not define neither format nor	the amount of scalars in the
       array, and as such presents a half-abstract class.

Prima::DirectoryOutline
       Provides	a standard widget with the item	tree mapped to the directory
       structure, so each item is mapped to a directory. Depending on the type
       of the host OS, there is	either single root directory ( unix ), or one
       or more disk drive root items ( win32 ).

       The format of a node is defined as follows:

       #0  Directory name, string.

       #1  Parent path;	an empty string	for the	root items.

       #2  Icon	width in pixels, integer.

       #3  Drive icon; defined only for	the root items under non-unix hosts in
	   order to reflect the	drive type ( hard, floppy, etc ).

   Properties
       closedGlyphs INTEGER
	   Number of horizontal	equal-width images, contained in "closedIcon"
	   property.

	   Default value: 1

       closedIcon ICON
	   Provides an icon representation for the collapsed items.

       openedGlyphs INTEGER
	   Number of horizontal	equal-width images, contained in "openedIcon"
	   property.

	   Default value: 1

       openedIcon OBJECT
	   Provides an icon representation for the expanded items.

       path STRING
	   Runtime-only	property. Selects current file system path.

       showDotDirs BOOLEAN
	   Selects if the directories with the first dot character are shown
	   the tree view. The treatment	of the dot-prefixed names as hidden is
	   traditional to unix,	and is of doubtful use under win32.

	   Default value: 0

   Methods
       files [ FILE_TYPE ]
	   If FILE_TYPE	value is not specified,	the list of all	files in the
	   current directory is	returned. If FILE_TYPE is given, only the
	   files of the	types are returned. The	FILE_TYPE is a string, one of
	   those returned by "Prima::Utils::getdir" ( see "getdir" in
	   Prima::Utils	).

       get_directory_tree PATH
	   Reads the file structure under PATH and returns a newly created
	   hierarchy structure in the class node format. If "showDotDirs"
	   property value is 0,	the dot-prefixed names are not included.

	   Used	internally inside "Expand" notification.

AUTHOR
       Dmitry Karasik, <dmitry@karasik.eu.org>.

SEE ALSO
       Prima, Prima::Widget, Prima::IntUtils, <examples/outline.pl>.

perl v5.24.1			  2017-02-28		    Prima::Outlines(3)

NAME | SYNOPSIS | DESCRIPTION | Prima::OutlineViewer | Prima::StringOutline | Prima::Outline | Prima::DirectoryOutline | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Prima::Outlines&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help