diff options
| author | Ian Roxborough <irox@redhat.com> | 2001-09-08 21:55:17 +0000 |
|---|---|---|
| committer | Ian Roxborough <irox@redhat.com> | 2001-09-08 21:55:17 +0000 |
| commit | 926d71c5c29102926ff1cf87828cad68a79bce56 (patch) | |
| tree | 5db22f4f17ca5f8c78ab7fffe45a79a617c3f666 /libgui/doc/tkTable.html | |
| parent | b111a96ea19bde1004ecea63c7827a1d4b0b73ef (diff) | |
| download | gdb-926d71c5c29102926ff1cf87828cad68a79bce56.tar.gz | |
libgui import for Tcl/Tk8.3 upgradeLIBGUI_TCL_8_3
Diffstat (limited to 'libgui/doc/tkTable.html')
| -rw-r--r-- | libgui/doc/tkTable.html | 1907 |
1 files changed, 1907 insertions, 0 deletions
diff --git a/libgui/doc/tkTable.html b/libgui/doc/tkTable.html new file mode 100644 index 00000000000..e7c65978d75 --- /dev/null +++ b/libgui/doc/tkTable.html @@ -0,0 +1,1907 @@ +<!-- manual page source format generated by PolyglotMan v3.0.7, --> +<!-- available via anonymous ftp from ftp.cs.berkeley.edu:/ucb/people/phelps/tcltk/rman.tar.Z --> + +<HTML> +<HEAD> +<TITLE>man page(1)</TITLE> +</HEAD> +<BODY bgcolor=white> +<A HREF="#toc">Table of Contents</A><P> +_________________________________________________________________ + +<H2><A NAME="sect0" HREF="#toc0"><B>Name</B></A></H2> + +<P> +table - Create and manipulate tables + +<H2><A NAME="sect1" HREF="#toc1"><B>Synopsis</B></A></H2> + +<P> +<B>table</B> <I>pathName</I> ?<I>options</I>? + +<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> +</DD> +</DL> +<P> +See the <B>options</B> manual entry for details on the standard +options. + +<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> +A boolean value which specifies whether the first +keypress in a cell will delete whatever text was +previously there. Defaults to 0. +<P> +Command-Line Name:<B>-bordercursor</B><BR> + +Database Name: <B>borderCursor</B><BR> + +Database Class: <B>Cursor</B> +<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> +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> +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> +Command-Line Name:<B>-browsecommand</B> <B>or</B> <B>-browsecmd</B> +Database Name: <B>browseCommand</B><BR> + +Database Class: <B>BrowseCommand</B> +<P> +Specifies a command which will be evaluated anytime +the active cell changes. It uses the %-substition +model described in COMMAND SUBSTITUTION below. +<P> +Command-Line Name:<B>-cache</B><BR> + +Database Name: <B>cache</B><BR> + +Database Class: <B>Cache</B> +<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> +Command-Line Name:<B>-colorigin</B><BR> + +Database Name: <B>colOrigin</B><BR> + +Database Class: <B>Origin</B> +<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> +Command-Line Name:<B>-cols</B><BR> + +Database Name: <B>cols</B><BR> + +Database Class: <B>Cols</B> +<P> +Number of cols in the table. Defaults to 10. +<P> +Command-Line Name:<B>-colseparator</B><BR> + +Database Name: <B>colSeparator</B><BR> + +Database Class: <B>Separator</B> +<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> +Command-Line Name:<B>-colstretchmode</B><BR> + +Database Name: <B>colStretchMode</B><BR> + +Database Class: <B>StretchMode</B> +<P> +Specifies one of the following stretch modes for +columns to fill extra allocated window space: +<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> +<B>unset</B> Only columns that do not have a specific +width set will be stretched. + +<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. +</DD> +</DL> +<P> +<B>last</B> The last column will be stretched to fill +the window space allocated to the table. +<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> +Command-Line Name:<B>-coltagcommand</B><BR> + +Database Name: <B>colTagCommand</B><BR> + +Database Class: <B>TagCommand</B> +<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 +occuring during the evaluation of the procedure, or +the return of an invalid tag name are silently +ignored. +<P> +Command-Line Name:<B>-colwidth</B><BR> + +Database Name: <B>colWidth</B><BR> + +Database Class: <B>ColWidth</B> +<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> +Command-Line Name:<B>-command</B><BR> + +Database Name: <B>command</B><BR> + +Database Class: <B>Command</B> +<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> +Command-Line Name:<B>-drawmode</B><BR> + +Database Name: <B>drawMode</B><BR> + +Database Class: <B>DrawMode</B> +<P> +Sets the table drawing mode to one of the following +options: +<P> +<B>slow</B> The table is drawn to an offscreen pixmap +using the Tk bordering functions (doublebuffering). +This means there will be no +flashing, but this mode is slow for larger +tables. +<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> +<B>fast</B> 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> +<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> +Command-Line Name:<B>-flashmode</B><BR> + +Database Name: <B>flashMode</B><BR> + +Database Class: <B>FlashMode</B> +<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> +Command-Line Name:<B>-flashtime</B><BR> + +Database Name: <B>flashTime</B><BR> + +Database Class: <B>FlashTime</B> +<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> +Command-Line Name:<B>-height</B><BR> + +Database Name: <B>height</B><BR> + +Database Class: <B>Height</B> +<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> +Command-Line Name:<B>-invertselected</B><BR> + +Database Name: <B>invertSelected</B><BR> + +Database Class: <B>InvertSelected</B> +<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> +Command-Line Name:<B>-ipadx</B><BR> + +Database Name: <B>ipadX</B><BR> + +Database Class: <B>Pad</B> +<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> +Command-Line Name:<B>-ipady</B><BR> + +Database Name: <B>ipadY</B><BR> + +Database Class: <B>Pad</B> +<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> +Command-Line Name:<B>-maxheight</B><BR> + +Database Name: <B>maxHeight</B><BR> + +Database Class: <B>MaxHeight</B> +<P> +The max height in pixels that the window will +request. Defaults to 600. +<P> +Command-Line Name:<B>-maxwidth</B><BR> + +Database Name: <B>maxWidth</B><BR> + +Database Class: <B>MaxWidth</B> +<P> +The max width in pixels that the window will +request. Defaults to 800. +<P> +Command-Line Name:<B>-multiline</B><BR> + +Database Name: <B>multiline</B><BR> + +Database Class: <B>Multiline</B> +<P> +Specifies the default setting for the multiline tag +option. Defaults to 1. +<P> +Command-Line Name:<B>-padx</B><BR> + +Database Name: <B>padX</B><BR> + +Database Class: <B>Pad</B> +<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> +Command-Line Name:<B>-pady</B><BR> + +Database Name: <B>padY</B><BR> + +Database Class: <B>Pad</B> +<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> +Command-Line Name:<B>-resizeborders</B><BR> + +Database Name: <B>resizeBorders</B><BR> + +Database Class: <B>ResizeBorders</B> +<P> +Specifies what kind of interactive border resizing +to allow, must be one of row, col, both (default) +or none. +<P> +Command-Line Name:<B>-rowheight</B><BR> + +Database Name: <B>rowHeight</B><BR> + +Database Class: <B>RowHeight</B> +<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> +Command-Line Name:<B>-roworigin</B><BR> + +Database Name: <B>rowOrigin</B><BR> + +Database Class: <B>Origin</B> +<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> +Command-Line Name:<B>-rows</B><BR> + +Database Name: <B>rows</B><BR> + +Database Class: <B>Rows</B> +<P> +Number of rows in the table. Defaults to 10. +<P> +Command-Line Name:<B>-rowseparator</B><BR> + +Database Name: <B>rowSeparator</B><BR> + +Database Class: <B>Separator</B> +<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> +Command-Line Name:<B>-rowstretchmode</B><BR> + +Database Name: <B>rowStretchMode</B><BR> + +Database Class: <B>StretchMode</B> +<P> +Specifies the stretch modes for rows to fill extra +allocated window space. See <B>-colstretchmode</B> for +valid options. +<P> +Command-Line Name:<B>-rowtagcommand</B><BR> + +Database Name: <B>rowTagCommand</B><BR> + +Database Class: <B>TagCommand</B> +<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> +Command-Line Name:<B>-selectioncommand</B> <B>or</B> <B>-selcmd</B> +Database Name: <B>selectionCommand</B><BR> + +Database Class: <B>SelectionCommand</B> +<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> +Command-Line Name:<B>-selectmode</B><BR> + +Database Name: <B>selectMode</B><BR> + +Database Class: <B>SelectMode</B> +<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> +Command-Line Name:<B>-selecttitle</B><BR> + +Database Name: <B>selectTitles</B><BR> + +Database Class: <B>SelectTitles</B> +<P> +Specifies whether title cells should be allowed in +the selection. Defaults to 0 (disallowed). +<P> +Command-Line Name:<B>-selecttype</B><BR> + +Database Name: <B>selectType</B><BR> + +Database Class: <B>SelectType</B> +<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> +Command-Line Name:<B>-sparsearray</B><BR> + +Database Name: <B>sparseArray</B><BR> + +Database Class: <B>SparseArray</B> +<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> +Command-Line Name:<B>-state</B><BR> + +Database Name: <B>state</B><BR> + +Database Class: <B>State</B> + +<DL> + +<DT>Specifies one of two states for the entry: </DT></DT> +<DD><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>. +</DD> +</DL> +<P> +Command-Line Name:<B>-titlecols</B><BR> + +Database Name: <B>titleCols</B><BR> + +Database Class: <B>TitleCols</B> +<P> +Number of columns to use as a title area. Defaults +to 0. +<P> +Command-Line Name:<B>-titlerows</B><BR> + +Database Name: <B>titleRows</B><BR> + +Database Class: <B>TitleRows</B> +<P> +Number of rows to use as a title area. Defaults to +0. +<P> +Command-Line Name:<B>-usecommand</B><BR> + +Database Name: <B>useCommand</B><BR> + +Database Class: <B>UseCommand</B> +<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> +Command-Line Name:<B>-validate</B><BR> + +Database Name: <B>validate</B><BR> + +Database Class: <B>Validate</B> +<P> +A boolean specifying whether validation should +occur for the active buffer. Defaults to 0. +<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> +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> +Command-Line Name:<B>-variable</B><BR> + +Database Name: <B>variable</B><BR> + +Database Class: <B>Variable</B> +<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 doesn't +require all valid indices have values). No stored +value for an index is equivalent to the empty +string, and clearing a cell will remove that index +from the Tcl array, unless the <B>-sparsearray</B> options +is set to 0. +<P> +Command-Line Name:<B>-width</B><BR> + +Database Name: <B>width</B><BR> + +Database Class: <B>Width</B> +<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> +Command-Line Name:<B>-wrap</B><BR> + +Database Name: <B>wrap</B><BR> + +Database Class: <B>Wrap</B> +<P> +Specifies the default wrap value for tags. +Defaults to 0.<BR> + +_________________________________________________________________ + +<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. 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> +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> +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> +In order to obtain good performance, the table widget supports +multiple drawing modes, two of which are fully Tk +compatible. + +<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> +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. + +<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> +<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). + +<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. +</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. +</DD> +</DL> +<P> +<B>bottomright</B> Indicates the bottom-rightmost cell visible in +the table. + +<DL> + +<DT><B>end</B> </DT></DT> +<DD> Indicates the bottom right cell of the table. +</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. +</DD> + +<DT><B>topleft</B> </DT></DT> +<DD> Indicates the top-leftmost editable cell visible +in the table (this excludes title cells). +</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. +</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. + +<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. +There may be any number of tags in a table, but +each row, column or cell can only have one tag associated +with it at a time. There are several permanent tags in +each table that can be configured by the user and will +determine the attributes for special cells: + +<DL> + +<DT><B>active</B> </DT></DT> +<DD> This tag is given to the <I>active</I> cell +</DD> + +<DT><B>flash</B> </DT></DT> +<DD> If flash mode is on, this tag is given to +any recently edited cells. +</DD> + +<DT><B>sel</B> </DT></DT> +<DD> This tag is given to any selected cells. +</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. +</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: + +<DL> + +<DT><B>-anchor</B> <I>anchor</I></DT></DT> +<DD> +Anchor for item in the cell space. +</DD> + +<DT><B>-background</B> or <B>-bg</B> <I>color</I></DT></DT> +<DD> +Background color of the cell. +</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). +</DD> + +<DT><B>-font</B> <I>fontName</I></DT></DT> +<DD> +Font for text in the cell. +</DD> + +<DT><B>-foreground</B> or <B>-fg</B> <I>color</I></DT></DT> +<DD> +Foreground color of the cell. +</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>. +</DD> + +<DT><B>-image</B> <I>imageName</I></DT></DT> +<DD> +An image to display in the cell instead of +text. +</DD> + +<DT><B>-multiline</B> <I>boolean</I></DT></DT> +<DD> +Whether to display text with newlines on +multiple lines. +</DD> + +<DT><B>-relief</B> <I>relief</I></DT></DT> +<DD> +The relief for the cell. +</DD> + +<DT><B>-showtext</B> <I>boolean</I></DT></DT> +<DD> +Whether to show the text over an image. +</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. +</DD> + +<DT><B>-wrap</B> <I>boolean</I></DT></DT> +<DD> +Whether characters should wrap in a cell +that is not wide enough. +</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>pathName</I> <B>tag</B> <B>lower</B>'' and ``<I>pathName</I> <B>tag</B> <B>raise</B>'' +widget commands. +<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> +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>. + +<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> +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> +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: + +<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. +</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. +</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). +</DD> + +<DT><B>-padx</B> <I>pixels</I></DT></DT> +<DD> +As defined in the Tk options man page. +</DD> + +<DT><B>-pady</B> <I>pixels</I></DT></DT> +<DD> +As defined in the Tk options man page. +</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. +</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. +</DD> + +<DT><B>-window</B> <I>pathName</I></DT></DT> +<DD> +Specifies the name of a window to display in +the annotation. It must exist before being +specified here. +</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. + +<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> +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> +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> +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. + +<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> +<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. + +<DL> + +<DT><B>%C</B> </DT></DT> +<DD>A convenience substitution for <I>%r</I>,<I>%c</I>. +</DD> + +<DT><B>%i</B> </DT></DT> +<DD>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. +</DD> + +<DT><B>%r</B> </DT></DT> +<DD>For <B>SelectionCommand</B>, it is the number of rows in the +selection. Otherwise it is the row of the triggered +cell. +</DD> +</DL> +<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). + +<DL> + +<DT><B>%S</B> </DT></DT> +<DD>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. +</DD> +</DL> +<P> +<B>%W</B> The pathname to the window for which the command was +generated. + +<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> +The following commands are possible for <B>table</B> widgets: +<P> +<I>pathName</I> <B>activate</B> <I>index</I><BR> + +Sets the active cell to the one indicated by <I>index</I>. +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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>path</I><B>_N</B><I>ame</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> +<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> +<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> +<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>: +<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> +<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: + +<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>. +</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.. +</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. +</DD> + +<DT><B>-holdwindows</B></DT></DT> +<DD> +Causes the embedded windows created +with the <I>window</I> method to not move +along with the data. By default, +these windows are properly adjusted. +</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. +</DD> + +<DT><B>--</B> </DT></DT> +<DD> Signifies the end of the switches. +</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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> postion 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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<I>pathName</I> <B>tag</B> <B>exists</B> <I>tagName</I><BR> + +Returns 1 if the named tag exists, 0 otherwise. +<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> +<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> +<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> +<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> +<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 columns 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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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>pat</I><B>_</B>t<I>ern</I> +is used as a glob pattern to show only +cells matching that pattern. +<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> +<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> +<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> +<I>pathName</I> <B>xview</B> <B>moveto</B> <I>fraction</I><BR> + +Adjusts the view in the window so that <I>frac</I><B>_</B>t<I>ion</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> +<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> character +units (the width of the <B>0</B> character) 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 characters farther to the left +become visible; if it is positive then +characters farther to the right become visible. +<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> +<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> +<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> +<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> +<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> lines; +if it is <B>pages</B> then the view adjusts by <I>num</I><B>_</B>b<I>er</I> +screenfuls. If <I>number</I> is negative then +earlier elements become visible; if it is +positive then later elements become visible. + +<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: + +<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. +</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. +</DD> + +<DT>[3] </DT></DT> +<DD> Moving the mouse while Button-2 is pressed causes +scanning to occur without any selection. +</DD> + +<DT>[4] </DT></DT> +<DD> Home moves the table to have the origin in view. +</DD> + +<DT>[5] </DT></DT> +<DD> End moves the table to have the <B>end</B> cell in view. +</DD> + +<DT>[6] </DT></DT> +<DD> Control-Home moves the table to the origin and +activates that cell. +</DD> + +<DT>[7] </DT></DT> +<DD> Control-End moves the table to the end and activates +that cell. +</DD> + +<DT>[8] </DT></DT> +<DD> Shift-Control-Home extends the selection to the +origin. +</DD> + +<DT>[9] </DT></DT> +<DD> Shift-Control-End extends the selection to the end. +</DD> + +<DT>[10] </DT></DT> +<DD>The left, right, up and down arrows move the active +cell. +</DD> +</DL> +<P> +[11] Shift-<arrow> extends the selection in that direction. +<P> +[12] Control-leftarrow and Control-rightarrow move the +insertion cursor within the cell. + +<DL> + +<DT>[13] </DT></DT> +<DD>Control-slash selects all the cells. +</DD> +</DL> +<P> +[14] Control-backslash clears selection from all the +cells. +<P> +[15] Backspace deletes the character before the insertion +cursor in the active cell. +<P> +[16] Delete deletes the character after the insertion +cursor in the active cell. +<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> +[18] Control-a moves the insertion cursor to the beginning +of the active cell. +<P> +[19] Control-e moves the insertion cursor to the end of +the active cell. +<P> +[20] Control-minus and Control-equals decrease and +increase the width of the column with the active +cell in it. +<P> +[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 <B>-resizeborders</B>. +<P> +Some bindings may have slightly different behavior dependent +on the <B>-selectionmode</B> of the widget. +<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> +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". + +<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> +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. + +<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. +$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] + +<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> |