NAME

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

SYNOPSIS

    use Tk;
    use Tk::DataHList

    my $mw = MainWindow->new();


    #my $listbox = $mw->DataHList(
    my $listbox = $mw->Scrolled('DataHList', 
        -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 in-place-editing, 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 DataHList 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 alphanumerical and reorders and all items and belonging

Configure() understands the new editing-related options -editactivationEvent, -editfinishonLeave, -posteditcommand and -validate. The first one allows to specify an event descriptor for the activation of the Editing features, the second enables the automatic finish-edit feature if the mouse leaves the edit-area, The others may be used to specify callbacks: One for postprocessing after editing is finished and the other one, which can be used to perform validation operations during editing.

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($direction)' sorts the whole list alphanumerical. The direction parameter may be 'ascending' or 'descending'

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 / second column).

AUTHORS

Michael Krause, KrauseM_AT_gmx_DOT_net

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

V1.1 (C) May 2005