1Prima::Outlines(3) User Contributed Perl Documentation Prima::Outlines(3)
2
6 Prima::Outlines - tree view widgets
7
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
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
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 #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 #1 Reference to a child node. "undef" if there is none.
39 #2 A boolean flag, which selects if the node shown as expanded, e.g.
41 all its immediate children are visible.
42 #3 Width of an item in pixels.
44 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 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 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 "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 The class is not usable directly.
67 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 Default value: 1
75 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 Default value: 1
82 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 Default value: 0
91 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 indent INTEGER
99 Width in pixels of the indent between item levels.
100 Default value: 12
102 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 Default value: default font height
109 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 Default value: []
116 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 Default value: 0
125 offset INTEGER
127 Horizontal offset of an item list in pixels.
128 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 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 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 See also: makehint.
146 Default value: 1
148 topItem INTEGER
150 Selects the first item drawn.
151 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 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 Only for multi-select mode.
161 adjust INDEX, EXPAND
163 Performs expansion ( 1 ) or collapse ( 0 ) of INDEXth item,
164 depending on EXPAND boolean flag value.
165 calibrate
167 Recalculates the node tree and the item dimensions. Used
168 internally.
169 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 delete_item NODE
176 Deletes NODE from the item list.
177 deselect_all
179 Removes selection from all items.
180 Only for multi-select mode.
182 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 This method is overridden in some descendant classes, to increase
190 the speed of the drawing routine.
191 See DrawItem for PAINT_DATA parameters description.
193 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 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 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 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 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 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 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 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 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 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 ACTION subroutine is called with the following parameters:
242 #0 Node reference
244 #1 Parent node reference; if "undef", the node is the root.
246 #2 Node offset in parent item list.
248 #3 Node index.
250 #4 Node depth level. 0 means the root node.
252 #5 A boolean flag, set to 1 if the node is the last child in
254 parent node list, set to 0 otherwise.
255 #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 When "iterate" is called with "FULL = 1", the index is always
261 the same as "node index".
262 is_selected INDEX, ITEM
264 Returns 1 if an item is selected, 0 if it is not.
265 The method can address the item either directly ( ITEM ) or by its
267 INDEX in the screen position.
268 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 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 select_all
285 Selects all items.
286 Only for multi-select mode.
288 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 The method can address the item either directly ( ITEM ) or by its
294 INDEX in the screen position. Only for multi-select mode.
295 select_item INDEX, ITEM
297 Selects an item.
298 The method can address the item either directly ( ITEM ) or by its
300 INDEX in the screen position. Only for multi-select mode.
301 toggle_item INDEX, ITEM
303 Toggles selection of an item.
304 The method can address the item either directly ( ITEM ) or by its
306 INDEX in the screen position. Only for multi-select mode.
307 unselect_item INDEX, ITEM
309 Deselects an item.
310 The method can address the item either directly ( ITEM ) or by its
312 INDEX in the screen position. Only for multi-select mode.
313 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 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 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 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 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 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 Stringify NODE, TEXT_REF
353 Puts text string, assigned to NODE item into TEXT_REF scalar
354 reference.
355
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 $string_outline-> items([ 'String', [ 'Descendant' ]]);
362
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
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 The format of a node is defined as follows:
377 #0 Directory name, string.
379 #1 Parent path; an empty string for the root items.
381 #2 Icon width in pixels, integer.
383 #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 Properties
388 closedGlyphs INTEGER
389 Number of horizontal equal-width images, contained in "closedIcon"
390 property.
391 Default value: 1
393 closedIcon ICON
395 Provides an icon representation for the collapsed items.
396 openedGlyphs INTEGER
398 Number of horizontal equal-width images, contained in "openedIcon"
399 property.
400 Default value: 1
402 openedIcon OBJECT
404 Provides an icon representation for the expanded items.
405 path STRING
407 Runtime-only property. Selects current file system path.
408 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 Default value: 0
415 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 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 Used internally inside "Expand" notification.
430
432 Dmitry Karasik, <dmitry@karasik.eu.org>.
433
435 Prima, Prima::Widget, Prima::IntUtils, <examples/outline.pl>.
436perl v5.34.0 2021-07-22 Prima::Outlines(3)