1Prima::Outlines(3) User Contributed Perl Documentation Prima::Outlines(3)
2
6 Prima::Outlines - tree view widgets
7
9 use Prima::Outlines;
10 my $outline = Prima::StringOutline-> create(
12 items => [
13 [ 'Simple item' ],
14 [[ 'Embedded item ']],
15 [[ 'More embedded items', [ '#1', '#2' ]]],
16 ],
17 );
18 $outline-> expand_all;
19
21 The module provides a set of widget classes, designed to display a
22 tree-like hierarchy of items. "Prima::OutlineViewer" presents a generic
23 class that contains basic functionality and defines the interface for
24 the descendants, which are "Prima::StringOutline", "Prima::Outline",
25 and "Prima::DirectoryOutline".
26
28 Presents a generic interface for browsing the tree-like lists. A node
29 in a linked list represents each item. The format of node is
30 predefined, and is an anonymous array with the following definitions of
31 indices:
32 #0 Item id with non-defined format. The simplest implementation,
34 "Prima::StringOutline", treats the scalar as a text string. The
35 more complex classes store references to arrays or hashes here. See
36 "items" article of a concrete class for the format of a node
37 record.
38 #1 Reference to a child node. "undef" if there is none.
40 #2 A boolean flag, which selects if the node shown as expanded, e.g.
42 all its immediate children are visible.
43 #3 Width of an item in pixels.
45 The indices above 3 should not be used, because eventual changes to the
47 implementation of the class may use these. It should be enough item 0
48 to store any value.
49 To support a custom format of node, it is sufficient to overload the
51 following notifications: "DrawItem", "MeasureItem", "Stringify". Since
52 "DrawItem" is called for every item, a gross method "draw_items" can be
53 overloaded instead. See also Prima::StringOutline and Prima::Outline.
54 The class employs two addressing methods, index-wise and item-wise. The
56 index-wise counts only the visible ( non-expanded ) items, and is
57 represented by an integer index. The item-wise addressing cannot be
58 expressed by an integer index, and the full node structure is used as a
59 reference. It is important to use a valid reference here, since the
60 class does not always perform the check if the node belongs to internal
61 node list due to the speed reasons.
62 "Prima::OutlineViewer" is a descendant of "Prima::GroupScroller" and
64 "Prima::MouseScroller", so some properties and methods are not
65 described here. See Prima::IntUtils for these.
66 The class is not usable directly.
68 Properties
70 autoHeight INTEGER
71 If set to 1, changes "itemHeight" automatically according to the
72 widget font height. If 0, does not influence anything. When
73 "itemHeight" is set explicitly, changes value to 0.
74 Default value: 1
76 dragable BOOLEAN
78 If 1, allows the items to be dragged interactively by pressing
79 control key together with left mouse button. If 0, item dragging is
80 disabled.
81 Default value: 1
83 extendedSelect BOOLEAN
85 Regards the way the user selects multiple items and is only actual
86 when "multiSelect" is 1. If 0, the user must click each item in
87 order to mark as selected. If 1, the user can drag mouse or use
88 "Shift" key plus arrow keys to perform range selection; the
89 "Control" key can be used to select individual items.
90 Default value: 0
92 focusedItem INTEGER
94 Selects the focused item index. If -1, no item is focused. It is
95 mostly a run-time property, however, it can be set during the
96 widget creation stage given that the item list is accessible on
97 this stage as well.
98 indent INTEGER
100 Width in pixels of the indent between item levels.
101 Default value: 12
103 itemHeight INTEGER
105 Selects the height of the items in pixels. Since the outline
106 classes do not support items with different vertical dimensions,
107 changes to this property affect all items.
108 Default value: default font height
110 items ARRAY
112 Provides access to the items as an anonymous array. The format of
113 items is described in the opening article ( see
114 Prima::OutlineViewer ).
115 Default value: []
117 multiSelect BOOLEAN
119 If 0, the user can only select one item, and it is reported by the
120 "focusedItem" property. If 1, the user can select more than one
121 item. In this case, "focusedItem"'th item is not necessarily
122 selected. To access selected item list, use "selectedItems"
123 property.
124 Default value: 0
126 offset INTEGER
128 Horizontal offset of an item list in pixels.
129 selectedItems ARRAY
131 ARRAY is an array of integer indices of selected items. Note, that
132 these are the items visible on the screen only. The property
133 doesn't handle the selection status of the collapsed items.
134 The widget keeps the selection status on each node, visible and
136 invisible ( e.g. the node is invisible if its parent node is
137 collapsed). However, "selectedItems" accounts for the visible nodes
138 only; to manipulate the node status or both visible and invisible
139 nodes, use "select_item", "unselect_item", "toggle_item" methods.
140 showItemHint BOOLEAN
142 If 1, allows activation of a hint label when the mouse pointer is
143 hovered above an item that does not fit horizontally into the
144 widget inferiors. If 0, the hint is never shown.
145 See also: makehint.
147 Default value: 1
149 topItem INTEGER
151 Selects the first item drawn.
152 Methods
154 add_selection ARRAY, FLAG
155 Sets item indices from ARRAY in selected or deselected state,
156 depending on FLAG value, correspondingly 1 or 0.
157 Note, that these are the items visible on the screen only. The
159 method doesn't handle the selection status of the collapsed items.
160 Only for multi-select mode.
162 adjust INDEX, EXPAND
164 Performs expansion ( 1 ) or collapse ( 0 ) of INDEXth item,
165 depending on EXPAND boolean flag value.
166 calibrate
168 Recalculates the node tree and the item dimensions. Used
169 internally.
170 delete_items [ NODE = undef, OFFSET = 0, LENGTH = undef ]
172 Deletes LENGTH children items of NODE at OFFSET. If NODE is
173 "undef", the root node is assumed. If LENGTH is "undef", all items
174 after OFFSET are deleted.
175 delete_item NODE
177 Deletes NODE from the item list.
178 deselect_all
180 Removes selection from all items.
181 Only for multi-select mode.
183 draw_items CANVAS, PAINT_DATA
185 Called from within "Paint" notification to draw items. The default
186 behavior is to call "DrawItem" notification for every visible item.
187 PAINT_DATA is an array of arrays, where each array consists of
188 parameters, passed to "DrawItem" notification.
189 This method is overridden in some descendant classes, to increase
191 the speed of the drawing routine.
192 See DrawItem for PAINT_DATA parameters description.
194 get_index NODE
196 Traverses all items for NODE and finds if it is visible. If it is,
197 returns two integers: the first is item index and the second is
198 item depth level. If it is not visible, "-1, undef" is returned.
199 get_index_text INDEX
201 Returns text string assigned to INDEXth item. Since the class does
202 not assume the item storage organization, the text is queried via
203 "Stringify" notification.
204 get_index_width INDEX
206 Returns width in pixels of INDEXth item, which is a cached result
207 of "MeasureItem" notification, stored under index #3 in node.
208 get_item INDEX
210 Returns two scalars corresponding to INDEXth item: node reference
211 and its depth level. If INDEX is outside the list boundaries, empty
212 array is returned.
213 get_item_parent NODE
215 Returns two scalars, corresponding to NODE: its parent node
216 reference and offset of NODE in the parent's immediate children
217 list.
218 get_item_text NODE
220 Returns text string assigned to NODE. Since the class does not
221 assume the item storage organization, the text is queried via
222 "Stringify" notification.
223 get_item_width NODE
225 Returns width in pixels of INDEXth item, which is a cached result
226 of "MeasureItem" notification, stored under index #3 in node.
227 expand_all [ NODE = undef ].
229 Expands all nodes under NODE. If NODE is "undef", the root node is
230 assumed. If the tree is large, the execution can take significant
231 amount of time.
232 insert_items NODE, OFFSET, @ITEMS
234 Inserts one or more ITEMS under NODE with OFFSET. If NODE is
235 "undef", the root node is assumed.
236 iterate ACTION, FULL
238 Traverses the item tree and calls ACTION subroutine for each node.
239 If FULL boolean flag is 1, all nodes are traversed. If 0, only the
240 expanded nodes are traversed.
241 ACTION subroutine is called with the following parameters:
243 #0 Node reference
245 #1 Parent node reference; if "undef", the node is the root.
247 #2 Node offset in parent item list.
249 #3 Node index.
251 #4 Node depth level. 0 means the root node.
253 #5 A boolean flag, set to 1 if the node is the last child in
255 parent node list, set to 0 otherwise.
256 #6 Visibility index. When "iterate" is called with "FULL = 1", the
258 index is the item index as seen of the screen. If the item is
259 not visible, the index is "undef".
260 When "iterate" is called with "FULL = 1", the index is always
262 the same as "node index".
263 is_selected INDEX, ITEM
265 Returns 1 if an item is selected, 0 if it is not.
266 The method can address the item either directly ( ITEM ) or by its
268 INDEX in the screen position.
269 makehint SHOW, INDEX
271 Controls hint label upon INDEXth item. If a boolean flag SHOW is
272 set to 1, and "showItemHint" property is 1, and the item index does
273 not fit horizontally in the widget inferiors then the hint label is
274 shown. By default the label is removed automatically as the user
275 moves the mouse pointer away from the item. If SHOW is set to 0,
276 the hint label is hidden immediately.
277 point2item Y, [ HEIGHT ]
279 Returns index of an item that contains horizontal axis at Y in the
280 widget coordinates. If HEIGHT is specified, it must be the widget
281 height; if it is not, the value is fetched by calling
282 "Prima::Widget::height". If the value is known, passing it to
283 "point2item" thus achieves some speed-up.
284 select_all
286 Selects all items.
287 Only for multi-select mode.
289 set_item_selected INDEX, ITEM, FLAG
291 Sets selection flag of an item. If FLAG is 1, the item is
292 selected. If 0, it is deselected.
293 The method can address the item either directly ( ITEM ) or by its
295 INDEX in the screen position. Only for multi-select mode.
296 select_item INDEX, ITEM
298 Selects an item.
299 The method can address the item either directly ( ITEM ) or by its
301 INDEX in the screen position. Only for multi-select mode.
302 toggle_item INDEX, ITEM
304 Toggles selection of an item.
305 The method can address the item either directly ( ITEM ) or by its
307 INDEX in the screen position. Only for multi-select mode.
308 unselect_item INDEX, ITEM
310 Deselects an item.
311 The method can address the item either directly ( ITEM ) or by its
313 INDEX in the screen position. Only for multi-select mode.
314 validate_items ITEMS
316 Traverses the array of ITEMS and puts every node to the common
317 format: cuts scalars above index #3, if there are any, or adds
318 default values to a node if it contains less than 3 scalars.
319 Events
321 Expand NODE, EXPAND
322 Called when NODE is expanded ( 1 ) or collapsed ( 0 ). The EXPAND
323 boolean flag reflects the action taken.
324 DragItem OLD_INDEX, NEW_INDEX
326 Called when the user finishes the drag of an item from OLD_INDEX to
327 NEW_INDEX position. The default action rearranges the item list in
328 accord with the dragging action.
329 DrawItem CANVAS, NODE, X1, Y1, X2, Y2, INDEX, SELECTED, FOCUSED,
331 PRELIGHT
332 Called when INDEXth item, contained in NODE is to be drawn on
333 CANVAS. X1, Y1, X2, Y2 coordinated define the exterior rectangle of
334 the item in widget coordinates. SELECTED, FOCUSED, and PRELIGHT
335 boolean flags are set to 1 if the item is selected, focused, or
336 pre-lighted, respectively; 0 otherwise.
337 MeasureItem NODE, LEVEL, REF
339 Puts width of NODE item in pixels into REF scalar reference. LEVEL
340 is the node depth as returned by "get_item" for the reference. This
341 notification must be called from within
342 "begin_paint_info/end_paint_info" block.
343 SelectItem [[INDEX, ITEM, SELECTED], [INDEX, ITEM, SELECTED], ...]
345 Called when an item gets selected or deselected. The array passed
346 contains set of arrays for each items, where the item can be
347 defined either as integer INDEX, or directly as ITEM, or both. In
348 case INDEX is undef, the item is invisible; if ITEM is undef, then
349 the caller didn't bother to call "get_item" for the speed reasons,
350 and the received should call this function. The SELECTED flag
351 contains the new value of the item.
352 Stringify NODE, TEXT_REF
354 Puts text string, assigned to NODE item into TEXT_REF scalar
355 reference.
356
358 Descendant of "Prima::OutlineViewer" class, provides standard single-
359 text items widget. The items can be set by merely supplying a text as
360 the first scalar in node array structure:
361 $string_outline-> items([ 'String', [ 'Descendant' ]]);
363
365 A variant of "Prima::StringOutline", with the only difference that the
366 text is stored not in the first scalar in a node but as a first scalar
367 in an anonymous array, which in turn is the first node scalar. The
368 class does not define neither format nor the amount of scalars in the
369 array, and as such presents a half-abstract class.
370
372 Provides a standard widget with the item tree mapped to the directory
373 structure, so each item is mapped to a directory. Depending on the type
374 of the host OS, there is either single root directory ( unix ), or one
375 or more disk drive root items ( win32 ).
376 The format of a node is defined as follows:
378 #0 Directory name, string.
380 #1 Parent path; an empty string for the root items.
382 #2 Icon width in pixels, integer.
384 #3 Drive icon; defined only for the root items under non-unix hosts in
386 order to reflect the drive type ( hard, floppy, etc ).
387 Properties
389 closedGlyphs INTEGER
390 Number of horizontal equal-width images, contained in "closedIcon"
391 property.
392 Default value: 1
394 closedIcon ICON
396 Provides an icon representation for the collapsed items.
397 openedGlyphs INTEGER
399 Number of horizontal equal-width images, contained in "openedIcon"
400 property.
401 Default value: 1
403 openedIcon OBJECT
405 Provides an icon representation for the expanded items.
406 path STRING
408 Runtime-only property. Selects current file system path.
409 showDotDirs BOOLEAN
411 Selects if the directories with the first dot character are shown
412 the tree view. The treatment of the dot-prefixed names as hidden is
413 traditional to unix, and is of doubtful use under win32.
414 Default value: 0
416 Methods
418 files [ FILE_TYPE ]
419 If FILE_TYPE value is not specified, the list of all files in the
420 current directory is returned. If FILE_TYPE is given, only the
421 files of the types are returned. The FILE_TYPE is a string, one of
422 those returned by "Prima::Utils::getdir" ( see "getdir" in
423 Prima::Utils ).
424 get_directory_tree PATH
426 Reads the file structure under PATH and returns a newly created
427 hierarchy structure in the class node format. If "showDotDirs"
428 property value is 0, the dot-prefixed names are not included.
429 Used internally inside "Expand" notification.
431
433 Dmitry Karasik, <dmitry@karasik.eu.org>.
434
436 Prima, Prima::Widget, Prima::IntUtils, <examples/outline.pl>.
437perl v5.28.0 2017-02-28 Prima::Outlines(3)