tk::columns(3)

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  schoolbookmedium-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 call
backs, 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->add
column.
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 sib
lings. 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 fol
lowing 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 col
umn 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 list
box.
-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 pro
vided 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 speci
fied 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 set
ting. 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 acti
vated. The active element is drawn with an under
line 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 ele
ments 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 ele
ment, 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 cur
rently 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 horizon
tally until the button is released whereupon the col
umn 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

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

docs.sk

comprehensive documentation repository

Most Viewed