Prima::Lists(3)

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 the section on 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
Prima::AbstractListViewer is a descendant of Prima::GroupScroller, and some properties are not described here. See the section on 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.

  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.

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.

    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

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.

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 the colorIndex entry in the Prima::Widget manpage ).

    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

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.

  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 mult-select mode.

draw_items CANVAS, ITEMS
    Called from within 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 the DrawItem manpage for parameters description.

draw_text_items CANVAS, FIRST, LAST, X, Y, OFFSET, CLIP_RECT
    Called by std_draw_text_items to draw sequence of text items with indices 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.

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 ITEMS
    Redraws all items in ITEMS array.

select_all
    Selects all items.

    Only for mult-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 mult-select mode.

select_item INDEX
    Selects INDEXth item.

    Only for mult-select mode.

std_draw_text_items CANVAS, ITEMS
    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.

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

toggle_item INDEX
    Toggles selection of INDEXth item.

    Only for mult-select mode.

unselect_item INDEX
    Deselects INDEXth item.

    Only for mult-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.

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 ITEMS
    Deletes items from the list. ITEMS 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 ITEMS
    Returns array of items. ITEMS 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 item indices.

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
the Prima manpage, the Prima::Widget manpage, the Prima::ComboBox manpage, the Prima::FileDialog manpage, examples/editor.pl