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: 0

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.

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.

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.