NAME¶
Prima::Lists - user-selectable item list widgets
DESCRIPTION¶
The module provides classes for several abstraction layers of item
representation. The hierarchy of classes is as follows:
AbstractListViewer
AbstractListBox
ListViewer
ProtectedListBox
ListBox
The root class, "Prima::AbstractListViewer", provides common
interface, while by itself it is not directly usable. The main differences
between classes are centered around the way the item list is stored. The
simplest organization of a text-only item list, provided by
"Prima::ListBox", stores an array of text scalars in a widget. More
elaborated storage and representation types are not realized, and the
programmer is urged to use the more abstract classes to derive own mechanisms.
For example, for a list of items that contain text strings and icons see
"Prima::DirectoryListBox" in Prima::FileDialog. To organize an item
storage, different from "Prima::ListBox", it is usually enough to
overload either the "Stringify", "MeasureItem", and
"DrawItem" events, or their method counterparts:
"get_item_text", "get_item_width", and
"draw_items".
Prima::AbstractListViewer¶
"Prima::AbstractListViewer" is a descendant of
"Prima::GroupScroller", and some properties are not described here.
See "Prima::GroupScroller" in Prima::IntUtils.
The class provides interface to generic list browsing functionality, plus
functionality for text-oriented lists. The class is not usable directly.
Properties¶
- autoHeight BOOLEAN
- If 1, the item height is changed automatically when the widget font is
changed; this is useful for text items. If 0, item height is not changed;
this is useful for non-text items.
Default value: 1
- count INTEGER
- An integer property, destined to reflect number of items in the list.
Since it is tied to the item storage organization, and hence, to
possibility of changing the number of items, this property is often
declared as read-only in descendants of
"Prima::AbstractListViewer".
- dragable BOOLEAN
- If 1, allows the items to be dragged interactively by pressing control key
together with left mouse button. If 0, item dragging is disabled.
Default value: 1
- drawGrid BOOLEAN
- If 1, vertical grid lines between columns are drawn with
"gridColor". Actual only in multi-column mode.
Default value: 1
- extendedSelect BOOLEAN
- Regards the way the user selects multiple items and is only actual when
"multiSelect" is 1. If 0, the user must click each item in order
to mark as selected. If 1, the user can drag mouse or use
"Shift" key plus arrow keys to perform range selection; the
"Control" key can be used to select individual items.
Default value: 0
- focusedItem INDEX
- Selects the focused item index. If -1, no item is focused. It is mostly a
run-time property, however, it can be set during the widget creation stage
given that the item list is accessible on this stage as well.
Default value: -1
- gridColor COLOR
- Color, used for drawing vertical divider lines for multi-column list
widgets. The list classes support also the indirect way of setting the
grid color, as well as widget does, via the "colorIndex"
property. To achieve this, "ci::Grid" constant is declared ( for
more detail see "colorIndex" in Prima::Widget ).
Default value: "cl::Black".
- integralHeight BOOLEAN
- If 1, only the items that fit vertically in the widget interiors are
drawn. If 0, the items that are partially visible are drawn also.
Default value: 0
- integralWidth BOOLEAN
- If 1, only the items that fit horizontally in the widget interiors are
drawn. If 0, the items that are partially visible are drawn also. Actual
only in multi-column mode.
Default value: 0
- itemHeight INTEGER
- Selects the height of the items in pixels. Since the list classes do not
support items with different dimensions, changes to this property affect
all items.
Default value: default font height
- itemWidth INTEGER
- Selects the width of the items in pixels. Since the list classes do not
support items with different dimensions, changes to this property affect
all items.
Default value: default widget width
- multiSelect BOOLEAN
- If 0, the user can only select one item, and it is reported by the
"focusedItem" property. If 1, the user can select more than one
item. In this case, "focusedItem"'th item is not necessarily
selected. To access selected item list, use "selectedItems"
property.
Default value: 0
- multiColumn BOOLEAN
- If 0, the items are arrayed vertically in one column, and the main scroll
bar is vertical. If 1, the items are arrayed in several columns,
"itemWidth" pixels wide each. In this case, the main scroll bar
is horizontal.
- offset INTEGER
- Horizontal offset of an item list in pixels.
- topItem INTEGER
- Selects the first item drawn.
- selectedCount INTEGER
- A read-only property. Returns number of selected items.
- selectedItems ARRAY
- ARRAY is an array of integer indices of selected items.
- vertical BOOLEAN
- Sets seneral direction of items in multi-column mode. If 1, items increase
down-to-right. Otherwise, right-to-down.
Doesn't have any effect in single-column mode. Default value: 1.
Methods¶
- add_selection ARRAY, FLAG
- Sets item indices from ARRAY in selected or deselected state, depending on
FLAG value, correspondingly 1 or 0.
Only for multi-select mode.
- deselect_all
- Removes selection from all items.
Only for multi-select mode.
- draw_items CANVAS, ITEM_DRAW_DATA
- Called from within "Paint" notification to draw items. The
default behavior is to call "DrawItem" notification for every
item in ITEM_DRAW_DATA array. ITEM_DRAW_DATA is an array or arrays, where
each array consists of parameters, passed to "DrawItem"
notification.
This method is overridden in some descendant classes, to increase the speed
of drawing routine. For example, "std_draw_text_items" is the
optimized routine for drawing unified text-based items. It is used in
"Prima::ListBox" class.
See DrawItem for parameters description.
- draw_text_items CANVAS, FIRST, LAST, STEP, X, Y, OFFSET, CLIP_RECT
- Called by "std_draw_text_items" to draw sequence of text items
with indices from FIRST to LAST, by STEP, on CANVAS, starting at point X,
Y, and incrementing the vertical position with OFFSET. CLIP_RECT is a
reference to array of four integers with inclusive-inclusive coordinates
of the active clipping rectangle.
- get_item_text INDEX
- Returns text string assigned to INDEXth item. Since the class does not
assume the item storage organization, the text is queried via
"Stringify" notification.
- get_item_width INDEX
- Returns width in pixels of INDEXth item. Since the class does not assume
the item storage organization, the value is queried via
"MeasureItem" notification.
- is_selected INDEX
- Returns 1 if INDEXth item is selected, 0 if it is not.
- item2rect INDEX, [ WIDTH, HEIGHT ]
- Calculates and returns four integers with rectangle coordinates of INDEXth
item within the widget. WIDTH and HEIGHT are optional parameters with
pre-fetched dimension of the widget; if not set, the dimensions are
queried by calling "size" property. If set, however, the
"size" property is not called, thus some speed-up can be
achieved.
- point2item X, Y
- Returns the index of an item that contains point (X,Y). If the point
belongs to the item outside the widget's interior, returns the index of
the first item outside the widget's interior in the direction of the
point.
- redraw_items INDICES
- Redraws all items in INDICES array.
- select_all
- Selects all items.
Only for multi-select mode.
- set_item_selected INDEX, FLAG
- Sets selection flag of INDEXth item. If FLAG is 1, the item is selected.
If 0, it is deselected.
Only for multi-select mode.
- select_item INDEX
- Selects INDEXth item.
Only for multi-select mode.
- std_draw_text_items CANVAS, ITEM_DRAW_DATA
- An optimized method, draws unified text-based items. It is fully
compatible to "draw_items" interface, and is used in
"Prima::ListBox" class.
The optimization is derived from the assumption that items maintain common
background and foreground colors, that differ in selected and non-selected
states only. The routine groups drawing requests for selected and
non-selected items, and draws items with reduced number of calls to
"color" property. While the background is drawn by the routine
itself, the foreground ( usually text ) is delegated to the
"draw_text_items" method, so the text positioning and eventual
decorations would not require full rewrite of code.
ITEM_DRAW_DATA is an array of arrays of scalars, where each array contains
parameters of "DrawItem" notification. See DrawItem for
parameters description.
- toggle_item INDEX
- Toggles selection of INDEXth item.
Only for multi-select mode.
- unselect_item INDEX
- Deselects INDEXth item.
Only for multi-select mode.
Events¶
- Click
- Called when the user presses return key or double-clicks on an item. The
index of the item is stored in "focusedItem".
- DragItem OLD_INDEX, NEW_INDEX
- Called when the user finishes the drag of an item from OLD_INDEX to
NEW_INDEX position. The default action rearranges the item list in accord
with the dragging action.
- DrawItem CANVAS, INDEX, X1, Y1, X2, Y2, SELECTED, FOCUSED
- Called when an INDEXth item is to be drawn on CANVAS. X1, Y1, X2, Y2
designate the item rectangle in widget coordinates, where the item is to
be drawn. SELECTED and FOCUSED are boolean flags, if the item must be
drawn correspondingly in selected and focused states.
- MeasureItem INDEX, REF
- Puts width in pixels of INDEXth item into REF scalar reference. This
notification must be called from within
"begin_paint_info/end_paint_info" block.
- SelectItem INDEX, FLAG
- Called when the item changed its selection state. INDEX is the index of
the item, FLAG is its new selection state: 1 if it is selected, 0 if it is
not.
- Stringify INDEX, TEXT_REF
- Puts text string, assigned to INDEXth item into TEXT_REF scalar
reference.
Prima::AbstractListBox¶
Exactly the same as its ascendant, "Prima::AbstractListViewer", except
that it does not propagate "DrawItem" message, assuming that the
items must be drawn as text.
Prima::ListViewer¶
The class implements items storage mechanism, but leaves the items format to the
programmer. The items are accessible via "items" property and
several other helper routines.
The class also defines the user navigation, by accepting character keyboard
input and jumping to the items that have text assigned with the first letter
that match the input.
"Prima::ListViewer" is derived from
"Prima::AbstractListViewer".
Properties¶
- autoWidth BOOLEAN
- Selects if the gross item width must be recalculated automatically when
either the font changes or item list is changed.
Default value: 1
- count INTEGER
- A read-only property; returns number of items.
- items ARRAY
- Accesses the storage array of items. The format of items is not defined,
it is merely treated as one scalar per index.
Methods¶
- add_items ITEMS
- Appends array of ITEMS to the end of the list.
- calibrate
- Recalculates all item widths and adjusts "itemWidth" if
"autoWidth" is set.
- delete_items INDICES
- Deletes items from the list. INDICES can be either an array, or a
reference to an array of item indices.
- get_item_width INDEX
- Returns width in pixels of INDEXth item from internal cache.
- get_items INDICES
- Returns array of items. INDICES can be either an array, or a reference to
an array of item indices. Depending on the caller context, the results are
different: in array context the item list is returned; in scalar - only
the first item from the list. The semantic of the last call is naturally
usable only for single item retrieval.
- insert_items OFFSET, ITEMS
- Inserts array of items at OFFSET index in the list. Offset must be a valid
index; to insert items at the end of the list use "add_items"
method.
ITEMS can be either an array, or a reference to an array of items.
- replace_items OFFSET, ITEMS
- Replaces existing items at OFFSET index in the list. Offset must be a
valid index.
ITEMS can be either an array, or a reference to an array of items.
Prima::ProtectedListBox¶
A semi-demonstrational class, derived from "Prima::ListViewer", that
applies certain protection for every item drawing session. Assuming that
several item drawing routines can be assembled in one widget,
"Prima::ProtectedListBox" provides a safety layer between these, so,
for example, one drawing routine that selects a font or a color and does not
care to restore the old value back, does not affect the outlook of the other
items.
This functionality is implementing by overloading "draw_items" method
and also all graphic properties.
Prima::ListBox¶
Descendant of "Prima::ListViewer", declares format of items as a
single text string. Incorporating all of functionality of its predecessors,
provides a standard listbox widget.
Synopsis¶
my $lb = Prima::ListBox-> create(
items => [qw(First Second Third)],
focusedItem => 2,
onClick => sub {
print $_[0]-> get_items( $_[0]-> focusedItem), " is selected\n";
}
);
Methods¶
- get_item_text INDEX
- Returns text string assigned to INDEXth item. Since the item storage
organization is implemented, does so without calling "Stringify"
notification.
AUTHOR¶
Dmitry Karasik, <dmitry@karasik.eu.org>.
SEE ALSO¶
Prima, Prima::Widget, Prima::ComboBox, Prima::FileDialog,
examples/editor.pl