Provided by: libprima-perl_1.28-1.2_amd64 
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
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.
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, os2 ).
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 and os2.
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>.