Prima::Outlines - tree view widgets |
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
.
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:
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.
Reference to a child node. undef
if there is none.
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 the Prima::StringOutline manpage and the Prima::Outline manpage.
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 the Prima::IntUtils manpage for these.
The class is not usable directly.
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
Default value: 1
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
Default value: 12
Default value: default font height
Default value: []
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
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.
See also: makehint.
Default value: 1
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.
undef
, the root node is assumed. If LENGTH
is undef
, all items after OFFSET are deleted.
Only for multi-select mode.
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.
-1, undef
is returned.
Stringify
notification.
MeasureItem
notification, stored
under index #3 in node.
Stringify
notification.
MeasureItem
notification, stored
under index #3 in node.
undef
, the root node
is assumed. If the tree is large, the execution can take
significant amount of time.
undef
, the root node is assumed.
ACTION subroutine is called with the following parameters:
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
.
When iterate
is called with FULL = 1
, the index is always the same
as node index
.
The method can address the item either directly ( ITEM ) or by its INDEX in the screen position.
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.
Prima::Widget::height
.
If the value is known, passing it to point2item
thus achieves
some speed-up.
Only for multi-select mode.
The method can address the item either directly ( ITEM ) or by its INDEX in the screen position. Only for multi-select mode.
The method can address the item either directly ( ITEM ) or by its INDEX in the screen position. Only for multi-select mode.
The method can address the item either directly ( ITEM ) or by its INDEX in the screen position. Only for multi-select mode.
The method can address the item either directly ( ITEM ) or by its INDEX in the screen position. Only for multi-select mode.
get_item
for the reference. This notification
must be called from within begin_paint_info/end_paint_info
block.
get_item
for the speed reasons, and
the received should call this function. The SELECTED flag contains
the new value of the item.
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 ).
The format of a node is defined as follows:
closedIcon
property.
Default value: 1
openedIcon
property.
Default value: 1
Default value: 0
Prima::Utils::getdir
( see getdir in the Prima::Utils manpage ).
showDotDirs
property value is 0,
the dot-prefixed names are not included.
Used internally inside Expand
notification.
Dmitry Karasik, <dmitry@karasik.eu.org>.
Prima, the Prima::Widget manpage, the Prima::IntUtils manpage, <examples/outline.pl>.
Prima::Outlines - tree view widgets |