1Prima::Lists(3) User Contributed Perl Documentation Prima::Lists(3)
2
6 Prima::Lists - user-selectable item list widgets
7
9 The module provides classes for several abstraction layers of item
10 representation. The hierarchy of classes is as follows:
11 AbstractListViewer
13 AbstractListBox
14 ListViewer
15 ProtectedListBox
16 ListBox
17 The root class, "Prima::AbstractListViewer", provides common interface,
19 while by itself it is not directly usable. The main differences
20 between classes are centered around the way the item list is stored.
21 The simplest organization of a text-only item list, provided by
22 "Prima::ListBox", stores an array of text scalars in a widget. More
23 elaborated storage and representation types are not realized, and the
24 programmer is urged to use the more abstract classes to derive own
25 mechanisms. For example, for a list of items that contain text strings
26 and icons see "Prima::DirectoryListBox" in Prima::FileDialog. To
27 organize an item storage, different from "Prima::ListBox", it is
28 usually enough to overload either the "Stringify", "MeasureItem", and
29 "DrawItem" events, or their method counterparts: "get_item_text",
30 "get_item_width", and "draw_items".
31
33 "Prima::AbstractListViewer" is a descendant of "Prima::GroupScroller",
34 and some properties are not described here. See "Prima::GroupScroller"
35 in Prima::IntUtils.
36 The class provides interface to generic list browsing functionality,
38 plus functionality for text-oriented lists. The class is not usable
39 directly.
40 Properties
42 autoHeight BOOLEAN
43 If 1, the item height is changed automatically when the widget font
44 is changed; this is useful for text items. If 0, item height is
45 not changed; this is useful for non-text items.
46 Default value: 1
48 count INTEGER
50 An integer property, destined to reflect number of items in the
51 list. Since it is tied to the item storage organization, and
52 hence, to possibility of changing the number of items, this
53 property is often declared as read-only in descendants of
54 "Prima::AbstractListViewer".
55 dragable BOOLEAN
57 If 1, allows the items to be dragged interactively by pressing
58 control key together with left mouse button. If 0, item dragging is
59 disabled.
60 Default value: 1
62 drawGrid BOOLEAN
64 If 1, vertical grid lines between columns are drawn with
65 "gridColor". Actual only in multi-column mode.
66 Default value: 1
68 extendedSelect BOOLEAN
70 Regards the way the user selects multiple items and is only actual
71 when "multiSelect" is 1. If 0, the user must click each item in
72 order to mark as selected. If 1, the user can drag mouse or use
73 "Shift" key plus arrow keys to perform range selection; the
74 "Control" key can be used to select individual items.
75 Default value: 0
77 focusedItem INDEX
79 Selects the focused item index. If -1, no item is focused. It is
80 mostly a run-time property, however, it can be set during the
81 widget creation stage given that the item list is accessible on
82 this stage as well.
83 Default value: -1
85 gridColor COLOR
87 Color, used for drawing vertical divider lines for multi-column
88 list widgets. The list classes support also the indirect way of
89 setting the grid color, as well as widget does, via the
90 "colorIndex" property. To achieve this, "ci::Grid" constant is
91 declared ( for more detail see "colorIndex" in Prima::Widget ).
92 Default value: "cl::Black".
94 integralHeight BOOLEAN
96 If 1, only the items that fit vertically in the widget interiors
97 are drawn. If 0, the items that are partially visible are drawn
98 also.
99 Default value: 0
101 integralWidth BOOLEAN
103 If 1, only the items that fit horizontally in the widget interiors
104 are drawn. If 0, the items that are partially visible are drawn
105 also. Actual only in multi-column mode.
106 Default value: 0
108 itemHeight INTEGER
110 Selects the height of the items in pixels. Since the list classes
111 do not support items with different dimensions, changes to this
112 property affect all items.
113 Default value: default font height
115 itemWidth INTEGER
117 Selects the width of the items in pixels. Since the list classes do
118 not support items with different dimensions, changes to this
119 property affect all items.
120 Default value: default widget width
122 multiSelect BOOLEAN
124 If 0, the user can only select one item, and it is reported by the
125 "focusedItem" property. If 1, the user can select more than one
126 item. In this case, "focusedItem"'th item is not necessarily
127 selected. To access selected item list, use "selectedItems"
128 property.
129 Default value: 0
131 multiColumn BOOLEAN
133 If 0, the items are arrayed vertically in one column, and the main
134 scroll bar is vertical. If 1, the items are arrayed in several
135 columns, "itemWidth" pixels wide each. In this case, the main
136 scroll bar is horizontal.
137 offset INTEGER
139 Horizontal offset of an item list in pixels.
140 topItem INTEGER
142 Selects the first item drawn.
143 selectedCount INTEGER
145 A read-only property. Returns number of selected items.
146 selectedItems ARRAY
148 ARRAY is an array of integer indices of selected items.
149 vertical BOOLEAN
151 Sets seneral direction of items in multi-column mode. If 1, items
152 increase down-to-right. Otherwise, right-to-down.
153 Doesn't have any effect in single-column mode. Default value: 1.
155 Methods
157 add_selection ARRAY, FLAG
158 Sets item indices from ARRAY in selected or deselected state,
159 depending on FLAG value, correspondingly 1 or 0.
160 Only for multi-select mode.
162 deselect_all
164 Removes selection from all items.
165 Only for multi-select mode.
167 draw_items CANVAS, ITEM_DRAW_DATA
169 Called from within "Paint" notification to draw items. The default
170 behavior is to call "DrawItem" notification for every item in
171 ITEM_DRAW_DATA array. ITEM_DRAW_DATA is an array or arrays, where
172 each array consists of parameters, passed to "DrawItem"
173 notification.
174 This method is overridden in some descendant classes, to increase
176 the speed of drawing routine. For example, "std_draw_text_items" is
177 the optimized routine for drawing unified text-based items. It is
178 used in "Prima::ListBox" class.
179 See DrawItem for parameters description.
181 draw_text_items CANVAS, FIRST, LAST, STEP, X, Y, OFFSET, CLIP_RECT
183 Called by "std_draw_text_items" to draw sequence of text items with
184 indices from FIRST to LAST, by STEP, on CANVAS, starting at point
185 X, Y, and incrementing the horizontal position with OFFSET.
186 CLIP_RECT is a reference to array of four integers with inclusive-
187 inclusive coordinates of the active clipping rectangle.
188 get_item_text INDEX
190 Returns text string assigned to INDEXth item. Since the class does
191 not assume the item storage organization, the text is queried via
192 "Stringify" notification.
193 get_item_width INDEX
195 Returns width in pixels of INDEXth item. Since the class does not
196 assume the item storage organization, the value is queried via
197 "MeasureItem" notification.
198 is_selected INDEX
200 Returns 1 if INDEXth item is selected, 0 if it is not.
201 item2rect INDEX, [ WIDTH, HEIGHT ]
203 Calculates and returns four integers with rectangle coordinates of
204 INDEXth item within the widget. WIDTH and HEIGHT are optional
205 parameters with pre-fetched dimension of the widget; if not set,
206 the dimensions are queried by calling "size" property. If set,
207 however, the "size" property is not called, thus some speed-up can
208 be achieved.
209 point2item X, Y
211 Returns the index of an item that contains point (X,Y). If the
212 point belongs to the item outside the widget's interior, returns
213 the index of the first item outside the widget's interior in the
214 direction of the point.
215 redraw_items INDICES
217 Redraws all items in INDICES array.
218 select_all
220 Selects all items.
221 Only for multi-select mode.
223 set_item_selected INDEX, FLAG
225 Sets selection flag of INDEXth item. If FLAG is 1, the item is
226 selected. If 0, it is deselected.
227 Only for multi-select mode.
229 select_item INDEX
231 Selects INDEXth item.
232 Only for multi-select mode.
234 std_draw_text_items CANVAS, ITEM_DRAW_DATA
236 An optimized method, draws unified text-based items. It is fully
237 compatible to "draw_items" interface, and is used in
238 "Prima::ListBox" class.
239 The optimization is derived from the assumption that items maintain
241 common background and foreground colors, that differ in selected
242 and non-selected states only. The routine groups drawing requests
243 for selected and non-selected items, and draws items with reduced
244 number of calls to "color" property. While the background is drawn
245 by the routine itself, the foreground ( usually text ) is delegated
246 to the "draw_text_items" method, so the text positioning and
247 eventual decorations would not require full rewrite of code.
248 ITEM_DRAW_DATA is an array of arrays of scalars, where each array
250 contains parameters of "DrawItem" notification. See DrawItem for
251 parameters description.
252 toggle_item INDEX
254 Toggles selection of INDEXth item.
255 Only for multi-select mode.
257 unselect_item INDEX
259 Deselects INDEXth item.
260 Only for multi-select mode.
262 Events
264 Click
265 Called when the user presses return key or double-clicks on an
266 item. The index of the item is stored in "focusedItem".
267 DragItem OLD_INDEX, NEW_INDEX
269 Called when the user finishes the drag of an item from OLD_INDEX to
270 NEW_INDEX position. The default action rearranges the item list in
271 accord with the dragging action.
272 DrawItem CANVAS, INDEX, X1, Y1, X2, Y2, SELECTED, FOCUSED, PRELIGHT,
274 COLUMN
275 Called when an INDEXth item is to be drawn on CANVAS. X1, Y1, X2,
276 Y2 designate the item rectangle in widget coordinates, where the
277 item is to be drawn. SELECTED, FOCUSED, and PRELIGHT are boolean
278 flags, if the item must be drawn correspondingly in selected and
279 focused states, with or without the prelight effect.
280 MeasureItem INDEX, REF
282 Puts width in pixels of INDEXth item into REF scalar reference.
283 This notification must be called from within
284 "begin_paint_info/end_paint_info" block.
285 SelectItem INDEX, FLAG
287 Called when the item changed its selection state. INDEX is the
288 index of the item, FLAG is its new selection state: 1 if it is
289 selected, 0 if it is not.
290 Stringify INDEX, TEXT_REF
292 Puts text string, assigned to INDEXth item into TEXT_REF scalar
293 reference.
294
296 Exactly the same as its ascendant, "Prima::AbstractListViewer", except
297 that it does not propagate "DrawItem" message, assuming that the items
298 must be drawn as text.
299
301 The class implements items storage mechanism, but leaves the items
302 format to the programmer. The items are accessible via "items" property
303 and several other helper routines.
304 The class also defines the user navigation, by accepting character
306 keyboard input and jumping to the items that have text assigned with
307 the first letter that match the input.
308 "Prima::ListViewer" is derived from "Prima::AbstractListViewer".
310 Properties
312 autoWidth BOOLEAN
313 Selects if the gross item width must be recalculated automatically
314 when either the font changes or item list is changed.
315 Default value: 1
317 count INTEGER
319 A read-only property; returns number of items.
320 items ARRAY
322 Accesses the storage array of items. The format of items is not
323 defined, it is merely treated as one scalar per index.
324 Methods
326 add_items ITEMS
327 Appends array of ITEMS to the end of the list.
328 calibrate
330 Recalculates all item widths and adjusts "itemWidth" if "autoWidth"
331 is set.
332 delete_items INDICES
334 Deletes items from the list. INDICES can be either an array, or a
335 reference to an array of item indices.
336 get_item_width INDEX
338 Returns width in pixels of INDEXth item from internal cache.
339 get_items INDICES
341 Returns array of items. INDICES can be either an array, or a
342 reference to an array of item indices. Depending on the caller
343 context, the results are different: in array context the item list
344 is returned; in scalar - only the first item from the list. The
345 semantic of the last call is naturally usable only for single item
346 retrieval.
347 insert_items OFFSET, ITEMS
349 Inserts array of items at OFFSET index in the list. Offset must be
350 a valid index; to insert items at the end of the list use
351 "add_items" method.
352 ITEMS can be either an array, or a reference to an array of items.
354 replace_items OFFSET, ITEMS
356 Replaces existing items at OFFSET index in the list. Offset must
357 be a valid index.
358 ITEMS can be either an array, or a reference to an array of items.
360
362 A semi-demonstrational class, derived from "Prima::ListViewer", that
363 applies certain protection for every item drawing session. Assuming
364 that several item drawing routines can be assembled in one widget,
365 "Prima::ProtectedListBox" provides a safety layer between these, so,
366 for example, one drawing routine that selects a font or a color and
367 does not care to restore the old value back, does not affect the
368 outlook of the other items.
369 This functionality is implementing by overloading "draw_items" method
371 and also all graphic properties.
372
374 Descendant of "Prima::ListViewer", declares format of items as a single
375 text string. Incorporating all of functionality of its predecessors,
376 provides a standard listbox widget.
377 Synopsis
379 my $lb = Prima::ListBox-> create(
380 items => [qw(First Second Third)],
381 focusedItem => 2,
382 onClick => sub {
383 print $_[0]-> get_items( $_[0]-> focusedItem), " is selected\n";
384 }
385 );
386 Methods
388 get_item_text INDEX
389 Returns text string assigned to INDEXth item. Since the item
390 storage organization is implemented, does so without calling
391 "Stringify" notification.
392
394 Dmitry Karasik, <dmitry@karasik.eu.org>.
395
397 Prima, Prima::Widget, Prima::ComboBox, Prima::FileDialog,
398 examples/editor.pl
399perl v5.30.0 2019-08-21 Prima::Lists(3)