Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Columns(3)	      User Contributed Perl Documentation	    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 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
       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

perl v5.24.1			  1999-11-26			    Columns(3)

NAME | SYNOPSIS | DESCRIPTION | STANDARD OPTIONS | WIDGET-SPECIFIC OPTIONS | WIDGET METHODS | BINDINGS | REQUIREMENTS | CAVEATS | AUTHORS | COPYRIGHT | HISTORY | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tk::Columns&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help