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 my $outline = Prima::StringOutline-> create(
20 iconStyle => 'triangle',
21 ...
22 );
23
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
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 #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 #1 Reference to a child node. "undef" if there is none.
44 #2 A boolean flag, which selects if the node shown as expanded, e.g.
46 all its immediate children are visible.
47 #3 Width of an item in pixels.
49 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 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 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 "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 The class is not usable directly.
72 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 Default value: 1
80 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 Default value: 1
87 drawLines BOOLEAN
89 If 1, draws dotted tree lines left to the items.
90 Default value: 1
92 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 Default value: 0
101 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 iconCollapsed ICON
109 Sets the image that is to be displayed when a tree branch is
110 collapsed
111 iconExpanded ICON
113 Sets the image that is to be displayed when a tree branch is
114 expanded
115 iconStyle STYLE
117 Sets visual style, one of: "default", "plusminus", "triangle".
118 The default style is set in $Prima::Outlines::default_style and is
120 currently 'plusminus'
121 indent INTEGER
123 Width in pixels of the indent between item levels.
124 Default value: 12
126 itemHeight INTEGER
128 Selects the height of the items in pixels. Since the outline
129 classes do not support items with different vertical dimensions,
130 changes to this property affect all items.
131 Default value: default font height
133 items ARRAY
135 Provides access to the items as an anonymous array. The format of
136 items is described in the opening article ( see
137 Prima::OutlineViewer ).
138 Default value: []
140 multiSelect BOOLEAN
142 If 0, the user can only select one item, and it is reported by the
143 "focusedItem" property. If 1, the user can select more than one
144 item. In this case, "focusedItem"'th item is not necessarily
145 selected. To access selected item list, use "selectedItems"
146 property.
147 Default value: 0
149 offset INTEGER
151 Horizontal offset of an item list in pixels.
152 selectedItems ARRAY
154 ARRAY is an array of integer indices of selected items. Note, that
155 these are the items visible on the screen only. The property
156 doesn't handle the selection status of the collapsed items.
157 The widget keeps the selection status on each node, visible and
159 invisible ( e.g. the node is invisible if its parent node is
160 collapsed). However, "selectedItems" accounts for the visible nodes
161 only; to manipulate the node status or both visible and invisible
162 nodes, use "select_item", "unselect_item", "toggle_item" methods.
163 showItemHint BOOLEAN
165 If 1, allows activation of a hint label when the mouse pointer is
166 hovered above an item that does not fit horizontally into the
167 widget inferiors. If 0, the hint is never shown.
168 See also: makehint.
170 Default value: 1
172 topItem INTEGER
174 Selects the first item drawn.
175 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 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 Only for multi-select mode.
185 adjust INDEX, EXPAND
187 Performs expansion ( 1 ) or collapse ( 0 ) of INDEXth item,
188 depending on EXPAND boolean flag value.
189 calibrate
191 Recalculates the node tree and the item dimensions. Used
192 internally.
193 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 delete_item NODE
200 Deletes NODE from the item list.
201 deselect_all
203 Removes selection from all items.
204 Only for multi-select mode.
206 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 This method is overridden in some descendant classes, to increase
214 the speed of the drawing routine.
215 See DrawItem for PAINT_DATA parameters description.
217 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 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 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 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 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 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 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 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 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 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 ACTION subroutine is called with the following parameters:
266 #0 Node reference
268 #1 Parent node reference; if "undef", the node is the root.
270 #2 Node offset in parent item list.
272 #3 Node index.
274 #4 Node depth level. 0 means the root node.
276 #5 A boolean flag, set to 1 if the node is the last child in
278 parent node list, set to 0 otherwise.
279 #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 When "iterate" is called with "FULL = 1", the index is always
285 the same as "node index".
286 is_selected INDEX, ITEM
288 Returns 1 if an item is selected, 0 if it is not.
289 The method can address the item either directly ( ITEM ) or by its
291 INDEX in the screen position.
292 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 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 select_all
309 Selects all items.
310 Only for multi-select mode.
312 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 The method can address the item either directly ( ITEM ) or by its
318 INDEX in the screen position. Only for multi-select mode.
319 select_item INDEX, ITEM
321 Selects an item.
322 The method can address the item either directly ( ITEM ) or by its
324 INDEX in the screen position. Only for multi-select mode.
325 toggle_item INDEX, ITEM
327 Toggles selection of an item.
328 The method can address the item either directly ( ITEM ) or by its
330 INDEX in the screen position. Only for multi-select mode.
331 unselect_item INDEX, ITEM
333 Deselects an item.
334 The method can address the item either directly ( ITEM ) or by its
336 INDEX in the screen position. Only for multi-select mode.
337 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 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 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 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 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 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 Stringify NODE, TEXT_REF
377 Puts text string, assigned to NODE item into TEXT_REF scalar
378 reference.
379
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 $string_outline-> items([ 'String', [ 'Descendant' ]]);
386
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
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 The format of a node is defined as follows:
401 #0 Directory name, string.
403 #1 Parent path; an empty string for the root items.
405 #2 Icon width in pixels, integer.
407 #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 Properties
412 closedGlyphs INTEGER
413 Number of horizontal equal-width images, contained in "closedIcon"
414 property.
415 Default value: 1
417 closedIcon ICON
419 Provides an icon representation for the collapsed items.
420 openedGlyphs INTEGER
422 Number of horizontal equal-width images, contained in "openedIcon"
423 property.
424 Default value: 1
426 openedIcon OBJECT
428 Provides an icon representation for the expanded items.
429 path STRING
431 Runtime-only property. Selects current file system path.
432 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 Default value: 0
439 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 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 Used internally inside "Expand" notification.
454
456 Dmitry Karasik, <dmitry@karasik.eu.org>.
457
459 Prima, Prima::Widget, <examples/outline.pl>.
460perl v5.38.0 2023-07-21 Prima::Outlines(3)