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
.
Default value: 1
gridColor
.
Actual only in multi-column mode.
Default value: 1
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
Default value: -1
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: 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.
Doesn't have any effect in single-column mode. Default value: 1.
Only for multi-select mode.
Only for multi-select mode.
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.
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.
Stringify
notification.
MeasureItem
notification.
size
property. If set, however,
the size
property is not called, thus some speed-up can be achieved.
Only for multi-select mode.
Only for multi-select mode.
Only for multi-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.
ITEM_DRAW_DATA is an array of arrays of scalars, where each array
contains parameters of DrawItem
notification.
See DrawItem for parameters description.
Only for multi-select mode.
Only for multi-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 items.
ITEMS can be either an array, or a reference to an array of items.
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 |