Provided by: libprima-perl_1.28-1.2_amd64 bug

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 "Prima::DirectoryListBox" in Prima::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::GroupScroller", and some properties
       are not described here. See "Prima::GroupScroller" in Prima::IntUtils.

       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".

       dragable BOOLEAN
           If 1, allows the items to be dragged interactively by pressing control key together
           with 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
           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; 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 on 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 widget
           does, via the "colorIndex" property. To achieve this, "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
           items that are partially visible 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 items that are partially visible are drawn also.  Actual only in 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 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.

       vertical BOOLEAN
           Sets seneral 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 FLAG value,
           correspondingly 1 or 0.

           Only for multi-select mode.

       deselect_all
           Removes selection from all items.

           Only for multi-select mode.

       draw_items CANVAS, ITEM_DRAW_DATA
           Called from within "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.

       draw_text_items CANVAS, FIRST, LAST, STEP, X, Y, OFFSET, CLIP_RECT
           Called by "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.

       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.

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

       select_all
           Selects all items.

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

       select_item INDEX
           Selects INDEXth item.

           Only for multi-select mode.

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

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

       toggle_item INDEX
           Toggles selection of INDEXth item.

           Only for multi-select mode.

       unselect_item INDEX
           Deselects INDEXth item.

           Only for multi-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".

       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 in accord with the dragging
           action.

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

       get_items INDICES
           Returns 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 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 items.

       replace_items OFFSET, ITEMS
           Replaces existing items at OFFSET index in the list.  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", 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

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