Provided by: tk-table_2.10.8-1_amd64 bug

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 interactive resizing is allowed (it is thus affect by the value  of
       -resizeborders).   Defaults  to  crosshair.  [-borderwidth or -bd borderWidth] Specifies a
       non-negative pixel value or list of values indicating the width of the 3-D border to  draw
       on  interior  table  cells  (if  such a border is being drawn; the 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  described  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 performance when used  with  -command  but  uses  extra
       memory.   Can  maintain  state  when  both -command and -variable are empty.  The cache is
       automatically 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  elements  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 default.

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

              all    All columns will be stretched by the same  number  of  pixels  to  fill  the
                     window  space  allocated  to  the  table.   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 numerous 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 expected to return the
       name of a tag to use, or a null string.  Errors occurring during  the  evaluation  of  the
       procedure,   or   the   return   of   an   invalid   tag   name   are   silently  ignored.
       [-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  instead 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 tables.

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

              fast   The table is drawn directly to the screen and the borders are done with fast
                     X calls, so they are always one pixel wide  only.   As  a  side  effect,  it
                     restricts  -borderwidth  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.

              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 ellipsis).
       [-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  second  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 selected.  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 (depending 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  justify  multi-line  text  in  a cell.  It must be one of left, right, or center.
       Defaults to left.  [-maxheight maxHeight] The max height in pixels that  the  window  will
       request.   Defaults  to 600.  [-maxwidth maxWidth] The max width in pixels that the window
       will request.  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  padding  style.   [-resizeborders resizeBorders]  Specifies  what  kind  of
       interactive border resizing to allow, must be one of row, col,  both  (default)  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]
       Number  of  rows  in the table.  Defaults to 10.  [-rowseparator rowSeparator] 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 rowTagCommand] 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 -coltagcommand, except that it applies to
       row tags.  [-selectioncommand or -selcmd selectionCommand] Specifies a command to evaluate
       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  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.   [-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   dimensions.
       [-selecttitle selectTitles]  Specifies  whether  title  cells  should  be  allowed  in the
       selection.  Defaults to 0 (disallowed).  [-selecttype 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  define  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  methods  will  be  ignored.
       Defaults  to  normal.   [-titlecols titleCols]  Number  of columns to use as a title area.
       Defaults to 0.  [-titlerows titleRows] 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 occur 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 table.  The widget has an active cell, the contents of which can be edited
       (when  the  state  is normal).  The widget supports a default style for the cells and also
       multiple 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 observe 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 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  -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 appropriate 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 setting $env(TK_TABLE_LIBRARY_FILE).

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

INDICES

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

       number,number
                   Specifies  the  cell  as a numerical index of row,col 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 table  (this  excludes
                   title cells).

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

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

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 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 ``pathName tag configure'' 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:

              -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 table, 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 ``pathName
       tag lower'' and ``pathName tag raise'' widget commands.

       If a cell has several tags associated with it that define the same display options (eg - a
       title  cell with specific row and cell 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.

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

       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  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:

              -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 table, 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 displayed 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
       Excel 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 always 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  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.

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

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 widget:

       %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 selection.  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 being validated.  For
            BrowseCommand, it is the index of the new active 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 returned.

       pathName border option args
              This  command  is  a  voodoo  hack  to implement border sizing for tables.  This is
              normally called through bindings, with the following 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 conjunction 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 tuple of both border
                     indices (an empty item means no border).  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  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.

       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 information managed by
              the  table.   first  and  last  represent  valid  table  indices.   If  neither are
              specified, then the command operates 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 specified, 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 specified 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 available options for pathName (see
              Tk_ConfigureInfo for information on  the  format  of  this  list).   If  option  is
              specified  with  no value, then the command returns a list describing the one named
              option (this list will be identical to  the  corresponding  sublist  of  the  value
              returned  if  no  option  is  specified).   If  one  or more option-value pairs are
              specified, then the command modifies the given widget option(s) to have  the  given
              value(s);   in  this case the command returns an empty string.  Option may have any
              of the values accepted by the table command.

       pathName curselection ?value?
              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.

       pathName curvalue ?value?
              If no value is given, the value of the cell being edited  (indexed  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, otherwise it deletes from the first index to
                     the second.  index 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 tables.  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 absolute 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 adjusted.  By default, these tags are properly adjusted.

                     -holdwindows
                            Causes the embedded windows created with the  window  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.  Otherwise 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 cursor in the active
              cell.  With one argument, sets the cursor to that point in the string.  0 is before
              the first character, you can also use insert or end for the current insertion point
              or the end of the text.  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 positioned 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
                     column 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
                     column deletion.

       pathName reread
              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).

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

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

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

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

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

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

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

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

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

       pathName set ?row|col? index ?value? ?index value ...?
              Sets the specified index to the associated value.  Table  validation  will  not  be
              triggered  via  this method.  If row or col 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 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 table 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 tuples 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
              supported:

              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 -*tagcommand 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  -coltagcommand  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
                     corresponding  sublist of the value returned if no option is specified).  If
                     one or more option-value pairs are specified, then the command modifies  the
                     given  option(s)  to  have  the  given value(s) in tagName; in this case the
                     command returns an empty string.  See TAGS above for details on the  options
                     available for tags.

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

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

              pathName tag 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 bottom, otherwise it is lowered to  one
                     below belowThis.

              pathName tag names ?pattern?
                     If  no pattern is specified, shows the names of all defined tags.  Otherwise
                     the pattern is used as a glob  pattern  to  show  only  tags  matching  that
                     pattern.   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 exist, 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 number) 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  follows  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 embedded 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  available
                     options  for  index  (see  Tk_ConfigureInfo for information on the format of
                     this list).  If option is specified with no value, then the command  returns
                     a  list  describing the one named option (this list will be identical to the
                     corresponding sublist of the value returned if no option is specified).   If
                     one  or more option-value pairs are specified, then the command modifies the
                     given option(s) to have the given  value(s)  in  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 associated 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  embedded  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
                     element is .6, 20% of the table's text is off-screen to the left, the middle
                     40%  is  visible  in  the  window,  and 40% of the text is off-screen to the
                     right.   These  are  the  same  values  passed   to   scrollbars   via   the
                     -xscrollcommand option.

              pathName xview index
                     Adjusts  the  view  in  the  window  so  that  the  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 negative 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 following forms:

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

              pathName yview index
                     Adjusts  the  view in the window so that the 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  element  in  the  table,  0.33  indicates  the  element
                     one-third the way through the table, and so on.

              pathName yview scroll number what
                     This  command  adjusts the view in the window up or down according to number
                     and what.  Number must be an integer.  What must be either units  or  pages.
                     If  what  is  units,  the  view adjusts up or down by number 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 default behaviour:

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

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

       [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 cursor 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 active 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 resizing 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 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".

PERFORMANCE ISSUES

       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.

       The display cell with the insert cursor is redrawn each  time  the  cursor  blinks,  which
       causes  a  steady  stream  of  graphics traffic.  Set the -insertofftime option to 0 avoid
       this.  The use of a -command  with  the  table  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 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]

KEYWORDS

       table, widget, extension