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
19               my $outline = Prima::StringOutline-> create(
20                       style => 'triangle',
21                       ...
22               );
23

DESCRIPTION

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

Prima::OutlineViewer

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

Prima::StringOutline

381       Descendant of "Prima::OutlineViewer" class, provides standard single-
382       text items widget. The items can be set by merely supplying a text as
383       the first scalar in node array structure:
384
385       $string_outline-> items([ 'String', [ 'Descendant' ]]);
386

Prima::Outline

388       A variant of "Prima::StringOutline", with the only difference that the
389       text is stored not in the first scalar in a node but as a first scalar
390       in an anonymous array, which in turn is the first node scalar. The
391       class does not define neither format nor the amount of scalars in the
392       array, and as such presents a half-abstract class.
393

Prima::DirectoryOutline

395       Provides a standard widget with the item tree mapped to the directory
396       structure, so each item is mapped to a directory. Depending on the type
397       of the host OS, there is either single root directory ( unix ), or one
398       or more disk drive root items ( win32 ).
399
400       The format of a node is defined as follows:
401
402       #0  Directory name, string.
403
404       #1  Parent path; an empty string for the root items.
405
406       #2  Icon width in pixels, integer.
407
408       #3  Drive icon; defined only for the root items under non-unix hosts in
409           order to reflect the drive type ( hard, floppy, etc ).
410
411   Properties
412       closedGlyphs INTEGER
413           Number of horizontal equal-width images, contained in "closedIcon"
414           property.
415
416           Default value: 1
417
418       closedIcon ICON
419           Provides an icon representation for the collapsed items.
420
421       openedGlyphs INTEGER
422           Number of horizontal equal-width images, contained in "openedIcon"
423           property.
424
425           Default value: 1
426
427       openedIcon OBJECT
428           Provides an icon representation for the expanded items.
429
430       path STRING
431           Runtime-only property. Selects current file system path.
432
433       showDotDirs BOOLEAN
434           Selects if the directories with the first dot character are shown
435           the tree view. The treatment of the dot-prefixed names as hidden is
436           traditional to unix, and is of doubtful use under win32.
437
438           Default value: 0
439
440   Methods
441       files [ FILE_TYPE ]
442           If FILE_TYPE value is not specified, the list of all files in the
443           current directory is returned. If FILE_TYPE is given, only the
444           files of the types are returned. The FILE_TYPE is a string, one of
445           those returned by "Prima::Utils::getdir" ( see "getdir" in
446           Prima::Utils ).
447
448       get_directory_tree PATH
449           Reads the file structure under PATH and returns a newly created
450           hierarchy structure in the class node format. If "showDotDirs"
451           property value is 0, the dot-prefixed names are not included.
452
453           Used internally inside "Expand" notification.
454

AUTHOR

456       Dmitry Karasik, <dmitry@karasik.eu.org>.
457

SEE ALSO

459       Prima, Prima::Widget, <examples/outline.pl>.
460
461
462
463perl v5.36.0                      2023-03-20                Prima::Outlines(3)
Impressum