tkTable(3)



table(3tk)                                                          table(3tk)

NAME
       table - Create and manipulate tables

SYNOPSIS
       table pathName ?options?

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

       See the options manual entry for details on the standard options.

WIDGET-SPECIFIC OPTIONS
       [-autoclear autoClear]  A  boolean  value  which  specifies whether the
       first keypress in a cell  will  delete  whatever  text  was  previously
       there.  Defaults to 0.  [-bordercursor borderCursor] Specifies the name
       of the cursor to show when over borders, a visual indication  that  in-
       teractive  resizing  is allowed (it is thus affect by the value of -re-
       sizeborders).  Defaults to  crosshair.   [-borderwidth  or  -bd border-
       Width]  Specifies a non-negative pixel value or list of values indicat-
       ing the width of the 3-D border to draw on  interior  table  cells  (if
       such  a  border  is being drawn; the relief option typically determines
       this).  If one value is specified, a rectangle of this  width  will  be
       drawn.  If two values are specified, then only the left and right edges
       of the cell will have borders.  If four values are specified, then  the
       values  correspond  to  the {left right top bottom} edges.  This can be
       overridden by the a tag's borderwidth option.  It can also be  affected
       by  the  defined  -drawmode for the table.  Each value in the list must
       have one of the forms acceptable to Tk_GetPixels.   [-browsecommand  or
       -browsecmd browseCommand]  Specifies  a command which will be evaluated
       anytime the active cell changes.  It uses the  %-substition  model  de-
       scribed  in COMMAND SUBSTITUTION below.  Any changes to the active cell
       while  the  command  is  running  are  ignored  to  prevent  recursion.
       [-cache cache] A boolean value that specifies whether an internal cache
       of the table contents should be kept.  This greatly enhances speed per-
       formance  when  used with -command but uses extra memory.  Can maintain
       state when both -command and -variable are empty.  The cache  is  auto-
       matically  flushed  whenever  the value of -cache or -variable changes,
       otherwise you have to explicitly call clear on it.   Defaults  to  off.
       [-colorigin colOrigin]  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.  [-cols cols] Number of cols in the table.
       Defaults to 10.   [-colseparator colSeparator]  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  ele-
       ments of a tcl list.  [-colstretchmode colStretchMode] Specifies one of
       the following stretch modes for columns to fill extra allocated  window
       space:

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

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

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

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

              fill (only valid for -rowstretch currently)
                     The  table will get more or less columns according to the
                     window space allocated to the table.  This mode  has  nu-
                     merous quirks and may disappear in the future.
       [-coltagcommand colTagCommand]  Provides  the  name of a procedure that
       will be evaluated by the widget to determine the tag to be used  for  a
       given  column.   When  displaying  a  cell, the table widget will first
       check to see if a tag has been defined using the tag col widget method.
       If  no  tag  is found, it will evaluate the named procedure passing the
       column number in question as the sole argument.  The procedure  is  ex-
       pected  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.  [-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.
       [-command command] Specified a command to use as a procedural interface
       to  cell values.  If -usecommand is true, this command will be used in-
       stead of any reference to the -variable array.   When  retrieving  cell
       values,  the  return  value of the command is used as the value for the
       cell.  It uses the %-substition model described in COMMAND SUBSTITUTION
       below.   [-drawmode drawMode] Sets the table drawing mode to one of the
       following options:

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

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

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

              single The table is drawn to the screen as  in  fast  mode,  but
                     only single pixel lines are drawn (not square borders).
       [-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 ellip-
       sis).  [-flashmode flashMode] A boolean value which  specifies  whether
       cells  should flash when their value changes.  The table tag flash will
       be applied to these cells for the  duration  specified  by  -flashtime.
       Defaults  to 0.  [-flashtime flashTime] The amount of time, in 1/4 sec-
       ond increments, for which a  cell  should  flash  when  its  value  has
       changed.   -flashmode  must  be  on.   Defaults to 2.  [-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
       -maxheight.   [-invertselected invertSelected]  Specifies  whether  the
       foreground and background of an item should simply  have  their  values
       swapped  instead  of  merging  the sel tag options when the cell is se-
       lected.  Defaults to 0 (merge sel tag).  [-ipadx ipadX] 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 (depend-
       ing on anchor).  Defaults to 0.  See -padx  for  an  alternate  padding
       style.   [-ipady ipadY]  A pixel value specifying the internal offset Y
       padding for text in a cell.  This value does not grow the size  of  the
       cell, it just causes the text to be drawn further from the cell border.
       It only affects one side (depending on anchor).  Defaults  to  0.   See
       -pady  for  an alternate padding style.  [-justify justify] How to jus-
       tify multi-line text in a cell.  It must be one of left, right, or cen-
       ter.   Defaults to left.  [-maxheight maxHeight] The max height in pix-
       els   that   the   window   will    request.     Defaults    to    600.
       [-maxwidth maxWidth]  The  max width in pixels that the window will re-
       quest.  Defaults to 800.  [-multiline multiline] Specifies the  default
       setting  for  the multiline tag option.  Defaults to 1.  [-padx padX] A
       pixel value specifying the offset X padding for  a  cell.   This  value
       causes  the default size of the cell to increase by two times the value
       (one for each side), unless a specific pixel size  is  chosen  for  the
       cell with the width command.  This will force an empty area on the left
       and right of each cell edge.  This padding affects all types of data in
       the  cell.   Defaults to 0.  See -ipadx for an alternate padding style.
       [-pady padY] A pixel value specifying the offset Y padding for a  cell.
       This value causes the default size of the cell to increase by two times
       the value (one for each side), unless a specific pixel size  is  chosen
       for the cell with the height command.  This will force an empty area on
       the top and bottom of each cell edge.  This padding affects  all  types
       of  data in the cell.  Defaults to 0.  See -ipadx for an alternate pad-
       ding style.  [-resizeborders resizeBorders] Specifies what kind of  in-
       teractive  border resizing to allow, must be one of row, col, both (de-
       fault) or none.  [-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.  [-roworigin rowOrigin] 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.  [-rows rows]  Num-
       ber  of  rows in the table.  Defaults to 10.  [-rowseparator rowSepara-
       tor] 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.   [-rowstretchmode rowStretchMode]
       Specifies  the  stretch  modes  for rows to fill extra allocated window
       space.  See -colstretchmode for valid options.  [-rowtagcommand rowTag-
       Command]  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 num-
       ber), and return a tag name or null string.  This operates in a similar
       manner as -coltagcommand, except that it applies to row tags.  [-selec-
       tioncommand or -selcmd selectionCommand] Specifies a command to  evalu-
       ate  when  the  selection  is  retrieved from a table via the selection
       mechanism (ie: evaluating ``selection get'').  The  return  value  from
       this  command  will become the string passed on by the selection mecha-
       nism.  It uses the %-substition model described in COMMAND SUBSTITUTION
       below.   If  an  error  occurs, a Tcl background error is generated and
       nothing is returned.  [-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  single,
       browse,  multiple,  or  extended;  the  default value is browse.  These
       styles are like those for the Tk listbox, except expanded for 2  dimen-
       sions.    [-selecttitle selectTitles]  Specifies  whether  title  cells
       should be allowed in the selection.  Defaults to 0 (disallowed).  [-se-
       lecttype selectType]  Specifies  one  of several types of selection for
       the table.  The value of the option may be one of row,  col,  cell,  or
       both  (meaning row && col); the default value is cell.  These types de-
       fine whether an entire row/col is affected when a cell's  selection  is
       changed  (set  or  clear).   [-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.
       [-state state] Specifies one of two states for the  entry:   normal  or
       disabled.   If  the table is disabled then the value may not be changed
       using widget commands and no insertion cursor will be  displayed,  even
       if  the input focus is in the widget.  Also, all insert or delete meth-
       ods will be ignored.  Defaults to normal.  [-titlecols titleCols]  Num-
       ber of columns to use as a title area.  Defaults to 0.  [-titlerows ti-
       tleRows] Number of rows to  use  as  a  title  area.   Defaults  to  0.
       [-usecommand useCommand] A boolean value which specifies whether to use
       the command option.  This value sets itself to zero if command is  used
       and  returns  an error.  Defaults to 1 (will use command if specified).
       [-validate validate] A boolean specifying whether validation should oc-
       cur  for  the  active  buffer.   Defaults  to  0.  [-validatecommand or
       -vcmd 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.  [-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 row,col  for  cells  and  the
       special  key active which contains the value of the active cell buffer.
       The Tcl array is managed as a sparse array (the table 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 -sparsearray options is set to 0.
       [-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 -maxwidth.  [-wrap wrap] Specifies the default wrap
       value for tags.  Defaults to 0.
_________________________________________________________________

DESCRIPTION
       The table 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 must be configured before any data is retained by the ta-
       ble.  The widget has an active cell,  the  contents  of  which  can  be
       edited (when the state is normal).  The widget supports a default style
       for the cells and also multiple tags, which can be used to  change  the
       style  of  a  row, column or cell (see TAGS for details).  A cell flash
       can be set up so that changed cells will change color for  a  specified
       amount  of  time ("blink").  Cells can have embedded images or windows,
       as described in TAGS and "EMBEDDED WINDOWS" respectively.

       One or more cells may be selected as described below.  If  a  table  is
       exporting its selection (see -exportselection option), then it will ob-
       serve the standard X11 protocols for handling the selection.   See  THE
       SELECTION for details.

       It is not necessary for all the cells to be displayed in the table win-
       dow at once; commands described below may be used to change the view in
       the  window.  Tables allow scrolling in both directions using the stan-
       dard -xscrollcommand and -yscrollcommand options.   They  also  support
       scanning, as described below.

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

INITIALIZATION
       When the table command is loaded into an interpreter,  a  built-in  Tcl
       command, tkTableInit, is evaluated.  This will search for the appropri-
       ate table binding init file to  load.   The  directories  searched  are
       those in $tcl_pkgPath, both with Tktable(version) appended and without,
       $tk_library and [pwd] (the current directory).  You can also define  an
       $env(TK_TABLE_LIBRARY)  to head this search list.  By default, the file
       searched for is called tkTable.tcl, but this can be overridden by  set-
       ting $env(TK_TABLE_LIBRARY_FILE).

       This  entire  init  script  can be overridden by providing your own tk-
       TableInit procedure before  the  library  is  loaded.   Otherwise,  the
       aforementioned  env(TK_TABLE_LIBRARY) variable will be set with the di-
       rectory in which $env(TK_TABLE_LIBRARY_FILE) was found.

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

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

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

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

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

       end         Indicates the bottom right cell of the table.

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

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

       @x,y        Indicates the cell that covers the point in the table  win-
                   dow  specified  by  x  and y (in pixel coordinates).  If no
                   cell covers that point, then the closest cell to that point
                   is used.

       In the widget command descriptions below, arguments named index, first,
       and last always contain text indices in one of the above forms.

TAGS
       A tag is a textual string that is associated with zero  or  more  rows,
       columns  or  cells  in a table.  Tags may contain arbitrary characters,
       but it is probably best to avoid using names which look like indices to
       reduce  coding  confusion.  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:

              active    This tag is given to the active cell

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

              sel       This tag is given to any selected cells.

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

       Tags control the way cells are displayed on the screen.   Where  appro-
       priate,  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 ``pathName tag configure'' widget command.
       If a cell, row or column has been tagged, then the display options  as-
       sociated  with the tag override the default display style.  The follow-
       ing options are currently supported for tags:

              -anchor anchor
                     Anchor for item in the cell space.

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

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

              -ellipsis string
                     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.

              -font fontName
                     Font for text in the cell.

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

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

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

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

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

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

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

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

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

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

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

EMBEDDED WINDOWS
       There  may be any number of embedded windows in a table widget (one per
       cell), and any widget may be used as an embedded window (subject to the
       usual  rules for geometry management, which require the table window to
       be the parent of the embedded window or a descendant  of  its  parent).
       The embedded window's position on the screen will be updated as the ta-
       ble 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 em-
       bedded window occupies one cell's worth of space in the  table  widget,
       and  it  is referred to by the index of the cell in the table.  Windows
       associated with the table widget are destroyed when the table widget is
       destroyed.

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

       When an embedded window is added to a table widget with the window con-
       figure 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  sup-
       ported:

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

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

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

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

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

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

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

              -window pathName
                     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  dis-
                     played it will cease to be managed by the table widget.

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

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

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

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

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

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

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

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

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

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

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

       %S   For ValidateCommand, it is the potential new value of the cell be-
            ing validated.  For BrowseCommand, it is the index of the new  ac-
            tive cell.

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

WIDGET COMMAND
       The  table  command  creates  a new Tcl command whose name is pathName.
       This command may be used to invoke various operations  on  the  widget.
       It has the following general form:
              pathName option ?arg arg ...?
       Option and the args determine the exact behavior of the command.

       The following commands are possible for table widgets:

       pathName activate index
              Sets the active cell to the one indicated by index.

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

       pathName border option args
              This command is a voodoo hack to implement border sizing for ta-
              bles.   This  is normally called through bindings, with the fol-
              lowing as valid options:

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

              pathName border dragto x y
                     This command computes the difference between its x and  y
                     arguments  and  the  x and y arguments to the last border
                     mark command for the widget.  It then adjusts the  previ-
                     ously  marked  border by the difference.  This command is
                     typically associated with mouse motion events in the wid-
                     get,  to  produce the effect of interactive border resiz-
                     ing.

       pathName cget option
              Returns the current value of the configuration option  given  by
              option.  Option may have any of the values accepted by the table
              command.

       pathName clear option ?first? ?last?
              This command is a convenience routine to clear certain state in-
              formation  managed by the table.  first and last represent valid
              table indices.  If neither are specified, then the command oper-
              ates on the whole table.  The following options are recognized:

              pathName clear cache ?first? ?last?
                     Clears  the  specified section of the cache, if the table
                     has been keeping one.

              pathName clear sizes ?first? ?last?
                     Clears the specified row and  column  areas  of  specific
                     height/width  dimensions.   When just one index is speci-
                     fied, for example 2,0, that is interpreted as row  2  and
                     column 0.

              pathName clear tags ?first? ?last?
                     Clears  the  specified  area of tags (all row, column and
                     cell tags).

              pathName clear all ?first? ?last?
                     Performs all of the above clear functions on  the  speci-
                     fied area.

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

       pathName curselection ?value?
              With  no  arguments,  it  returns the sorted indices of the cur-
              rently selected cells.  Otherwise it sets all the selected cells
              to  the given value.  The set has no effect if there is no asso-
              ciated Tcl array or the state is disabled.

       pathName curvalue ?value?
              If no value is given, the value of the cell  being  edited  (in-
              dexed by active) is returned, else it is set to the given value.

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

              pathName delete active index ?index?
                     Deletes text from the active cell.  If only one index  is
                     given,  it deletes the character after that index, other-
                     wise it deletes from the first index to the second.   in-
                     dex can be a number, insert or end.

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

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

                     -holdselection
                            Causes the selection to be maintained on the abso-
                            lute cells values.  Otherwise, the selection  will
                            be cleared..

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

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

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

                     --     Signifies the end of the switches.

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

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

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

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

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

       pathName index index ?row|col?
              Returns the integer cell coordinate that corresponds to index in
              the form row,col.  If row or col is specified, then only the row
              or column index is returned.

       pathName insert option arg arg
              This command is used to into various things into  a  table.   It
              has several forms, depending on the option:

              pathName insert active index value
                     The value is a text string which is inserted at the index
                     position of the active cell.  The cursor  is  then  posi-
                     tioned  after the new text. index can be a number, insert
                     or end.

              pathName insert cols ?switches? index ?count?
                     Inserts count cols starting at col index.   If  count  is
                     negative, it inserts before the specified col.  Otherwise
                     it inserts after the specified col.  The  selection  will
                     be  cleared.  The switches are the same as those for col-
                     umn deletion.

              pathName insert rows ?switches? index ?count?
                     Inserts count rows starting at row index.   If  count  is
                     negative, it inserts before the specified row.  Otherwise
                     it inserts after the specified row.  The  selection  will
                     be  cleared.  The switches are the same as those for col-
                     umn deletion.

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

       pathName scan option args
              This command is used to implement scanning on  tables.   It  has
              two forms, depending on option:

              pathName scan mark x y
                     Records x and y and the current view in the table window;
                     used in conjunction  with  later  scan  dragto  commands.
                     Typically  this command is associated with a mouse button
                     press in the widget.  It returns an empty string.

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

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

       pathName selection option arg
              This command is used to adjust the selection within a table.  It
              has several forms, depending on option:

              pathName selection anchor index
                     Sets the selection anchor to the  cell  given  by  index.
                     The  selection anchor is the end of the selection that is
                     fixed while dragging out a selection with the mouse.  The
                     index anchor may be used to refer to the anchor cell.

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

              pathName selection includes index
                     Returns 1 if the cell indicated by index is currently se-
                     lected, 0 if it isn't.

              pathName selection set first ?last?
                     Selects all of the cells in the range between  first  and
                     last, inclusive, without affecting the selection state of
                     cells outside that range.

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

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

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

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

              pathName tag cget tagName option
                     This command returns the  current  value  of  the  option
                     named  option  associated  with the tag given by tagName.
                     Option may have any of the values  accepted  by  the  tag
                     configure widget command.

              pathName tag col tagName ?col ...?
                     With  no  arguments, prints out the list of cols that use
                     the tag.  Otherwise it sets the specified columns to  use
                     the  named  tag, replacing any tag that may have been set
                     using this method before.  If tagName is {}, the cols are
                     reset  to the default tag.  Tags added during -coltagcom-
                     mand evaluation do not register here.   If  tagName  does
                     not exist, it will be created with the default options.

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

              pathName tag delete tagName
                     Deletes a tag.  No error if the tag does not exist.

              pathName tag exists tagName
                     Returns 1 if the named tag exists, 0 otherwise.

              pathName tag includes tagName index
                     Returns 1 if the specified index has  the  named  tag,  0
                     otherwise.

              pathName tag lower tagName ?belowThis?
                     Lower the priority of the named tag.  If belowThis is not
                     specified, then the tag's priority is lowered to the bot-
                     tom, otherwise it is lowered to one below belowThis.

              pathName tag names ?pattern?
                     If  no  pattern  is specified, shows the names of all de-
                     fined tags.  Otherwise the pattern is used as a glob pat-
                     tern  to show only tags matching that pattern.  Tag names
                     are returned in  priority  order  (highest  priority  tag
                     first).

              pathName tag raise tagName ?aboveThis?
                     Raise the priority of the named tag.  If aboveThis is not
                     specified, then the tag's priority is raised to the  top,
                     otherwise it is raised to one above aboveThis.

              pathName tag row tagName ?row ...?
                     With  no  arguments, prints out the list of rows that use
                     the tag.  Otherwise it sets the specified rows to use the
                     named tag, replacing any tag that may have been set using
                     this method before.  If tagName is {}, the rows are reset
                     to use the default tag.  Tags added during -rowtagcommand
                     evaluation do not register here.  If tagName does not ex-
                     ist, it will be created with the default options.

       pathName validate index
              Explicitly  validates  the  specified index based on the current
              -validatecommand and returns 0 or 1 based on  whether  the  cell
              was validated.

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

       pathName window option ?arg arg ...?
              This command is used to manipulate embedded windows.  The  exact
              behavior of the command depends on the option argument that fol-
              lows the window argument.  The following forms  of  the  command
              are currently supported:

              pathName window cget index option
                     This  command  returns  the  current  value of the option
                     named option associated with the window given  by  index.
                     Option  may have any of the values accepted by the window
                     configure widget command.

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

              pathName window delete index ?index ...?
                     Deletes  an  embedded window from the table.  The associ-
                     ated window will also be deleted.

              pathName window move indexFrom indexTo
                     Moves an embedded window from one cell to another.  If  a
                     window  already  exists  in  the  target cell, it will be
                     deleted.

              pathName window names ?pattern?
                     If no pattern is specified, shows the cells of all embed-
                     ded  windows.   Otherwise  the  pattern is used as a glob
                     pattern to show only cells matching that pattern.

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

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

              pathName xview index
                     Adjusts the view in the window so that the  column  given
                     by index is displayed at the left edge of the window.

              pathName xview moveto fraction
                     Adjusts  the  view  in the window so that fraction of the
                     total width of the table text is off-screen to the  left.
                     fraction must be a fraction between 0 and 1.

              pathName xview scroll number what
                     This  command shifts the view in the window left or right
                     according to number and what.  Number must be an integer.
                     What  must be either units or pages or an abbreviation of
                     one of these.  If what is units, the view adjusts left or
                     right by number cells on the display; if it is pages then
                     the view adjusts by number screenfuls.  If number is neg-
                     ative  then cells farther to the left become visible;  if
                     it is positive then cells farther  to  the  right  become
                     visible.

       pathName yview ?args?
              This  command  is used to query and change the vertical position
              of the text in the widget's window.  It can take any of the fol-
              lowing forms:

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

              pathName yview index
                     Adjusts  the  view in the window so that the row given by
                     index is displayed at the top of the window.

              pathName yview moveto fraction
                     Adjusts the view in the window so that the element  given
                     by  fraction  appears at the top of the window.  Fraction
                     is a fraction between 0 and 1;  0 indicates the first el-
                     ement  in the table, 0.33 indicates the element one-third
                     the way through the table, and so on.

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

DEFAULT BINDINGS
       The initialization creates class bindings that give the  following  de-
       fault behaviour:

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

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

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

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

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

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

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

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

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

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

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

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

       [13]   Control-slash selects all the cells.

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

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

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

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

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

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

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

       [21]   Moving the mouse while Button-3 (the right button on Windows) is
              pressed while you are over a border will cause  interactive  re-
              sizing of that row and/or column to occur, based on the value of
              -resizeborders.

       Some bindings may have slightly different  behavior  dependent  on  the
       -selectionmode of the widget.

       If  the  widget  is disabled using the -state option, then its view can
       still be adjusted and cells can still be  selected,  but  no  insertion
       cursor will be displayed and no cell modifications will take place.

       The  behavior of tables can be changed by defining new bindings for in-
       dividual widgets or by redefining  the  class  bindings.   The  default
       bindings  are either compiled in or read from a file expected to corre-
       spond to: "[lindex $tcl_pkgPath 0]/Tktable<version>/tkTable.tcl".

PERFORMANCE ISSUES
       The number of rows and columns or a table widget  should  not  signifi-
       cantly  affect  the speed of redraw.  Recalculation and redraw of table
       parameters and cells is restricted as much as possible.

       The display cell with the insert cursor is redrawn each time the cursor
       blinks, which causes a steady stream of graphics traffic.  Set the -in-
       sertofftime option to 0 avoid this.  The use of a -command with the ta-
       ble  without a cache can cause significant slow-down, as the command is
       called once for each request of a cell value.

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

KEYWORDS
       table, widget, extension

Tk Table Extension                  2.10 Tk                         table(3tk)

Man(1) output converted with man2html
list of all man pages