Man Linux: Main Page and Category List

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