Table of Contents
table - Create and manipulate tables
table pathName
?options?
-anchor -background -borderwidth -cursor
-font -foreground -highlightbackground -highlightcolor
-highlightthickness -insertbackground -insertborderwidth
-insertofftime -insertontime -insertwidth -relief
-takefocus -xscrollcommand -yscrollcommand
See the options manual entry for
details on the standard options.
Command-Line Name: -autoclear
Database Name: autoClear
Database Class: AutoClear
- A boolean value which
specifies whether the first keypress in a cell will
- delete whatever text
was previously there. Defaults to 0.
Command-Line Name: -batchmode
Database
Name: batchMode
Database Class: BatchMode
- If true, updates are not forced
out at any point, the widget waits for Tk to
- be idle before it repaints
the screen. Otherwise flashes, variable updates and the cursor changes
are forced immediately to the screen. Defaults to 0.
Command-Line Name: -colorigin
Database Name: colOrigin
Database Class: Origin
- Column origin of top left
corner of screen into the array variable
- First column maps to array(x,
$colorigin). Defaults to 0.
Command-Line Name: -cols
Database Name: cols
Database
Class: Cols
- Number of cols in the table. Defaults to 10.
Command-Line Name: -colstretchmode
Database Name: colStretchMode
Database 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.
- 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.
Command-Line Name: -coltagcommand
Database Name: colTagCommand
Database 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 coltag widget command. 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.
Command-Line Name: -drawmode
Database Name: drawMode
Database
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. This means there will be no flashing, but this mode is slow
for all but small 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. This mode provides best performance for large
tables, but can flash on redraw and is not 100% Tk compatible on the border
mode.
Command-Line Name: -flashmode
Database Name: flashMode
Database 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.
Command-Line Name: -flashtime
Database Name: flashTime
Database Class: FlashTime
- The amount of time,
in 1/4 second increments, for which a cell should flash
- when it is edited.
-flashmode must be on. Defaults to 2.
Command-Line Name: -height
Database
Name: height
Database Class: Height
- Height of default row in pixels (-1,
the default, means set to font height).
Command-Line Name: -maxheight
Database
Name: maxHeight
Database Class: MaxHeight
- The max height in pixels that
the window will request. Defaults to 800.
Command-Line Name: -maxwidth
Database
Name: maxWidth
Database Class: MaxWidth
- The max width in pixels that the
window will request. Defaults to 1000.
Command-Line Name: -rowfirstmode
Database
Name: rowFirstMode
Database Class: RowFirstMode
- If true, the index into
the array is (row,col) else it is (col,row).
- Defaults to true.
Command-Line
Name: -roworigin
Database Name: rowOrigin
Database Class: Origin
- Row origin
of top left corner of screen into the array variable.
- First row maps to
array(x, $roworigin). Defaults to 0.
Command-Line Name: -rows
Database Name: rows
Database Class: Rows
- Number of rows in the table. Defaults to 10.
Command-Line
Name: -rowstretchmode
Database Name: rowStretchMode
Database Class: StretchMode
- Specifies the stretch modes for rows to fill extra
- allocated window space.
See -colstretchmode for valid options.
Command-Line Name: -rowtagcommand
Database
Name: rowTagCommand
Database 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
Command-Line Name: -selectmode
Database
Name: selectMode
Database 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 single. These styles are like those
for the Tk listbox, except expanded for 2 dimensions.
Command-Line Name: -state
Database Name: state
Database 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.
Command-Line Name: -titlerows
Database Name: titleRows
Database Class: TitleRows
- Number of rows to use
as a title area. Defaults to 0.
Command-Line Name: -titlecols
Database Name: titleCols
Database Class: TitleCols
- Number of columns to use as a title area. Defaults
to 0.
Command-Line Name: -variable
Database Name: variable
Database Class: Variable
- Tcl array variable to attach to the table's C array. It will be created
- if it doesn't already exist. The table is effectively useless without an
attached array (no data will be stored).
Command-Line Name: -width
Database
Name: width
Database Class: Width
- Default column width in characters in
the default font. Defaults to 10.
The table command
creates a 2-dimensional grid of cells which can used to display, or update
the contents of a Tcl array variable. The table can index into the array
on either a row-first or column-first basis. The widget has a selected 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 foreground, background, font, relief and anchor
for a row, column or cell. A cell flash can be set up so that newly changing
cells will change color for a specified amount of time.
In order to obtain
good performance, the Table widget supports three drawing modes, two of
which are fully Tk compatible.
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 (or col,row if -rowfirstmode is
0), where -roworigin,-colorigin corresponds to the first cell in the table
(0,0 by default).
- 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.
- 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.
- select
- Indicates the last selected cell of the table.
- 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.
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. There may be any number
of tags associated with rows, columns or cells in a table. 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.
Tags control the way
cells are displayed on the screen. By default, cells are displayed as determined
by the background, font, and foreground options for the table widget. However,
display options may be associated with individual tags using the ``pathName
tag configure'' widget command. If a cell 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
- anchoring in
the cell space
- -background or -bg
- background color of the cell
- -font
- font
for the cell
- -foreground or -fg
- foreground color of the cell
- -relief
the
relief for the cell
A priority order is defined among tags, 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. Including the special tags, this order is active,
flash, sel, title, celltag, rowtag, coltag, default.
If a cell has several
tags associated with it, and if their display options conflict, 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 never be used; the next-highest-priority
tag's option will used instead. If no tag specifies a particular display
option, then the default style for the widget will be used.
The
table command creates a new Tcl command whose name is pathName. This command
may be used to invoke various operations on the widget. It has the following
general form:
pathName option ?arg arg ...?
Option and the args determine
the exact behavior of the command.
The following commands are possible
for table widgets:
- pathName activate index
- Sets the active cell to the
one indicated by index.
- pathName bbox index
- Gives the x, y, width and height
of the cell at the index in pixels, if it is visible in the display. Otherwise
an empty string is returned.
- pathName boundary top|left|bottom|right ?rowOrCol?
- If no argument is given, it prints the value of the rowOrCol that is displayed
at that edge of the displayed region. For top|left, that rowOrCol can be
set with the extra argument.
- pathName 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.
- pathName 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.
- pathName curselection ?set value?
- With no arguments,
it returns the 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.
- pathName curvalue
- Returns the value of the cell being edited (indexed by active).
- pathName
delete option arg ?arg?
- This command is used to delete various things
in a table. It has several forms, depending on the option:
- pathName delete
active 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.
- pathName delete cols col ?number?
- Currently unsupported.
- pathName delete
rows row ?number?
- Currently unsupported.
- pathName get first ?last?
- Returns
the value of the cells specified by the table indices first and (optionally)
last.
- pathName height ?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
pixels. If one or more row-value pairs are specified, then it sets each
row to be that height in pixels. If value is negative, then the row uses
the default height.
- pathName 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.
- pathName index index ?row|col?
- Returns the integer cell
coordinate that corresponds to index in the form row,col (or col,row if
-rowfirstmode is 0). If row or col is specified, them only the row or col
index is returned.
- pathName insert option arg arg
- This command is used
to into various things into a table. It has several forms, depending on
the option:
- pathName insert active 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.
- pathName insert cols col number
- Currently unsupported.
- pathName insert
rows row number
- Currently unsupported.
- pathName reread
- Rereads the old
contents of the cell back into the editing buffer. Useful for a key binding
when <esc> is pressed to abort the edit.
- pathName scan option args
- This command
is used to implement scanning on tables. It has two forms, depending on
option:
- pathName scan mark 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.
- pathName scan dragto 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.
- pathName 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.
- pathName selection option arg
- This command is used to adjust the selection
within a table. It has several forms, depending on option:
- pathName selection
anchor 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.
- pathName selection clear 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.
- pathName
selection includes index
- Returns 1 if the cell indicated by index is currently
selected, 0 if it isn't.
- pathName selection set 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.
- pathName set index value
?index value ...?
- Sets the specified index to the associated value.
- pathName
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. The following forms of the command are currently supported:
- pathName tag celltag tag ?index ... ?
- With no arguments, prints out the list
of cells that use the tag. Otherwise it sets the specified cells to use
the tag. If tag is {}, the cells are reset to the default tag. Tags added
during -*tagcommand evaluation do not register here.
- pathName tag cget 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.
- pathName tag coltag tag ?col
... ?
- With no arguments, prints out the list of cols that use the tag. Otherwise
it sets the specified cols to use the tag. If tag is {}, the cols are
reset to the default tag. Tags added during -coltagcommand evaluation do
not register here.
- pathName tag configure 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 text 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.
- pathName tag delete tagName
- Deletes a tag. No error if the tag does
not exist.
- pathName tag exists tagName
- Returns 1 if the named tag exists,
0 otherwise.
- pathName tag names ?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.
- pathName tag rowtag tag
?row ...?
- With no arguments, prints out the list of rows that use the tag.
Otherwise it sets the specified rows to use the tag. If tag is {}, the
rows are reset to use the default tag. Tags added during -rowtagcommand
evaluation do not register here.
- pathName width ?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. If one or more col-value pairs are
specified, then it sets each col to be that width in characters. If value
is negative, then the col uses the default width.
- pathName 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:
- pathName
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.
- pathName xview index
- Adjusts the view in the window so that the
character position given by index is displayed at the left edge of the
window. Character positions are defined by the width of the character 0.
- pathName xview moveto 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.
- pathName xview scroll 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 character units (the width of the 0 character)
on the display; if it is pages then the view adjusts by number screenfuls.
If number is negative then characters farther to the left become visible;
if it is positive then characters farther to the right become visible.
- pathName 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:
- pathName 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.
- pathName yview index
- Adjusts the view in the window so that the element given by index is displayed
at the top of the window.
- pathName yview moveto 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.
- pathName yview scroll 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 lines; 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.
The initialization creates class bindings that
give the following default behaviour:
- Clicking the mouse button in a cell
activates that cell.
- 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.
- Moving the mouse while button
2 is pressed causes scanning to occur without any selection.
- Home moves
the table to have the origin in view.
- End moves the table to have the end
cell in view.
- Control-Home moves the table to the origin and activates that
cell.
- Control-End moves the table to the end and activates that cell.
- Shift-Control-Home
extends the selection to the origin.
- Shift-Control-End extends the selection
to the end.
- The left, right, up and down arrows move the active cell.
- Shift-<arrow>
extends the selection in that direction.
- Control-leftarrow and Control-rightarrow
move the insertion cursor within the cell.
- Control-slash selects all the
cells.
- Control-backslash clears selection from all the cells.
- Backspace deletes
the character before the insertion cursor in the active cell.
- Delete deletes
the character after the insertion cursor in the active cell.
- Escape rereads
the value of the active cell from the array variable, discarding any edits
that have may been performed on the cell.
- Return sets the array value of
the active cell to the edited value and moves to the next cell down.
- Control-a
moves the insertion cursor to the beginning of the active cell.
- Control-e
moves the insertion cursor to the end of the active cell.
- Control-minus
and Control-equals decrease and increase the width of the column with the
active cell in it.
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 or read from a file expected to
correspond to: "[lindex $tcl_pkgPath 0]/Tktable/tkTable.tcl".
table,
widget, extension
Table of Contents