man page(1) manual page
Table of Contents

NAME

tktable pathName ?options?

DESCRIPTION

The tktable 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 an optional selected cell, the contents of which can optionally be edited. 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 colour for a few seconds.

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

WIDGET COMMANDS

pathname configure ?arg arg ...?
Configures the widget. These are the same options that can be specified on the original creation line for the widget. With no arguments it prints a list of configuration options and their values, with one argument it prints the value for that option.

pathname cget option
Returns the current value of the given option.

-background
background colour

-bg
synonym for background

-foreground
foreground colour

-fg
synonym for colour

-cursorbg
The colour for the cursor

-borderwidth
borderwidth in pixels or units like mm

-rows
number of rows

-cols
number of cols

-width default
column width in characters in the default font

-height
height of default row in pixels (0 means set to font height)

-colorigin
column origin of top left corner of screen into the array variable (ie first column maps to array(x, $colorigin)

-roworigin
row origin of top left corner of screen into the array variable (ie first row maps to array(x, $roworigin)

-maxwidth
The max width in pixels that the window will request

-maxwidth
The max height in pixels that the window will request

-rowtitle
number of rows to use as the title

-coltitle
number of columns to use as a title

-variable
variable to attach to the array, will create it if it doesn't exist

-relief
the relief for the cells flat, raised etc.

-font
default font

-anchor
the anchor point for each of the cells

-xscrollcmd
the command issued to the xscrollbar, usually { <scrollname> set }

-yscrollcmd
the command issued to the yscrollbar, usually { <scrollname> set }

-rowfirstmode
if true, the index into the array is (row,col) else it is (col,row)

pathname width ?arg arg ...?
sets the width of individual columns to a multiple of the width of a character in the default font.

pathname width
shows the widths of all columns not set to the default width.

pathname width {col width} | col ... sets or resets the width of the specified column.

pathname height ?arg arg ...?
sets the height of individual rows to a number of pixels.

pathname height
shows the heights of all rows not set to the default height.

pathname height {row width} | row sets or resets the height of the specified row.

pathname height row
shows the actual height of the row in pixels

pathname getwidth col
shows the actual width of the column in characters

pathname tag option ?arg arg ...?
calls the tag functions to give various styles to a row, column or cell

pathname tag names
shows the names of all defined tags

pathname tag delete tag
deletes a tag. No error if the tag does not exist

pathname tag configure tag ?arg arg ... ? configures a tag. The options can all be set to null in which case the attribute from the default tag are used instead. Using config_ure with a new tag name adds the tag, with an existing tag it reconfigures it. If there are no arguments, it prints the tag configuration, with one argument, it prints the tag information for that attribute. The following attributes can be set per tag

-background
background colour

-bg
synonym for background

-foregroundfR
foreground colour

-fg
synonym for colour

-font
font for the tag

-anchor
anchor for the tag

-relief
the relief for the tag

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 NULL ie {}, the rows are reset to use the default tag.

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 NULL ie {}, the cols are reset to the default =tag.

pathname tag celltag tag ?{<row> <col>} ... ? 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 NULL ie {}, the cells are reset to the default tag.

pathname toprow ?arg?
Sets the topmost row in the main body of the display to the given argument. This is relative to the title row ie. if there are three title rows, and toprow is set to two, then the title rows will be followed by row five of the table. If there is no argument then it prints the value of the top row.

pathname leftcol ?arg?
Sets the leftmost column in the main body of the display to the given argument. This is relative to the title column ie. if there are two title rows, and leftcol is set to four, then the title cols will be followed by row six of the table. If there is no argument then it prints the value of the left column.

pathname whatcell arg arg
gives the row, column of the cell at cursor position (x,y)

pathname wheris arg arg
gives the x, y, width and height of the cell at position (row, col) in pixels. Useful for positioning menus.

pathname setcell ?arg arg?
With no arguments, prints out the location of the current /fIselected cell/fR. With two arguments, sets the /fIselected cell/fR to that (row, column) position

pathname getcellval
gives the current cell's value.

pathname icursor ?arg?
With no arguments, prints out the location of the insertion cursor in the current 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 insert arg arg
the second argument is a text string which is inserted at the cursor position specified by the first argument. The cursor is then positioned after the new text. The position argument can be a number, `insert' or `end'

pathname delete arg ?arg?
deletes text from the current selected cell. If only one argument is given, deletes the character after that argument, otherwise it deletes from the first argument to the second. The arguments can be a number, `insert' or `end'.

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 editmode arg
sets the editing mode to one of three options

off
no editing is allowed

autoclear
the first keypress deletes the text in the cell

noclear
the cell is not cleared on the first keypress

pathname drawmode arg
sets the drawing mode to one of three options

slow
the table is drawn to an offscreen pixmap, using the tk bordering functions. This means there wil 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

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

pathname flash option ?arg?
sets the parameters for the flashing for updating cells

pathname flash mode on|off
turns flashing on or off. Note that flashing will only be turned on by this command if a tag is set up for the flashed cells to be painted in.

pathname flash tag tagname
sets the flashing cells to be painted with this tag style. The tag must already exist.

pathname timeout arg
sets the number of 1/4 second tics before a cell reverts to its usual style.

pathname batch on|off
turns batch mode on or off. When it is on, updates are not forced out at any point, the widget waits for Tk to be idle before it repaints the screen. When batch mode is off, flashes, variable updates and the cursor changes are forced immediately to the screen.

pathname rowstretch option ?arg?
sets the parameters for stretching rows to fill the assigned window space. Note that if you do not pack the table with -fill both -expand on the packing manager will not allocate extra space for the window and it will not stretch.

pathname rowstretch none
Rows will not stretch to fill the assigned window space. If the rows are too narrow, there will be a blank space at the bottom of the table.

pathname rowstretch unset
Only rows that do not have a specific height set will be stretched.

pathname rowstretch all
All rows will be stretched by the same number of pixels to fill the window space allocated to the table.

pathname colstretch option
sets the parameters for stretching columns to fill the assigned window space. Note that if you do not pack the table with -fill both -expand on the packing manager will not allocate extra space for the window and it will not stretch.

pathname colstretch 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.

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

pathname colstretch all
All columns will be stretched by the same number of pixels to fill the window space allocated to the table.

DEFAULT BINDINGS

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

[1]
Clicking the mouse button in a cell moves the selection to that cell.

[2]
The left, right, up and down arrows move the selected cell.

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

[4]
Backspace deletes the character before the insertion cursor.

[5]
Delete deletes the character after the insertion cursor.

[6]
Escape rereads the value from the array variable, discarding the edits that have been performed on the cell.

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

Table of Contents