NAME

Tk::DHList - A HList widget with a visible/hidden data column

SYNOPSIS

    use Tk;
    use Tk::DHList

    my $mw = MainWindow->new();


    #my $listbox = $mw->DHList(
    my $listbox = $mw->Scrolled('DHList', 
        -scrollbars          => 'e',
        -cursor              => 'right_ptr',
        -relief              => 'sunken',
        -borderwidth         => '2',
        -width               => '10',  # columns
        -height              => '15',  # lines
        -background          => 'orange',
        -selectmode          => 'single',
                -sizecmd             => \&size_cb,
                #new options
        -viewtype            => 'withdata',
                -datastyle           => $datastyle;
                -databackground      => 'skyblue',
        -numeric_primary_sort   => '0',
        -numeric_secondary_sort => '1',
    )->pack;

        
    Tk::MainLoop;
        
    sub add_data
    {
        # 1) insert a complete array with texts and data, keys become 'visible' entry,
        # values are stored as data and are shown in transient column.
        $listbox->add($key, -data => 'i02',
                                        -itemtype => 'imagetext',
                                        -text => 'Dummy',
                                        -image => $xpms{dummy},
                                        #-datastyle => $datastyle,
                );
   }
   sub size_cb
   {
      print "we have resized\n";
   }

DESCRIPTION

A HList derived widget that offers several add-on functions like sorting, reordering and inserting/retrieving of item text & data, suitable for perl Tk800.x (developed with Tk800.024).

You can insert item-texts or item-text/-value pair/s into the DHList widget with the standard-like add() method . The delete removes visible list-items as well as the associated data.

get_item(), get_item_text(), get_item_value() retrieve either a scalar or lists, depending on the context it was invoked. In scalar mode they return the first item only (/first item-text/-text/-value/). In list context they return the text AND the belonging data.

getcurselection(), getcurselection_text(), getcurselection_value(), and getcurselection_index() also retrieve either a scalar or a list, depending on the context but for the currently selected listitem. For scalar mode same rule applies as for get_item.

reverse() reverses the whole list and all item values.

sort() sorts the whole list (alpha)numerical and reorders all entries. Depending on the sortmode either the first column content or the data column content is used as the searchkey.

viewtype() might be invoked directly or via configure to switch between 'withdata' or 'normal' listbox view.

If the Listbox has the input focus the key 'Control-Key-[' makes the data-list visible and 'Control-Key-]' hides it.

METHODS

add()

'add($path, <options> )' inserts item text & data in the list. Inserting without '-data' just uses the HList the with a default 'undef'-data per item.

delete()

'delete(what [, $path] )' removes item text & data from/to the specified positions in the list -acts as the default delete().

get_item()

'get_item($path )' retrieves item text & data from/to the specified positions in the list. get_item_text() and get_item_value() work analogous but for texts/values only

getcurselection()

'getcurselection()' retrieves item-text & -data from the current selected position in the list. getcurselection_text(), getcurselection_value() and getcurselection_index() work anlogous but for texts/values only

reverse()

'reverse()' reverses the whole list and all belonging item values.

sort()

'sort($sortmode)' sorts the whole list (alpha)numerical. Available Sortmodes are: ascending, descending, ascending data' or descending data' (case-insensitiv, order of sortmode-keywords does not matter).

viewtype()

'viewtype()' switches the listbox' visible area between the 'normal' view and the extended one 'withdata', that shows a second column with all the belonging data.

OPTIONS

viewtype

'-viewtype()' switches the listbox' visible area between the 'normal' view and the extended one 'withdata', that shows a second column with all the belonging data.

datastyle

'-datastyle()' allows to specify an ItemStyle for the data column (see Tk::ItemStyle for details).

databackground

'-databackground()' allows to specify just a different background color for the data column. Note that it still uses the build-in ItemStyle (beside bg-color) for the data column.

numeric_primary_sort

'-numeric_primary_sort()' allows to enable numeric ordering for the internal sort() function (numeric on primary keys / first column).

numeric_secondary_sort

'-numeric_secondary_sort()' allows to enable numeric ordering for the internal sort() function (numeric on secondary keys / data column).

columnseparator

'-columnseparator' allows to specify a different column separator char (default is '|') If a multicolumn layout is desired simply specify '-columns' option and supply a combined string (-text) to the add() function $list->add( -text => 'Entry|Col2|col3|col4', ... );

headline

'-headline' allows to specify a combined string for all column headers (uses the column separator)

headerforeground

'-headerforeground' allows to specify a different HeaderFOREground (default is List's Background color)

headerbackground

'-headerbackground' allows to specify a different HeaderBACKground (default is NO color)

headerfont

'-headerfont' allows to specify a different HeaderFONT (default is 'Helvetica -10')

headerrelief

'-headerrelief' allows to specify a different HeaderRELIEF (default is 'groove')

AUTHORS

Michael Krause, KrauseM_AT_gmx_DOT_net

This code may be distributed under the same conditions as Perl.

V2.1 (C) Sept 2009