NAME

Tk::Columns - A multicolumn list widget with sortable & sizeable columns

SYNOPSIS

    use Tk::Columns;
    $Columns = $parent->B<Columns>
       (
        '-columnlabels' => [qw (column1 column2)]
        '-listbackground' => 'white',
        '-listforeground' => 'black',
        '-buttonforeground' => 'black',
        '-buttonbackground' => 'blue',
       );
    $ColumnHeader = $Columns->B<ColumnButton>
       (
        '-listfont' => '-adobe-new century schoolbook-medium-r-normal--14-*-*-*-*-*-*-*',
        '-buttoncolor' => 'beige',
        '-text' => 'column3',
        '-width' => 15,
        '-trimcount' => 2,
        '-listbackground' => 'white',
        '-listforeground' => 'black',
        '-buttonforeground' => 'black',
        '-buttonbackground' => 'blue',
        '-sort' => 'true',
        '-sortcommand' => '$a cmp $b',
        '-image' => $icon_image,
        '-buttoncommand' => sub {...},
        '-selectcommand' => sub {...}
       );
   $Columns->insert ('end', ['List', 'Row', 'Contents']);
   $Columns->insert ('end', {'column1' => 'List', 'column2' => 'Row', 'column3' => 'Contents'});
   $Columns->insert ('end', 'List', 'Row', 'Contents');
   $Columns->delete (0, 'end');
   ...
   Tk::MainLoop;

DESCRIPTION

Implements a multicolumn list with resizeable, scrollable columns and configurable sorting by column. Other features include column selection callbacks and row selection callbacks, global and per-column color and font selection, and column insertion data specified by column label (hash) or by index (list).

STANDARD OPTIONS

Columns

-background -foreground -font -bg

ColumnButton

-font -image -foreground -background -borderwidth -relief -text -width -bg

See Tk for details of the standard options.

WIDGET-SPECIFIC OPTIONS

Name: buttonbackground

Class: ButtonBackground

Switch: -buttonbackground

Aliases: -buttoncolor -color

Specifies the background (surface) color for all existing buttons

Name: buttoncommand

Class: ButtonCommand

Switch: -buttoncommand

Specifies a callback to be executed when a column header is clicked. The callback is passed the list index. When specified, this callback is registered for every existing listbox and sets the default for new ones. If the -sort option is turned on, it overrides this option but does not negate it, allowing it to return when the -sort option is turned off.

Name: buttonfont

Class: ButtonFont

Switch: -buttonfont

Specifies the font to use for all the existing column header labels

Name: columns

Class: Columns

Switch: -columns

Aliases: -columnlabels

This option takes a reference to a list of options. If the list consists of scalar values, these are assumed to be the labels for column headers. These elements are created with default options which should normally be alright. If the list consists of references to arrays, then these are assumed to be key => value pairs specifying the options to pass to $Columns->addcolumn.

Name: image

Class: Image

Switch: -image

Setting this to a reference to a Tk::Image causes that image to be set for all of the column labels and sets the default for all future columns. By default column headers are displayed without icons.

See Tk::Label

WIDGET METHODS

$Button = $Columns->ColumnButton (option => value, ...)

$Button = $Columns->addcolumn (option => value, ...)

$Button = $Columns->Column (option => value, ...)

$Button = $Columns->Button (option => value, ...)

$Button = $Columns->column (option => value, ...)

Creates a column header and an attached listbox. The listbox is 'tied' to any preexisting ones. The new listbox is padded with empty rows to match its siblings. This method really invokes an instantiation of the ColumnButton class. All the options given apply to the ColumnButton. The widget reference returned can be used to alter the column's behaviour later. The following options are available :-

$Columns->activate(index)

Sets the row element to the one indicated by index. If index is outside the range of elements in the listbox then the closest element is activated. The active element is drawn with an underline when the widget has the input focus, and its index may be retrieved with the index active.

See listbox for more details.

$Columns->bbox(index, [columnspec])

Returns a list of four numbers describing the bounding box of the text in the element given by index in the listbox specified by column or the first listbox in the composite. The first two elements of the list give the x and y coordinates of the upper-left corner of the screen area covered by the text (specified in pixels relative to the widget) and the last two elements give the width and height of the area, in pixels. If no part of the element given by index is visible on the screen, or if index refers to a non-existent element, then the result is an empty string; if the element is partially visible, the result gives the full area of the element, including any parts that are not visible.

See listbox for more details.

$Columns->buttonhash()

Returns a hash of column buttons keyed by column label

$Columns->buttons()

Returns an ordered list of the column buttons

$Columns->buttonwidth(columnspec, ?newwidth?)

$Columns->columnwidth(columnspec, ?newwidth?)

$Columns->width(columnspec, ?newwidth?)

This uses the numeric or textual columnspec to locate a column header and sets the width to newwidth if present, or returns the current width of that column. It the column doesn't exist then the return value 0 is quietly returned.

$Columns->columnlabels(array reference)

$Columns->columns(array reference)

This invokes $Columns->configure (-columnlabels => array reference). See -columnlabels for details as this is a convenience method.

$Columns->curselection()

Returns a list containing the numerical indices of all of the elements in the listbox that are currently selected. If there are no elements selected in the listbox then an empty string is returned.

See listbox for more details.

$Columns->delete(where, where)

This has identical behaviour to listbox->delete.

See listbox for more details.

$Columns->get(from, to)

Retrieves the rows in the range from .. to. This method is an analog of the listbox->get method. The data returned is an array of references to the row lists specified.

See listbox for more details.

$Columns->index(index)

Returns the integer index value that corresponds to index. If index is end the return value is a count of the number of elements in the listbox (not the index of the last element).

See listbox for more details.

$Columns->indexedbutton(columnspec)

Returns the column button associated with the numeric column index or the textual column name.

$Columns->indexedlist(columnspec)

Returns the listbox associated with the numeric column index or the textual column name.

$Columns->insert(where, ?<option>?, ...)

This method inserts rows across all listboxes. where is the same as documented in the listbox pod. The following options can be a list of scalars, a list of references to hashes, or a list of references to arrays. These can appear in any order. A list of scalars will be interpreted up to an array reference or the end of the parameter list, whichever comes first. The list is padded out so it can be applied to all listboxes. It is then inserted using where.

An array reference is dereferenced and applied just as the inline list. A hash is assumed to be keyed by the column header labels. It is converted into a list using the column header order and applied normally after 'padding'.

NOTE: The insertions are 'cached' and then applied to each listbox at once, avoiding flicker and slow updates.

$Columns->labels()

Returns an ordered list of the column names

$Columns->listhash()

$Columns->hash()

Returns a hash of listboxes keyed by column label

$Columns->lists()

Returns an ordered list of the column listboxes

$Columns->nearest(y)

Given a y-coordinate within the listbox window, this command returns the index of the (visible) listbox element nearest to that y-coordinate.

See listbox for more details.

$Columns->selection (option, argument)

Adjusts the selection. It has several forms, depending on option.

See listbox for more details.

$Columns->see(index)

Makes row index visible.

See listbox for more details.

$Columns->size()

$Columns->rows()

Returns the number of rows.

$Columns->update(where, ...)

$Columns->replace(where, ...)

This takes the same options as <$Columns>->insert but deletes the row found there first.

BINDINGS

[1]

Pressing and releasing the left mouse button on a columns label will cause the -sortcommand or the default sort method to be invoked if the -sort option has been enabled. Otherwise, the callback specified in -buttoncommand is invoked if it is defined.

[2]

Double-clicking the left mouse button on any listbox will cause the callback specified by -selectcommand to be invoked with the row index of the selected listbox item.

[3]

Pressing and releasing the right mouse button on the column label trim elements will cause that column to 'zoom'. That is, it will collapse the column to its smallest size without the need to drag it. When pressed again, the column will return to its original size. The mouse pointer will change to a 'resize' form when this action is possible.

[4]

Pressing the left mouse button on the column label trim elements will initiate resizing of that column. The edge of the column will follow the mouse horizontally until the button is released whereupon the column will remain at the selected size. The mouse pointer will change to a 'resize' form when this action is possible.

REQUIREMENTS

Tk::TiedListbox from Tk-Contrib-0.06

CAVEATS

I regret that there appears to be no way to justify the listboxes. If anyone knows, please tell me how.

AUTHORS

Damion K. Wilson, dwilson@ibl.bm, http://pwp.ibl.bm/~dkw

COPYRIGHT

Copyright (c) 1999 Damion K. Wilson.

All rights reserved.

This program is free software, you may redistribute it and/or modify it under the same terms as Perl itself.

HISTORY

July 4, 1999: fixed scrollbar redisplay failure after insertion bug

September 1, 1999: Rewrite with legacy support

November 25, 1999: Fixed index and delete methods

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 1393:

=cut found outside a pod block. Skipping to next block.

Around line 1640:

You forgot a '=back' before '=head1'

Around line 1660:

You can't have =items (as at line 1664) unless the first thing after the =over is an =item

Around line 1678:

You can't have =items (as at line 1682) unless the first thing after the =over is an =item

Around line 1691:

You can't have =items (as at line 1695) unless the first thing after the =over is an =item

Around line 1703:

You can't have =items (as at line 1707) unless the first thing after the =over is an =item

Around line 1717:

You can't have =items (as at line 1721) unless the first thing after the =over is an =item

Around line 1730:

You can't have =items (as at line 1734) unless the first thing after the =over is an =item

Around line 1742:

You can't have =items (as at line 1746) unless the first thing after the =over is an =item

Around line 1752:

You can't have =items (as at line 1756) unless the first thing after the =over is an =item

Around line 1762:

You can't have =items (as at line 1766) unless the first thing after the =over is an =item

Around line 1772:

You can't have =items (as at line 1776) unless the first thing after the =over is an =item

Around line 1785:

You can't have =items (as at line 1789) unless the first thing after the =over is an =item

Around line 1796:

You can't have =items (as at line 1800) unless the first thing after the =over is an =item

Around line 1810:

You can't have =items (as at line 1814) unless the first thing after the =over is an =item

Around line 1828:

You can't have =items (as at line 1832) unless the first thing after the =over is an =item

Around line 1839:

You can't have =items (as at line 1843) unless the first thing after the =over is an =item

Around line 1850:

You can't have =items (as at line 1854) unless the first thing after the =over is an =item