1Prima::Lists(3)       User Contributed Perl Documentation      Prima::Lists(3)
2
3
4

NAME

6       Prima::Lists - user-selectable item list widgets
7

DESCRIPTION

9       The module provides classes for several abstraction layers of item
10       representation. The hierarchy of classes is as follows:
11
12               AbstractListViewer
13                       AbstractListBox
14                       ListViewer
15                               ProtectedListBox
16                               ListBox
17
18       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

Prima::AbstractListViewer

33       "Prima::AbstractListViewer" is a descendant of
34       "Prima::Widget::GroupScroller", and some properties are not described
35       here.
36
37       The class provides interface to generic list browsing functionality,
38       plus functionality for text-oriented lists. The class is not usable
39       directly.
40
41   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
47           Default value: 1
48
49       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
56       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
61           Default value: 1
62
63       drawGrid BOOLEAN
64           If 1, vertical grid lines between columns are drawn with
65           "gridColor".  Actual only in multi-column mode.
66
67           Default value: 1
68
69       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
76           Default value: 0
77
78       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
84           Default value: -1
85
86       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
93           Default value: "cl::Black".
94
95       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
100           Default value: 0
101
102       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
107           Default value: 0
108
109       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
114           Default value: default font height
115
116       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
121           Default value: default widget width
122
123       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
130           Default value: 0
131
132       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
138       offset INTEGER
139           Horizontal offset of an item list in pixels.
140
141       topItem INTEGER
142           Selects the first item drawn.
143
144       selectedCount INTEGER
145           A read-only property. Returns number of selected items.
146
147       selectedItems ARRAY
148           ARRAY is an array of integer indices of selected items.
149
150       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
154           Doesn't have any effect in single-column mode.  Default value: 1.
155
156   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
161           Only for multi-select mode.
162
163       deselect_all
164           Removes selection from all items.
165
166           Only for multi-select mode.
167
168       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
175           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
180           See DrawItem for parameters description.
181
182       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
189           Note that OFFSET must be an integer, otherwise bad effects will be
190           observed when text is drawn below Y=0
191
192       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
197       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
202       is_selected INDEX
203           Returns 1 if INDEXth item is selected, 0 if it is not.
204
205       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
213       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
219       redraw_items INDICES
220           Redraws all items in INDICES array.
221
222       select_all
223           Selects all items.
224
225           Only for multi-select mode.
226
227       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
231           Only for multi-select mode.
232
233       select_item INDEX
234           Selects INDEXth item.
235
236           Only for multi-select mode.
237
238       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
243           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
252           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
256       toggle_item INDEX
257           Toggles selection of INDEXth item.
258
259           Only for multi-select mode.
260
261       unselect_item INDEX
262           Deselects INDEXth item.
263
264           Only for multi-select mode.
265
266   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
271       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
276       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
284       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
289       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
294       Stringify INDEX, TEXT_REF
295           Puts text string, assigned to INDEXth item into TEXT_REF scalar
296           reference.
297

Prima::AbstractListBox

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

Prima::ListViewer

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
308       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
312       "Prima::ListViewer" is derived from "Prima::AbstractListViewer".
313
314   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
319           Default value: 1
320
321       count INTEGER
322           A read-only property; returns number of items.
323
324       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
328   Methods
329       add_items ITEMS
330           Appends array of ITEMS to the end of the list.
331
332       calibrate
333           Recalculates all item widths and adjusts "itemWidth" if "autoWidth"
334           is set.
335
336       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
340       get_item_width INDEX
341           Returns width in pixels of INDEXth item from internal cache.
342
343       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
351       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
356           ITEMS can be either an array, or a reference to an array of items.
357
358       replace_items OFFSET, ITEMS
359           Replaces existing items at OFFSET index in the list.  Offset must
360           be a valid index.
361
362           ITEMS can be either an array, or a reference to an array of items.
363

Prima::ProtectedListBox

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
373       This functionality is implementing by overloading "draw_items" method
374       and also all graphic properties.
375

Prima::ListBox

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
381   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
390   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

AUTHOR

397       Dmitry Karasik, <dmitry@karasik.eu.org>.
398

SEE ALSO

400       Prima, Prima::Widget, Prima::ComboBox, Prima::Dialog::FileDialog,
401       examples/editor.pl
402
403
404
405perl v5.38.0                      2023-07-21                   Prima::Lists(3)
Impressum