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