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

FreeBSD Manual Pages

  
 
  

home | help
TableMatrix(3)	      User Contributed Perl Documentation	TableMatrix(3)

NAME
       TableMatrix - Create and	manipulate tables

Synopsis
       $table =	$parent->TableMatrix(?options?);

STANDARD OPTIONS
       -anchor	-background  -cursor
	  -exportselection  -font  -foreground	  -highlightbackground
       -highlightcolor
	-highlightthickness    -insertbackground  -insertborderwidth
       -insertofftime
	  -insertontime	 -insertwidth  -invertselected	-relief	 -takefocus
	-xscrollcommand	   -yscrollcommand

Widget-specific	Options
       Switch: -autoclear
       Name: autoClear
       Class: AutoClear
	A boolean value	which specifies	whether	the first keypress in a	cell
	will delete whatever text was previously there.	 Defaults to 0.

       Switch:	-bordercursor
       Name: borderCursor
       Class: Cursor
	Specifies the name of the cursor to show when over borders, a visual
	indication that	interactive resizing is	allowed	(it is thus affect by
	the value of -resizeborders).  Defaults	to crosshair .

       Switch: -borderwidth or -bd
       Name: borderWidth
       Class: BorderWidth
	Specifies a non-negative pixel value or	list of	values indicating the
	width of the 3-D border	to draw	on interior table cells	(if such a
	border is being	drawn; the <Brelief> option typically determines
	this).	If one value is	specified, a rectangle of this width will be
	drawn.	If two values are specified, then only the left	and right
	edges of the cell will have borders.  If four values are specified,
	then the values	correspond to the {left	right top bottom} edges.  This
	can be overridden by the a tag's borderwidth option.  It can also be
	affected by the	defined	-drawmode for the table.  Each value in	the
	list must have one of the forms	acceptable to Tk_GetPixels.

       Switch: -browsecommand or -browsecmd
       Name: browseCommand
       Class: BrowseCommand
	Specifies a command (callback) which will be evaluated anytime the
	active cell changes. The Previous Index	and the	Current	index is
	passed to this command as arguments.

       Switch: -cache
       Name: cache
       Class: Cache
	A boolean value	that specifies whether an internal cache of the	table
	contents should	be kept.  This greatly enhances	speed performance when
	used with -command  but	uses extra memory.  Can	maintain state when
	both -command  and -variable  are empty.  The cache is automatically
	flushed	whenever the value of -cache  or -variable  changes, otherwise
	you have to explicitly call clear on it.  Defaults to off.

       Switch: -colorigin
       Name: colOrigin
       Class: Origin
	Specifies what column index to interpret as the	leftmost column	in the
	table. This value is used for user indices in the table.  Defaults to
	0.

       Switch: -cols
       Name: cols
       Class: Cols
	Number of cols in the table.  Defaults to 10.

       Switch: -colseparator
       Name: colSeparator
       Class: Separator
	Specifies a separator character	that will be interpreted as the	column
	separator when cutting or pasting data in a table.  By default,
	columns	are separated as elements of a tcl list.

       Switch: -colstretchmode
       Name: colStretchMode
       Class: StretchMode
	Specifies one of the following stretch modes for columns to fill extra
	allocated window space:

       none
	 Columns will not stretch to fill the assigned window space.  If the
	 columns are too narrow, there will be a blank space at	the right of
	 the table.  This is the default.

       unset
	 Only columns that do not have a specific width	set will be stretched.

       all
	 All columns will be stretched by the same number of pixels to fill
	 the window space allocated to the table.  This	mode can interfere
	 with interactive border resizing which	tries to force column width.

       last
	 The last column will be stretched to fill the window space allocated
	 to the	table.

       fill
	 (only valid for -rowstretch  currently)

	 The table will	get more or less columns according to the window space
	 allocated to the table.  This mode has	numerous quirks	and may
	 disappear in the future.

       Switch: -coltagcommand
       Name: colTagCommand
       Class: TagCommand
	Provides the name of a procedure that will be evaluated	by the widget
	to determine the tag to	be used	for a given column.  When displaying a
	cell, the table	widget will first check	to see if a tag	has been
	defined	using the tag col  widget method.  If no tag is	found, it will
	evaluate the named procedure passing the column	number in question as
	the sole argument.  The	procedure is expected to return	the name of a
	tag to use, or a null string. Errors occuring during the evaluation of
	the procedure, or the return of	an invalid tag name are	silently
	ignored.

	The Current column number is passed as an argument to the col command.

       Switch: -colwidth
       Name: colWidth
       Class: ColWidth
	Default	column width, interpreted as characters	in the default font
	when the number	is positive, or	pixels if it is	negative.  Defaults to
	10.

       Switch: -command
       Name: command
       Class: Command
	Specified a command to use as a	procedural interface to	cell values.
	If -usecommand	is true, this command will be used instead of any
	reference to the -variable  array.  When retrieving cell values, the
	return value of	the command is used as the value for the cell.

	Args passed to this callback: The Set Flag (=1 if setting, else
	retrieving), the current row, the current col, the cell	value (if
	setting).

       Switch: -drawmode
       Name: drawMode
       Class: DrawMode
	Sets the table drawing mode to one of the following options:

       slow
	 The table is drawn to an offscreen pixmap using the Tk	bordering
	 functions (double-buffering).	This means there will be no flashing,
	 but this mode is slow for larger tables.

       compatible
	 The table is drawn directly to	the screen using the Tk	border
	 functions. It is faster, but the screen may flash on update.  This is
	 the default.

       fast
	 The table is drawn directly to	the screen and the borders are done
	 with fast X calls, so they are	always one pixel wide only.  As	a side
	 effect, it restricts -borderwidth  to a range of 0 or 1.  This	mode
	 provides best performance for large tables, but can flash on redraw
	 and is	not 100% Tk compatible on the border mode.

       single
	 The table is drawn to the screen as in	fast mode, but only single
	 pixel lines are drawn (not square borders).

       Switch: -flashmode
       Name: flashMode
       Class: FlashMode
	A boolean value	which specifies	whether	cells should flash when	their
	value changes.	The table tag flash  will be applied to	these cells
	for the	duration specified by -flashtime .  Defaults to	0.

       Switch: -flashtime
       Name: flashTime
       Class: FlashTime
	The amount of time, in 1/4 second increments, for which	a cell should
	flash when its value has changed.  -flashmode  must be on.  Defaults
	to 2.

       Switch: -height
       Name: height
       Class: Height
	Specifies the desired height for the window, in	rows. If zero or less,
	then the desired height	for the	window is made just large enough to
	hold all the rows in the table.	 The height can	be further limited by
	-maxheight .

       Switch: -invertselected
       Name: invertSelected
       Class: InvertSelected
	Specifies whether the foreground and background	of an item should
	simply have their values swapped instead of merging the	sel  tag
	options	when the cell is selected.  Defaults to	0 (merge sel tag).

       Switch: -ipadx
       Name: ipadX
       Class: Pad
	A pixel	value specifying the internal offset X padding for text	in a
	cell.  This value does not grow	the size of the	cell, it just causes
	the text to be drawn further from the cell border.  It only affects
	one side (depending on anchor).	 Defaults to 0.	 See -padx for an
	alternate padding style.

       Switch: -ipady
       Name: ipadY
       Class: Pad
	A pixel	value specifying the internal offset Y padding for text	in a
	cell.  This value does not grow	the size of the	cell, it just causes
	the text to be drawn further from the cell border.  It only affects
	one side (depending on anchor).	 Defaults to 0.	 See -pady for an
	alternate padding style.

       Switch: -justify
       Name: justify
       Class: Justify
	How to justify multi-line text in a cell. It must be one of left,
	right, or center. Defaults to left.

       Switch: -maxheight
       Name: maxHeight
       Class: MaxHeight
	The max	height in pixels that the window will request.	Defaults to
	600.

       Switch: -maxwidth
       Name: maxWidth
       Class: MaxWidth
	The max	width in pixels	that the window	will request.  Defaults	to
	800.

       Switch: -multiline
       Name: multiline
       Class: Multiline
	Specifies the default setting for the multiline	tag option.  Defaults
	to 1.

       Switch: -pady
       Name: padX
       Class: Pad
	A pixel	value specifying the offset X padding for a cell.  This	value
	causes the default size	of the cell to increase	by two times the value
	(one for each side), unless a specific pixel size is chosen for	the
	cell with the width command.  This will	force an empty area on the
	left and right of each cell edge.  This	padding	affects	all types of
	data in	the cell.  Defaults to 0.  See -ipadx for an alternate padding
	style.

       Switch: -pady
       Name: padY
       Class: Pad
	A pixel	value specifying the offset Y padding for a cell.  This	value
	causes the default size	of the cell to increase	by two times the value
	(one for each side), unless a specific pixel size is chosen for	the
	cell with the height command.  This will force an empty	area on	the
	top and	bottom of each cell edge.  This	padding	affects	all types of
	data in	the cell.  Defaults to 0.  See -ipadx for an alternate padding
	style.

       Switch: -resizeborders
       Name: resizeBorders
       Class: ResizeBorders
	Specifies what kind of interactive border resizing to allow, must be
	one of row, col, both (default)	or none.

       Switch: -rowheight
       Name: rowHeight
       Class:
	RowHeight  Default row height, interpreted as lines in the default
	font when the number is	positive, or pixels if it is negative.
	Defaults to 1.

       Switch: -roworigin
       Name: rowOrigin
       Class: Origin
	Specifies what row index to interpret as the topmost row in the	table.
	This value is used for user indices in the table.  Defaults to 0.

       Switch: -rows
       Name: rows
       Class: Rows
	Number of rows in the table.  Defaults to 10.

       Switch: -rowseparator
       Name: rowSeparator
       Class: Separator
	Specifies a separator character	that will be interpreted as the	row
	separator when cutting or pasting data in a table.  By default,	rows
	are separated as tcl lists.

       Switch: -rowstretchmode
       Name: rowStretchMode
       Class: StretchMode
	Specifies the stretch modes for	rows to	fill extra allocated window
	space.	See -colstretchmode  for valid options.

       Switch: -rowtagcommand
       Name: rowTagCommand
       Class: TagCommand
	Provides the name of a procedure that can evaluated by the widget to
	determine the tag to be	used for a given row.  The procedure must be
	defined	by the user to accept a	single argument	(the row number), and
	return a tag name or null string.  This	operates in a similar manner
	as -coltagcommand , except that	it applies to row tags.

	The Current row	number is passed as an argument	to the row command.

       Switch: -selectioncommand or -selcmd
       Name: selectionCommand
       Class: SelectionCommand
	Specifies a command (callback) to evaluate when	the selection is
	retrieved from a table via the selection mechanism (ie:	evaluating
	"selection get "). The return value from this command will become the
	string passed on by the	selection mechanism.  The following arguments
	are passed to this callback: The number	of rows	in the selection,
	number of columns in the selection, the	selection string, the number
	of cell	in the selection.

       Switch: -selectmode
       Name: selectMode
       Class: SelectMode
	Specifies one of several styles	for manipulating the selection.	 The
	value of the option may	be arbitrary, but the default bindings expect
	it to be either	single , browse	, multiple , or	extended ; the default
	value is browse	.  These styles	are like those for the Tk listbox,
	except expanded	for 2 dimensions.

       Switch: -selecttitle
       Name: selectTitles
       Class: SelectTitles
	Specifies whether title	cells should be	allowed	in the selection.
	Defaults to 0 (disallowed).

       Switch: -selecttype
       Name: selectType
       Class: SelectType
	Specifies one of several types of selection for	the table.  The	value
	of the option may be one of row	, col ,	cell , or both	(meaning row
	&& col ); the default value is cell .  These types define whether an
	entire row/col is affected when	a cell's selection is changed (set or
	clear).

       Switch: -sparsearray
       Name: sparseArray
       Class: SparseArray
	A boolean value	that specifies whether an associated Tcl array should
	be kept	as a sparse array (1, the default) or as a full	array (0).  If
	true, then cell	values that are	empty will be deleted from the array
	(taking	less memory).  If false, then all values in the	array will be
	maintained.

       Switch: -state
       Name: state
       Class: State
	Specifies one of two states for	the entry:  normal  or disabled.  If
	the table is disabled then the value may not be	changed	using widget
	commands and no	insertion cursor will be displayed, even if the	input
	focus is in the	widget.	 Also, all insert or delete methods will be
	ignored.  Defaults to normal .

       Switch: -titlecols
       Name: titleCols
       Class: TitleCols
	Number of columns to use as a title area.  Defaults to 0.

       Switch: -titlerows
       Name: titleRows
       Class: TitleRows
	Number of rows to use as a title area.	Defaults to 0.

       Switch: -usecommand
       Name: useCommand
       Class: UseCommand
	A boolean value	which specifies	whether	to use the command  option.
	This value sets	itself to zero if command  is used and returns an
	error. Defaults	to 1 (will use command	if specified).

       Switch: -validate
       Name: validate
       Class: Validate
	A boolean specifying whether validation	should occur for the active
	buffer.	Defaults to 0.

       Switch: -validatecommand	or -vcmd
       Name: validateCommand
       Class: ValidateCommand
	Specifies a command (callback) to execute when the active cell is
	edited.	 This command is expected to return a 1	or 0.  If it returns
	1, then	it is assumed the new value is OK, otherwise the new value is
	rejected (the edition will not take place).  Errors in this command
	are handled in the background. The following arguments are supplied to
	the callback: row, col,	oldContents of cell, potential new contents of
	cell, Current Index in the cell.

       Switch: -variable
       Name: variable
       Class: Variable
	Global Tcl array variable to attach to the table's C array.  It	will
	be created if it doesn't already exist or is a simple variable.	 Keys
	used by	the table in the array are of the form row ,col	 for cells and
	the special key	active	which contains the value of the	active cell
	buffer.	 The Tcl array is managed as a sparse array (the table doesn't
	require	all valid indices have values).	 No stored value for an	index
	is equivalent to the empty string, and clearing	a cell will remove
	that index from	the Tcl	array, unless the -sparsearray	options	is set
	to 0.

       Switch: -width
       Name: width
       Class: Width
	Specifies the desired width for	the window, in columns.	If zero	or
	less, then the desired width for the window is made just large enough
	to hold	all the	columns	in the table.  The width can be	further
	limited	by -maxwidth .

       Switch: -wrap
       Name: wrap
       Class: Wrap
	Specifies the default wrap value for tags.  Defaults to	0.

DESCRIPTION
       The TableMatrix	command	creates	a 2-dimensional	grid of	cells.	The
       table can use a Tcl array variable or Tcl command for data storage and
       retrieval.  The widget has an active cell, the contents of which	can be
       edited (when the	state is normal).  The widget supports a default style
       for the cells and also multiple tags , which can	be used	to change the
       style of	a row, column or cell (see TAGS	for details).  A cell flash
       can be set up so	that changed cells will	change color for a specified
       amount of time ("blink").
	Cells can have embedded	images or windows, as described	in Tags	and
       "Embedded Windows" respectively.

       One or more cells may be	selected as described below.
	If a table is exporting	its selection (see -exportselection  option),
       then it will observe the	standard X11 protocols for handling the
       selection.
	See "the Selection" for	details. It is not necessary for all the cells
       to be displayed in the table window at once; commands described below
       may be used to change the view in the window. Tables allow scrolling in
       both directions using the standard -xscrollcommand  and -yscrollcommand
       options.
	They also support scanning, as described below.

       In order	to obtain good performance, the	table widget supports multiple
       drawing modes, two of which are fully Tk	compatible.

Indices
       Many of the widget commands for tables take one or more indices as
       arguments. An index specifies a particular cell of the table, in	any of
       the following ways:

       number,number
	Specifies the cell as a	numerical index	of row,col which corresponds
	to the index of	the associated Perl Hash, where	-roworigin,-colorigin
	corresponds to the first cell in the table (0,0	by default). The
	values for row and column will be constrained to actual	values in the
	table, which means a valid cell	is always found.

       active
	Indicates the cell that	has the	location cursor. It is specified with
	the activate  widget command.

       anchor
	Indicates the anchor point for the selection, which is set with	the
	selection anchor  widget command.

       bottomright
	Indicates the bottom-rightmost cell visible in the table.

       end
	Indicates the bottom right cell	of the table.

       origin
	Indicates the top-leftmost editable cell of the	table, not necessarily
	in the display.	 This takes into account the user specified origin and
	title area.

       topleft
	Indicates the top-leftmost editable cell visible in the	table (this
	excludes title cells).

       @x,y
	Indicates the cell that	covers the point in the	table window specified
	by x  and y (in	pixel coordinates).  If	no cell	covers that point,
	then the closest cell to that point is used. In	the widget command
	descriptions below, arguments named index , first , and	last  always
	contain	text indices in	one of the above forms.

Tags
       A tag is	a textual string that is associated with zero or more rows,
       columns or cells	in a table.  Tags may contain arbitrary	characters,
       but it is probably best to avoid	using names which look like indices to
       reduce coding confusion.	 There may be any number of tags in a table,
       but each	row, column or cell can	only have one tag associated with it
       at a time.  There are several permanent tags in each table that can be
       configured by the user and will determine the attributes	for special
       cells:

       active
	This tag is given to the active	 cell

       flash
	If flash mode is on, this tag is given to any recently edited cells.

       sel
	This tag is given to any selected cells.

       title
	This tag is given to any cells in the title rows and columns.  This
	tag has	-state	disabled  by default.

       Tags control the	way cells are displayed	on the screen.	Where
       appropriate, the	default	for displaying cells is	determined by the
       options for the table widget.  However, display options may be
       associated with individual tags using the tagConfigure method.  If a
       cell, row or column has been tagged, then the display options
       associated with the tag override	the default display style.  The
       following options are currently supported for tags:

       -anchor anchor
	Anchor for item	in the cell space.

       -background  or -bg  color
	Background color of the	cell.

       -borderwidth  or	-bd  pixel
	Borderwidth of the cell, of the	same format for	the table, but may
	also be	empty to inherit the default table borderwidth value (the
	default).

       -font fontName
	Font for text in the cell.

       -foreground or -fg  color
	Foreground color of the	cell.

       -justify	justify
	How to justify multi-line text in a cell. It must be one of left ,
	right ,	or center.

       -image imageName
	An image to display in the cell	instead	of text.

       -multiline boolean
	Whether	to display text	with newlines on multiple lines.

       -relief
	The relief for the cell. May be	the empty string to cause this tag to
	not disturb the	value.

       -showtext boolean
	Whether	to show	the text over an image.

       -state state
	The state of the cell, to allow	for certain cells to be	disabled. This
	prevents the cell from being edited by the insert  or delete  methods,
	but a direct set  will not be prevented.

       -wrap boolean
	Whether	characters should wrap in a cell that is not wide enough.

       A priority order	is defined among tags based on creation	order (first
       created tag has highest default priority), and this order is used in
       implementing some of the	tag-related functions described	below.	When a
       cell is displayed, its properties are determined	by the tags which are
       assigned	to it.	The priority of	a tag can be modified by the tagLower
       and the tagRaise	methods.

       If a cell has several tags associated with it that define the same
       display options (eg - a title cell with specific	row and	cell tags),
       then the	options	of the highest priority	tag are	used.  If a particular
       display option hasn't been specified for	a particular tag, or if	it is
       specified as an empty string, then that option will not be used;	the
       next-highest-priority tag's option will be used instead.	 If no tag
       specifies a particular display option, then the default style for the
       widget will be used.

       Images are used for display purposes only.  Editing in that cell	will
       still be	enabled	and any	querying of the	cell will show the text	value
       of the cell, regardless of the value of -showtext .

       Note: There can be only one tag for a given tag type. ( Tag types =
       flash , active ,	sel , title , celltag rowtag , coltag .) For example,
       you can't apply two cell	tags to	a single cell (or two row tags to a
       single row, etc)	and expect the tag's properties	to be merged. The last
       tag-type	applied	will be	the one	that is	used.

Embedded Windows
       There may be any	number of embedded windows in a	table widget (one per
       cell), and any widget may be used as an embedded	window (subject	to the
       usual rules for geometry	management, which require the table window to
       be the parent of	the embedded window or a descendant of its parent).
       The embedded window's position on the screen will be updated as the
       table is	modified or scrolled, and it will be mapped and	unmapped as it
       moves into and out of the visible area of the table widget.  Each
       embedded	window occupies	one cell's worth of space in the table widget,
       and it is referred to by	the index of the cell in the table.  Windows
       associated with the table widget	are destroyed when the table widget is
       destroyed.

       Windows are used	for display purposes only.  A value still exists for
       that cell, but will not be shown	unless the window is deleted in	some
       way.  If	the window is destroyed	or lost	by the table widget to another
       geometry	manager, then any data associated with it is lost (the cell it
       occupied	will no	longer appear in window	names ).

       When an embedded	window is added	to a table widget with the window
       configure widget	command, several configuration options may be
       associated with it.  These options may be modified with later calls to
       the window configure widget command.  The following options are
       currently supported:

       -create callback
	NOT CURRENTLY SUPPORTED.  Specifies a Tcl script that may be evaluated
	to create the window for the annotation.
	 If no -window option has been specified for this cell then this
	script will be evaluated when the cell is about	to be displayed	on the
	screen.
	 Script	must create a window for the cell and return the name of that
	window as its result. If the cell's window should ever be deleted, the
	script will be evaluated again the next	time the cell is displayed.

       -background or -bg color
	Background color of the	cell.  If not specified, it uses the table's
	default	background.

       -borderwidth or -bd pixelList
	Borderwidth of the cell, of the	same format for	the table, but may
	also be	empty to inherit the default table borderwidth value (the
	default).

       -padx pixels
	As defined in the Tk options man page.

       -pady pixels
	As defined in the Tk options man page.

       -relief relief
	The relief to use for the cell in which	the window lies.  If not
	specified, it uses the table's default relief.

       -sticky sticky
	Stickiness of the window inside	the cell, as defined by	the grid
	command.

       -window $widget
	Specifies the a	window to display in the  annotation.  It must exist
	before being specified here.

the Selection
       Table selections	are available as type STRING.  By default, the value
       of the selection	will be	the values of the selected cells in nested Tcl
       list form where each row	is a list and each column is an	element	of a
       row list. You can change	the way	this value is interpreted by setting
       the -rowseparator  and -colseparator  options.
	For example, default Excel format would	be to set -rowseparator	 to
       "\n" and	-colseparator  to "\t".	 Changing these	values affects both
       how the table sends out the selection and reads in pasted data,
       ensuring	that the table should always be	able to	cut and	paste to
       itself.	It is possible to change how pastes are	handled	by editing the
       table library procedure tk_tablePasteHandler .  This might be necessary
       if -selectioncommand  is	set.

Row/Col	Spanning
       Individual cells	can span multiple rows and/or columns.	This is	done
       via the spans  command (see below for exact arguments).	Cells in the
       title area that span are	not permitted to span beyond the title area,
       and will	be constrained accordingly.  If	the title area shrinks during
       a configure, sanity checking will occur to ensure the above.  You may
       set spans on regular cells that extend beyond the defined row/col area.
       These spans will	not be constrained, so that when the defined row/col
       area expands, the span will expand with it.

       When setting a span, checks are made as to whether the span would
       overlap an already spanning or hidden cell.  This is an error and it
       not allowed. Spans can affect the overall speed of table	drawing,
       although	not significantly.  If spans are not used, then	there is no
       performance loss.

       Cells hidden  by	spanning cells still have valid	data.  This will be
       seen during cut and paste operations that involve hidden	cells, or
       through direct access by	a command like get  or set .

       The drawing properties of spanning cells	apply to only the visual area
       of the cell.  For example, if a cell is center justified	over 5
       columns,	then when viewing any portion of those columns,	it will	appear
       centered	in the visible area. The non-visible column area will not be
       considered in the centering calculations.

Command	Substitution
       The various option based	commands that the table	supports all support
       the familiar Tk %-substitution model (see "Tk::bind " for more
       details).
	The following %-sequences are recognized and substituted by the	table
       widget:

       %c
	For SelectionCommand , it is the maximum number	of columns in any row
	in the selection.  Otherwise it	is the column of the triggered cell.

       %C
	A convenience substitution for %r ,%c .

       %i
	For SelectionCommand, it is the	total number of	cells in the
	selection. For Command , it is 0 for a read (get) and 1	for a write
	(set). Otherwise it is the current cursor position in the cell.

       %r
	For SelectionCommand , it is the number	of rows	in the selection.
	Otherwise it is	the row	of the triggered cell.

       %s
	For ValidateCommand , it is the	current	value of the cell being
	validated.  For	SelectionCommand , it is the default value of the
	selection. For BrowseCommand , it is the index of the last active
	cell. For Command , it is empty	for reads (get)	and the	current	value
	of the cell for	writes (set).

       %S
	For ValidateCommand , it is the	potential new value of the cell	being
	validated.  For	BrowseCommand ,	it is the index	of the new active
	cell.

       %W
	The pathname to	the window for which the command was generated.

Widget Methods
       The $window->TableMatrix	 method	creates	a widget object. This object
       supports	the configure and cget methods described in Tk::options	which
       can be used to enquire and modify the options described above.  The
       widget also inherits all	the methods provided by	the generic Tk::Widget
       class.

       The following additional	methods	are available for scale	widgets:

       $table->activate(index)
	Sets the active	cell to	the one	indicated by index.

       $table->bbox(first, ?last?)
	It returns the bounding	box for	the specified cell (range) as a
	4-tuple	of x, y, width and height in pixels.  It clips the box to the
	visible	portion, if any, otherwise an empty string is returned.

       $table->border(option, args)
	This command is	a voodoo hack to implement border sizing for tables.
	This is	normally called	through	bindings, with the following as	valid
	options:

       $table->borderMark(x, y,	?row|col?)
	 Records x  and	y  and the row and/or column border under that point
	 in the	table window, if any; used in conjunction with later border
	 dragto	 commands.  Typically this command is associated with a	mouse
	 button	press in the widget.  If row  or col  is not specified,	it
	 returns a tuple of both border	indices	(an empty item means no
	 border). Otherwise, just the specified	item is	returned.

       $table->borderDragto(x, y)
	 This command computes the difference between its x  and y  arguments
	 and the x  and	y  arguments to	the last border	mark  command for the
	 widget.  It then adjusts the previously marked	border by the
	 difference.  This command is typically	associated with	mouse motion
	 events	in the widget, to produce the effect of	interactive border
	 resizing.

       $table->cget(option)
	Returns	the current value of the configuration option given by option
	.  Option  may have any	of the values accepted by the table  command.

       $table->clear(option, ?first?, ?last?)
	This command is	a convenience routine to clear certain state
	information managed by the table.  first  and last  represent valid
	table indices.	If neither are specified, then the command operates on
	the whole table.  The following	options	are recognized:

       $table->clearCache(?first?, ?last?)
	 Clears	the specified section of the cache, if the table has been
	 keeping one.

       $table->clearSizes(?first?, ?last?)
	 Clears	the specified row and column areas of specific height/width
	 dimensions.  When just	one index is specified,	for example 2,0	, that
	 is interpreted	as row 2 and  column 0.

       $table->clearTags(?first?, ?last?)
	 Clears	the specified area of tags (all	row, column and	cell tags).

       $table->clearAll(?first?, ?last?)
	 Performs all of the above clear functions on the specified area.

       $table->colWidth(?col?, ?value, col, value, ...?)
	If no col  is specified, returns a list	describing all cols for	which
	a width	has been set.  If col  is specified with no value, it prints
	out the	width of that col in characters	(positive number) or pixels
	(negative number).  If one or more col-value  pairs are	specified,
	then it	sets each col to be that width in characters (positive number)
	or pixels (negative number).  If value	is default , then the col uses
	the default width, specified by	-colwidth .

	$table->configure(?option?, ?value, option, value, ...?)
	 Query or modify the configuration options of the widget. If no	option
	 is specified, returns a list describing all of	the available options
	 for pathName  (see Tk_ConfigureInfo  for information on the format of
	 this list).  If option	 is specified with no value , then the command
	 returns a list	describing the one named option	(this list will	be
	 identical to the corresponding	sublist	of the value returned if no
	 option	 is specified).	 If one	or more	option-value  pairs are
	 specified, then the command modifies the given	widget option(s) to
	 have the given	value(s);  in this case	the command returns an empty
	 string. Option	 may have any of the values accepted by	the table
	 command.

	$table->curselection(?value?)
	 With no arguments, it returns the sorted indices of the currently
	 selected cells.  Otherwise it sets all	the selected cells to the
	 given value.  The set has no effect if	there is no associated Tcl
	 array or the state is disabled.

	$table->curvalue(?value?)
	 If no value is	given, the value of the	cell being edited (indexed by
	 active	) is returned, else it is set to the given value.

	$table->delete(option, arg, ?arg?)
	 This command is used to delete	various	things in a table.  It has
	 several forms,	depending on the option	:

	$table->deleteActive(index, ?index?)
	  Deletes text from the	active cell.  If only one index	is given, it
	  deletes the character	after that index, otherwise it deletes from
	  the first index to the second.  index	 can be	a number, insert  or
	  end .

	$table->deleteCols(?switches?, index, ?count?)
	  Deletes count	 cols starting at (and including) col index .  The
	  index	 will be constrained to	the limits of the tables.  If count
	  is negative, it deletes cols to the left.  Otherwise it deletes cols
	  to the right.	 count	defaults to 1 (meaning just the	column
	  specified).  The selection will be cleared.  At the moment, spans
	  are not adjusted with	this action.  Optional switches	are:

	-holddimensions
	   Causes the table cols to be unaffected by the deletion (empty cols
	   may appear).
	    By default the dimensions are adjusted by count .

	-holdtags
	   Causes the tags specified by	the tag	 method	to not move along with
	   the data.  Also prevents specific widths set	by the width  method
	   from	being adjusted.
	    By default,	these tags are properly	adjusted.

	-holdwindows
	   Causes the embedded windows created with the	window	method to not
	   move	along with the data.  By default, these	windows	are properly
	   adjusted.

	-keeptitles
	   Prevents title area cells from being	changed.  Otherwise they are
	   treated just	like regular cells and will move as specified.

	$table->deleteRows(?switches?, index, ?count?)
	  Deletes count	 rows starting at (and including) row index .  If
	  count	 is negative, it deletes rows going up.	 Otherwise it deletes
	  rows going down.  The	selection will be cleared.  The	switches are
	  the same as those for	column deletion.

	$table->get(first, ?last?)
	 Returns the value of the cells	specified by the table indices first
	 and (optionally) last	in a list.

	$table->hidden(?index?,	?index,	...?)
	 When called without args, it returns all the hidden  cells (those
	 cells covered by a spanning cell).  If	one index is specified,	it
	 returns the spanning cell covering that index,	if any.	 If multiple
	 indices are specified,	it returns 1 if	all indices are	hidden cells,
	 0 otherwise.

	$table->icursor(?arg?)
	 With no arguments, prints out the location of the insertion cursor in
	 the active cell.  With	one argument, sets the cursor to that point in
	 the string.  0	is before the first character, you can also use	insert
	 or end	 for the current insertion point or the	end of the text.  If
	 there is no active cell, or the cell or table is disabled, this will
	 return	-1.

	$table->index(index, ?row|col?)
	 Returns the integer cell coordinate that corresponds to index	in the
	 form row,col.	If row	or col	is specified, then only	the row	or
	 column	index is returned.

	$table->insert(option, arg, arg)
	 This command is used to into various things into a table.  It has
	 several forms,	depending on the option	:

	$table->insertActive(index, value)
	  The value  is	a text string which is inserted	at the index  postion
	  of the active	cell.  The cursor is then positioned after the new
	  text.	index  can be a	number,	insert	or end .

	$table->insertCols(?switches?, index, ?count?)
	  Inserts count	 cols starting at col index .  If count	 is negative,
	  it inserts before the	specified col.	Otherwise it inserts after the
	  specified col.  The selection	will be	cleared.  The switches are the
	  same as those	for column deletion.

	$table->insertRows(?switches?, index, ?count?)
	  Inserts count	 rows starting at row index .  If count	 is negative,
	  it inserts before the	specified row.	Otherwise it inserts after the
	  specified row.  The selection	will be	cleared.  The switches are the
	  same as those	for column deletion.

	$table->reread()
	 Rereads the old contents of the cell back into	the editing buffer.
	 Useful	for a key binding when <Escape>	is pressed to abort the	edit
	 (a default binding).

	$table->rowHeight(?row?, ?value, row, value, ...?)
	 If no row  is specified, returns a list describing all	rows for which
	 a height has been set.	 If row	 is specified with no value, it	prints
	 out the height	of that	row in characters (positive number) or pixels
	 (negative number).  If	one or more row-value  pairs are specified,
	 then it sets each row to be that height in lines (positive number) or
	 pixels	(negative number).  If value  is default , then	the row	uses
	 the default height, specified by -rowheight .

	$table->scan(option, args)
	 This command is used to implement scanning on tables.	It has two
	 forms,	depending on option :

	$table->scanMark(x, y)
	  Records x  and y  and	the current view in the	table window;
	   used	in conjunction with later scan dragto  commands. Typically
	  this command is associated with a mouse button press in the widget.
	  It returns an	empty string.

	$table->scanDragto(x, y.)
	  This command computes	the difference between its x  and y  arguments
	  and the x  and y  arguments to the last scan mark  command for the
	  widget.  It then adjusts the view by 5 times the difference in
	  coordinates.	This command is	typically associated with mouse	motion
	  events in the	widget,	to produce the effect of dragging the list at
	  high speed through the window.  The return value is an empty string.

	$table->see(index)
	 Adjust	the view in the	table so that the cell given by	index  is
	 positioned as the cell	one off	from top left (excluding title rows
	 and columns) if the cell is not currently visible on the screen.  The
	 actual	cell may be different to keep the screen full.

	$table->selection(option, arg)
	 This command is used to adjust	the selection within a table.
	  It has several forms,	depending on option :

	$table->selectionAnchor(index)
	  Sets the selection anchor to the cell	given by index .  The
	  selection anchor is the end of the selection that is fixed while
	  dragging out a selection with	the mouse.  The	index anchor  may be
	  used to refer	to the anchor cell.

	$table->selectionClear(first?last?)
	  If any of the	cells between first  and last  (inclusive) are
	  selected, they are deselected.
	   The selection state is not changed for cells	outside	this range.
	  first	 may be	specified as all  to remove the	selection from all
	  cells.

	$table->selectionIncludes(index)
	  Returns 1 if the cell	indicated by index is currently	selected, 0 if
	  it isn't.

	$table->selectionSet(first, ?last?)
	  Selects all of the cells in the range	between	first  and last	,
	  inclusive, without affecting the selection state of cells outside
	  that range.

	 perltk	note this needs	to be perlized

	 $table->set(?row|col?,	index, ?value?,	?index,	value, ...?)

	 Sets the specified index to the associated value.  Table validation
	 will not be triggered via this	method.	 If row	 or col	 precedes the
	 list of index/value pairs, then the value is assumed to be a Tcl list
	 whose values will be split and	set into the subsequent	columns	(if
	 row  is specified) or rows (for col ).	 For example,  set row 2,3
	 {2,3 2,4 2,5}	will set 3 cells, from 2,3 to 2,5.  The	setting	of
	 cells is silently bounded by the known	table dimensions.

	 $table->spans(?index?,	?rows,cols, index, rows,cols, ...?)

	 This command is used to manipulate row/col spans.  When called	with
	 no arguments, all known spans are returned as a list of tuples	of the
	 form {index span}.  When called with only the index , the span	for
	 that index  only is returned, if any.	Otherwise an even number of
	 index rows,cols  pairs	are used to set	spans.	A span starts at the
	 index	and continues for the specified	number of rows and cols.
	 Negative spans	are not	supported.  A span of 0,0 unsets any span on
	 that cell.  See EXAMPLES for more info.

	 $table->tag(option, ?arg, arg,	...?)

	 This command is used to manipulate tags.  The exact behavior of the
	 command depends on the	option	argument that follows the tag
	 argument. cget	, cell , and row|col  complain about unknown tag
	 names.	 The following forms of	the command are	currently supported:

	$table->tagCell(tagName, ?index, ...?)
	  With no arguments, prints out	the list of cells that use the tag.
	  Otherwise it sets the	specified cells	to use the named tag,
	  replacing any	tag that may have been set using this method before.
	  If tagName is	'', the	cells are reset	to the default tag.  Tags
	  added	during -*tagcommand evaluation do not register here.  If
	  tagName does not exist, it will be created with the default options.

	$table->tagCget(tagName, option)
	  This command returns the current value of the	option named option
	  associated with the tag given	by tagName .  Option  may have any of
	  the values accepted by the tag configure  widget command.

	$table->tagCol(tagName,	?col, ...?)
	  With no arguments, prints out	the list of cols that use the tag.
	  Otherwise it sets the	specified columns to use the named tag,
	  replacing any	tag that may have been set using this method before.
	  If <tagName> is '', the cols are reset to the	default	tag.  Tags
	  added	during -coltagcommand evaluation do not	register here.	If
	  tagName does not exist, it will be created with the default options.

	$table->tagConfigure(tagName, ?option?,	?value?, ?option, value, ...?)
	  This command is similar to the configure  widget command except that
	  it modifies options associated with the tag given by tagName
	  instead of modifying options for the overall table widget.  If no
	  option  is specified,	the command returns a list describing all of
	  the available	options	for tagName  (see Tk_ConfigureInfo  for
	  information on the format of this list).  If option  is specified
	  with no value	, then the command returns a list describing the one
	  named	option (this list will be identical to the corresponding
	  sublist of the value returned	if no option  is specified).  If one
	  or more option-value	pairs are specified, then the command modifies
	  the given option(s) to have the given	value(s) in tagName ; in this
	  case the command returns an empty string. See	TAGS above for details
	  on the options available for tags.

	$table->tagDelete(tagName)
	  Deletes a tag.  No error if the tag does not exist.

	$table->tagExists(tagName)
	  Returns 1 if the named tag exists, 0 otherwise.

	$table->tagIncludes(tagName, index)
	  Returns 1 if the specified index has the named tag, 0	otherwise.

	$table->tagLower(tagName, ?belowThis?)
	  Lower	the priority of	the named tag.	If belowThis is	not specified,
	  then the tag's priority is lowered to	the bottom, otherwise it is
	  lowered to one below belowThis.

	$table->tagNames(?pattern?)
	  If no	pattern	is specified, shows the	names of all defined tags.
	  Otherwise the	pattern	is used	as a glob pattern to show only tags
	  matching that	pattern.  Tag names are	returned in priority order
	  (highest priority tag	first).

	$table->tagRaise(tagName, ?aboveThis?)
	  Raise	the priority of	the named tag.	If aboveThis is	not specified,
	  then the tag's priority is raised to the top,	otherwise it is	raised
	  to one above aboveThis.

	$table->tagRow(tagName,	?row, ...?)
	  With no arguments, prints out	the list of rows that use the tag.
	  Otherwise it sets the	specified columns to use the named tag,
	  replacing any	tag that may have been set using this method before.
	  If tagName is	'', the	rows are reset to use the default tag.	Tags
	  added	during -rowtagcommand evaluation do not	register here.	If
	  tagName does not exist, it will be created with the default options.

	$table->validate(index)
	 Explicitly validates the specified index based	on the current
	 -validatecommand  and returns 0 or 1 based on whether the cell	was
	 validated.

	$table->window(option, ?arg, arg, ...?)
	 This command is used to manipulate embedded windows.  The exact
	 behavior of the command depends on the	option	argument that follows
	 the window  argument.	The following forms of the command are
	 currently supported:

	$table->windowCget(index, option)
	  This command returns the current value of the	option named option
	  associated with the window given by index .  Option  may have	any of
	  the values accepted by the window configure  widget command.

	$table->windowConfigure(index, ?option?, ?value?, ?option, value,
	...?)
	  This command is similar to the configure  widget command except that
	  it modifies options associated with the embedded window given	by
	  index	 instead of modifying options for the overall table widget.
	  If no	option	is specified, the command returns a list describing
	  all of the available options for index  (see Tk_ConfigureInfo	 for
	  information on the format of this list).  If option  is specified
	  with no value	, then the command returns a list describing the one
	  named	option (this list will be identical to the corresponding
	  sublist of the value returned	if no option  is specified).  If one
	  or more option-value	pairs are specified, then the command modifies
	  the given option(s) to have the given	value(s) in index ; in this
	  case the command returns an empty string. See	EMBEDDED WINDOWS above
	  for details on the options available for windows.

	$table->windowDelete(index, ?index, ...?)
	  Deletes an embedded window from the table.  The associated window
	  will also be deleted.

	$table->windowMove(indexFrom, indexTo)
	  Moves	an embedded window from	one cell to another.  If a window
	  already exists in the	target cell, it	will be	deleted.

	$table->windowNames(?pattern?)
	  If no	pattern	is specified, shows the	cells of all embedded windows.
	  Otherwise the	pattern	is used	as a glob pattern to show only cells
	  matching that	pattern.

	$table->xview(args)
	 This command is used to query and change the horizontal position of
	 the information in the	widget's window.  It can take any of the
	 following forms:

	$table->xview()
	 Returns a list	containing two elements. Each element is a real
	 fraction between 0 and	1;  together they describe the horizontal span
	 that is visible in the	window.	For example, if	the first element is
	 .2 and	the second element is .6, 20% of the table's text is off-
	 screen	to the left, the middle	40% is visible in the window, and 40%
	 of the	text is	off-screen to the right. These are the same values
	 passed	to scrollbars via the -xscrollcommand  option.

	$table->xview(index)
	 Adjusts the view in the window	so that	the column given by index  is
	 displayed at the left edge of the window.

	$table->xviewMoveto(fraction)
	 Adjusts the view in the window	so that	fraction  of the total width
	 of the	table text is off-screen to the	left. fraction	must be	a
	 fraction between 0 and	1.

	$table->xviewScroll(number, what)
	 This command shifts the view in the window left or right according to
	 number	 and what . Number  must be an integer.	What must be either
	 units	or pages  or an	abbreviation of	one of these. If what  is
	 units , the view adjusts left or right	by number  cells on the
	 display;  if it is pages  then	the view adjusts by number
	 screenfuls. If	number	is negative then cells farther to the left
	 become	visible;  if it	is positive then cells farther to the right
	 become	visible.

	$table->yview(?args?)
	 This command is used to query and change the vertical position	of the
	 text in the widget's window.  It can take any of the following	forms:

	$table->yview()
	  Returns a list containing two	elements, both of which	are real
	  fractions between 0 and 1.  The first	element	gives the position of
	  the table element at the top of the window, relative to the table as
	  a whole (0.5 means it	is halfway through the table, for example).
	  The second element gives the position	of the table element just
	  after	the last one in	the window, relative to	the table as a whole.
	  These	are the	same values passed to scrollbars via the
	  -yscrollcommand  option.

	$table->yview(index)
	  Adjusts the view in the window so that the row given by index	 is
	  displayed at the top of the window.

	$table->yviewMoveto(fraction)
	  Adjusts the view in the window so that the element given by fraction
	  appears at the top of	the window. Fraction  is a fraction between 0
	  and 1;  0 indicates the first	element	in the table, 0.33 indicates
	  the element one-third	the way	through	the table, and so on.

	$table->yviewscroll(number, what)
	  This command adjusts the view	in the window up or down according to
	  number  and what .  Number  must be an integer.  What	 must be
	  either units	or pages .  If what  is	units ,	the view adjusts up or
	  down by number  cells; if it is pages	 then the view adjusts by
	  number  screenfuls.  If number  is negative then earlier elements
	  become visible; if it	is positive then later elements	become
	  visible.

Default	Bindings
       The initialization creates class	bindings that give the following
       default behaviour:

       [1]
	Clicking Button-1 in a cell activates that cell.  Clicking into	an
	already	active cell moves the insertion	cursor to the character
	nearest	the mouse.

       [2]
	Moving the mouse while Button-1	is pressed will	stroke out a selection
	area. Exiting while Button-1 is	pressed	causing	scanning to occur on
	the table along	with selection.

       [3]
	Moving the mouse while Button-2	is pressed causes scanning to occur
	without	any selection.

       [4]
	Home moves the table to	have the origin	in view.

       [5]
	End moves the table to have the	end  cell in view.

       [6]
	Control-Home moves the table to	the origin and activates that cell.

       [7]
	Control-End moves the table to the end and activates that cell.

       [8]
	Shift-Control-Home extends the selection to the	origin.

       [9]
	Shift-Control-End extends the selection	to the end.

       [10]
	The left, right, up and	down arrows move the active cell.

       [11]
	Shift-<arrow> extends the selection in that direction.

       [12]
	Control-leftarrow and Control-rightarrow move the insertion cursor
	within the cell.

       [13]
	Control-slash selects all the cells.

       [14]
	Control-backslash clears selection from	all the	cells.

       [15]
	Backspace deletes the character	before the insertion cursor in the
	active cell.

       [16]
	Delete deletes the character after the insertion cursor	in the active
	cell.

       [17]
	Escape rereads the value of the	active cell from the specified data
	source,	discarding any edits that have may been	performed on the cell.

       [18]
	Control-a moves	the insertion cursor to	the beginning of the active
	cell.

       [19]
	Control-e moves	the insertion cursor to	the end	of the active cell.

       [20]
	Control-minus and Control-equals decrease and increase the width of
	the column with	the active cell	in it.

       [21]
	Moving the mouse while Button-3	(the right button on Windows) is
	pressed	while you are over a border will cause interactive resizing of
	that row and/or	column to occur, based on the value of -resizeborders
	. Some bindings	may have slightly different behavior dependent on the
	-selectionmode	of the widget. If the widget is	disabled using the
	-state	option,	then its view can still	be adjusted and	cells can
	still be selected, but no insertion cursor will	be displayed and no
	cell modifications will	take place. The	behavior of tables can be
	changed	by defining new	bindings for individual	widgets	or by
	redefining the class bindings.	The default bindings are either
	compiled in the	TableMatrix.pm file

Performance Issues
       The number of rows and columns or a table widget	should not
       significantly affect the	speed of redraw.  Recalculation	and redraw of
       table parameters	and cells is restricted	as much	as possible. The
       display cell with the insert cursor is redrawn each time	the cursor
       blinks, which causes a steady stream of graphics	traffic.  Set the
       -insertofftime  option to 0 avoid this.	The use	of a -command with the
       table without a cache can cause significant slow-down, as the command
       is called once for each request of a cell value.

Examples
       Set the topleft title area to be	one spanning cell.  This overestimates
       both row	and column span	by one,	but the	command	does all the
       constraining for	us.  $table span [$table cget -roworigin],[$table cget
       -colorigin] [$table cget	-titlerows],[$table cget -titlecols]  Force a
       table window refresh (useful for	the slight chance that a bug in	the
       table is	not causing proper refresh):  $table configure -padx [$table
       cget -padx]

Keywords
       table, widget, extension

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

       Around line 938:
	   L<> starts or ends with whitespace

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

       Around line 1608:
	   You forgot a	'=back'	before '=head1'

perl v5.24.1			  2002-11-18			TableMatrix(3)

NAME | Synopsis | STANDARD OPTIONS | Widget-specific Options | DESCRIPTION | Indices | Tags | Embedded Windows | the Selection | Row/Col Spanning | Command Substitution | Widget Methods | Default Bindings | Performance Issues | Examples | Keywords | POD ERRORS

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

home | help