.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Prima::Outlines 3"
.TH Prima::Outlines 3 "2009-02-24" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Prima::Outlines \- tree view widgets
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&        use Prima::Outlines;
\&
\&        my $outline = Prima::StringOutline\-> create(
\&                items => [
\&                        [  \*(AqSimple item\*(Aq ],
\&                        [[ \*(AqEmbedded item \*(Aq]],
\&                        [[ \*(AqMore embedded items\*(Aq, [ \*(Aq#1\*(Aq, \*(Aq#2\*(Aq ]]],
\&                ],
\&        );
\&        $outline\-> expand_all;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The module provides a set of widget classes, designed to display a tree-like
hierarchy of items. \f(CW\*(C`Prima::OutlineViewer\*(C'\fR presents a generic class that
contains basic functionality and defines the interface for the descendants, which are
\&\f(CW\*(C`Prima::StringOutline\*(C'\fR, \f(CW\*(C`Prima::Outline\*(C'\fR, and \f(CW\*(C`Prima::DirectoryOutline\*(C'\fR.
.SH "Prima::OutlineViewer"
.IX Header "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:
.IP "0" 4
Item id with non-defined format. The simplest implementation, \f(CW\*(C`Prima::StringOutline\*(C'\fR, 
treats the scalar as a text string. The more complex classes store 
references to arrays or hashes here. See \f(CW\*(C`items\*(C'\fR article of a concrete class
for the format of a node record.
.IP "1" 4
.IX Item "1"
Reference to a child node. \f(CW\*(C`undef\*(C'\fR if there is none.
.IP "2" 4
.IX Item "2"
A boolean flag, which selects if the node shown as expanded, e.g.
all its immediate children are visible.
.IP "3" 4
.IX Item "3"
Width of an item in pixels.
.PP
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.
.PP
To support a custom format of node, it is sufficient to overload the following 
notifications: \f(CW\*(C`DrawItem\*(C'\fR, \f(CW\*(C`MeasureItem\*(C'\fR, \f(CW\*(C`Stringify\*(C'\fR. Since \f(CW\*(C`DrawItem\*(C'\fR is
called for every item, a gross method \f(CW\*(C`draw_items\*(C'\fR can be overloaded instead.
See also Prima::StringOutline and Prima::Outline.
.PP
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.
.PP
\&\f(CW\*(C`Prima::OutlineViewer\*(C'\fR is a descendant of \f(CW\*(C`Prima::GroupScroller\*(C'\fR and \f(CW\*(C`Prima::MouseScroller\*(C'\fR, 
so some properties and methods are not described here. See Prima::IntUtils for these.
.PP
The class is not usable directly.
.SS "Properties"
.IX Subsection "Properties"
.IP "autoHeight \s-1INTEGER\s0" 4
.IX Item "autoHeight INTEGER"
If set to 1, changes \f(CW\*(C`itemHeight\*(C'\fR automatically according to the widget font height.
If 0, does not influence anything.  When \f(CW\*(C`itemHeight\*(C'\fR is set explicitly, 
changes value to 0.
.Sp
Default value: 1
.IP "dragable \s-1BOOLEAN\s0" 4
.IX Item "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.
.Sp
Default value: 1
.IP "extendedSelect \s-1BOOLEAN\s0" 4
.IX Item "extendedSelect BOOLEAN"
Regards the way the user selects multiple items and is only actual
when \f(CW\*(C`multiSelect\*(C'\fR 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 \f(CW\*(C`Shift\*(C'\fR key plus arrow keys to perform range selection;
the \f(CW\*(C`Control\*(C'\fR key can be used to select individual items.
.Sp
Default value: 0
.IP "focusedItem \s-1INTEGER\s0" 4
.IX Item "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.
.IP "indent \s-1INTEGER\s0" 4
.IX Item "indent INTEGER"
Width in pixels of the indent between item levels.
.Sp
Default value: 12
.IP "itemHeight \s-1INTEGER\s0" 4
.IX Item "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.
.Sp
Default value: default font height
.IP "items \s-1ARRAY\s0" 4
.IX Item "items ARRAY"
Provides access to the items as an anonymous array. The format of items is
described in the opening article ( see Prima::OutlineViewer ).
.Sp
Default value: []
.IP "multiSelect \s-1BOOLEAN\s0" 4
.IX Item "multiSelect BOOLEAN"
If 0, the user can only select one item, and it is reported by
the \f(CW\*(C`focusedItem\*(C'\fR property. If 1, the user can select more than one item. 
In this case, \f(CW\*(C`focusedItem\*(C'\fR'th item is not necessarily selected.
To access selected item list, use \f(CW\*(C`selectedItems\*(C'\fR property.
.Sp
Default value: 0
.IP "offset \s-1INTEGER\s0" 4
.IX Item "offset INTEGER"
Horizontal offset of an item list in pixels.
.IP "selectedItems \s-1ARRAY\s0" 4
.IX Item "selectedItems ARRAY"
\&\s-1ARRAY\s0 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.
.Sp
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, \f(CW\*(C`selectedItems\*(C'\fR
accounts for the visible nodes only; to manipulate the node status or both visible
and invisible nodes, use \f(CW\*(C`select_item\*(C'\fR, \f(CW\*(C`unselect_item\*(C'\fR, \f(CW\*(C`toggle_item\*(C'\fR methods.
.IP "showItemHint \s-1BOOLEAN\s0" 4
.IX Item "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.
.Sp
See also: makehint.
.Sp
Default value: 1
.IP "topItem \s-1INTEGER\s0" 4
.IX Item "topItem INTEGER"
Selects the first item drawn.
.SS "Methods"
.IX Subsection "Methods"
.IP "add_selection \s-1ARRAY\s0, \s-1FLAG\s0" 4
.IX Item "add_selection ARRAY, FLAG"
Sets item indices from \s-1ARRAY\s0 in selected
or deselected state, depending on \s-1FLAG\s0 value, correspondingly 1 or 0.
.Sp
Note, that these are the items visible on the screen only. The method doesn't
handle the selection status of the collapsed items.
.Sp
Only for multi-select mode.
.IP "adjust \s-1INDEX\s0, \s-1EXPAND\s0" 4
.IX Item "adjust INDEX, EXPAND"
Performs expansion ( 1 ) or collapse ( 0 ) of INDEXth item, depending on \s-1EXPAND\s0
boolean flag value.
.IP "calibrate" 4
.IX Item "calibrate"
Recalculates the node tree and the item dimensions. 
Used internally.
.IP "delete_items [ \s-1NODE\s0 = undef, \s-1OFFSET\s0 = 0, \s-1LENGTH\s0 = undef ]" 4
.IX Item "delete_items [ NODE = undef, OFFSET = 0, LENGTH = undef ]"
Deletes \s-1LENGTH\s0 children items of \s-1NODE\s0 at \s-1OFFSET\s0. 
If \s-1NODE\s0 is \f(CW\*(C`undef\*(C'\fR, the root node is assumed. If \s-1LENGTH\s0 
is \f(CW\*(C`undef\*(C'\fR, all items after \s-1OFFSET\s0 are deleted.
.IP "delete_item \s-1NODE\s0" 4
.IX Item "delete_item NODE"
Deletes \s-1NODE\s0 from the item list.
.IP "deselect_all" 4
.IX Item "deselect_all"
Removes selection from all items.
.Sp
Only for multi-select mode.
.IP "draw_items \s-1CANVAS\s0, \s-1PAINT_DATA\s0" 4
.IX Item "draw_items CANVAS, PAINT_DATA"
Called from within \f(CW\*(C`Paint\*(C'\fR notification to draw
items. The default behavior is to call \f(CW\*(C`DrawItem\*(C'\fR
notification for every visible item. \s-1PAINT_DATA\s0
is an array of arrays, where each array consists
of parameters, passed to \f(CW\*(C`DrawItem\*(C'\fR notification.
.Sp
This method is overridden in some descendant classes,
to increase the speed of the drawing routine.
.Sp
See DrawItem for \s-1PAINT_DATA\s0 parameters description.
.IP "get_index \s-1NODE\s0" 4
.IX Item "get_index NODE"
Traverses all items for \s-1NODE\s0 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,
\&\f(CW\*(C`\-1, undef\*(C'\fR is returned.
.IP "get_index_text \s-1INDEX\s0" 4
.IX Item "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 \f(CW\*(C`Stringify\*(C'\fR notification.
.IP "get_index_width \s-1INDEX\s0" 4
.IX Item "get_index_width INDEX"
Returns width in pixels of INDEXth item, which is a
cached result of \f(CW\*(C`MeasureItem\*(C'\fR notification, stored
under index #3 in node.
.IP "get_item \s-1INDEX\s0" 4
.IX Item "get_item INDEX"
Returns two scalars corresponding to INDEXth item: 
node reference and its depth level. If \s-1INDEX\s0 is outside
the list boundaries, empty array is returned.
.IP "get_item_parent \s-1NODE\s0" 4
.IX Item "get_item_parent NODE"
Returns two scalars, corresponding to \s-1NODE:\s0
its parent node reference and offset of \s-1NODE\s0 in the parent's
immediate children list.
.IP "get_item_text \s-1NODE\s0" 4
.IX Item "get_item_text NODE"
Returns text string assigned to \s-1NODE\s0.
Since the class does not assume the item storage organization,
the text is queried via \f(CW\*(C`Stringify\*(C'\fR notification.
.IP "get_item_width \s-1NODE\s0" 4
.IX Item "get_item_width NODE"
Returns width in pixels of INDEXth item, which is a
cached result of \f(CW\*(C`MeasureItem\*(C'\fR notification, stored
under index #3 in node.
.IP "expand_all [ \s-1NODE\s0 = undef ]." 4
.IX Item "expand_all [ NODE = undef ]."
Expands all nodes under \s-1NODE\s0. If \s-1NODE\s0 is \f(CW\*(C`undef\*(C'\fR, the root node
is assumed. If the tree is large, the execution can take
significant amount of time.
.ie n .IP "insert_items \s-1NODE\s0, \s-1OFFSET\s0, @ITEMS" 4
.el .IP "insert_items \s-1NODE\s0, \s-1OFFSET\s0, \f(CW@ITEMS\fR" 4
.IX Item "insert_items NODE, OFFSET, @ITEMS"
Inserts one or more \s-1ITEMS\s0 under \s-1NODE\s0 with \s-1OFFSET\s0.
If \s-1NODE\s0 is \f(CW\*(C`undef\*(C'\fR, the root node is assumed.
.IP "iterate \s-1ACTION\s0, \s-1FULL\s0" 4
.IX Item "iterate ACTION, FULL"
Traverses the item tree and calls \s-1ACTION\s0 subroutine
for each node. If \s-1FULL\s0 boolean flag is 1, all nodes
are traversed. If 0, only the expanded nodes are traversed.
.Sp
\&\s-1ACTION\s0 subroutine is called with the following parameters:
.RS 4
.IP "0" 4
Node reference
.IP "1" 4
.IX Item "1"
Parent node reference; if \f(CW\*(C`undef\*(C'\fR, the node is the root.
.IP "2" 4
.IX Item "2"
Node offset in parent item list.
.IP "3" 4
.IX Item "3"
Node index.
.IP "4" 4
.IX Item "4"
Node depth level. 0 means the root node.
.IP "5" 4
.IX Item "5"
A boolean flag, set to 1 if the node is the last child in parent node list,
set to 0 otherwise.
.IP "6" 4
.IX Item "6"
Visibility index. When \f(CW\*(C`iterate\*(C'\fR is called with \f(CW\*(C`FULL = 1\*(C'\fR, the index is
the item index as seen of the screen. If the item is not visible, the index
is \f(CW\*(C`undef\*(C'\fR.
.Sp
When \f(CW\*(C`iterate\*(C'\fR is called with \f(CW\*(C`FULL = 1\*(C'\fR, the index is always the same 
as \f(CW\*(C`node index\*(C'\fR.
.RE
.RS 4
.RE
.IP "is_selected \s-1INDEX\s0, \s-1ITEM\s0" 4
.IX Item "is_selected INDEX, ITEM"
Returns 1 if an item is selected, 0 if it is not.
.Sp
The method can address the item either directly ( \s-1ITEM\s0 ) or
by its \s-1INDEX\s0 in the screen position.
.IP "makehint \s-1SHOW\s0, \s-1INDEX\s0" 4
.IX Item "makehint SHOW, INDEX"
Controls hint label upon INDEXth item. If a boolean flag \s-1SHOW\s0 is set to 1,
and \f(CW\*(C`showItemHint\*(C'\fR 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 \s-1SHOW\s0 is set to 0, the hint label is hidden immediately.
.IP "point2item Y, [ \s-1HEIGHT\s0 ]" 4
.IX Item "point2item Y, [ HEIGHT ]"
Returns index of an item that contains horizontal axis at Y in the widget coordinates.
If \s-1HEIGHT\s0 is specified, it must be the widget height; if it is
not, the value is fetched by calling \f(CW\*(C`Prima::Widget::height\*(C'\fR.
If the value is known, passing it to \f(CW\*(C`point2item\*(C'\fR thus achieves
some speed-up.
.IP "select_all" 4
.IX Item "select_all"
Selects all items.
.Sp
Only for multi-select mode.
.IP "set_item_selected \s-1INDEX\s0, \s-1ITEM\s0, \s-1FLAG\s0" 4
.IX Item "set_item_selected INDEX, ITEM, FLAG"
Sets selection flag of an item.
If \s-1FLAG\s0 is 1, the item is selected. If 0, it is deselected.
.Sp
The method can address the item either directly ( \s-1ITEM\s0 ) or
by its \s-1INDEX\s0 in the screen position. Only for multi-select mode.
.IP "select_item \s-1INDEX\s0, \s-1ITEM\s0" 4
.IX Item "select_item INDEX, ITEM"
Selects an item.
.Sp
The method can address the item either directly ( \s-1ITEM\s0 ) or
by its \s-1INDEX\s0 in the screen position. Only for multi-select mode.
.IP "toggle_item \s-1INDEX\s0, \s-1ITEM\s0" 4
.IX Item "toggle_item INDEX, ITEM"
Toggles selection of an item.
.Sp
The method can address the item either directly ( \s-1ITEM\s0 ) or
by its \s-1INDEX\s0 in the screen position. Only for multi-select mode.
.IP "unselect_item \s-1INDEX\s0, \s-1ITEM\s0" 4
.IX Item "unselect_item INDEX, ITEM"
Deselects an item.
.Sp
The method can address the item either directly ( \s-1ITEM\s0 ) or
by its \s-1INDEX\s0 in the screen position. Only for multi-select mode.
.IP "validate_items \s-1ITEMS\s0" 4
.IX Item "validate_items ITEMS"
Traverses the array of \s-1ITEMS\s0 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.
.SS "Events"
.IX Subsection "Events"
.IP "Expand \s-1NODE\s0, \s-1EXPAND\s0" 4
.IX Item "Expand NODE, EXPAND"
Called when \s-1NODE\s0 is expanded ( 1 ) or collapsed ( 0 ). 
The \s-1EXPAND\s0 boolean flag reflects the action taken.
.IP "DragItem \s-1OLD_INDEX\s0, \s-1NEW_INDEX\s0" 4
.IX Item "DragItem OLD_INDEX, NEW_INDEX"
Called when the user finishes the drag of an item
from \s-1OLD_INDEX\s0 to \s-1NEW_INDEX\s0 position. The default action
rearranges the item list in accord with the dragging action.
.IP "DrawItem \s-1CANVAS\s0, \s-1NODE\s0, X1, Y1, X2, Y2, \s-1INDEX\s0, \s-1SELECTED\s0, \s-1FOCUSED\s0" 4
.IX Item "DrawItem CANVAS, NODE, X1, Y1, X2, Y2, INDEX, SELECTED, FOCUSED"
Called when INDEXth item, contained in \s-1NODE\s0 is to be drawn on 
\&\s-1CANVAS\s0. X1, Y1, X2, Y2 coordinated define the exterior rectangle
of the item in widget coordinates. \s-1SELECTED\s0 and \s-1FOCUSED\s0 boolean flags are set to
1 if the item is selected or focused, respectively; 0 otherwise.
.IP "MeasureItem \s-1NODE\s0, \s-1LEVEL\s0, \s-1REF\s0" 4
.IX Item "MeasureItem NODE, LEVEL, REF"
Puts width of \s-1NODE\s0 item in pixels into \s-1REF\s0 scalar reference. \s-1LEVEL\s0 is the node 
depth as returned by \f(CW\*(C`get_item\*(C'\fR for the reference. This notification
must be called from within \f(CW\*(C`begin_paint_info/end_paint_info\*(C'\fR block.
.IP "SelectItem [[\s-1INDEX\s0, \s-1ITEM\s0, \s-1SELECTED\s0], [\s-1INDEX\s0, \s-1ITEM\s0, \s-1SELECTED\s0], ...]" 4
.IX Item "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 \s-1INDEX\s0, or directly as \s-1ITEM\s0, or both.
In case \s-1INDEX\s0 is undef, the item is invisible; if \s-1ITEM\s0 is undef, then
the caller didn't bother to call \f(CW\*(C`get_item\*(C'\fR for the speed reasons, and
the received should call this function. The \s-1SELECTED\s0 flag contains
the new value of the item.
.IP "Stringify \s-1NODE\s0, \s-1TEXT_REF\s0" 4
.IX Item "Stringify NODE, TEXT_REF"
Puts text string, assigned to \s-1NODE\s0 item into \s-1TEXT_REF\s0
scalar reference.
.SH "Prima::StringOutline"
.IX Header "Prima::StringOutline"
Descendant of \f(CW\*(C`Prima::OutlineViewer\*(C'\fR 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:
.PP
\&\f(CW$string_outline\fR\-> items([ 'String', [ 'Descendant' ]]);
.SH "Prima::Outline"
.IX Header "Prima::Outline"
A variant of \f(CW\*(C`Prima::StringOutline\*(C'\fR, 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.
.SH "Prima::DirectoryOutline"
.IX Header "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 \s-1OS\s0, there is either single root directory ( unix ), or
one or more disk drive root items ( win32, os2 ).
.PP
The format of a node is defined as follows:
.IP "0" 4
Directory name, string.
.IP "1" 4
.IX Item "1"
Parent path; an empty string for the root items.
.IP "2" 4
.IX Item "2"
Icon width in pixels, integer.
.IP "3" 4
.IX Item "3"
Drive icon; defined only for the root items under non-unix hosts
in order to reflect the drive type ( hard, floppy, etc ).
.SS "Properties"
.IX Subsection "Properties"
.IP "closedGlyphs \s-1INTEGER\s0" 4
.IX Item "closedGlyphs INTEGER"
Number of horizontal equal-width images, contained in \f(CW\*(C`closedIcon\*(C'\fR
property.
.Sp
Default value: 1
.IP "closedIcon \s-1ICON\s0" 4
.IX Item "closedIcon ICON"
Provides an icon representation for the collapsed items.
.IP "openedGlyphs \s-1INTEGER\s0" 4
.IX Item "openedGlyphs INTEGER"
Number of horizontal equal-width images, contained in \f(CW\*(C`openedIcon\*(C'\fR
property.
.Sp
Default value: 1
.IP "openedIcon \s-1OBJECT\s0" 4
.IX Item "openedIcon OBJECT"
Provides an icon representation for the expanded items.
.IP "path \s-1STRING\s0" 4
.IX Item "path STRING"
Runtime-only property. Selects current file system path.
.IP "showDotDirs \s-1BOOLEAN\s0" 4
.IX Item "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.
.Sp
Default value: 0
.SS "Methods"
.IX Subsection "Methods"
.IP "files [ \s-1FILE_TYPE\s0 ]" 4
.IX Item "files [ FILE_TYPE ]"
If \s-1FILE_TYPE\s0 value is not specified, the list of all files in the
current directory is returned. If \s-1FILE_TYPE\s0 is given, only the files
of the types are returned. The \s-1FILE_TYPE\s0 is a string, one of those
returned by \f(CW\*(C`Prima::Utils::getdir\*(C'\fR ( see \*(L"getdir\*(R" in Prima::Utils ).
.IP "get_directory_tree \s-1PATH\s0" 4
.IX Item "get_directory_tree PATH"
Reads the file structure under \s-1PATH\s0 and returns a newly created hierarchy 
structure in the class node format. If \f(CW\*(C`showDotDirs\*(C'\fR property value is 0,
the dot-prefixed names are not included.
.Sp
Used internally inside \f(CW\*(C`Expand\*(C'\fR notification.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dmitry Karasik, <dmitry@karasik.eu.org>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Prima, Prima::Widget, Prima::IntUtils, <examples/outline.pl>.