NAME

       Prima::DetailedList - a multi-column list viewer with controlling header widget.

SYNOPSIS

       use Prima::DetailedList;

               my $l = $w-> insert( 'Prima::DetailedList',
                       columns => 2,
                       headers => [ 'Column 1', 'Column 2' ],
                       items => [
                               ['Row 1, Col 1', 'Row 1, Col 2'],
                               ['Row 2, Col 1', 'Row 2, Col 2']
                       ],
               );
               $l-> sort(1);

DESCRIPTION

       Prima::DetailedList is a descendant of Prima::ListViewer, and as such provides a certain level of
       abstraction. It overloads format of items in order to support multi-column ( 2D ) cell span. It also
       inserts Prima::Header widget on top of the list, so the user can interactively move, resize and sort the
       content of the list. The sorting mechanism is realized inside the package; it is activated by the mouse
       click on a header tab.

       Since the class inherits Prima::ListViewer, some functionality, like 'item search by key', or
       "get_item_text" method can not operate on 2D lists. Therefore, mainColumn property is introduced, that
       selects the column representing all the data.

API

   Events
       Sort COLUMN, DIRECTION
           Called  inside sort method, to facilitate custom algorithms of sorting.  If the callback procedure is
           willing to sort by COLUMN index, then it must call "clear_event", to signal the event flow stop.  The
           DIRECTION  is  a boolean flag, specifying whether the sorting must be performed is ascending ( 1 ) or
           descending ( 0 ) order.

           The callback procedure must operate on the internal storage of "{items}", which is an array of arrays
           of scalars.

           The default action is the literal sorting algorithm, where precedence is arbitrated by "cmp" operator
           ( see "Equality Operators" in perlop ) .

   Properties
       columns INTEGER
           Governs the number of columns in items. If set-called, and the new number is different from  the  old
           number, both items and headers are restructured.

           Default value: 0

       headerClass
           Assigns a header class.

           Create-only property.

           Default value: "Prima::Header"

       headerProfile HASH
           Assigns hash of properties, passed to the header widget during the creation.

           Create-only property.

       headerDelegations ARRAY
           Assigns a header widget list of delegated notifications.

           Create-only property.

       headers ARRAY
           Array of strings, passed to the header widget as column titles.

       items ARRAY
           Array  of  arrays  of  scalars,  of  arbitrary  kind. The default behavior, however, assumes that the
           scalars are strings.  The data direction is from left to right and from top to bottom.

       mainColumn INTEGER
           Selects the column, responsible for representation of all the data.  As the user  clicks  the  header
           tab, "mainColumn" is automatically changed to the corresponding column.

           Default value: 0

   Methods
       sort [ COLUMN ]
           Sorts  items  by  the  COLUMN index in ascending order. If COLUMN is not specified, sorts by the last
           specified column, or by #0 if it is the first "sort" invocation.

           If COLUMN was specified, and the last specified column  equals  to  COLUMN,  the  sort  direction  is
           reversed.

           The  method does not perform sorting itself, but invokes Sort notification, so the sorting algorithms
           can be overloaded, or be applied differently to the columns.

AUTHOR

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

SEE ALSO

       Prima, Prima::Lists, Prima::Header, examples/sheet.pl

perl v5.22.1                                       2009-02-24                             Prima::DetailedList(3)