table man page on OpenSuSE

Man page or keyword search:  
man Server   25941 pages
apropos Keyword Search (all sections)
Output format
OpenSuSE logo
[printable version]

table(n)		      Tk Table Extension		      table(n)

______________________________________________________________________________

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 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
       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 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
		     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 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
		     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  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
       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 (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
       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 pad‐
       ding 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.   [-rowori‐
       gin 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.	[-row‐
       stretchmode 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 proce‐
       dure 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]	Speci‐
       fies  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  dis‐
       played,	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 exe‐
       cute  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 ta‐
       ble.   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
       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 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
       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 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
       associated  with	 the tag override the default display style.  The fol‐
       lowing 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
       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 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
       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 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
	    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 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
		     tuple 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
	      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	recog‐
	      nized:

	      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
	      (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,	other‐
		     wise  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 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
			    adjusted.	By  default,  these  tags are properly
			    adjusted.

		     -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
		     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 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
	      tuples of the form {index span}.	 When  called  with  only  the
	      index, the span for that index only is returned, if any.	Other‐
	      wise an even number of index rows,cols pairs  are	 used  to  set
	      spans.   A span starts at the index and continues for the speci‐
	      fied 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
		     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 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
		     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 iden‐
		     tical 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
		     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 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
		     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 charac‐
	      ter 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 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
	      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	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
       -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  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				      2.8			      table(n)
[top]

List of man pages available for OpenSuSE

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net