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>.