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::Dialog::FileDialog.
27 To 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
34 "Prima::Widget::GroupScroller", and some properties are not described
35 here.
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 general 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 vertical position with OFFSET. CLIP_RECT
186 is a reference to array of four integers with inclusive-inclusive
187 coordinates of the active clipping rectangle.
188 Note that OFFSET must be an integer, otherwise bad effects will be
190 observed when text is drawn below Y=0
191 get_item_text INDEX
193 Returns text string assigned to INDEXth item. Since the class does
194 not assume the item storage organization, the text is queried via
195 "Stringify" notification.
196 get_item_width INDEX
198 Returns width in pixels of INDEXth item. Since the class does not
199 assume the item storage organization, the value is queried via
200 "MeasureItem" notification.
201 is_selected INDEX
203 Returns 1 if INDEXth item is selected, 0 if it is not.
204 item2rect INDEX, [ WIDTH, HEIGHT ]
206 Calculates and returns four integers with rectangle coordinates of
207 INDEXth item within the widget. WIDTH and HEIGHT are optional
208 parameters with pre-fetched dimension of the widget; if not set,
209 the dimensions are queried by calling "size" property. If set,
210 however, the "size" property is not called, thus some speed-up can
211 be achieved.
212 point2item X, Y
214 Returns the index of an item that contains point (X,Y). If the
215 point belongs to the item outside the widget's interior, returns
216 the index of the first item outside the widget's interior in the
217 direction of the point.
218 redraw_items INDICES
220 Redraws all items in INDICES array.
221 select_all
223 Selects all items.
224 Only for multi-select mode.
226 set_item_selected INDEX, FLAG
228 Sets selection flag of INDEXth item. If FLAG is 1, the item is
229 selected. If 0, it is deselected.
230 Only for multi-select mode.
232 select_item INDEX
234 Selects INDEXth item.
235 Only for multi-select mode.
237 std_draw_text_items CANVAS, ITEM_DRAW_DATA
239 An optimized method, draws unified text-based items. It is fully
240 compatible to "draw_items" interface, and is used in
241 "Prima::ListBox" class.
242 The optimization is derived from the assumption that items maintain
244 common background and foreground colors, that differ in selected
245 and non-selected states only. The routine groups drawing requests
246 for selected and non-selected items, and draws items with reduced
247 number of calls to "color" property. While the background is drawn
248 by the routine itself, the foreground ( usually text ) is delegated
249 to the "draw_text_items" method, so the text positioning and
250 eventual decorations would not require full rewrite of code.
251 ITEM_DRAW_DATA is an array of arrays of scalars, where each array
253 contains parameters of "DrawItem" notification. See DrawItem for
254 parameters description.
255 toggle_item INDEX
257 Toggles selection of INDEXth item.
258 Only for multi-select mode.
260 unselect_item INDEX
262 Deselects INDEXth item.
263 Only for multi-select mode.
265 Events
267 Click
268 Called when the user presses return key or double-clicks on an
269 item. The index of the item is stored in "focusedItem".
270 DragItem OLD_INDEX, NEW_INDEX
272 Called when the user finishes the drag of an item from OLD_INDEX to
273 NEW_INDEX position. The default action rearranges the item list in
274 accord with the dragging action.
275 DrawItem CANVAS, INDEX, X1, Y1, X2, Y2, SELECTED, FOCUSED, PRELIGHT,
277 COLUMN
278 Called when an INDEXth item is to be drawn on CANVAS. X1, Y1, X2,
279 Y2 designate the item rectangle in widget coordinates, where the
280 item is to be drawn. SELECTED, FOCUSED, and PRELIGHT are boolean
281 flags, if the item must be drawn correspondingly in selected and
282 focused states, with or without the prelight effect.
283 MeasureItem INDEX, REF
285 Puts width in pixels of INDEXth item into REF scalar reference.
286 This notification must be called from within
287 "begin_paint_info/end_paint_info" block.
288 SelectItem INDEX, FLAG
290 Called when the item changed its selection state. INDEX is the
291 index of the item, FLAG is its new selection state: 1 if it is
292 selected, 0 if it is not.
293 Stringify INDEX, TEXT_REF
295 Puts text string, assigned to INDEXth item into TEXT_REF scalar
296 reference.
297
299 Exactly the same as its ascendant, "Prima::AbstractListViewer", except
300 that it does not propagate "DrawItem" message, assuming that the items
301 must be drawn as text.
302
304 The class implements items storage mechanism, but leaves the items
305 format to the programmer. The items are accessible via "items" property
306 and several other helper routines.
307 The class also defines the user navigation, by accepting character
309 keyboard input and jumping to the items that have text assigned with
310 the first letter that match the input.
311 "Prima::ListViewer" is derived from "Prima::AbstractListViewer".
313 Properties
315 autoWidth BOOLEAN
316 Selects if the gross item width must be recalculated automatically
317 when either the font changes or item list is changed.
318 Default value: 1
320 count INTEGER
322 A read-only property; returns number of items.
323 items ARRAY
325 Accesses the storage array of items. The format of items is not
326 defined, it is merely treated as one scalar per index.
327 Methods
329 add_items ITEMS
330 Appends array of ITEMS to the end of the list.
331 calibrate
333 Recalculates all item widths and adjusts "itemWidth" if "autoWidth"
334 is set.
335 delete_items INDICES
337 Deletes items from the list. INDICES can be either an array, or a
338 reference to an array of item indices.
339 get_item_width INDEX
341 Returns width in pixels of INDEXth item from internal cache.
342 get_items INDICES
344 Returns array of items. INDICES can be either an array, or a
345 reference to an array of item indices. Depending on the caller
346 context, the results are different: in array context the item list
347 is returned; in scalar - only the first item from the list. The
348 semantic of the last call is naturally usable only for single item
349 retrieval.
350 insert_items OFFSET, ITEMS
352 Inserts array of items at OFFSET index in the list. Offset must be
353 a valid index; to insert items at the end of the list use
354 "add_items" method.
355 ITEMS can be either an array, or a reference to an array of items.
357 replace_items OFFSET, ITEMS
359 Replaces existing items at OFFSET index in the list. Offset must
360 be a valid index.
361 ITEMS can be either an array, or a reference to an array of items.
363
365 A semi-demonstrational class, derived from "Prima::ListViewer", that
366 applies certain protection for every item drawing session. Assuming
367 that several item drawing routines can be assembled in one widget,
368 "Prima::ProtectedListBox" provides a safety layer between these, so,
369 for example, one drawing routine that selects a font or a color and
370 does not care to restore the old value back, does not affect the
371 outlook of the other items.
372 This functionality is implementing by overloading "draw_items" method
374 and also all graphic properties.
375
377 Descendant of "Prima::ListViewer", declares format of items as a single
378 text string. Incorporating all of functionality of its predecessors,
379 provides a standard listbox widget.
380 Synopsis
382 my $lb = Prima::ListBox-> create(
383 items => [qw(First Second Third)],
384 focusedItem => 2,
385 onClick => sub {
386 print $_[0]-> get_items( $_[0]-> focusedItem), " is selected\n";
387 }
388 );
389 Methods
391 get_item_text INDEX
392 Returns text string assigned to INDEXth item. Since the item
393 storage organization is implemented, does so without calling
394 "Stringify" notification.
395
397 Dmitry Karasik, <dmitry@karasik.eu.org>.
398
400 Prima, Prima::Widget, Prima::ComboBox, Prima::Dialog::FileDialog,
401 examples/editor.pl
402perl v5.38.0 2023-07-21 Prima::Lists(3)