|
Prima::Lists - user-selectable item list widgets |
Prima::Lists - user-selectable item list widgets
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 the Prima::FileDialog manpage.
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 is a descendant of Prima::GroupScroller,
and some properties are not described here. See Prima::GroupScroller in the Prima::IntUtils manpage.
The class provides interface to generic list browsing functionality, plus functionality for text-oriented lists. The class is not usable directly.
Default value: 1
Prima::AbstractListViewer.
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.
Default value: 0
Default value: -1
Stringify notification.
MeasureItem notification.
colorIndex property. To achieve this, ci::Grid constant
is declared ( for more detail see colorIndex in the Prima::Widget manpage ).
Default value: cl::Black.
Default value: 0
Default value: default font height
Default value: default widget width
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
itemWidth
pixels wide each. In this case, the main scroll bar is horizontal.
Only for multi-select mode.
Only for mult-select mode.
Paint notification to draw
items. The default behavior is to call DrawItem
notification for every item in ITEMS array. ITEMS
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.
std_draw_text_items to draw sequence of text items with
indexes from FIRST to LAST 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.
size property. If set, however,
the size property is not called, thus some speed-up can be achieved.
Only for mult-select mode.
Only for mult-select mode.
Only for mult-select mode.
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.
ITEMS is an array of arrays of scalars, where each array
contains parameters of DrawItem notification.
See DrawItem for parameters description.
Only for mult-select mode.
Only for mult-select mode.
focusedItem.
begin_paint_info/end_paint_info block.
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.
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.
Default value: 1
itemWidth if
autoWidth is set.
add_items method.
ITEMS can be either an array, or a reference to an array of item indeces.
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.
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.
my $lb = Prima::ListBox-> create(
items => [qw(First Second Third)],
focusedItem => 2,
onClick => sub {
print $_[0]-> get_items( $_[0]-> focusedItem), " is selected\n";
}
);
Stringify notification.
Dmitry Karasik, <dmitry@karasik.eu.org>.
Prima, the Prima::Widget manpage, the Prima::ComboBox manpage, the Prima::FileDialog manpage, examples/editor.pl
|
Prima::Lists - user-selectable item list widgets |