diff options
| author | William Joye <wjoye@cfa.harvard.edu> | 2016-10-27 18:27:18 (GMT) |
|---|---|---|
| committer | William Joye <wjoye@cfa.harvard.edu> | 2016-10-27 18:27:18 (GMT) |
| commit | 949f96e29bfe0bd8710d775ce220e597064e2589 (patch) | |
| tree | ae84b7ae710575f4debb610a126b1317a2247777 /tktable/doc | |
| parent | 5b44fb0d6530c4ff66a446afb69933aa8ffd014f (diff) | |
| parent | 32c31a3b172990fd736e0ed21bcab1e1d6ab6570 (diff) | |
| download | blt-949f96e29bfe0bd8710d775ce220e597064e2589.zip blt-949f96e29bfe0bd8710d775ce220e597064e2589.tar.gz blt-949f96e29bfe0bd8710d775ce220e597064e2589.tar.bz2 | |
Merge commit '32c31a3b172990fd736e0ed21bcab1e1d6ab6570' as 'tktable'
Diffstat (limited to 'tktable/doc')
| -rw-r--r-- | tktable/doc/tkTable.html | 2039 | ||||
| -rwxr-xr-x | tktable/doc/tkTable.n | 1432 |
2 files changed, 3471 insertions, 0 deletions
diff --git a/tktable/doc/tkTable.html b/tktable/doc/tkTable.html new file mode 100644 index 0000000..4b264ff --- /dev/null +++ b/tktable/doc/tkTable.html @@ -0,0 +1,2039 @@ +<!-- manual page source format generated by PolyglotMan v3.0.8+X.Org, --> +<!-- available at http://polyglotman.sourceforge.net/ --> + +<html> +<head> +<title>man page(1) manual page</title> +</head> +<body bgcolor='#efefef' text='black' link='blue' vlink='#551A8B' alink='red'> +<a href='#toc'>Table of Contents</a><p> +______________________________________________________________________________ + +<p> +<h2><a name='sect0' href='#toc0'><b>Name</b></a></h2> + +<p> +table - Create and manipulate tables + +<p> +<h2><a name='sect1' href='#toc1'><b>Synopsis</b></a></h2> + +<p> +<b>table</b> <i>pathName</i> ?<i>options</i>? + +<p> +<h2><a name='sect2' href='#toc2'><b>Standard</b> <b>Options</b></a></h2> + + +<dl> + +<dt><b>-anchor</b> </dt></dt> +<dd> <b>-background</b> <b>-cursor</b> +</dd> + +<dt><b>-exportselection</b> </dt></dt> +<dd> <b>-font</b> <b>-foreground</b> +</dd> + +<dt><b>-highlightbackground</b> </dt></dt> +<dd> <b>-highlightcolor</b> <b>-highlightthickness</b> +</dd> + +<dt><b>-insertbackground</b> </dt></dt> +<dd> <b>-insertborderwidth-insertofftime</b> +<b>-insertontime</b> <b>-insertwidth</b> <b>-invertselected</b> +</dd> + +<dt><b>-relief</b> </dt></dt> +<dd> <b>-takefocus</b> <b>-xscrollcommand</b> +<b>-yscrollcommand</b> + +<p></dd> +</dl> +<p> +See the <b>options</b> manual entry for details on the standard options. + +<p> +<h2><a name='sect3' href='#toc3'><b>Widget-specific</b> <b>Options</b></a></h2> + +<p> +Command-Line Name:<b>-autoclear</b><br> + +Database Name: <b>autoClear</b><br> + +Database Class: <b>AutoClear</b> + +<p><p> +A boolean value which specifies whether the first keypress in a +cell will delete whatever text was previously there. Defaults +to 0. + +<p><p> +Command-Line Name:<b>-bordercursor</b><br> + +Database Name: <b>borderCursor</b><br> + +Database Class: <b>Cursor</b> + +<p><p> +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 +<i>crosshair</i>. + +<p><p> +Command-Line Name:<b>-borderwidth</b> <b>or</b> <b>-bd</b><br> + +Database Name: <b>borderWidth</b><br> + +Database Class: <b>BorderWidth</b> + +<p><p> +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 <b>relief</b> 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 <b>-drawmode</b> for the table. Each value in the list must +have one of the forms acceptable to <b>Tk_GetPixels</b>. + +<p><p> +Command-Line Name:<b>-browsecommand</b> <b>or</b> <b>-browsecmd</b> +Database Name: <b>browseCommand</b><br> + +Database Class: <b>BrowseCommand</b> + +<p><p> +Specifies a command which will be evaluated anytime the active +cell changes. It uses the %-substition model described in COMMAND +SUBSTITUTION below. Any changes to the active cell while +the command is running are ignored to prevent recursion. + +<p><p> +Command-Line Name:<b>-cache</b><br> + +Database Name: <b>cache</b><br> + +Database Class: <b>Cache</b> + +<p><p> +A boolean value that specifies whether an internal cache of the +table contents should be kept. This greatly enhances speed performance +when used with <b>-command</b> but uses extra memory. Can +maintain state when both <b>-command</b> and <b>-variable</b> are empty. The +cache is automatically flushed whenever the value of <b>-cache</b> or +<b>-variable</b> changes, otherwise you have to explicitly call <b>clear</b> +on it. Defaults to off. + +<p><p> +Command-Line Name:<b>-colorigin</b><br> + +Database Name: <b>colOrigin</b><br> + +Database Class: <b>Origin</b> + +<p><p> +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. + +<p><p> +Command-Line Name:<b>-cols</b><br> + +Database Name: <b>cols</b><br> + +Database Class: <b>Cols</b> + +<p><p> +Number of cols in the table. Defaults to 10. + +<p><p> +Command-Line Name:<b>-colseparator</b><br> + +Database Name: <b>colSeparator</b><br> + +Database Class: <b>Separator</b> + +<p><p> +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. + +<p><p> +Command-Line Name:<b>-colstretchmode</b><br> + +Database Name: <b>colStretchMode</b><br> + +Database Class: <b>StretchMode</b> + +<p><p> +Specifies one of the following stretch modes for columns to fill +extra allocated window space: + +<p><p> +<b>none</b> 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. + +<p><p> +<b>unset</b> Only columns that do not have a specific width set will +be stretched. + +<p> +<dl> + +<dt><b>all</b> </dt></dt> +<dd> 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. + +<p></dd> +</dl> +<p> +<b>last</b> The last column will be stretched to fill the window +space allocated to the table. + +<p><p> +<b>fill</b> (only valid for <b>-rowstretch</b> 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. + +<p><p> +Command-Line Name:<b>-coltagcommand</b><br> + +Database Name: <b>colTagCommand</b><br> + +Database Class: <b>TagCommand</b> + +<p><p> +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 <b>tag</b> <b>col</b> 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 occurring during the evaluation of the procedure, or the +return of an invalid tag name are silently ignored. + +<p><p> +Command-Line Name:<b>-colwidth</b><br> + +Database Name: <b>colWidth</b><br> + +Database Class: <b>ColWidth</b> + +<p><p> +Default column width, interpreted as characters in the default +font when the number is positive, or pixels if it is negative. +Defaults to 10. + +<p><p> +Command-Line Name:<b>-command</b><br> + +Database Name: <b>command</b><br> + +Database Class: <b>Command</b> + +<p><p> +Specified a command to use as a procedural interface to cell +values. If <b>-usecommand</b> is true, this command will be used +instead of any reference to the <b>-variable</b> array. When retrieving +cell values, the return value of the command is used as the +value for the cell. It uses the %-substition model described in +COMMAND SUBSTITUTION below. + +<p><p> +Command-Line Name:<b>-drawmode</b><br> + +Database Name: <b>drawMode</b><br> + +Database Class: <b>DrawMode</b> + +<p><p> +Sets the table drawing mode to one of the following options: + +<p><p> +<b>slow</b> 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. + +<p><p> +<b>compatible</b><br> + +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. + +<p> +<dl> + +<dt><b>fast</b> </dt></dt> +<dd>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 <b>-borderwidth</b> +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. + +<p></dd> +</dl> +<p> +<b>single</b> The table is drawn to the screen as in fast mode, but +only single pixel lines are drawn (not square borders). + +<p><p> +Command-Line Name:<b>-ellipsis</b><br> + +Database Name: <b>ellipsis</b><br> + +Database Class: <b>Ellipsis</b> + +<p><p> +This specifies a string to display at the end of a line that +would be clipped by its cell, like ``...''. An ellipsis will be +displayed only on non-wrapping, non-multiline cells that would +be clipped. The ellipsis will display on the left for east +anchored cells, otherwise it displays on the right. Defaults to + (no ellipsis). + +<p><p> +Command-Line Name:<b>-flashmode</b><br> + +Database Name: <b>flashMode</b><br> + +Database Class: <b>FlashMode</b> + +<p><p> +A boolean value which specifies whether cells should flash when +their value changes. The table tag <b>flash</b> will be applied to +these cells for the duration specified by <b>-flashtime</b>. Defaults +to 0. + +<p><p> +Command-Line Name:<b>-flashtime</b><br> + +Database Name: <b>flashTime</b><br> + +Database Class: <b>FlashTime</b> + +<p><p> +The amount of time, in 1/4 second increments, for which a cell +should flash when its value has changed. <b>-flashmode</b> must be on. +Defaults to 2. + +<p><p> +Command-Line Name:<b>-height</b><br> + +Database Name: <b>height</b><br> + +Database Class: <b>Height</b> + +<p><p> +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 <b>-maxheight</b>. + +<p><p> +Command-Line Name:<b>-invertselected</b><br> + +Database Name: <b>invertSelected</b><br> + +Database Class: <b>InvertSelected</b> + +<p><p> +Specifies whether the foreground and background of an item +should simply have their values swapped instead of merging the +<i>sel</i> tag options when the cell is selected. Defaults to 0 (merge +<i>sel</i> tag). + +<p><p> +Command-Line Name:<b>-ipadx</b><br> + +Database Name: <b>ipadX</b><br> + +Database Class: <b>Pad</b> + +<p><p> +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 <b>-padx</b> for an alternate padding style. + +<p><p> +Command-Line Name:<b>-ipady</b><br> + +Database Name: <b>ipadY</b><br> + +Database Class: <b>Pad</b> + +<p><p> +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 <b>-pady</b> for an alternate padding style. + +<p><p> +Command-Line Name:<b>-justify</b><br> + +Database Name: <b>justify</b><br> + +Database Class: <b>Justify</b> + +<p><p> +How to justify multi-line text in a cell. It must be one of +<b>left</b>, <b>right</b>, or <b>center</b>. Defaults to left. + +<p><p> +Command-Line Name:<b>-maxheight</b><br> + +Database Name: <b>maxHeight</b><br> + +Database Class: <b>MaxHeight</b> + +<p><p> +The max height in pixels that the window will request. Defaults +to 600. + +<p><p> +Command-Line Name:<b>-maxwidth</b><br> + +Database Name: <b>maxWidth</b><br> + +Database Class: <b>MaxWidth</b> + +<p><p> +The max width in pixels that the window will request. Defaults +to 800. + +<p><p> +Command-Line Name:<b>-multiline</b><br> + +Database Name: <b>multiline</b><br> + +Database Class: <b>Multiline</b> + +<p><p> +Specifies the default setting for the multiline tag option. +Defaults to 1. + +<p><p> +Command-Line Name:<b>-padx</b><br> + +Database Name: <b>padX</b><br> + +Database Class: <b>Pad</b> + +<p><p> +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 <b>width</b> 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 <b>-ipadx</b> for an alternate padding style. + +<p><p> +Command-Line Name:<b>-pady</b><br> + +Database Name: <b>padY</b><br> + +Database Class: <b>Pad</b> + +<p><p> +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 <b>height</b> 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 <b>-ipadx</b> for an alternate padding style. + +<p><p> +Command-Line Name:<b>-resizeborders</b><br> + +Database Name: <b>resizeBorders</b><br> + +Database Class: <b>ResizeBorders</b> + +<p><p> +Specifies what kind of interactive border resizing to allow, +must be one of row, col, both (default) or none. + +<p><p> +Command-Line Name:<b>-rowheight</b><br> + +Database Name: <b>rowHeight</b><br> + +Database Class: <b>RowHeight</b> + +<p><p> +Default row height, interpreted as lines in the default font +when the number is positive, or pixels if it is negative. +Defaults to 1. + +<p><p> +Command-Line Name:<b>-roworigin</b><br> + +Database Name: <b>rowOrigin</b><br> + +Database Class: <b>Origin</b> + +<p><p> +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. + +<p><p> +Command-Line Name:<b>-rows</b><br> + +Database Name: <b>rows</b><br> + +Database Class: <b>Rows</b> + +<p><p> +Number of rows in the table. Defaults to 10. + +<p><p> +Command-Line Name:<b>-rowseparator</b><br> + +Database Name: <b>rowSeparator</b><br> + +Database Class: <b>Separator</b> + +<p><p> +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. + +<p><p> +Command-Line Name:<b>-rowstretchmode</b><br> + +Database Name: <b>rowStretchMode</b><br> + +Database Class: <b>StretchMode</b> + +<p><p> +Specifies the stretch modes for rows to fill extra allocated +window space. See <b>-colstretchmode</b> for valid options. + +<p><p> +Command-Line Name:<b>-rowtagcommand</b><br> + +Database Name: <b>rowTagCommand</b><br> + +Database Class: <b>TagCommand</b> + +<p><p> +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 <b>-coltagcommand</b>, except that it +applies to row tags. + +<p><p> +Command-Line Name:<b>-selectioncommand</b> <b>or</b> <b>-selcmd</b> +Database Name: <b>selectionCommand</b><br> + +Database Class: <b>SelectionCommand</b> + +<p><p> +Specifies a command to evaluate when the selection is retrieved +from a table via the selection mechanism (ie: evaluating +``<b>selection</b> <b>get</b>''). The return value from this command will +become the string passed on by the selection mechanism. It uses +the %-substition model described in COMMAND SUBSTITUTION below. +If an error occurs, a Tcl background error is generated and +nothing is returned. + +<p><p> +Command-Line Name:<b>-selectmode</b><br> + +Database Name: <b>selectMode</b><br> + +Database Class: <b>SelectMode</b> + +<p><p> +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 <b>single</b>, <b>browse</b>, <b>multiple</b>, or +<b>extended</b>; the default value is <b>browse</b>. These styles are like +those for the Tk listbox, except expanded for 2 dimensions. + +<p><p> +Command-Line Name:<b>-selecttitle</b><br> + +Database Name: <b>selectTitles</b><br> + +Database Class: <b>SelectTitles</b> + +<p><p> +Specifies whether title cells should be allowed in the selection. +Defaults to 0 (disallowed). + +<p><p> +Command-Line Name:<b>-selecttype</b><br> + +Database Name: <b>selectType</b><br> + +Database Class: <b>SelectType</b> + +<p><p> +Specifies one of several types of selection for the table. The +value of the option may be one of <b>row</b>, <b>col</b>, <b>cell</b>, or <b>both</b> +(meaning <b>row</b> <b>&&</b> <b>col</b>); the default value is <b>cell</b>. These types +define whether an entire row/col is affected when a cell's +selection is changed (set or clear). + +<p><p> +Command-Line Name:<b>-sparsearray</b><br> + +Database Name: <b>sparseArray</b><br> + +Database Class: <b>SparseArray</b> + +<p><p> +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. + +<p><p> +Command-Line Name:<b>-state</b><br> + +Database Name: <b>state</b><br> + +Database Class: <b>State</b> + +<p><p> +Specifies one of two states for the entry: <b>normal</b> or <b>disabled</b>. +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 <b>normal</b>. + +<p><p> +Command-Line Name:<b>-titlecols</b><br> + +Database Name: <b>titleCols</b><br> + +Database Class: <b>TitleCols</b> + +<p><p> +Number of columns to use as a title area. Defaults to 0. + +<p><p> +Command-Line Name:<b>-titlerows</b><br> + +Database Name: <b>titleRows</b><br> + +Database Class: <b>TitleRows</b> + +<p><p> +Number of rows to use as a title area. Defaults to 0. + +<p><p> +Command-Line Name:<b>-usecommand</b><br> + +Database Name: <b>useCommand</b><br> + +Database Class: <b>UseCommand</b> + +<p><p> +A boolean value which specifies whether to use the <b>command</b> +option. This value sets itself to zero if <b>command</b> is used and +returns an error. Defaults to 1 (will use <b>command</b> if specified). + +<p><p> +Command-Line Name:<b>-validate</b><br> + +Database Name: <b>validate</b><br> + +Database Class: <b>Validate</b> + +<p><p> +A boolean specifying whether validation should occur for the +active buffer. Defaults to 0. + +<p><p> +Command-Line Name:<b>-validatecommand</b> <b>or</b> <b>-vcmd</b> +Database Name: <b>validateCommand</b><br> + +Database Class: <b>ValidateCommand</b> + +<p><p> +Specifies a command to execute when the active cell is edited. +This command is expected to return a Tcl boolean. If it returns +true, 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. It uses the %-substition +model described in COMMAND SUBSTITUTION below. + +<p><p> +Command-Line Name:<b>-variable</b><br> + +Database Name: <b>variable</b><br> + +Database Class: <b>Variable</b> + +<p><p> +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 +<i>row</i>,<i>col</i> for cells and the special key <i>active</i> which contains the +value of the active cell buffer. The Tcl array is managed as a +sparse array (the table does not require that 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 <b>-sparsearray</b> options is set to 0. + +<p><p> +Command-Line Name:<b>-width</b><br> + +Database Name: <b>width</b><br> + +Database Class: <b>Width</b> + +<p><p> +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 <b>-maxwidth</b>. + +<p><p> +Command-Line Name:<b>-wrap</b><br> + +Database Name: <b>wrap</b><br> + +Database Class: <b>Wrap</b> + +<p><p> +Specifies the default wrap value for tags. Defaults to 0. +_________________________________________________________________ + +<p> +<h2><a name='sect4' href='#toc4'><b>Description</b></a></h2> + +<p> +The <b>table</b> command creates a 2-dimensional grid of cells. The table can +use a Tcl array variable or Tcl command for data storage and retrieval, +as well as optionally cache data in memory for speed. One of these +data sources <i>must</i> be configured before any data is retained by the table. +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 <i>tags</i>, which can be used to change the +style of a row, column or cell (see TAGS for details). A cell <i>flash</i> +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. + +<p><p> +One or more cells may be selected as described below. If a table is +exporting its selection (see <b>-exportselection</b> option), then it will +observe the standard X11 protocols for handling the selection. See THE +SELECTION for details. + +<p><p> +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 +<b>-xscrollcommand</b> and <b>-yscrollcommand</b> options. They also support +scanning, as described below. + +<p><p> +In order to obtain good performance, the table widget supports multiple +drawing modes, two of which are fully Tk compatible. + +<p> +<h2><a name='sect5' href='#toc5'><b>Initialization</b></a></h2> + +<p> +When the <b>table</b> command is loaded into an interpreter, a built-in Tcl +command, <b>tkTableInit</b>, is evaluated. This will search for the appropriate +table binding init file to load. The directories searched are +those in <i>$tcl</i><b>_</b><i>pkgPath</i>, both with Tktable(version) appended and without, +<i>$tk</i><b>_</b><i>library</i> and <i>[pwd]</i> (the current directory). You can also define an +<i>$env(TK</i><b>_</b><i>TABLE</i><b>_</b><i>LIBRARY)</i> to head this search list. By default, the file +searched for is called <b>tkTable.tcl</b>, but this can be overridden by setting +<i>$env(TK</i><b>_</b><i>TABLE</i><b>_</b><i>LIBRARY</i><b>_</b><i>FILE)</i>. + +<p><p> +This entire init script can be overridden by providing your own +<b>tkTableInit</b> procedure before the library is loaded. Otherwise, the +aforementioned <i>env(TK</i><b>_</b><i>TABLE</i><b>_</b><i>LIBRARY)</i> variable will be set with the +directory in which <i>$env(TK</i><b>_</b><i>TABLE</i><b>_</b><i>LIBRARY</i><b>_</b><i>FILE)</i> was found. + +<p> +<h2><a name='sect6' href='#toc6'><b>Indices</b></a></h2> + +<p> +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: + +<p><p> +<i>number,number</i><br> + +Specifies the cell as a numerical index of row,col which +corresponds to the index of the associated Tcl array, where +<b>-roworigin,-colorigin</b> 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. + +<p> +<dl> + +<dt><b>active</b> </dt></dt> +<dd> Indicates the cell that has the location cursor. It is +specified with the <b>activate</b> widget command. + +<p></dd> + +<dt><b>anchor</b> </dt></dt> +<dd> Indicates the anchor point for the selection, which is set +with the <b>selection</b> <b>anchor</b> widget command. + +<p></dd> +</dl> +<p> +<b>bottomright</b> Indicates the bottom-rightmost cell visible in the table. + +<p> +<dl> + +<dt><b>end</b> </dt></dt> +<dd> Indicates the bottom right cell of the table. + +<p></dd> + +<dt><b>origin</b> </dt></dt> +<dd> 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. + +<p></dd> + +<dt><b>topleft</b> </dt></dt> +<dd> Indicates the top-leftmost editable cell visible in the table +(this excludes title cells). + +<p></dd> + +<dt><b>@</b><i>x</i><b>,</b><i>y</i> </dt></dt> +<dd> Indicates the cell that covers the point in the table window +specified by <i>x</i> and <i>y</i> (in pixel coordinates). If no +cell covers that point, then the closest cell to that point +is used. + +<p></dd> +</dl> +<p> +In the widget command descriptions below, arguments named <i>index</i>, <i>first</i>, +and <i>last</i> always contain text indices in one of the above forms. + +<p> +<h2><a name='sect7' href='#toc7'><b>Tags</b></a></h2> + +<p> +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. A tag can apply to an entire row or column, +or just a single cell. There are several permanent tags in each table +that can be configured by the user and will determine the attributes +for special cells: + +<p> +<dl> + +<dt><b>active</b> </dt></dt> +<dd> This tag is given to the <i>active</i> cell + +<p></dd> + +<dt><b>flash</b> </dt></dt> +<dd> If flash mode is on, this tag is given to any recently +edited cells. + +<p></dd> + +<dt><b>sel</b> </dt></dt> +<dd> This tag is given to any selected cells. + +<p></dd> + +<dt><b>title</b> </dt></dt> +<dd> This tag is given to any cells in the title rows and +columns. This tag has <b>-state</b> <i>disabled</i> by default. + +<p></dd> +</dl> +<p> +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 ``<i>pathName</i> <b>tag</b> <b>configure</b>'' widget command. +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: + +<p> +<dl> + +<dt><b>-anchor</b> <i>anchor</i></dt></dt> +<dd> +Anchor for item in the cell space. + +<p></dd> + +<dt><b>-background</b> or <b>-bg</b> <i>color</i></dt></dt> +<dd> +Background color of the cell. + +<p></dd> + +<dt><b>-borderwidth</b> or <b>-bd</b> <i>pixelList</i></dt></dt> +<dd> +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). + +<p></dd> + +<dt><b>-ellipsis</b> <i>string</i></dt></dt> +<dd> +String to display at the end of a line that would be +clipped by its cell, like ``...''. An ellipsis will be +displayed only on non-wrapping, non-multiline cells that +would be clipped. The ellipsis will display on the left +for east anchored cells, otherwise it displays on the +right. + +<p></dd> + +<dt><b>-font</b> <i>fontName</i></dt></dt> +<dd> +Font for text in the cell. + +<p></dd> + +<dt><b>-foreground</b> or <b>-fg</b> <i>color</i></dt></dt> +<dd> +Foreground color of the cell. + +<p></dd> + +<dt><b>-justify</b> <i>justify</i></dt></dt> +<dd> +How to justify multi-line text in a cell. It must be one +of <b>left</b>, <b>right</b>, or <b>center</b>. + +<p></dd> + +<dt><b>-image</b> <i>imageName</i></dt></dt> +<dd> +An image to display in the cell instead of text. + +<p></dd> + +<dt><b>-multiline</b> <i>boolean</i></dt></dt> +<dd> +Whether to display text with newlines on multiple lines. + +<p></dd> + +<dt><b>-relief</b> <i>relief</i></dt></dt> +<dd> +The relief for the cell. May be the empty string to +cause this tag to not disturb the value. + +<p></dd> + +<dt><b>-showtext</b> <i>boolean</i></dt></dt> +<dd> +Whether to show the text over an image. + +<p></dd> + +<dt><b>-state</b> <i>state</i></dt></dt> +<dd> +The state of the cell, to allow for certain cells to be +disabled. This prevents the cell from being edited by +the <i>insert</i> or <i>delete</i> methods, but a direct <i>set</i> will not +be prevented. + +<p></dd> + +<dt><b>-wrap</b> <i>boolean</i></dt></dt> +<dd> +Whether characters should wrap in a cell that is not wide +enough. + +<p></dd> +</dl> +<p> +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 ``<i>path</i><b>_N</b><i>ame</i> +<b>tag</b> <b>lower</b>'' and ``<i>pathName</i> <b>tag</b> <b>raise</b>'' widget commands. + +<p><p> +If a cell has several tags associated with it that define the same +display options (eg - a <b>title</b> cell with specific <b>row</b> and <b>cell</b> 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. + +<p><p> +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 <b>-showtext</b>. + +<p> +<h2><a name='sect8' href='#toc8'><b>Embedded</b> <b>Windows</b></a></h2> + +<p> +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. + +<p><p> +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 <b>window</b> <b>names</b>). + +<p><p> +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: + +<p> +<dl> + +<dt><b>-create</b> <i>script</i></dt></dt> +<dd> +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. + +<p></dd> + +<dt><b>-background</b> or <b>-bg</b> <i>color</i></dt></dt> +<dd> +Background color of the cell. If not specified, it uses +the table's default background. + +<p></dd> + +<dt><b>-borderwidth</b> or <b>-bd</b> <i>pixelList</i></dt></dt> +<dd> +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). + +<p></dd> + +<dt><b>-padx</b> <i>pixels</i></dt></dt> +<dd> +As defined in the Tk options man page. + +<p></dd> + +<dt><b>-pady</b> <i>pixels</i></dt></dt> +<dd> +As defined in the Tk options man page. + +<p></dd> + +<dt><b>-relief</b> <i>relief</i></dt></dt> +<dd> +The relief to use for the cell in which the window lies. +If not specified, it uses the table's default relief. + +<p></dd> + +<dt><b>-sticky</b> <i>sticky</i></dt></dt> +<dd> +Stickiness of the window inside the cell, as defined by +the <b>grid</b> command. + +<p></dd> + +<dt><b>-window</b> <i>pathName</i></dt></dt> +<dd> +Specifies the name of a window (widget) to display in the +annotation. It must exist before being specified here. +When an empty string is specified, if a window was displayed +it will cease to be managed by the table widget. + +<p></dd> +</dl> + +<h2><a name='sect9' href='#toc9'><b>the</b> <b>Selection</b></a></h2> + +<p> +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 <b>-rowseparator</b> and <b>-colseparator</b> options. For example, default +Excel format would be to set <b>-rowseparator</b> to `\n' and <b>-colseparator</b> 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 +<b>tk_tablePasteHandler</b>. This might be necessary if <b>-selectioncommand</b> is +set. + +<p> +<h2><a name='sect10' href='#toc10'><b>Row/Col</b> <b>Spanning</b></a></h2> + +<p> +Individual cells can span multiple rows and/or columns. This is done +via the <b>spans</b> 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. + +<p><p> +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. + +<p><p> +Cells <i>hidden</i> 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 <b>get</b> or <b>set</b>. + +<p><p> +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. + +<p> +<h2><a name='sect11' href='#toc11'><b>Command</b> <b>Substitution</b></a></h2> + +<p> +The various option based commands that the table supports all support +the familiar Tk %-substitution model (see <b>bind</b> for more details). The +following %-sequences are recognized and substituted by the table widget: + +<p><p> +<b>%c</b> For <b>SelectionCommand</b>, it is the maximum number of columns in any +row in the selection. Otherwise it is the column of the triggered +cell. + +<p> +<dl> + +<dt><b>%C</b> </dt></dt> +<dd>A convenience substitution for <i>%r</i>,<i>%c</i>. + +<p></dd> +</dl> +<p> +<b>%i</b> For <b>SelectionCommand</b>, it is the total number of cells in the +selection. For <b>Command</b>, it is 0 for a read (get) and 1 for a +write (set). Otherwise it is the current cursor position in the +cell. + +<p><p> +<b>%r</b> For <b>SelectionCommand</b>, it is the number of rows in the selection. +Otherwise it is the row of the triggered cell. + +<p><p> +<b>%s</b> For <b>ValidateCommand</b>, it is the current value of the cell being +validated. For <b>SelectionCommand</b>, it is the default value of the +selection. For <b>BrowseCommand</b>, it is the index of the last active +cell. For <b>Command</b>, it is empty for reads (get) and the current +value of the cell for writes (set). + +<p><p> +<b>%S</b> For <b>ValidateCommand</b>, it is the potential new value of the cell +being validated. For <b>BrowseCommand</b>, it is the index of the new +active cell. + +<p> +<dl> + +<dt><b>%W</b> </dt></dt> +<dd>The pathname to the window for which the command was generated. + +<p></dd> +</dl> + +<h2><a name='sect12' href='#toc12'><b>Widget</b> <b>Command</b></a></h2> + +<p> +The <b>table</b> command creates a new Tcl command whose name is <i>pathName</i>. +This command may be used to invoke various operations on the widget. +It has the following general form:<br> + +<i>pathName</i> <i>option</i> ?<i>arg</i> <i>arg</i> <i>...</i>?<br> + +<i>Option</i> and the <i>arg</i>s determine the exact behavior of the command. + +<p><p> +The following commands are possible for <b>table</b> widgets: + +<p><p> +<i>pathName</i> <b>activate</b> <i>index</i><br> + +Sets the active cell to the one indicated by <i>index</i>. + +<p><p> +<i>pathName</i> <b>bbox</b> <i>first</i> ?<i>last</i>?<br> + +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. + +<p><p> +<i>pathName</i> <b>border</b> <i>option</i> <i>args</i><br> + +This command is a voodoo hack to implement border sizing for +tables. This is normally called through bindings, with the following +as valid options: + +<p><p> +<i>pathName</i> <b>border</b> <b>mark</b> <i>x</i> <i>y</i> ?<i>row|col</i>? +Records <i>x</i> and <i>y</i> and the row and/or column border under +that point in the table window, if any; used in conjunction +with later <b>border</b> <b>dragto</b> commands. Typically this +command is associated with a mouse button press in the +widget. If <i>row</i> or <i>col</i> is not specified, it returns a +tuple of both border indices (an empty item means no border). +Otherwise, just the specified item is returned. + +<p><p> +<i>pathName</i> <b>border</b> <b>dragto</b> <i>x</i> <i>y</i><br> + +This command computes the difference between its <i>x</i> and <i>y</i> +arguments and the <i>x</i> and <i>y</i> arguments to the last <b>border</b> +<b>mark</b> 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. + +<p><p> +<i>pathName</i> <b>cget</b> <i>option</i><br> + +Returns the current value of the configuration option given by +<i>option</i>. <i>Option</i> may have any of the values accepted by the <b>table</b> +command. + +<p><p> +<i>pathName</i> <b>clear</b> <i>option</i> ?<i>first</i>? ?<i>last</i>?<br> + +This command is a convenience routine to clear certain state +information managed by the table. <i>first</i> and <i>last</i> represent +valid table indices. If neither are specified, then the command +operates on the whole table. The following options are recognized: + +<p><p> +<i>pathName</i> <b>clear</b> <b>cache</b> ?<i>first</i>? ?<i>last</i>? +Clears the specified section of the cache, if the table +has been keeping one. + +<p><p> +<i>pathName</i> <b>clear</b> <b>sizes</b> ?<i>first</i>? ?<i>last</i>? +Clears the specified row and column areas of specific +height/width dimensions. When just one index is specified, +for example <b>2,0</b>, that is interpreted as row 2 <b>and</b> +column 0. + +<p><p> +<i>pathName</i> <b>clear</b> <b>tags</b> ?<i>first</i>? ?<i>last</i>? +Clears the specified area of tags (all row, column and +cell tags). + +<p><p> +<i>pathName</i> <b>clear</b> <b>all</b> ?<i>first</i>? ?<i>last</i>? +Performs all of the above clear functions on the specified +area. + +<p><p> +<i>pathName</i> <b>configure</b> ?<i>option</i>? ?<i>value</i> <i>option</i> <i>value</i> <i>...</i>? +Query or modify the configuration options of the widget. If no +<i>option</i> is specified, returns a list describing all of the available +options for <i>pathName</i> (see <b>Tk_ConfigureInfo</b> for information +on the format of this list). If <i>option</i> is specified with no +<i>value</i>, 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 <i>option</i> is specified). If one or +more <i>option-value</i> 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. <i>Option</i> may have any +of the values accepted by the <b>table</b> command. + +<p><p> +<i>pathName</i> <b>curselection</b> ?<i>value</i>?<br> + +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. + +<p><p> +<i>pathName</i> <b>curvalue</b> ?<i>value</i>?<br> + +If no value is given, the value of the cell being edited +(indexed by <b>active</b>) is returned, else it is set to the given +value. + +<p><p> +<i>pathName</i> <b>delete</b> <i>option</i> <i>arg</i> ?<i>arg</i>?<br> + +This command is used to delete various things in a table. It +has several forms, depending on the <i>option</i>: + +<p><p> +<i>pathName</i> <b>delete</b> <b>active</b> <i>index</i> ?<i>index</i>? +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. +<i>index</i> can be a number, <b>insert</b> or <b>end</b>. + +<p><p> +<i>pathName</i> <b>delete</b> <b>cols</b> ?<i>switches</i>? <i>index</i> ?<i>count</i>? +Deletes <i>count</i> cols starting at (and including) col <i>index</i>. +The <i>index</i> will be constrained to the limits of the +tables. If <i>count</i> is negative, it deletes cols to the +left. Otherwise it deletes cols to the right. <i>count</i> +defaults to 1 (meaning just the column specified). At +the moment, spans are not adjusted with this action. +Optional switches are: + +<p> +<dl> + +<dt><b>-holddimensions</b></dt></dt> +<dd> +Causes the table cols to be unaffected by the +deletion (empty cols may appear). By default the +dimensions are adjusted by <b>count</b>. + +<p></dd> + +<dt><b>-holdselection</b></dt></dt> +<dd> +Causes the selection to be maintained on the +absolute cells values. Otherwise, the selection +will be cleared.. + +<p></dd> + +<dt><b>-holdtags</b></dt></dt> +<dd> +Causes the tags specified by the <i>tag</i> method to +not move along with the data. Also prevents specific +widths set by the <i>width</i> method from being +adjusted. By default, these tags are properly +adjusted. + +<p></dd> + +<dt><b>-holdwindows</b></dt></dt> +<dd> +Causes the embedded windows created with the <i>win</i><b>_</b>d<i>ow</i> +method to not move along with the data. By +default, these windows are properly adjusted. + +<p></dd> + +<dt><b>-keeptitles</b></dt></dt> +<dd> +Prevents title area cells from being changed. +Otherwise they are treated just like regular +cells and will move as specified. + +<p></dd> + +<dt><b>--</b> </dt></dt> +<dd> Signifies the end of the switches. + +<p></dd> +</dl> +<p> +<i>pathName</i> <b>delete</b> <b>rows</b> ?<i>switches</i>? <i>index</i> ?<i>count</i>? +Deletes <b>count</b> rows starting at (and including) row <b>index</b>. +If <b>count</b> 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. + +<p><p> +<i>pathName</i> <b>get</b> <i>first</i> ?<i>last</i>?<br> + +Returns the value of the cells specified by the table indices +<i>first</i> and (optionally) <i>last</i> in a list. + +<p><p> +<i>pathName</i> <b>height</b> ?<i>row</i>? ?<i>value</i> <i>row</i> <i>value</i> <i>...</i>? +If no <i>row</i> is specified, returns a list describing all rows for +which a height has been set. If <b>row</b> 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 <i>row-value</i> +pairs are specified, then it sets each row to be that height in +lines (positive number) or pixels (negative number). If <i>value</i> +is <i>default</i>, then the row uses the default height, specified by +<b>-rowheight</b>. + +<p><p> +<i>pathName</i> <b>hidden</b> ?<i>index</i>? ?<i>index</i> <i>...</i>?<br> + +When called without args, it returns all the <i>hidden</i> 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. + +<p><p> +<i>pathName</i> <b>icursor</b> ?<i>arg</i>?<br> + +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 <b>insert</b> or <b>end</b> 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. + +<p><p> +<i>pathName</i> <b>index</b> <i>index</i> ?<i>row|col</i>?<br> + +Returns the integer cell coordinate that corresponds to <i>index</i> in +the form row,col. If <b>row</b> or <b>col</b> is specified, then only the row +or column index is returned. + +<p><p> +<i>pathName</i> <b>insert</b> <i>option</i> <i>arg</i> <i>arg</i><br> + +This command is used to into various things into a table. It +has several forms, depending on the <i>option</i>: + +<p><p> +<i>pathName</i> <b>insert</b> <b>active</b> <i>index</i> <i>value</i> +The <i>value</i> is a text string which is inserted at the <i>index</i> +position of the active cell. The cursor is then positioned +after the new text. <i>index</i> can be a number, <b>insert</b> +or <b>end</b>. + +<p><p> +<i>pathName</i> <b>insert</b> <b>cols</b> ?<i>switches</i>? <i>index</i> ?<i>count</i>? +Inserts <b>count</b> cols starting at col <b>index</b>. If <b>count</b> 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. + +<p><p> +<i>pathName</i> <b>insert</b> <b>rows</b> ?<i>switches</i>? <i>index</i> ?<i>count</i>? +Inserts <b>count</b> rows starting at row <b>index</b>. If <b>count</b> 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. + +<p><p> +<i>pathName</i> <b>reread</b><br> + +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). + +<p><p> +<i>pathName</i> <b>scan</b> <i>option</i> <i>args</i><br> + +This command is used to implement scanning on tables. It has +two forms, depending on <i>option</i>: + +<p><p> +<i>pathName</i> <b>scan</b> <b>mark</b> <i>x</i> <i>y</i><br> + +Records <i>x</i> and <i>y</i> and the current view in the table window; +used in conjunction with later <b>scan</b> <b>dragto</b> commands. +Typically this command is associated with a mouse button +press in the widget. It returns an empty string. + +<p><p> +<i>pathName</i> <b>scan</b> <b>dragto</b> <i>x</i> <i>y</i>.<br> + +This command computes the difference between its <i>x</i> and <i>y</i> +arguments and the <i>x</i> and <i>y</i> arguments to the last <b>scan</b> <b>mark</b> +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. + +<p><p> +<i>pathName</i> <b>see</b> <i>index</i><br> + +Adjust the view in the table so that the cell given by <i>index</i> 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. + +<p><p> +<i>pathName</i> <b>selection</b> <i>option</i> <i>arg</i><br> + +This command is used to adjust the selection within a table. It +has several forms, depending on <i>option</i>: + +<p><p> +<i>pathName</i> <b>selection</b> <b>anchor</b> <i>index</i><br> + +Sets the selection anchor to the cell given by <i>index</i>. +The selection anchor is the end of the selection that is +fixed while dragging out a selection with the mouse. The +index <b>anchor</b> may be used to refer to the anchor cell. + +<p><p> +<i>pathName</i> <b>selection</b> <b>clear</b> <i>first</i> ?<i>last</i>? +If any of the cells between <i>first</i> and <i>last</i> (inclusive) +are selected, they are deselected. The selection state +is not changed for cells outside this range. <i>first</i> may +be specified as <b>all</b> to remove the selection from all +cells. + +<p><p> +<i>pathName</i> <b>selection</b> <b>includes</b> <i>index</i> +Returns 1 if the cell indicated by <i>index</i> is currently +selected, 0 if it isn't. + +<p><p> +<i>pathName</i> <b>selection</b> <b>set</b> <i>first</i> ?<i>last</i>? +Selects all of the cells in the range between <i>first</i> and +<i>last</i>, inclusive, without affecting the selection state of +cells outside that range. + +<p><p> +<i>pathName</i> <b>set</b> ?<i>row|col</i>? <i>index</i> ?<i>value</i>? ?<i>index</i> <i>value</i> <i>...</i>? +Sets the specified index to the associated value. Table validation +will not be triggered via this method. If <b>row</b> or <b>col</b> 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 <b>row</b> is specified) or rows (for <b>col</b>). For +example, <b>set</b> <b>row</b> <b>2,3</b> <b>{2,3</b> <b>2,4</b> <b>2,5}</b> will set 3 cells, from 2,3 to +2,5. The setting of cells is silently bounded by the known table +dimensions. + +<p><p> +<i>pathName</i> <b>spans</b> ?<i>index</i>? ?<i>rows,cols</i> <i>index</i> <i>rows,cols</i> <i>...</i>? +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 +<i>index</i>, the span for that <i>index</i> only is returned, if any. Otherwise +an even number of <i>index</i> <i>rows,cols</i> pairs are used to set +spans. A span starts at the <i>index</i> 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. + +<p><p> +<i>pathName</i> <b>tag</b> option ?<i>arg</i> <i>arg</i> <i>...</i>?<br> + +This command is used to manipulate tags. The exact behavior of +the command depends on the <i>option</i> argument that follows the <b>tag</b> +argument. <i>cget</i>, <i>cell</i>, and <i>row|col</i> complain about unknown tag +names. The following forms of the command are currently supported: + +<p><p> +<i>pathName</i> <b>tag</b> <b>cell</b> <i>tagName</i> <i>?index</i> <i>...?</i> +With no arguments, prints out the list of cells that use +the <i>tag</i>. Otherwise it sets the specified cells to use +the named tag, replacing any tag that may have been set +using this method before. If <i>tagName</i> is {}, the cells +are reset to the default <i>tag</i>. Tags added during -*tagcommand +evaluation do not register here. If <i>tagName</i> does +not exist, it will be created with the default options. + +<p><p> +<i>pathName</i> <b>tag</b> <b>cget</b> <i>tagName</i> <i>option</i> +This command returns the current value of the option +named <i>option</i> associated with the tag given by <i>tagName</i>. +<i>Option</i> may have any of the values accepted by the <b>tag</b> +<b>configure</b> widget command. + +<p><p> +<i>pathName</i> <b>tag</b> <b>col</b> <i>tagName</i> <i>?col</i> <i>...?</i> +With no arguments, prints out the list of cols that use +the <i>tag</i>. Otherwise it sets the specified columns to use +the named tag, replacing any tag that may have been set +using this method before. If <i>tagName</i> is {}, the cols are +reset to the default <i>tag</i>. Tags added during -coltagcommand +evaluation do not register here. If <i>tagName</i> does +not exist, it will be created with the default options. + +<p><p> +<i>pathName</i> <b>tag</b> <b>configure</b> <i>tagName</i> ?<i>option</i>? ?<i>value</i>? ?<i>option</i> <i>value</i> +<i>...</i>?<br> + +This command is similar to the <b>configure</b> widget command +except that it modifies options associated with the tag +given by <i>tagName</i> instead of modifying options for the +overall table widget. If no <i>option</i> is specified, the +command returns a list describing all of the available +options for <i>tagName</i> (see <b>Tk_ConfigureInfo</b> for information +on the format of this list). If <i>option</i> is specified with +no <i>value</i>, 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 <i>option</i> is +specified). If one or more <i>option-value</i> pairs are specified, +then the command modifies the given option(s) to +have the given value(s) in <i>tagName</i>; in this case the command +returns an empty string. See TAGS above for details +on the options available for tags. + +<p><p> +<i>pathName</i> <b>tag</b> <b>delete</b> <i>tagName</i><br> + +Deletes a tag. No error if the tag does not exist. + +<p><p> +<i>pathName</i> <b>tag</b> <b>exists</b> <i>tagName</i><br> + +Returns 1 if the named tag exists, 0 otherwise. + +<p><p> +<i>pathName</i> <b>tag</b> <b>includes</b> <i>tagName</i> <i>index</i> +Returns 1 if the specified index has the named tag, 0 +otherwise. + +<p><p> +<i>pathName</i> <b>tag</b> <b>lower</b> <i>tagName</i> ?<i>belowThis</i>? +Lower the priority of the named tag. If <i>belowThis</i> is not +specified, then the tag's priority is lowered to the bottom, +otherwise it is lowered to one below <i>belowThis</i>. + +<p><p> +<i>pathName</i> <b>tag</b> <b>names</b> ?<i>pattern</i>?<br> + +If no pattern is specified, shows the names of all +defined tags. Otherwise the <i>pattern</i> is used as a glob +pattern to show only tags matching that pattern. Tag +names are returned in priority order (highest priority +tag first). + +<p><p> +<i>pathName</i> <b>tag</b> <b>raise</b> <i>tagName</i> ?<i>aboveThis</i>? +Raise the priority of the named tag. If <i>aboveThis</i> is not +specified, then the tag's priority is raised to the top, +otherwise it is raised to one above <i>aboveThis</i>. + +<p><p> +<i>pathName</i> <b>tag</b> <b>row</b> <i>tagName</i> ?<i>row</i> <i>...</i>? +With no arguments, prints out the list of rows that use +the <i>tag</i>. Otherwise it sets the specified rows to use the +named tag, replacing any tag that may have been set using +this method before. If <i>tagName</i> is {}, the rows are reset +to use the default tag. Tags added during -rowtagcommand +evaluation do not register here. If <i>tagName</i> does not +exist, it will be created with the default options. + +<p><p> +<i>pathName</i> <b>validate</b> <i>index</i><br> + +Explicitly validates the specified index based on the current +<b>-validatecommand</b> and returns 0 or 1 based on whether the cell +was validated. + +<p><p> +<i>pathName</i> <b>width</b> ?<i>col</i>? ?<i>value</i> <i>col</i> <i>value</i> <i>...</i>? +If no <i>col</i> is specified, returns a list describing all cols for +which a width has been set. If <b>col</b> 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 <i>col-value</i> +pairs are specified, then it sets each col to be that width in +characters (positive number) or pixels (negative number). If +<i>value</i> is <i>default</i>, then the col uses the default width, specified +by <b>-colwidth</b>. + +<p><p> +<i>pathName</i> <b>window</b> option ?<i>arg</i> <i>arg</i> <i>...</i>?<br> + +This command is used to manipulate embedded windows. The exact +behavior of the command depends on the <i>option</i> argument that follows +the <b>window</b> argument. The following forms of the command +are currently supported: + +<p><p> +<i>pathName</i> <b>window</b> <b>cget</b> <i>index</i> <i>option</i> +This command returns the current value of the option +named <i>option</i> associated with the window given by <i>index</i>. +<i>Option</i> may have any of the values accepted by the <b>window</b> +<b>configure</b> widget command. + +<p><p> +<i>pathName</i> <b>window</b> <b>configure</b> <i>index</i> ?<i>option</i>? ?<i>value</i>? ?<i>option</i> <i>value</i> +<i>...</i>?<br> + +This command is similar to the <b>configure</b> widget command +except that it modifies options associated with the +embedded window given by <i>index</i> instead of modifying +options for the overall table widget. If no <i>option</i> is +specified, the command returns a list describing all of +the available options for <i>index</i> (see <b>Tk_ConfigureInfo</b> for +information on the format of this list). If <i>option</i> is +specified with no <i>value</i>, 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 <i>option</i> is specified). If one or more <i>option-value</i> +pairs are specified, then the command modifies the given +option(s) to have the given value(s) in <i>index</i>; in this +case the command returns an empty string. See EMBEDDED +WINDOWS above for details on the options available for +windows. + +<p><p> +<i>pathName</i> <b>window</b> <b>delete</b> <i>index</i> ?<i>index</i> <i>...</i>? +Deletes an embedded window from the table. The associated +window will also be deleted. + +<p><p> +<i>pathName</i> <b>window</b> <b>move</b> <i>indexFrom</i> <i>indexTo</i> +Moves an embedded window from one cell to another. If a +window already exists in the target cell, it will be +deleted. + +<p><p> +<i>pathName</i> <b>window</b> <b>names</b> ?<i>pattern</i>?<br> + +If no pattern is specified, shows the cells of all embedded +windows. Otherwise the <i>pattern</i> is used as a glob +pattern to show only cells matching that pattern. + +<p><p> +<i>pathName</i> <b>xview</b> <i>args</i><br> + +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: + +<p><p> +<i>pathName</i> <b>xview</b><br> + +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 <b>-xscrollcommand</b> +option. + +<p><p> +<i>pathName</i> <b>xview</b> <i>index</i><br> + +Adjusts the view in the window so that the column given +by <i>index</i> is displayed at the left edge of the window. + +<p><p> +<i>pathName</i> <b>xview</b> <b>moveto</b> <i>fraction</i><br> + +Adjusts the view in the window so that <i>fraction</i> of the +total width of the table text is off-screen to the left. +<i>fraction</i> must be a fraction between 0 and 1. + +<p><p> +<i>pathName</i> <b>xview</b> <b>scroll</b> <i>number</i> <i>what</i> +This command shifts the view in the window left or right +according to <i>number</i> and <i>what</i>. <i>Number</i> must be an integer. +<i>What</i> must be either <b>units</b> or <b>pages</b> or an abbreviation of +one of these. If <i>what</i> is <b>units</b>, the view adjusts left or +right by <i>number</i> cells on the display; if it is <b>pages</b> then +the view adjusts by <i>number</i> screenfuls. If <i>number</i> is negative +then cells farther to the left become visible; if +it is positive then cells farther to the right become +visible. + +<p><p> +<i>pathName</i> <b>yview</b> <i>?args</i>?<br> + +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: + +<p><p> +<i>pathName</i> <b>yview</b><br> + +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 <b>-yscrollcommand</b> option. + +<p><p> +<i>pathName</i> <b>yview</b> <i>index</i><br> + +Adjusts the view in the window so that the row given by +<i>index</i> is displayed at the top of the window. + +<p><p> +<i>pathName</i> <b>yview</b> <b>moveto</b> <i>fraction</i><br> + +Adjusts the view in the window so that the element given +by <i>fraction</i> appears at the top of the window. <i>Fraction</i> +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. + +<p><p> +<i>pathName</i> <b>yview</b> <b>scroll</b> <i>number</i> <i>what</i> +This command adjusts the view in the window up or down +according to <i>number</i> and <i>what</i>. <i>Number</i> must be an integer. +<i>What</i> must be either <b>units</b> or <b>pages</b>. If <i>what</i> is <b>units</b>, +the view adjusts up or down by <i>number</i> cells; if it is +<b>pages</b> then the view adjusts by <i>number</i> screenfuls. If +<i>number</i> is negative then earlier elements become visible; +if it is positive then later elements become visible. + +<p> +<h2><a name='sect13' href='#toc13'><b>Default</b> <b>Bindings</b></a></h2> + +<p> +The initialization creates class bindings that give the following +default behaviour: + +<p> +<dl> + +<dt>[1] </dt></dt> +<dd> 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. + +<p></dd> + +<dt>[2] </dt></dt> +<dd> 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. + +<p></dd> + +<dt>[3] </dt></dt> +<dd> Moving the mouse while Button-2 is pressed causes scanning to +occur without any selection. + +<p></dd> + +<dt>[4] </dt></dt> +<dd> Home moves the table to have the origin in view. + +<p></dd> + +<dt>[5] </dt></dt> +<dd> End moves the table to have the <b>end</b> cell in view. + +<p></dd> + +<dt>[6] </dt></dt> +<dd> Control-Home moves the table to the origin and activates that +cell. + +<p></dd> + +<dt>[7] </dt></dt> +<dd> Control-End moves the table to the end and activates that cell. + +<p></dd> + +<dt>[8] </dt></dt> +<dd> Shift-Control-Home extends the selection to the origin. + +<p></dd> + +<dt>[9] </dt></dt> +<dd> Shift-Control-End extends the selection to the end. + +<p></dd> + +<dt>[10] </dt></dt> +<dd>The left, right, up and down arrows move the active cell. + +<p></dd> + +<dt>[11] </dt></dt> +<dd>Shift-<arrow> extends the selection in that direction. + +<p></dd> + +<dt>[12] </dt></dt> +<dd>Control-leftarrow and Control-rightarrow move the insertion cursor +within the cell. + +<p></dd> + +<dt>[13] </dt></dt> +<dd>Control-slash selects all the cells. + +<p></dd> + +<dt>[14] </dt></dt> +<dd>Control-backslash clears selection from all the cells. + +<p></dd> +</dl> +<p> +[15] Backspace deletes the character before the insertion cursor in +the active cell. + +<p><p> +[16] Delete deletes the character after the insertion cursor in the +active cell. + +<p><p> +[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. + +<p><p> +[18] Control-a moves the insertion cursor to the beginning of the +active cell. + +<p><p> +[19] Control-e moves the insertion cursor to the end of the active +cell. + +<p> +<dl> + +<dt>[20] </dt></dt> +<dd>Control-minus and Control-equals decrease and increase the width +of the column with the active cell in it. + +<p></dd> + +<dt>[21] </dt></dt> +<dd>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 <b>-resizeborders</b>. + +<p></dd> +</dl> +<p> +Some bindings may have slightly different behavior dependent on the +<b>-selectionmode</b> of the widget. + +<p><p> +If the widget is disabled using the <b>-state</b> 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. + +<p><p> +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<version>/tkTable.tcl". + +<p> +<h2><a name='sect14' href='#toc14'><b>Performance</b> <b>Issues</b></a></h2> + +<p> +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. + +<p><p> +The display cell with the insert cursor is redrawn each time the cursor +blinks, which causes a steady stream of graphics traffic. Set the +<b>-insertofftime</b> option to 0 avoid this. The use of a <b>-command</b> with the +table without a cache can cause significant slow-down, as the command +is called once for each request of a cell value. + +<p> +<h2><a name='sect15' href='#toc15'><b>Examples</b></a></h2> + +<p> +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.<br> + +$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] + +<p> +<h2><a name='sect16' href='#toc16'><b>Keywords</b></a></h2> + +<p> +table, widget, extension +<p> + +<hr><p> +<a name='toc'><b>Table of Contents</b></a><p> +<ul> +<li><a name='toc0' href='#sect0'>Name</a></li> +<li><a name='toc1' href='#sect1'>Synopsis</a></li> +<li><a name='toc2' href='#sect2'>Standard Options</a></li> +<li><a name='toc3' href='#sect3'>Widget-specific Options</a></li> +<li><a name='toc4' href='#sect4'>Description</a></li> +<li><a name='toc5' href='#sect5'>Initialization</a></li> +<li><a name='toc6' href='#sect6'>Indices</a></li> +<li><a name='toc7' href='#sect7'>Tags</a></li> +<li><a name='toc8' href='#sect8'>Embedded Windows</a></li> +<li><a name='toc9' href='#sect9'>the Selection</a></li> +<li><a name='toc10' href='#sect10'>Row/Col Spanning</a></li> +<li><a name='toc11' href='#sect11'>Command Substitution</a></li> +<li><a name='toc12' href='#sect12'>Widget Command</a></li> +<li><a name='toc13' href='#sect13'>Default Bindings</a></li> +<li><a name='toc14' href='#sect14'>Performance Issues</a></li> +<li><a name='toc15' href='#sect15'>Examples</a></li> +<li><a name='toc16' href='#sect16'>Keywords</a></li> +</ul> +</body> +</html> diff --git a/tktable/doc/tkTable.n b/tktable/doc/tkTable.n new file mode 100755 index 0000000..5be90f2 --- /dev/null +++ b/tktable/doc/tkTable.n @@ -0,0 +1,1432 @@ +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" RCS: @(#) $Id: tkTable.n,v 1.1.1.1 2011/03/01 20:00:38 joye Exp $ +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. If an argument is present, then a line break is +'\" forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !'\\$4'' .TP \\$4 +.el \{\ +. ie !'\\$2'' .TP \\n()Cu +. el .TP 15 +.\} +.ie !'\\$3'' \{\ +.ta \\n()Au \\n()Bu +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !'\\$2'' \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !'\\$1'' .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !'\\$2'' .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !'\\$1'' .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH table n 2.8 Tk "Tk Table Extension" +.HS table tk +.BS +.SH NAME +table \- Create and manipulate tables +.SH SYNOPSIS +\fBtable\fI \fIpathName \fR?\fIoptions\fR? +.SO +\-anchor \-background \-cursor +\-exportselection \-font \-foreground +\-highlightbackground \-highlightcolor \-highlightthickness +\-insertbackground \-insertborderwidth \-insertofftime +\-insertontime \-insertwidth \-invertselected +\-relief \-takefocus \-xscrollcommand +\-yscrollcommand +.SE + +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-autoclear autoClear AutoClear +A boolean value which specifies whether the first keypress in a cell will +delete whatever text was previously there. Defaults to 0. +.OP \-bordercursor borderCursor 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 \fIcrosshair\fR. +.OP "\-borderwidth or \-bd" borderWidth 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 \fBrelief\fR 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 +\fB\-drawmode\fR for the table. Each value in the list must have one of +the forms acceptable to \fBTk_GetPixels\fR. +.OP "\-browsecommand or \-browsecmd" browseCommand BrowseCommand +Specifies a command which will be evaluated anytime the active cell changes. +It uses the %\-substition model described in COMMAND SUBSTITUTION below. +Any changes to the active cell while the command is running are ignored to +prevent recursion. +.OP \-cache cache 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 \fB\-command\fR but uses extra memory. Can maintain state when both +\fB\-command\fR and \fB\-variable\fR are empty. The cache is automatically +flushed whenever the value of \fB\-cache\fR or \fB\-variable\fR changes, +otherwise you have to explicitly call \fBclear\fR on it. Defaults to off. +.OP \-colorigin colOrigin 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. +.OP \-cols cols Cols +Number of cols in the table. Defaults to 10. +.OP \-colseparator colSeparator 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. +.OP \-colstretchmode colStretchMode StretchMode +Specifies one of the following stretch modes for columns to fill extra +allocated window space: +.RS +.TP +\fBnone\fR +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. +.TP +\fBunset\fR +Only columns that do not have a specific width set will be stretched. +.TP +\fBall\fR +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. +.TP +\fBlast\fR +The last column will be stretched +to fill the window space allocated to the table. +.TP +\fBfill\fR (only valid for \fB\-rowstretch\fR 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. +.RE +.OP \-coltagcommand colTagCommand 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 +\fBtag col\fR 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 occurring during the evaluation of the procedure, or the return of an +invalid tag name are silently ignored. +.OP \-colwidth colWidth 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. +.OP \-command command Command +Specified a command to use as a procedural interface to cell values. +If \fB\-usecommand\fR is true, this command will be used instead of any +reference to the \fB\-variable\fR array. When retrieving cell values, +the return value of the command is used as the value for the cell. +It uses the %\-substition model described in COMMAND SUBSTITUTION below. +.OP \-drawmode drawMode DrawMode +Sets the table drawing mode to one of the following options: +.RS +.TP +\fBslow\fR +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. +.TP +\fBcompatible\fR +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. +.TP +\fBfast\fR +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 \fB\-borderwidth\fR 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. +.TP +\fBsingle\fR +The table is drawn to the screen as in fast mode, but only single pixel +lines are drawn (not square borders). +.RE +.OP \-ellipsis ellipsis Ellipsis +This specifies a string to display at the end of a line that would be +clipped by its cell, like ``...''. An ellipsis will be displayed only +on non-wrapping, non-multiline cells that would be clipped. The ellipsis +will display on the left for east anchored cells, otherwise it displays +on the right. +Defaults to "" (no ellipsis). +.OP \-flashmode flashMode FlashMode +A boolean value which specifies whether cells should flash when their value +changes. The table tag \fBflash\fR will be applied to these cells for the +duration specified by \fB\-flashtime\fR. Defaults to 0. +.OP \-flashtime flashTime FlashTime +The amount of time, in 1/4 second increments, for which a cell should flash +when its value has changed. \fB\-flashmode\fR must be on. Defaults to 2. +.OP \-height height 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 \fB\-maxheight\fR. +.OP \-invertselected invertSelected InvertSelected +Specifies whether the foreground and background of an item should simply +have their values swapped instead of merging the \fIsel\fR tag options +when the cell is selected. Defaults to 0 (merge \fIsel\fR tag). +.OP \-ipadx ipadX 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 \fB\-padx\fR for an alternate padding +style. +.OP \-ipady ipadY 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 \fB\-pady\fR for an alternate padding +style. +.OP \-justify justify Justify +How to justify multi\-line text in a cell. +It must be one of \fBleft\fR, \fBright\fR, or \fBcenter\fR. +Defaults to left. +.OP \-maxheight maxHeight MaxHeight +The max height in pixels that the window will request. Defaults to 600. +.OP \-maxwidth maxWidth MaxWidth +The max width in pixels that the window will request. Defaults to 800. +.OP \-multiline multiline Multiline +Specifies the default setting for the multiline tag option. Defaults to 1. +.OP \-padx padX 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 \fBwidth\fR 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 \fB\-ipadx\fR for an alternate padding style. +.OP \-pady padY 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 \fBheight\fR 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 \fB\-ipadx\fR for an alternate padding style. +.OP \-resizeborders resizeBorders ResizeBorders +Specifies what kind of interactive border resizing to allow, must be one of +row, col, both (default) or none. +.OP \-rowheight rowHeight 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. +.OP \-roworigin rowOrigin 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. +.OP \-rows rows Rows +Number of rows in the table. Defaults to 10. +.OP \-rowseparator rowSeparator 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. +.OP \-rowstretchmode rowStretchMode StretchMode +Specifies the stretch modes for rows to fill extra +allocated window space. See \fB\-colstretchmode\fR for valid options. +.OP \-rowtagcommand rowTagCommand 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 +\fB\-coltagcommand\fR, except that it applies to row tags. +.OP "\-selectioncommand or \-selcmd" selectionCommand SelectionCommand +Specifies a command to evaluate when the selection is retrieved from a +table via the selection mechanism (ie: evaluating ``\fBselection get\fR''). +The return value from this command will become the string passed on by the +selection mechanism. It uses the %\-substition model described in COMMAND +SUBSTITUTION below. If an error occurs, a Tcl background error is +generated and nothing is returned. +.OP \-selectmode selectMode 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 \fBsingle\fR, \fBbrowse\fR, \fBmultiple\fR, or \fBextended\fR; the +default value is \fBbrowse\fR. These styles are like those for the Tk +listbox, except expanded for 2 dimensions. +.OP \-selecttitle selectTitles SelectTitles +Specifies whether title cells should be allowed in the selection. +Defaults to 0 (disallowed). +.OP \-selecttype selectType SelectType +Specifies one of several types of selection for the table. The value of the +option may be one of \fBrow\fR, \fBcol\fR, \fBcell\fR, or \fBboth\fR +(meaning \fBrow && col\fR); the default value is \fBcell\fR. These types +define whether an entire row/col is affected when a cell's selection is +changed (set or clear). +.OP \-sparsearray sparseArray 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. +.OP \-state state State +Specifies one of two states for the entry: \fBnormal\fR or \fBdisabled\fR. +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 \fBnormal\fR. +.OP \-titlecols titleCols TitleCols +Number of columns to use as a title area. Defaults to 0. +.OP \-titlerows titleRows TitleRows +Number of rows to use as a title area. Defaults to 0. +.OP \-usecommand useCommand UseCommand +A boolean value which specifies whether to use the \fBcommand\fR option. +This value sets itself to zero if \fBcommand\fR is used and returns an error. +Defaults to 1 (will use \fBcommand\fR if specified). +.OP \-validate validate Validate +A boolean specifying whether validation should occur for the active buffer. +Defaults to 0. +.OP "\-validatecommand or \-vcmd" validateCommand ValidateCommand +Specifies a command to execute when the active cell is edited. This command +is expected to return a Tcl boolean. If it returns true, 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. It +uses the %\-substition model described in COMMAND SUBSTITUTION below. +.OP \-variable variable 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 \fIrow\fR,\fIcol\fR for cells and +the special key \fIactive\fR which contains the value of the active cell +buffer. The Tcl array is managed as a sparse array (the table does not +require that 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 \fB\-sparsearray\fR options is set to 0. +.OP \-width width 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 \fB\-maxwidth\fR. +.OP \-wrap wrap Wrap +Specifies the default wrap value for tags. Defaults to 0. +.BE + +.SH DESCRIPTION +.PP +The \fBtable\fR command creates a 2\-dimensional grid of cells. The table +can use a Tcl array variable or Tcl command for data storage and retrieval, +as well as optionally cache data in memory for speed. One of these data +sources \fImust\fR be configured before any data is retained by the table. +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 \fItags\fR, which can be used to change the style of a +row, column or cell (see TAGS for details). A cell \fIflash\fR 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. +.PP +One or more cells may be selected as described below. If a table is +exporting its selection (see \fB\-exportselection\fR option), then it will +observe the standard X11 protocols for handling the selection. See THE +SELECTION for details. +.PP +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 +\fB\-xscrollcommand\fR and \fB\-yscrollcommand\fR options. They also support +scanning, as described below. +.PP +In order to obtain good performance, the table widget supports multiple +drawing modes, two of which are fully Tk compatible. + +.SH "INITIALIZATION" +.PP +When the \fBtable\fR command is loaded into an interpreter, a built-in +Tcl command, \fBtkTableInit\fR, is evaluated. This will search for the +appropriate table binding init file to load. The directories searched +are those in \fI$tcl_pkgPath\fR, both with Tktable(version) appended and +without, \fI$tk_library\fR and \fI[pwd]\fR (the current directory). You +can also define an \fI$env(TK_TABLE_LIBRARY)\fR to head this search list. +By default, the file searched for is called \fBtkTable.tcl\fR, but this +can be overridden by setting \fI$env(TK_TABLE_LIBRARY_FILE)\fR. +.PP +This entire init script can be overridden by providing your own +\fBtkTableInit\fR procedure before the library is loaded. Otherwise, the +aforementioned \fIenv(TK_TABLE_LIBRARY)\fR variable will be set with the +directory in which \fI$env(TK_TABLE_LIBRARY_FILE)\fR was found. + +.SH "INDICES" +.PP +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: +.TP 12 +\fInumber,number\fR +Specifies the cell as a numerical index of row,col which corresponds to the +index of the associated Tcl array, where \fB\-roworigin,\-colorigin\fR +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. +.TP 12 +\fBactive\fR +Indicates the cell that has the location cursor. +It is specified with the \fBactivate\fR widget command. +.TP 12 +\fBanchor\fR +Indicates the anchor point for the selection, which is set with the +\fBselection anchor\fR widget command. +.TP 12 +\fBbottomright\fR +Indicates the bottom\-rightmost cell visible in the table. +.TP 12 +\fBend\fR +Indicates the bottom right cell of the table. +.TP 12 +\fBorigin\fR +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. +.TP 12 +\fBtopleft\fR +Indicates the top\-leftmost editable cell visible in the table (this +excludes title cells). +.TP 12 +\fB@\fIx\fB,\fIy\fR +Indicates the cell that covers the point in the table window +specified by \fIx\fR and \fIy\fR (in pixel coordinates). If no +cell covers that point, then the closest cell to that +point is used. +.LP +In the widget command descriptions below, arguments named \fIindex\fR, +\fIfirst\fR, and \fIlast\fR always contain text indices in one of +the above forms. + +.SH TAGS +.PP +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. A tag can apply to an entire row or column, or just a +single cell. There are several permanent tags in each table that can be +configured by the user and will determine the attributes for special cells: +.RS +.TP 10 +\fBactive\fR +This tag is given to the \fIactive\fR cell +.TP 10 +\fBflash\fR +If flash mode is on, this tag is given to any recently +edited cells. +.TP 10 +\fBsel\fR +This tag is given to any selected cells. +.TP 10 +\fBtitle\fR +This tag is given to any cells in the title rows and columns. This +tag has \fB\-state\fR \fIdisabled\fR by default. +.RE +.PP +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 ``\fIpathName \fBtag configure\fR'' widget command. 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: +.RS +.TP +\fB\-anchor\fR \fIanchor\fR +Anchor for item in the cell space. +.TP +\fB\-background\fR or \fB\-bg\fR \fIcolor\fR +Background color of the cell. +.TP +\fB\-borderwidth\fR or \fB\-bd\fR \fIpixelList\fR +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). +.TP +\fB\-ellipsis\fR \fIstring\fR +String to display at the end of a line that would be clipped by its cell, +like ``...''. An ellipsis will be displayed only +on non-wrapping, non-multiline cells that would be clipped. The ellipsis +will display on the left for east anchored cells, otherwise it displays +on the right. +.TP +\fB\-font\fR \fIfontName\fR +Font for text in the cell. +.TP +\fB\-foreground\fR or \fB\-fg\fR \fIcolor\fR +Foreground color of the cell. +.TP +\fB\-justify\fR \fIjustify\fR +How to justify multi\-line text in a cell. +It must be one of \fBleft\fR, \fBright\fR, or \fBcenter\fR. +.TP +\fB\-image\fR \fIimageName\fR +An image to display in the cell instead of text. +.TP +\fB\-multiline\fR \fIboolean\fR +Whether to display text with newlines on multiple lines. +.TP +\fB\-relief\fR \fIrelief\fR +The relief for the cell. May be the empty string to cause this tag to +not disturb the value. +.TP +\fB\-showtext\fR \fIboolean\fR +Whether to show the text over an image. +.TP +\fB\-state\fR \fIstate\fR +The state of the cell, to allow for certain cells to be disabled. +This prevents the cell from being edited by the \fIinsert\fR or \fIdelete\fR +methods, but a direct \fIset\fR will not be prevented. +.TP +\fB\-wrap\fR \fIboolean\fR +Whether characters should wrap in a cell that is not wide enough. +.RE +.PP +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 ``\fIpathName \fBtag +lower\fR'' and ``\fIpathName \fBtag raise\fR'' widget commands. +.PP +If a cell has several tags associated with it that define the same display +options (eg - a \fBtitle\fR cell with specific \fBrow\fR and \fBcell\fR +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. +.PP +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 \fB\-showtext\fR. + +.SH "EMBEDDED WINDOWS" +.PP +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. +.PP +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 \fBwindow names\fR). +.PP +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: +.RS +.TP +\fB\-create \fIscript\fR +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. +.TP +\fB\-background\fR or \fB\-bg\fR \fIcolor\fR +Background color of the cell. If not +specified, it uses the table's default background. +.TP +\fB\-borderwidth\fR or \fB\-bd\fR \fIpixelList\fR +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). +.TP +\fB\-padx \fIpixels\fR +As defined in the Tk options man page. +.TP +\fB\-pady \fIpixels\fR +As defined in the Tk options man page. +.TP +\fB\-relief \fIrelief\fR +The relief to use for the cell in which the window lies. If not +specified, it uses the table's default relief. +.TP +\fB\-sticky \fIsticky\fR +Stickiness of the window inside the cell, as defined by the \fBgrid\fR command. +.TP +\fB\-window \fIpathName\fR +Specifies the name of a window (widget) to display in the annotation. It +must exist before being specified here. When an empty string is specified, +if a window was displayed it will cease to be managed by the table widget. +.RE + +.SH "THE SELECTION" +.PP +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 +\fB\-rowseparator\fR and \fB\-colseparator\fR options. For example, +default Excel format would be to set \fB\-rowseparator\fR to '\\n' and +\fB\-colseparator\fR 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 +\fBtk_tablePasteHandler\fR. This might be necessary if +\fB\-selectioncommand\fR is set. + +.SH "ROW/COL SPANNING" +.PP +Individual cells can span multiple rows and/or columns. This is done +via the \fBspans\fR 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. +.PP +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. +.PP +Cells \fIhidden\fR 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 \fBget\fR or \fBset\fR. +.PP +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. + +.SH "COMMAND SUBSTITUTION" +.PP + +The various option based commands that the table supports all support the +familiar Tk %\-substitution model (see \fBbind\fR for more details). The +following %\-sequences are recognized and substituted by the table widget: +.TP 5 +\fB%c\fR +For \fBSelectionCommand\fR, it is the maximum number of columns in any +row in the selection. Otherwise it is the column of the triggered cell. +.TP 5 +\fB%C\fR +A convenience substitution for \fI%r\fR,\fI%c\fR. +.TP 5 +\fB%i\fR +For \fBSelectionCommand\fR, it is the total number of cells in the selection. +For \fBCommand\fR, it is 0 for a read (get) and 1 for a write (set). +Otherwise it is the current cursor position in the cell. +.TP 5 +\fB%r\fR +For \fBSelectionCommand\fR, it is the number of rows in the selection. +Otherwise it is the row of the triggered cell. +.TP 5 +\fB%s\fR +For \fBValidateCommand\fR, it is the current value of the cell being validated. +For \fBSelectionCommand\fR, it is the default value of the selection. +For \fBBrowseCommand\fR, it is the index of the last active cell. +For \fBCommand\fR, it is empty for reads (get) and the current value of the +cell for writes (set). +.TP 5 +\fB%S\fR +For \fBValidateCommand\fR, it is the potential new value of the cell +being validated. +For \fBBrowseCommand\fR, it is the index of the new active cell. +.TP 5 +\fB%W\fR +The pathname to the window for which the command was generated. +.LP + +.SH "WIDGET COMMAND" +.PP +The \fBtable\fR command creates a new Tcl command whose +name is \fIpathName\fR. This command may be used to invoke various +operations on the widget. It has the following general form: +.CS +\fIpathName option \fR?\fIarg arg ...\fR? +.CE +\fIOption\fR and the \fIarg\fRs +determine the exact behavior of the command. +.PP +The following commands are possible for \fBtable\fR widgets: +.TP +\fIpathName \fBactivate\fR \fIindex\fR +Sets the active cell to the one indicated by \fIindex\fR. +.TP +\fIpathName \fBbbox\fR \fIfirst\fR ?\fIlast\fR? +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. +.TP +\fIpathName \fBborder\fR \fIoption args\fR +This command is a voodoo hack to implement border sizing for tables. +This is normally called through bindings, with the following as valid +options: +.RS +.TP +\fIpathName \fBborder mark\fR \fIx y\fR ?\fIrow|col\fR? +Records \fIx\fR and \fIy\fR and the row and/or column border under that +point in the table window, if any; used in conjunction with later \fBborder +dragto\fR commands. Typically this command is associated with a mouse +button press in the widget. If \fIrow\fR or \fIcol\fR is not specified, it +returns a tuple of both border indices (an empty item means no border). +Otherwise, just the specified item is returned. +.TP +\fIpathName \fBborder dragto\fR \fIx y\fR +This command computes the difference between its \fIx\fR and \fIy\fR +arguments and the \fIx\fR and \fIy\fR arguments to the last \fBborder +mark\fR 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. +.RE +.TP +\fIpathName \fBcget\fR \fIoption\fR +Returns the current value of the configuration option given +by \fIoption\fR. \fIOption\fR may have any of the values accepted +by the \fBtable\fR command. +.TP +\fIpathName \fBclear\fR \fIoption\fR ?\fIfirst\fR? ?\fIlast\fR? +This command is a convenience routine to clear certain state information +managed by the table. \fIfirst\fR and \fIlast\fR represent valid table +indices. If neither are specified, then the command operates on the +whole table. The following options are recognized: +.RS +.TP +\fIpathName \fBclear cache\fR ?\fIfirst\fR? ?\fIlast\fR? +Clears the specified section of the cache, if the table has been +keeping one. +.TP +\fIpathName \fBclear sizes\fR ?\fIfirst\fR? ?\fIlast\fR? +Clears the specified row and column areas of specific height/width +dimensions. When just one index is specified, for example \fB2,0\fR, +that is interpreted as row 2 \fBand\fR column 0. +.TP +\fIpathName \fBclear tags\fR ?\fIfirst\fR? ?\fIlast\fR? +Clears the specified area of tags (all row, column and cell tags). +.TP +\fIpathName \fBclear all\fR ?\fIfirst\fR? ?\fIlast\fR? +Performs all of the above clear functions on the specified area. +.RE +.TP +\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +Query or modify the configuration options of the widget. +If no \fIoption\fR is specified, returns a list describing all of +the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified +with no \fIvalue\fR, 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 \fIoption\fR is specified). If +one or more \fIoption\-value\fR 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. +\fIOption\fR may have any of the values accepted by the \fBtable\fR +command. +.TP +\fIpathName \fBcurselection\fR ?\fIvalue\fR? +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. +.TP +\fIpathName \fBcurvalue\fR ?\fIvalue\fR? +If no value is given, the value of the cell being edited (indexed by +\fBactive\fR) is returned, else it is set to the given value. +.TP +\fIpathName \fBdelete\fR \fIoption arg\fR ?\fIarg\fR? +This command is used to delete various things in a table. It has several +forms, depending on the \fIoption\fR: +.RS +.TP +\fIpathName \fBdelete active\fR \fIindex\fR ?\fIindex\fR? +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. \fIindex\fR can be a number, \fBinsert\fR or \fBend\fR. +.TP +\fIpathName \fBdelete cols\fR ?\fIswitches\fR? \fIindex\fR ?\fIcount\fR? +Deletes \fIcount\fR cols starting at (and including) col \fIindex\fR. The +\fIindex\fR will be constrained to the limits of the tables. If +\fIcount\fR is negative, it deletes cols to the left. Otherwise it deletes +cols to the right. \fIcount\fR defaults to 1 (meaning just the column +specified). At the moment, spans are +not adjusted with this action. Optional switches are: +.RS +.TP +\fB\-holddimensions\fR +Causes the table cols to be unaffected by the deletion (empty cols may +appear). By default the dimensions are adjusted by \fBcount\fR. +.TP +\fB\-holdselection\fR +Causes the selection to be maintained on the absolute cells values. +Otherwise, the selection will be cleared.. +.TP +\fB\-holdtags\fR +Causes the tags specified by the \fItag\fR method to not move along +with the data. Also prevents specific widths set by the \fIwidth\fR method +from being adjusted. By default, these tags are properly adjusted. +.TP +\fB\-holdwindows\fR +Causes the embedded windows created with the \fIwindow\fR method to not +move along with the data. By default, these windows are properly adjusted. +.TP +\fB\-keeptitles\fR +Prevents title area cells from being changed. Otherwise they are +treated just like regular cells and will move as specified. +.TP +\fB\-\-\fR +Signifies the end of the switches. +.RE +.TP +\fIpathName \fBdelete rows\fR ?\fIswitches\fR? \fIindex\fR ?\fIcount\fR? +Deletes \fBcount\fR rows starting at (and including) row \fBindex\fR. If +\fBcount\fR 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. +.RE +.TP +\fIpathName \fBget\fR \fIfirst\fR ?\fIlast\fR? +Returns the value of the cells specified by the table indices \fIfirst\fR +and (optionally) \fIlast\fR in a list. +.TP +\fIpathName \fBheight\fR ?\fIrow\fR? ?\fIvalue row value ...\fR? +If no \fIrow\fR is specified, returns a list describing all rows for which +a height has been set. If \fBrow\fR 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 \fIrow\-value\fR pairs are specified, +then it sets each row to be that height in lines (positive number) or +pixels (negative number). If \fIvalue\fR is \fIdefault\fR, then the row +uses the default height, specified by \fB\-rowheight\fR. +.TP +\fIpathName \fBhidden\fR ?\fIindex\fR? ?\fIindex ...\fR? +When called without args, it returns all the \fIhidden\fR 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. +.TP +\fIpathName \fBicursor\fR ?\fIarg\fR? +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 \fBinsert\fR or +\fBend\fR 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. +.TP +\fIpathName \fBindex\fR \fIindex\fR ?\fIrow|col\fR? +Returns the integer cell coordinate that corresponds to \fIindex\fR in the +form row,col. If \fBrow\fR or \fBcol\fR is specified, then only the row or +column index is returned. +.TP +\fIpathName \fBinsert\fR \fIoption arg arg\fR +This command is used to into various things into a table. It has several +forms, depending on the \fIoption\fR: +.RS +.TP +\fIpathName \fBinsert active\fR \fIindex value\fR +The \fIvalue\fR is a text string which is inserted at the \fIindex\fR +position of the active cell. The cursor is then positioned after the +new text. \fIindex\fR can be a number, \fBinsert\fR or \fBend\fR. +.TP +\fIpathName \fBinsert cols\fR ?\fIswitches\fR? \fIindex\fR ?\fIcount\fR? +Inserts \fBcount\fR cols starting at col \fBindex\fR. If \fBcount\fR 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. +.TP +\fIpathName \fBinsert rows\fR ?\fIswitches\fR? \fIindex\fR ?\fIcount\fR? +Inserts \fBcount\fR rows starting at row \fBindex\fR. If \fBcount\fR 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. +.RE +.TP +\fIpathName \fBreread\fR +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). +.TP +\fIpathName \fBscan\fR \fIoption args\fR +This command is used to implement scanning on tables. It has +two forms, depending on \fIoption\fR: +.RS +.TP +\fIpathName \fBscan mark\fR \fIx y\fR +Records \fIx\fR and \fIy\fR and the current view in the table +window; used in conjunction with later \fBscan dragto\fR commands. +Typically this command is associated with a mouse button press in +the widget. It returns an empty string. +.TP +\fIpathName \fBscan dragto\fR \fIx y\fR. +This command computes the difference between its \fIx\fR and \fIy\fR +arguments and the \fIx\fR and \fIy\fR arguments to the last \fBscan mark\fR +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. +.RE +.TP +\fIpathName \fBsee\fR \fIindex\fR +Adjust the view in the table so that the cell given by \fIindex\fR 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. +.TP +\fIpathName \fBselection\fR \fIoption arg\fR +This command is used to adjust the selection within a table. It +has several forms, depending on \fIoption\fR: +.RS +.TP +\fIpathName \fBselection anchor\fR \fIindex\fR +Sets the selection anchor to the cell given by \fIindex\fR. The selection +anchor is the end of the selection that is fixed while dragging out a +selection with the mouse. The index \fBanchor\fR may be used to refer to +the anchor cell. +.TP +\fIpathName \fBselection clear\fR \fIfirst \fR?\fIlast\fR? +If any of the cells between \fIfirst\fR and \fIlast\fR (inclusive) are +selected, they are deselected. The selection state is not changed for cells +outside this range. \fIfirst\fR may be specified as \fBall\fR to remove +the selection from all cells. +.TP +\fIpathName \fBselection includes\fR \fIindex\fR +Returns 1 if the cell indicated by \fIindex\fR is currently +selected, 0 if it isn't. +.TP +\fIpathName \fBselection set\fR \fIfirst\fR ?\fIlast\fR? +Selects all of the cells in the range between \fIfirst\fR and \fIlast\fR, +inclusive, without affecting the selection state of cells outside that +range. +.RE +.TP +\fIpathName \fBset\fR ?\fIrow|col\fR? \fIindex\fR ?\fIvalue\fR? ?\fIindex value ...\fR? +Sets the specified index to the associated value. Table validation will +not be triggered via this method. If \fBrow\fR or \fBcol\fR 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 \fBrow\fR is +specified) or rows (for \fBcol\fR). For example, \fBset row 2,3 +{2,3 2,4 2,5}\fR will set 3 cells, from 2,3 to 2,5. The setting of cells +is silently bounded by the known table dimensions. +.TP +\fIpathName \fBspans\fR ?\fIindex\fR? ?\fIrows,cols index rows,cols ...\fR? +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 \fIindex\fR, the span for that +\fIindex\fR only is returned, if any. Otherwise an even number of +\fIindex rows,cols\fR pairs are used to set spans. A span starts at the +\fIindex\fR 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. +.TP +\fIpathName \fBtag\fR option ?\fIarg arg ...\fR? +This command is used to manipulate tags. The exact behavior of the command +depends on the \fIoption\fR argument that follows the \fBtag\fR argument. +\fIcget\fR, \fIcell\fR, and \fIrow|col\fR complain about unknown tag names. +The following forms of the command are currently supported: +.RS +.TP +\fIpathName \fBtag cell\fR \fItagName ?index ...?\fR +With no arguments, prints out the list of cells that use the \fItag\fR. +Otherwise it sets the specified cells to use the named tag, replacing any +tag that may have been set using this method before. If \fItagName\fR is +{}, the cells are reset to the default \fItag\fR. Tags added during +\-*tagcommand evaluation do not register here. If \fItagName\fR does +not exist, it will be created with the default options. +.TP +\fIpathName \fBtag cget\fR \fItagName option\fR +This command returns the current value of the option named \fIoption\fR +associated with the tag given by \fItagName\fR. \fIOption\fR may have any +of the values accepted by the \fBtag configure\fR widget command. +.TP +\fIpathName \fBtag col\fR \fItagName ?col ...?\fR +With no arguments, prints out the list of cols that use the \fItag\fR. +Otherwise it sets the specified columns to use the named tag, replacing any +tag that may have been set using this method before. If \fItagName\fR is +{}, the cols are reset to the default \fItag\fR. Tags added during +\-coltagcommand evaluation do not register here. If \fItagName\fR does +not exist, it will be created with the default options. +.TP +\fIpathName \fBtag configure \fItagName\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? +This command is similar to the \fBconfigure\fR widget command except that +it modifies options associated with the tag given by \fItagName\fR instead +of modifying options for the overall table widget. If no \fIoption\fR is +specified, the command returns a list describing all of the available +options for \fItagName\fR (see \fBTk_ConfigureInfo\fR for information on +the format of this list). If \fIoption\fR is specified with no +\fIvalue\fR, 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 \fIoption\fR is specified). If one or more +\fIoption\-value\fR pairs are specified, then the command modifies the +given option(s) to have the given value(s) in \fItagName\fR; in this case +the command returns an empty string. +See TAGS above for details on the options available for tags. +.TP +\fIpathName \fBtag delete\fR \fItagName\fR +Deletes a tag. No error if the tag does not exist. +.TP +\fIpathName \fBtag exists\fR \fItagName\fR +Returns 1 if the named tag exists, 0 otherwise. +.TP +\fIpathName \fBtag includes\fR \fItagName index\fR +Returns 1 if the specified index has the named tag, 0 otherwise. +.TP +\fIpathName \fBtag lower\fR \fItagName\fR ?\fIbelowThis\fR? +Lower the priority of the named tag. If \fIbelowThis\fR is not specified, +then the tag's priority is lowered to the bottom, otherwise it is lowered +to one below \fIbelowThis\fR. +.TP +\fIpathName \fBtag names\fR ?\fIpattern\fR? +If no pattern is specified, shows the names of all defined tags. +Otherwise the \fIpattern\fR is used as a glob pattern to show only +tags matching that pattern. Tag names are returned in priority order +(highest priority tag first). +.TP +\fIpathName \fBtag raise\fR \fItagName\fR ?\fIaboveThis\fR? +Raise the priority of the named tag. If \fIaboveThis\fR is not specified, +then the tag's priority is raised to the top, otherwise it is raised to +one above \fIaboveThis\fR. +.TP +\fIpathName \fBtag row\fR \fItagName\fR ?\fIrow ...\fR? +With no arguments, prints out the list of rows that use the \fItag\fR. +Otherwise it sets the specified rows to use the named tag, replacing any +tag that may have been set using this method before. If \fItagName\fR is +{}, the rows are reset to use the default tag. Tags added during +\-rowtagcommand evaluation do not register here. If \fItagName\fR does +not exist, it will be created with the default options. +.RE +.TP +\fIpathName \fBvalidate\fR \fIindex\fR +Explicitly validates the specified index based on the current +\fB\-validatecommand\fR and returns 0 or 1 based on whether the cell was +validated. +.TP +\fIpathName \fBwidth\fR ?\fIcol\fR? ?\fIvalue col value ...\fR? +If no \fIcol\fR is specified, returns a list describing all cols for which +a width has been set. If \fBcol\fR 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 \fIcol\-value\fR pairs are specified, +then it sets each col to be that width in characters (positive number) or +pixels (negative number). If \fIvalue\fR is \fIdefault\fR, then the col +uses the default width, specified by \fB\-colwidth\fR. +.TP +\fIpathName \fBwindow\fR option ?\fIarg arg ...\fR? +This command is used to manipulate embedded windows. The exact behavior of +the command depends on the \fIoption\fR argument that follows the +\fBwindow\fR argument. The following forms of the command are currently +supported: +.RS +.TP +\fIpathName \fBwindow cget\fR \fIindex option\fR +This command returns the current value of the option named \fIoption\fR +associated with the window given by \fIindex\fR. \fIOption\fR may have any +of the values accepted by the \fBwindow configure\fR widget command. +.TP +\fIpathName \fBwindow configure \fIindex\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? +This command is similar to the \fBconfigure\fR widget command except that +it modifies options associated with the embedded window given by +\fIindex\fR instead of modifying options for the overall table widget. If +no \fIoption\fR is specified, the command returns a list describing all of +the available options for \fIindex\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified with +no \fIvalue\fR, 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 \fIoption\fR is specified). If one or more +\fIoption\-value\fR pairs are specified, then the command modifies the +given option(s) to have the given value(s) in \fIindex\fR; in this case +the command returns an empty string. +See EMBEDDED WINDOWS above for details on the options available for windows. +.TP +\fIpathName \fBwindow delete\fR \fIindex\fR ?\fIindex ...\fR? +Deletes an embedded window from the table. The associated window will +also be deleted. +.TP +\fIpathName \fBwindow move\fR \fIindexFrom indexTo\fR +Moves an embedded window from one cell to another. If a window already +exists in the target cell, it will be deleted. +.TP +\fIpathName \fBwindow names\fR ?\fIpattern\fR? +If no pattern is specified, shows the cells of all embedded windows. +Otherwise the \fIpattern\fR is used as a glob pattern to show only +cells matching that pattern. +.RE +.TP +\fIpathName \fBxview \fIargs\fR +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: +.RS +.TP +\fIpathName \fBxview\fR +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 \fB\-xscrollcommand\fR +option. +.TP +\fIpathName \fBxview\fR \fIindex\fR +Adjusts the view in the window so that the column given by +\fIindex\fR is displayed at the left edge of the window. +.TP +\fIpathName \fBxview moveto\fI fraction\fR +Adjusts the view in the window so that \fIfraction\fR of the +total width of the table text is off\-screen to the left. +\fIfraction\fR must be a fraction between 0 and 1. +.TP +\fIpathName \fBxview scroll \fInumber what\fR +This command shifts the view in the window left or right according to +\fInumber\fR and \fIwhat\fR. +\fINumber\fR must be an integer. +\fIWhat\fR must be either \fBunits\fR or \fBpages\fR or an abbreviation +of one of these. +If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by +\fInumber\fR cells on the display; if it is \fBpages\fR then the view +adjusts by \fInumber\fR screenfuls. +If \fInumber\fR is negative then cells farther to the left +become visible; if it is positive then cells farther to the right +become visible. +.RE +.TP +\fIpathName \fByview \fI?args\fR? +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: +.RS +.TP +\fIpathName \fByview\fR +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 \fB\-yscrollcommand\fR option. +.TP +\fIpathName \fByview\fR \fIindex\fR +Adjusts the view in the window so that the row given by +\fIindex\fR is displayed at the top of the window. +.TP +\fIpathName \fByview moveto\fI fraction\fR +Adjusts the view in the window so that the element given by \fIfraction\fR +appears at the top of the window. +\fIFraction\fR 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. +.TP +\fIpathName \fByview scroll \fInumber what\fR +This command adjusts the view in the window up or down according to +\fInumber\fR and \fIwhat\fR. \fINumber\fR must be an integer. \fIWhat\fR +must be either \fBunits\fR or \fBpages\fR. If \fIwhat\fR is \fBunits\fR, +the view adjusts up or down by \fInumber\fR cells; if it is \fBpages\fR then +the view adjusts by \fInumber\fR screenfuls. If \fInumber\fR is negative +then earlier elements become visible; if it is positive then later elements +become visible. +.RE + +.SH "DEFAULT BINDINGS" +.PP +The initialization creates class bindings that give the +following default behaviour: +.IP [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. +.IP [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. +.IP [3] +Moving the mouse while Button\-2 is pressed causes scanning to +occur without any selection. +.IP [4] +Home moves the table to have the origin in view. +.IP [5] +End moves the table to have the \fBend\fR cell in view. +.IP [6] +Control\-Home moves the table to the origin and activates that cell. +.IP [7] +Control\-End moves the table to the end and activates that cell. +.IP [8] +Shift\-Control\-Home extends the selection to the origin. +.IP [9] +Shift\-Control\-End extends the selection to the end. +.IP [10] +The left, right, up and down arrows move the active cell. +.IP [11] +Shift\-<arrow> extends the selection in that direction. +.IP [12] +Control\-leftarrow and Control\-rightarrow move the insertion +cursor within the cell. +.IP [13] +Control\-slash selects all the cells. +.IP [14] +Control\-backslash clears selection from all the cells. +.IP [15] +Backspace deletes the character before the insertion cursor +in the active cell. +.IP [16] +Delete deletes the character after the insertion cursor +in the active cell. +.IP [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. +.IP [18] +Control\-a moves the insertion cursor to the beginning of the active cell. +.IP [19] +Control\-e moves the insertion cursor to the end of the active cell. +.IP [20] +Control\-minus and Control\-equals decrease and increase the +width of the column with the active cell in it. +.IP [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 \fB\-resizeborders\fR. +.PP +Some bindings may have slightly different behavior dependent on the +\fB\-selectionmode\fR of the widget. +.PP +If the widget is disabled using the \fB\-state\fR 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. +.PP +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<version>/tkTable.tcl". + +.SH "PERFORMANCE ISSUES" +.PP +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. +.PP +The display cell with the insert cursor is redrawn each time the cursor +blinks, which causes a steady stream of graphics traffic. Set the +\fB\-insertofftime\fR option to 0 avoid this. The use of a \fB\-command\fR +with the table without a cache can cause significant slow\-down, as the +command is called once for each request of a cell value. + + +.SH EXAMPLES +.PP +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. +.CS +$table span [$table cget -roworigin],[$table cget -colorigin] [$table cget -titlerows],[$table cget -titlecols] +.CE +Force a table window refresh (useful for the slight chance that a bug +in the table is not causing proper refresh): +.CS +$table configure -padx [$table cget -padx] +.CE + +.SH KEYWORDS +table, widget, extension |