Prima::Outlines - tree view widgets
use Prima::Outlines; my $outline = Prima::StringOutline-> create( items => [ [ 'Simple item' ], [[ 'Embedded item ']], [[ 'More embedded items', [ '#1', '#2' ]]], ], ); $outline-> expand_all;
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
Prima::StringOutline
Prima::Outline
Prima::DirectoryOutline
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:
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.
items
Reference to a child node. undef if there is none.
undef
A boolean flag, which selects if the node shown as expanded, e.g. all its immediate children are visible.
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.
DrawItem
MeasureItem
Stringify
draw_items
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.
Prima::GroupScroller
Prima::MouseScroller
The class is not usable directly.
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.
itemHeight
Default value: 1
If 1, allows the items to be dragged interactively by pressing control key together with left mouse button. If 0, item dragging is disabled.
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.
multiSelect
Shift
Control
Default value: 0
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.
Width in pixels of the indent between item levels.
Default value: 12
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
Provides access to the items as an anonymous array. The format of items is described in the opening article ( see Prima::OutlineViewer ).
Default value: []
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.
focusedItem
selectedItems
Horizontal offset of an item list in pixels.
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.
select_item
unselect_item
toggle_item
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.
Selects the first item drawn.
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.
Performs expansion ( 1 ) or collapse ( 0 ) of INDEXth item, depending on EXPAND boolean flag value.
Recalculates the node tree and the item dimensions. Used internally.
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.
Deletes NODE from the item list.
Removes selection from all items.
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.
Paint
This method is overridden in some descendant classes, to increase the speed of the drawing routine.
See DrawItem for PAINT_DATA parameters description.
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.
-1, undef
Returns text string assigned to INDEXth item. Since the class does not assume the item storage organization, the text is queried via Stringify notification.
Returns width in pixels of INDEXth item, which is a cached result of MeasureItem notification, stored under index #3 in node.
Returns two scalars corresponding to INDEXth item: node reference and its depth level. If INDEX is outside the list boundaries, empty array is returned.
Returns two scalars, corresponding to NODE: its parent node reference and offset of NODE in the parent's immediate children list.
Returns text string assigned to NODE. Since the class does not assume the item storage organization, the text is queried via Stringify notification.
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.
Inserts one or more ITEMS under NODE with OFFSET. If NODE is undef, the root node is assumed.
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:
Node reference
Parent node reference; if undef, the node is the root.
Node offset in parent item list.
Node index.
Node depth level. 0 means the root node.
A boolean flag, set to 1 if the node is the last child in parent node list, set to 0 otherwise.
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.
iterate
FULL = 1
When iterate is called with FULL = 1, the index is always the same as node index.
node index
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.
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.
showItemHint
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.
Prima::Widget::height
point2item
Selects all items.
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.
Selects an item.
Toggles selection of an item.
Deselects an item.
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.
Called when NODE is expanded ( 1 ) or collapsed ( 0 ). The EXPAND boolean flag reflects the action taken.
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.
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 and FOCUSED boolean flags are set to 1 if the item is selected or focused, respectively; 0 otherwise.
Puts width of NODE item in pixels into REF scalar reference. This notification must be called from within begin_paint_info/end_paint_info block.
begin_paint_info/end_paint_info
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.
get_item
Puts text string, assigned to NODE item into TEXT_REF scalar reference.
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' ]]);
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.
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, os2 ).
The format of a node is defined as follows:
Directory name, string.
Parent path; an empty string for the root items.
Icon width in pixels, integer.
Drive icon; defined only for the root items under non-unix hosts in order to reflect the drive type ( hard, floppy, etc ).
Number of horizontal equal-width images, contained in closedIcon property.
closedIcon
Provides an icon representation for the collapsed items.
Number of horizontal equal-width images, contained in openedIcon property.
openedIcon
Provides an icon representation for the expanded items.
Runtime-only property. Selects current file system path.
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 and os2.
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 ).
Prima::Utils::getdir
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.
showDotDirs
Used internally inside Expand notification.
Expand
Dmitry Karasik, <dmitry@karasik.eu.org>.
Prima, Prima::Widget, Prima::IntUtils, <examples/outline.pl>.
12 POD Errors
The following errors were encountered while parsing the POD:
Expected text after =item, not a number
To install Prima, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Prima
CPAN shell
perl -MCPAN -e shell install Prima
For more information on module installation, please visit the detailed CPAN module installation guide.