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

Name: listbackground

Class: ListBackground

Switch: -listbackground

Aliases: -listcolor -background -bg

Specifies the background (surface) color for all existing listboxes and sets the default for all new ones. Default is 'white'

Name: listfont

Class: ListFont

Switch: -listfont

Alias: -font

Specifies the font for all existing listboxes and sets the default for all new ones. The default is to use the system default font.

Name: listforeground

Class: ListForeground

Switch: -listforeground

Specifies the foreground (writing) color for all existing listboxes and sets the default for all new ones. Default is 'black'

Name: selectcommand

Class: SelectCommand

Switch: -selectcommand

Aliases: -command

Specifies a callback to be executed when a list entry is double-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.

Name: selectmode

Class: SelectMode

Switch: -selectmode

Sets the selection mode for all existing listboxes and sets the default to use for new ones. The default is 'browse'.

Name: trimcount

Class: TrimCount

Switch: -trimcount

Specifies the number of button trim 'handles' for all existing buttons.

Name: zoom

Class: Zoom

Switch: -zoom

This option takes a boolean argument. When set to 1, all the existing columns are 'zoomed', that is, reduced to their smallest width. When set to 0, all the columns are returned to the original widths

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 :-

-background => color

-buttonbackground => color

-bg => color

-buttoncolor => color

-color => color

Specifies the button's background (surface) color.

-buttoncommand => callback

Specifies a callback to be executed when a column header is clicked. The callback is passed the list index. 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.

-font => fontspec

-buttonfont => fontspec

Specifies the font for the text in the button label.

-foreground => color

-buttonforeground => color

-fg => color

Specifies the button's foreground (text) color. Defaults to black.

-image => image

Setting this to a reference to a Tk::Image causes that image to be displayed in the column label.

See Tk::Label

-listbackground => color

-slavecolor => color

Sets the background color for the attached listbox

-listfont => fontspec

Specifies the font for the text in the attached listbox.

-listforeground => color

Sets the foreground (text) color for the attached listbox.

-listselectmode => mode

Sets the selection mode for the attached listbox.

-selectcommand => callback

-command => callback

Specifies a callback to be executed when a list entry is double-clicked. The callback is passed the list index.

-slave => widget

DO NOT USE ! This option is use to inform the button which widget it must manage. It is provided here only for completeness.

-sort => boolean

Setting this to boolean 'true' allows all columns to be sorted by this column when the button is pressed. Each invocation reverses the sort order. The sort method can be specified with -sortcommand. Setting this to boolean false (0) disables the sorting. When active, this option overrides any existing -buttoncommand. When inactive, any preexisting -buttoncommand is re-enabled.

-sortcommand => string

-sortfunction => string

-sortmethod => string

This specifies the sort function to pass to the sort Perl function for sorting of this column. The default is '{lc ($a) cmp lc ($b)}' for (caseless) alphanumeric comparison.

Read the perlfunc documentation for more details on sort.

-trimcount => integer

Specifies the number of trim 'handles' for the button. It defaults to 2. Setting it to 0 makes the column unresizeable.

-width => integer

Set this to the desired width of the column, in characters. The default is the natural width of the text and image parts combined.

-zoom => boolean

This option takes a boolean argument. When set to 1, the column is 'zoomed', that is, its width is reduced to the smallest possible setting. When set to 0, the column is returned to its original width.

$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

cpanm Tk::Signals

perl -MCPAN -e shell
install Tk::Signals