GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  TK::COLUMNS (3)

.ds Aq ’

NAME

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

CONTENTS

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:  <B>buttonbackgroundB>
Class: <B>ButtonBackgroundB>
Switch:        <B>-buttonbackgroundB>
Aliases:       <B>-buttoncolorB> <B>-colorB> Specifies the background (surface) color for all existing buttons
Name:  <B>buttoncommandB>
Class: <B>ButtonCommandB>
Switch:        <B>-buttoncommandB> 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 <B>-sortB> option is turned on, it overrides this option but does not negate it, allowing it to return when the <B>-sortB> option is turned off.
Name:  <B>buttonfontB>
Class: <B>ButtonFontB>
Switch:        <B>-buttonfontB> Specifies the font to use for all the existing column header labels
Name:  <B>columnsB>
Class: <B>ColumnsB>
Switch:        <B>-columnsB>
Aliases:       <B>-columnlabelsB> 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-><B>addcolumnB>.
Name:  <B>imageB>
Class: <B>ImageB>
Switch:        <B>-imageB> 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:  <B>listbackgroundB>
Class: <B>ListBackgroundB>
Switch:        <B>-listbackgroundB>
Aliases:       <B>-listcolorB> <B>-backgroundB> <B>-bgB> Specifies the background (surface) color for all existing listboxes and sets the default for all new ones. Default is ’white’
Name:  <B>listfontB>
Class: <B>ListFontB>
Switch:        <B>-listfontB>
Alias: <B>-fontB> 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:  <B>listforegroundB>
Class: <B>ListForegroundB>
Switch:        <B>-listforegroundB> Specifies the foreground (writing) color for all existing listboxes and sets the default for all new ones. Default is ’black’
Name:  <B>selectcommandB>
Class: <B>SelectCommandB>
Switch:        <B>-selectcommandB>
Aliases:       <B>-commandB> 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:  <B>selectmodeB>
Class: <B>SelectModeB>
Switch:        <B>-selectmodeB> Sets the selection mode for all existing listboxes and sets the default to use for new ones. The default is ’browse’.
Name:  <B>trimcountB>
Class: <B>TrimCountB>
Switch:        <B>-trimcountB> Specifies the number of button trim ’handles’ for all existing buttons.
Name:  <B>zoomB>
Class: <B>ZoomB>
Switch:        <B>-zoomB> 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-><B>ColumnButtonB> (option => <B>valueB>, ...)
$Button = $Columns-><B>addcolumnB> (option => <B>valueB>, ...)
$Button = $Columns-><B>ColumnB> (option => <B>valueB>, ...)
$Button = $Columns-><B>ButtonB> (option => <B>valueB>, ...)
$Button = $Columns-><B>columnB> (option => <B>valueB>, ...) 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 :-

 

<B>-backgroundB> => <B>colorB>

<B>-buttonbackgroundB> => <B>colorB>

<B>-bgB> => <B>colorB>

<B>-buttoncolorB> => <B>colorB>

<B>-colorB> => <B>colorB>

Specifies the button’s background (surface) color.

 

<B>-buttoncommandB> => <B>callbackB>

Specifies a callback to be executed when a column header is clicked. The callback is passed the list index. If the <B>-sortB> option is turned on, it overrides this option but does not negate it, allowing it to return when the <B>-sortB> option is turned off.

 

<B>-fontB> => <B>fontspecB>

<B>-buttonfontB> => <B>fontspecB>

Specifies the font for the text in the button label.

 

<B>-foregroundB> => <B>colorB>

<B>-buttonforegroundB> => <B>colorB>

<B>-fgB> => <B>colorB>

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

 

<B>-imageB> => <B>imageB>

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

See Tk::Label

 

<B>-listbackgroundB> => <B>colorB>

<B>-slavecolorB> => <B>colorB>

Sets the background color for the attached listbox

 

<B>-listfontB> => <B>fontspecB>

Specifies the font for the text in the attached listbox.

 

<B>-listforegroundB> => <B>colorB>

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

 

<B>-listselectmodeB> => <B>modeB>

Sets the selection mode for the attached listbox.

 

<B>-selectcommandB> => <B>callbackB>

<B>-commandB> => <B>callbackB>

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

 

<B>-slaveB> => <B>widgetB>

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

 

<B>-sortB> => <B>booleanB>

Setting this to booleantrue’ 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 <B>-sortcommandB>. Setting this to boolean false (0) disables the sorting. When active, this option overrides any existing <B>-buttoncommandB>. When inactive, any preexisting <B>-buttoncommandB> is re-enabled.

 

<B>-sortcommandB> => <B>stringB>

<B>-sortfunctionB> => <B>stringB>

<B>-sortmethodB> => <B>stringB>

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

Read the <B>perlfuncB> documentation for more details on <B>sortB>.

 

<B>-trimcountB> => <B>integerB>

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

 

<B>-widthB> => <B>integerB>

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

 

<B>-zoomB> => <B>booleanB>

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-><B>activateB>(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-><B>bboxB>(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 <B>columnB> 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-><B>buttonhashB>() Returns a hash of column buttons keyed by column label
$Columns-><B>buttonsB>() Returns an ordered list of the column buttons
$Columns-><B>buttonwidthB>(columnspec, ?newwidth?)
$Columns-><B>columnwidthB>(columnspec, ?newwidth?)
$Columns-><B>widthB>(columnspec, ?newwidth?) This uses the numeric or textual <B>columnspecB> to locate a column header and sets the width to <B>newwidthB> 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-><B>columnlabelsB>(array reference)
$Columns-><B>columnsB>(array reference) This invokes $Columns->configure (-columnlabels => <B>array referenceB>). See <B>-columnlabelsB> for details as this is a convenience method.
$Columns-><B>curselectionB>() 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-><B>deleteB>(where, where) This has identical behaviour to listbox-><B>deleteB>.

See listbox for more details.

$Columns-><B>getB>(from, to) Retrieves the rows in the range from .. to. This method is an analog of the listbox-><B>getB> method. The data returned is an array of references to the row lists specified.

See listbox for more details.

$Columns-><B>indexB>(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-><B>indexedbuttonB>(columnspec) Returns the column button associated with the numeric column index or the textual column name.
$Columns-><B>indexedlistB>(columnspec) Returns the listbox associated with the numeric column index or the textual column name.
$Columns-><B>insertB>(where, ?<option>?, ...) This method inserts rows across all listboxes. <B>whereB> is the same as documented in the <B>listboxB> 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 <B>whereB>.

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-><B>labelsB>() Returns an ordered list of the column names
$Columns-><B>listhashB>()
$Columns-><B>hashB>() Returns a hash of listboxes keyed by column label
$Columns-><B>listsB>() Returns an ordered list of the column listboxes
$Columns-><B>nearestB>(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-><B>selectionB> (option, argument) Adjusts the selection. It has several forms, depending on <B>optionB>.

See listbox for more details.

$Columns-><B>seeB>(index) Makes row index visible.

See listbox for more details.

$Columns-><B>sizeB>()
$Columns-><B>rowsB>() Returns the number of rows.
$Columns-><B>updateB>(where, ...)
$Columns-><B>replaceB>(where, ...) This takes the same options as <$Columns>-><B>insertB> but deletes the row found there first.

BINDINGS

<B>[1]B> Pressing and releasing the left mouse button on a columns label will cause the <B>-sortcommandB> or the default sort method to be invoked if the <B>-sortB> option has been enabled. Otherwise, the callback specified in <B>-buttoncommandB> is invoked if it is defined.
<B>[2]B> Double-clicking the left mouse button on any listbox will cause the callback specified by <B>-selectcommandB> to be invoked with the row index of the selected listbox item.
<B>[3]B> 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.
<B>[4]B> 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

<B>Tk::TiedListboxB> from <B>Tk-Contrib-0.06B>

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

<B>July 4, 1999B>: fixed scrollbar redisplay failure after insertion bug
<B>September 1, 1999B>: Rewrite with legacy support
<B>November 25, 1999B>: Fixed index and delete methods

POD ERRORS

Hey! <B>The above document had some coding errors, which are explained below:B>
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
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 COLUMNS (3) 1999-11-26

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.