NAME

Prima::Lists - list widgets

DESCRIPTION

The module provides several listbox classes that differ in the way items in the list widget are associated with data. The hierarchy of classes is as follows:

AbstractListViewer
	AbstractListBox
	ListViewer
		ProtectedListBox
		ListBox

The root class Prima::AbstractListViewer provides a common interface that is though not usable directly. The main differences between classes are centered around the way the items are 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 their own mechanisms. For example, for a list of items that contain text strings and icons see "Prima::DirectoryListBox" in Prima::Dialog::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::Widget::GroupScroller, and some of its properties are not described here.

The class provides an 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, the item height is not changed; this is useful for non-text items.

Default value: 1

count INTEGER

An integer property, used to access the number of items in the list. Since it is tied to the item storage organization, and hence the 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 the Control key together with the 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

Manages the way the user selects multiple items that is only actual when multiSelect is 1. If 0, the user must click each item to mark it as selected. If 1, the user can drag the mouse or use the 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 at 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 the widget does, via the colorIndex property. To achieve this, the 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 partially visible items 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 partially visible items are drawn also. Actual only in the 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 variable heights, 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 variable widths, 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, the focusedItem'th item is not necessarily selected. To access the selected item list use the selectedItems property.

Default value: 0

multiColumn BOOLEAN

If 0, the items are arranged vertically in a single column and the main scroll bar is vertical. If 1, the items are arranged in several columns, each itemWidth pixels wide. 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 the number of selected items.

selectedItems ARRAY

ARRAY is an array of integer indices of selected items.

vertical BOOLEAN

Sets the general 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 the FLAG value, correspondingly 1 or 0.

Only for the multi-select mode.

deselect_all

Clears the selection

Only for the multi-select mode.

draw_items CANVAS, ITEM_DRAW_DATA

Called from within the Paint notification to draw items. The default behavior is to call the DrawItem notification for every item in the ITEM_DRAW_DATA array. ITEM_DRAW_DATA is an array or arrays, where each array consists of parameters passed to the DrawItem notification.

This method is overridden in some descendant classes to increase the speed of drawing. For example, std_draw_text_items is the optimized routine for drawing text-based items. It is used in the Prima::ListBox class.

See DrawItem for the description of the parameters.

draw_text_items CANVAS, FIRST, LAST, STEP, X, Y, OFFSET, CLIP_RECT

Called by std_draw_text_items to draw a 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 an array of four integers given in the inclusive-inclusive coordinates that represent the active clipping rectangle.

Note that OFFSET must be an integer, otherwise bad effects will be observed when text is drawn below Y=0

get_item_text INDEX

Returns the text string assigned to the INDEXth item. Since the class does not assume the item storage organization, the text is queried via the Stringify notification.

get_item_width INDEX

Returns width in pixels of the INDEXth item. Since the class does not assume the item storage organization, the value is queried via the MeasureItem notification.

is_selected INDEX

Returns 1 if the INDEXth item is selected, 0 otherwise.

item2rect INDEX, [ WIDTH, HEIGHT ]

Calculates and returns four integers with rectangle coordinates of the INDEXth item. WIDTH and HEIGHT are optional parameters with pre-fetched dimensions of the widget; if not set, the dimensions are queried by calling the 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 the point at (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 the INDICES array.

select_all

Selects all items.

Only for the multi-select mode.

set_item_selected INDEX, FLAG

Sets the selection flag on the INDEXth item. If FLAG is 1, the item is selected. If 0, it is deselected.

Only for the multi-select mode.

select_item INDEX

Selects the INDEXth item.

Only for the multi-select mode.

std_draw_text_items CANVAS, ITEM_DRAW_DATA

An optimized method, draws text-based items. It is fully compatible with the draw_items interface and is used in the Prima::ListBox class.

The optimization is derived from the assumption that items maintain common background and foreground colors, that only differ in the selected and non-selected states. The routine groups drawing requests for selected and non-selected items, and then draws items with a reduced number of calls to the color property. While the background is drawn by the routine itself, the foreground ( usually text ) is delegated to the draw_text_items method, so that the text positioning and eventual decorations would be easier to implement.

ITEM_DRAW_DATA is an array of arrays of scalars, where each array contains parameters of the DrawItem notification. See DrawItem for the description of the parameters.

toggle_item INDEX

Toggles selection of the INDEXth item.

Only for the multi-select mode.

unselect_item INDEX

Deselects the INDEXth item.

Only for the multi-select mode.

Events

Click

Called when the user presses the 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 according to the dragging action.

DrawItem CANVAS, INDEX, X1, Y1, X2, Y2, SELECTED, FOCUSED, PRELIGHT, COLUMN

Called when the INDEXth item is to be drawn on CANVAS. X1, Y1, X2, Y2 define the item rectangle in widget coordinates where the item is to be drawn. SELECTED, FOCUSED, and PRELIGHT are boolean flags, if the item must be drawn correspondingly in selected and focused states, with or without the prelight effect.

MeasureItem INDEX, REF

Stores width in pixels of the INDEXth item into the REF scalar reference. This notification must be called from within the begin_paint_info/end_paint_info block.

SelectItem INDEX, FLAG

Called when an item changes 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

Stores the text string associated with the INDEXth item into TEXT_REF scalar reference.

Prima::AbstractListBox

The same as its ascendant Prima::AbstractListViewer except that it does not the propagate DrawItem message, assuming that all items must be drawn as text strings.

Prima::ListViewer

The class implements an item storage mechanism but leaves the definition of the format of the item to the programmer. The items are accessible via the items property and several other helper routines.

The class also defines user navigation by accepting character keyboard input and jumping to the items that have text assigned with the first letter that matches the input.

Prima::ListViewer is derived from Prima::AbstractListViewer.

Properties

autoWidth BOOLEAN

Selects if the item width must be recalculated automatically when either the font or item list is changed.

Default value: 1

count INTEGER

A read-only property; returns the number of items.

items ARRAY

Accesses the storage array of the items. The format of items is not defined, it is merely treated as one scalar per index.

Methods

add_items ITEMS

Appends an array of ITEMS to the end of the item list.

calibrate

Recalculates all item widths. 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 the width in pixels of the INDEXth item from the internal cache.

get_items INDICES

Returns an 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 the array context the item list is returned; in scalar - only the first item from the list.

insert_items OFFSET, ITEMS

Inserts an array of items at the OFFSET index in the list. Offset must be a valid index; to insert items at the end of the list use the 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 the OFFSET index in the list. The 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, implements certain protections for every item during drawing. Assuming that several item drawing algorithms can be used in the same widget, Prima::ProtectedListBox provides a safety layer between these. If an algorithm selects a font or a color and does not restore the old value, this does not affect the outlook of other items.

This functionality is implemented by overloading the draw_items method and also all graphic properties.

Prima::ListBox

Descendant of Prima::ListViewer, declares that an item must be a single text string. Incorporating all the functionality of its predecessors, provides the standard workhorse 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 the text string associated with the INDEXth item. Since the item storage organization is implemented, does so without calling the Stringify notification.

AUTHOR

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

SEE ALSO

Prima, Prima::Widget, Prima::ComboBox, Prima::Dialog::FileDialog, examples/editor.pl

cpanm Prima

perl -MCPAN -e shell
install Prima