1Prima::Outlines(3)    User Contributed Perl Documentation   Prima::Outlines(3)
2
3
4

NAME

6       Prima::Outlines - tree view widgets
7

SYNOPSIS

9               use Prima qw(Outlines Application);
10               my $outline = Prima::StringOutline-> create(
11                       items => [
12                               [ 'Simple item' ],
13                               [ 'Embedded items', [['#1'], ['#2']]],
14                       ],
15               );
16               $outline-> expand_all;
17               run Prima;
18

DESCRIPTION

20       The module provides a set of widget classes, designed to display a
21       tree-like hierarchy of items. "Prima::OutlineViewer" presents a generic
22       class that contains basic functionality and defines the interface for
23       the descendants, which are "Prima::StringOutline", "Prima::Outline",
24       and "Prima::DirectoryOutline".
25

Prima::OutlineViewer

27       Presents a generic interface for browsing the tree-like lists.  A node
28       in a linked list represents each item.  The format of node is
29       predefined, and is an anonymous array with the following definitions of
30       indices:
31
32       #0  Item id with non-defined format. The simplest implementation,
33           "Prima::StringOutline", treats the scalar as a text string. The
34           more complex classes store references to arrays or hashes here. See
35           "items" article of a concrete class for the format of a node
36           record.
37
38       #1  Reference to a child node. "undef" if there is none.
39
40       #2  A boolean flag, which selects if the node shown as expanded, e.g.
41           all its immediate children are visible.
42
43       #3  Width of an item in pixels.
44
45       The indices above 3 should not be used, because eventual changes to the
46       implementation of the class may use these. It should be enough item 0
47       to store any value.
48
49       To support a custom format of node, it is sufficient to overload the
50       following notifications: "DrawItem", "MeasureItem", "Stringify". Since
51       "DrawItem" is called for every item, a gross method "draw_items" can be
52       overloaded instead.  See also Prima::StringOutline and Prima::Outline.
53
54       The class employs two addressing methods, index-wise and item-wise. The
55       index-wise counts only the visible ( non-expanded ) items, and is
56       represented by an integer index.  The item-wise addressing cannot be
57       expressed by an integer index, and the full node structure is used as a
58       reference. It is important to use a valid reference here, since the
59       class does not always perform the check if the node belongs to internal
60       node list due to the speed reasons.
61
62       "Prima::OutlineViewer" is a descendant of "Prima::GroupScroller" and
63       "Prima::MouseScroller", so some properties and methods are not
64       described here. See Prima::IntUtils for these.
65
66       The class is not usable directly.
67
68   Properties
69       autoHeight INTEGER
70           If set to 1, changes "itemHeight" automatically according to the
71           widget font height.  If 0, does not influence anything.  When
72           "itemHeight" is set explicitly, changes value to 0.
73
74           Default value: 1
75
76       dragable BOOLEAN
77           If 1, allows the items to be dragged interactively by pressing
78           control key together with left mouse button. If 0, item dragging is
79           disabled.
80
81           Default value: 1
82
83       extendedSelect BOOLEAN
84           Regards the way the user selects multiple items and is only actual
85           when "multiSelect" is 1. If 0, the user must click each item in
86           order to mark as selected. If 1, the user can drag mouse or use
87           "Shift" key plus arrow keys to perform range selection; the
88           "Control" key can be used to select individual items.
89
90           Default value: 0
91
92       focusedItem INTEGER
93           Selects the focused item index. If -1, no item is focused.  It is
94           mostly a run-time property, however, it can be set during the
95           widget creation stage given that the item list is accessible on
96           this stage as well.
97
98       indent INTEGER
99           Width in pixels of the indent between item levels.
100
101           Default value: 12
102
103       itemHeight INTEGER
104           Selects the height of the items in pixels. Since the outline
105           classes do not support items with different vertical dimensions,
106           changes to this property affect all items.
107
108           Default value: default font height
109
110       items ARRAY
111           Provides access to the items as an anonymous array. The format of
112           items is described in the opening article ( see
113           Prima::OutlineViewer ).
114
115           Default value: []
116
117       multiSelect BOOLEAN
118           If 0, the user can only select one item, and it is reported by the
119           "focusedItem" property. If 1, the user can select more than one
120           item.  In this case, "focusedItem"'th item is not necessarily
121           selected.  To access selected item list, use "selectedItems"
122           property.
123
124           Default value: 0
125
126       offset INTEGER
127           Horizontal offset of an item list in pixels.
128
129       selectedItems ARRAY
130           ARRAY is an array of integer indices of selected items. Note, that
131           these are the items visible on the screen only. The property
132           doesn't handle the selection status of the collapsed items.
133
134           The widget keeps the selection status on each node, visible and
135           invisible ( e.g. the node is invisible if its parent node is
136           collapsed). However, "selectedItems" accounts for the visible nodes
137           only; to manipulate the node status or both visible and invisible
138           nodes, use "select_item", "unselect_item", "toggle_item" methods.
139
140       showItemHint BOOLEAN
141           If 1, allows activation of a hint label when the mouse pointer is
142           hovered above an item that does not fit horizontally into the
143           widget inferiors. If 0, the hint is never shown.
144
145           See also: makehint.
146
147           Default value: 1
148
149       topItem INTEGER
150           Selects the first item drawn.
151
152   Methods
153       add_selection ARRAY, FLAG
154           Sets item indices from ARRAY in selected or deselected state,
155           depending on FLAG value, correspondingly 1 or 0.
156
157           Note, that these are the items visible on the screen only. The
158           method doesn't handle the selection status of the collapsed items.
159
160           Only for multi-select mode.
161
162       adjust INDEX, EXPAND
163           Performs expansion ( 1 ) or collapse ( 0 ) of INDEXth item,
164           depending on EXPAND boolean flag value.
165
166       calibrate
167           Recalculates the node tree and the item dimensions.  Used
168           internally.
169
170       delete_items [ NODE = undef, OFFSET = 0, LENGTH = undef ]
171           Deletes LENGTH children items of NODE at OFFSET.  If NODE is
172           "undef", the root node is assumed. If LENGTH is "undef", all items
173           after OFFSET are deleted.
174
175       delete_item NODE
176           Deletes NODE from the item list.
177
178       deselect_all
179           Removes selection from all items.
180
181           Only for multi-select mode.
182
183       draw_items CANVAS, PAINT_DATA
184           Called from within "Paint" notification to draw items. The default
185           behavior is to call "DrawItem" notification for every visible item.
186           PAINT_DATA is an array of arrays, where each array consists of
187           parameters, passed to "DrawItem" notification.
188
189           This method is overridden in some descendant classes, to increase
190           the speed of the drawing routine.
191
192           See DrawItem for PAINT_DATA parameters description.
193
194       get_index NODE
195           Traverses all items for NODE and finds if it is visible.  If it is,
196           returns two integers: the first is item index and the second is
197           item depth level. If it is not visible, "-1, undef" is returned.
198
199       get_index_text INDEX
200           Returns text string assigned to INDEXth item.  Since the class does
201           not assume the item storage organization, the text is queried via
202           "Stringify" notification.
203
204       get_index_width INDEX
205           Returns width in pixels of INDEXth item, which is a cached result
206           of "MeasureItem" notification, stored under index #3 in node.
207
208       get_item INDEX
209           Returns two scalars corresponding to INDEXth item: node reference
210           and its depth level. If INDEX is outside the list boundaries, empty
211           array is returned.
212
213       get_item_parent NODE
214           Returns two scalars, corresponding to NODE: its parent node
215           reference and offset of NODE in the parent's immediate children
216           list.
217
218       get_item_text NODE
219           Returns text string assigned to NODE.  Since the class does not
220           assume the item storage organization, the text is queried via
221           "Stringify" notification.
222
223       get_item_width NODE
224           Returns width in pixels of INDEXth item, which is a cached result
225           of "MeasureItem" notification, stored under index #3 in node.
226
227       expand_all [ NODE = undef ].
228           Expands all nodes under NODE. If NODE is "undef", the root node is
229           assumed. If the tree is large, the execution can take significant
230           amount of time.
231
232       insert_items NODE, OFFSET, @ITEMS
233           Inserts one or more ITEMS under NODE with OFFSET.  If NODE is
234           "undef", the root node is assumed.
235
236       iterate ACTION, FULL
237           Traverses the item tree and calls ACTION subroutine for each node.
238           If FULL boolean flag is 1, all nodes are traversed. If 0, only the
239           expanded nodes are traversed.
240
241           ACTION subroutine is called with the following parameters:
242
243           #0  Node reference
244
245           #1  Parent node reference; if "undef", the node is the root.
246
247           #2  Node offset in parent item list.
248
249           #3  Node index.
250
251           #4  Node depth level. 0 means the root node.
252
253           #5  A boolean flag, set to 1 if the node is the last child in
254               parent node list, set to 0 otherwise.
255
256           #6  Visibility index. When "iterate" is called with "FULL = 1", the
257               index is the item index as seen of the screen. If the item is
258               not visible, the index is "undef".
259
260               When "iterate" is called with "FULL = 1", the index is always
261               the same as "node index".
262
263       is_selected INDEX, ITEM
264           Returns 1 if an item is selected, 0 if it is not.
265
266           The method can address the item either directly ( ITEM ) or by its
267           INDEX in the screen position.
268
269       makehint SHOW, INDEX
270           Controls hint label upon INDEXth item. If a boolean flag SHOW is
271           set to 1, and "showItemHint" property is 1, and the item index does
272           not fit horizontally in the widget inferiors then the hint label is
273           shown.  By default the label is removed automatically as the user
274           moves the mouse pointer away from the item. If SHOW is set to 0,
275           the hint label is hidden immediately.
276
277       point2item Y, [ HEIGHT ]
278           Returns index of an item that contains horizontal axis at Y in the
279           widget coordinates.  If HEIGHT is specified, it must be the widget
280           height; if it is not, the value is fetched by calling
281           "Prima::Widget::height".  If the value is known, passing it to
282           "point2item" thus achieves some speed-up.
283
284       select_all
285           Selects all items.
286
287           Only for multi-select mode.
288
289       set_item_selected INDEX, ITEM, FLAG
290           Sets selection flag of an item.  If FLAG is 1, the item is
291           selected. If 0, it is deselected.
292
293           The method can address the item either directly ( ITEM ) or by its
294           INDEX in the screen position. Only for multi-select mode.
295
296       select_item INDEX, ITEM
297           Selects an item.
298
299           The method can address the item either directly ( ITEM ) or by its
300           INDEX in the screen position. Only for multi-select mode.
301
302       toggle_item INDEX, ITEM
303           Toggles selection of an item.
304
305           The method can address the item either directly ( ITEM ) or by its
306           INDEX in the screen position. Only for multi-select mode.
307
308       unselect_item INDEX, ITEM
309           Deselects an item.
310
311           The method can address the item either directly ( ITEM ) or by its
312           INDEX in the screen position. Only for multi-select mode.
313
314       validate_items ITEMS
315           Traverses the array of ITEMS and puts every node to the common
316           format: cuts scalars above index #3, if there are any, or adds
317           default values to a node if it contains less than 3 scalars.
318
319   Events
320       Expand NODE, EXPAND
321           Called when NODE is expanded ( 1 ) or collapsed ( 0 ).  The EXPAND
322           boolean flag reflects the action taken.
323
324       DragItem OLD_INDEX, NEW_INDEX
325           Called when the user finishes the drag of an item from OLD_INDEX to
326           NEW_INDEX position. The default action rearranges the item list in
327           accord with the dragging action.
328
329       DrawItem CANVAS, NODE, X1, Y1, X2, Y2, INDEX, SELECTED, FOCUSED,
330       PRELIGHT
331           Called when INDEXth item, contained in NODE is to be drawn on
332           CANVAS. X1, Y1, X2, Y2 coordinated define the exterior rectangle of
333           the item in widget coordinates. SELECTED, FOCUSED, and PRELIGHT
334           boolean flags are set to 1 if the item is selected, focused, or
335           pre-lighted, respectively; 0 otherwise.
336
337       MeasureItem NODE, LEVEL, REF
338           Puts width of NODE item in pixels into REF scalar reference. LEVEL
339           is the node depth as returned by "get_item" for the reference. This
340           notification must be called from within
341           "begin_paint_info/end_paint_info" block.
342
343       SelectItem [[INDEX, ITEM, SELECTED], [INDEX, ITEM, SELECTED], ...]
344           Called when an item gets selected or deselected. The array passed
345           contains set of arrays for each items, where the item can be
346           defined either as integer INDEX, or directly as ITEM, or both.  In
347           case INDEX is undef, the item is invisible; if ITEM is undef, then
348           the caller didn't bother to call "get_item" for the speed reasons,
349           and the received should call this function. The SELECTED flag
350           contains the new value of the item.
351
352       Stringify NODE, TEXT_REF
353           Puts text string, assigned to NODE item into TEXT_REF scalar
354           reference.
355

Prima::StringOutline

357       Descendant of "Prima::OutlineViewer" class, provides standard single-
358       text items widget. The items can be set by merely supplying a text as
359       the first scalar in node array structure:
360
361       $string_outline-> items([ 'String', [ 'Descendant' ]]);
362

Prima::Outline

364       A variant of "Prima::StringOutline", with the only difference that the
365       text is stored not in the first scalar in a node but as a first scalar
366       in an anonymous array, which in turn is the first node scalar. The
367       class does not define neither format nor the amount of scalars in the
368       array, and as such presents a half-abstract class.
369

Prima::DirectoryOutline

371       Provides a standard widget with the item tree mapped to the directory
372       structure, so each item is mapped to a directory. Depending on the type
373       of the host OS, there is either single root directory ( unix ), or one
374       or more disk drive root items ( win32 ).
375
376       The format of a node is defined as follows:
377
378       #0  Directory name, string.
379
380       #1  Parent path; an empty string for the root items.
381
382       #2  Icon width in pixels, integer.
383
384       #3  Drive icon; defined only for the root items under non-unix hosts in
385           order to reflect the drive type ( hard, floppy, etc ).
386
387   Properties
388       closedGlyphs INTEGER
389           Number of horizontal equal-width images, contained in "closedIcon"
390           property.
391
392           Default value: 1
393
394       closedIcon ICON
395           Provides an icon representation for the collapsed items.
396
397       openedGlyphs INTEGER
398           Number of horizontal equal-width images, contained in "openedIcon"
399           property.
400
401           Default value: 1
402
403       openedIcon OBJECT
404           Provides an icon representation for the expanded items.
405
406       path STRING
407           Runtime-only property. Selects current file system path.
408
409       showDotDirs BOOLEAN
410           Selects if the directories with the first dot character are shown
411           the tree view. The treatment of the dot-prefixed names as hidden is
412           traditional to unix, and is of doubtful use under win32.
413
414           Default value: 0
415
416   Methods
417       files [ FILE_TYPE ]
418           If FILE_TYPE value is not specified, the list of all files in the
419           current directory is returned. If FILE_TYPE is given, only the
420           files of the types are returned. The FILE_TYPE is a string, one of
421           those returned by "Prima::Utils::getdir" ( see "getdir" in
422           Prima::Utils ).
423
424       get_directory_tree PATH
425           Reads the file structure under PATH and returns a newly created
426           hierarchy structure in the class node format. If "showDotDirs"
427           property value is 0, the dot-prefixed names are not included.
428
429           Used internally inside "Expand" notification.
430

AUTHOR

432       Dmitry Karasik, <dmitry@karasik.eu.org>.
433

SEE ALSO

435       Prima, Prima::Widget, Prima::IntUtils, <examples/outline.pl>.
436
437
438
439perl v5.34.0                      2021-07-22                Prima::Outlines(3)
Impressum