WIDGET COMMAND: pathName activate index; pathName bbox first ?last?; pathName canvas script; pathName cellconfigure cell ?option value? ?option value...?
pathName cellconfigure default ?option?
pathName cellconfigure bg color cell ?cell...?
pathName cellconfigure fg color cell ?cell...?; pathName cget option; pathName clone from to canvas row_mag; pathName color cell; pathName configure ?option? ?value option value ...?; pathName curselection; pathName curtextcell; pathName curvalue ?value?; pathName delete index from?to?; pathName displayedrows; pathName fast_canvas cmd ?arg...?; pathName height ?row? ?value? ?row value...?
pathName height default; pathName hide get
pathName hide toggle col ?col...?; pathName icursor ?pos?; pathName index col
pathName index row; pathName insert value; pathName minheight row; pathName minwidth col ?value?; pathName nextemptyrow row; pathName redisplay ?-now? ?-trim?; pathName see index; pathName selection anchor index
pathName selection clear firstindex ?lastindex?
pathName selection includes index
pathName selection present
pathName selection set ?-only? firstindex ?lastindex?
pathName selection setlist cells; pathName selrect bbox
pathName selrect draw topleftcell bottomrightcell color tag; pathName set index ?value?; pathName textselection clear
pathName textselection get
pathName textselection set index from to; pathName trim; pathName viewport; pathName width ?col? ?value? ?col value...?
pathName width default; pathName xview
pathName xview leftcol
pathName xview moveto fraction
pathName xview scroll number what; pathName yview
pathName yview toprow
pathName yview moveto fraction
pathName yview scroll number what

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 -variable Tcl array, where -roworigin,-colorigin corresponds to the first cell in the table (0,0 by default).
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.
bottomleft: Indicates the bottom-leftmost 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.

THE SELECTION

The ss widget defines two different types of selection: the cell selection and the text selection.

The cell selection describes the currently selected set of cells. The curselection command returns this list and the selection command manipulates this selection in various ways.

The text selection describes the text that is selected within the currently active cell (if there is any). The curtextsel command returns a description of the text selection and the textselection command manipulates the text selection.

DESCRIPTION

The ss command creates a 2-dimensional grid of cells. The table can use a Tcl array variable (using the -variable option), or the set widget command, for data storage and retrieval. The widget has an active cell, the contents of which can be edited (when the value of the -state option is normal).

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.

WIDGET-SPECIFIC OPTIONS

-cols: Number of columns in the ss widget. Defaults to 1.

-colwidth: The default width of each column, in pixels. Defaults to 60.

-expandcol: The column that will be automatically expanded when the screen dimensions change. If -1, then no expansion is done. Defaults to -1.

-height: Specifies the desired height of the ss widget, in rows. If 0 or less, then the ss widget is made just large enough to hold all the rows in the table. The height can be further limited by -maxrows. Defaults to 0.

-hidecolor: The color of the vertical line representing hidden columns. "gray50" is the default.

-hresizecursor: The cursor when the pointer is over a horizontal resize line. Defaults to the cursor named "sb_v_double_arrow".

-ifdisabled: This value qualifies the value of the -state option, when -state is set to "disabled". If "all" (the default), then all interaction with the ss widget is disabled. But if "table", then only ss widget data changes are disabled. Other attributes of the ss widget, such as row heights, remain changeable.

-maxrows: The maximum number of rows that can appear in the ss widget. Defaults to 500.

-mincolwidth: The minimum width of any one column, in pixels. Default is 12.

-minrowheight: The minimum height of any one row, in pixels. Default is 12.

-resizecolor: The color of the line that is drawn indicating that a row or column is being resized. Default is "white".

-rowheight: The default height of any row, in pixels. Default is 20.

-rows: The default number of rows in the ss widget. Default is 1.

-state: The state of the ss widget: either "normal" or "disabled". Default is "normal". If this is set to "disabled" then the -ifdisabled option further modifies this state.

-titlecolwidth: The width of a title cell in the title column (i.e., column 0). Defaults to 36.

-titlebackground: The background color of a title cell. Defaults to "drakgray".

-titlecursor: The name of the cursor displayed when the mouse is over a title cell. Defaults to {} (so the cursor of the parent window is displayed).

-titleforeground: The foreground color of a title cell text. Defaults to "white".

-titlerowheight: The height of a title cell in the title row (i.e., row 0). Defaults to 20.

-variable: The name of a 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 currently active cell. The Tcl array is managed as a sparse array (the table doesn't require all valid indices have values). No stored value for an index is equivalent to the empty string, and clearing a cell will remove that index from the Tcl array.

-vresizecursor: The cursor when the pointer is over a vertical resize line. Defaults to the cursor named "sb_h_double_arrow".

-watermark: The name of a Tk image that is used as a "watermark", which will be displayed in the center of the visible spreadsheet. By default, no watermark is displayed.

-width: Specifies the desired width of the ss widget, in columns. Defaults to 0.

WIDGET COMMAND

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

pathName bbox first ?last?: Returns the bounding box containing all cells within the box of cells, from the cell indicated by index first, to the cell indicated by index last. If last is not specified, then only the cell indicated by first is used. The returned bounding box consists of a list of the form {x0, y0, x1, y1}. The bounding box is in canvas coordinates.

pathName canvas script: The underlying implementation of the ss widget is a canvas. This command evaluates script as a command on that underlying canvas.

pathName cellconfigure cell ?option value? ?option value...?
pathName cellconfigure default ?option?
pathName cellconfigure bg color cell ?cell?
pathName cellconfigure fg color cell ?cell?

"pathName cellconfigure cell ?option value..." configures the options for a particular cell. The only valid options are "-bg" and "-fg", and the value must be a valid color.

"pathName cellconfigure default", with no arguments, sets all of the options to their default values, for all cells.

"pathName cellconfigure default option" sets the given option to its default value, for all cells.

"pathName cellconfigure bg cell..." and " "pathName cellconfigure fg cell..." are used to set the background or foreground color for the set of specified cells.

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

pathName clone from to canvas row_mag: This command "clones" the part of the ss widget within the range of the rows given by from and to. The canvas must be a valid canvas widget into which the rows will be written.
Row_mag is the magnification factor for each row. If it is set to 1, the rows will be written as they appear in the original ss widget. Otherwise, the row height will be scaled using the row_mag factor. (The data in each cell will not be scaled by this magnification; only the space for each row will be scaled.)

pathName color cell: Returns the foreground color and background color of cell as a list.

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

pathName curselection: Returns the sorted list of cells that are currently selected.

pathName curtextsel: Returns a list of three values of the form cell from to, where cell is the currently active cell, and from and to are the indices for that cell that describe the range of the text selection.

pathName curvalue ?value?: With no arguments, returns the value in the active cell. If value is specified, sets the value in the active cell to value.

pathName delete index from ?to?: Delete text within the cell referenced by index, from the from-th character, to the to-th character. If to is not specified, only the single character at from is deleted.

pathName displayedrows: Returns the number of rows that are currently being displayed.

pathName fast_canvas cmd arg...

Executes the cmd on the underlying canvas, giving it the arguments from "arg...". The command is called fast_canvas because it makes use of the ss widget's special implementation of canvas tags, which does canvas id lookup in constant rather than linear time. Valid values for cmd and arg... are:

pathName fast_canvas bbox tag: Return the bounding box for all canvas items with the given tag.

pathName fast_canvas find tag: Return all canvas IDs with the given tag.

pathName fast_canvas gettags id: Return all tags that the item whose canvas id is id contains.

pathName fast_canvas index tag index: Returns the numerical index within the first canvas ID possessing the given tag corresponding to the index. See the index command for the canvas widget for more information.

pathName fast_canvas itemcget tag option: Returns the value for the given option, for the first canvas id that possesses tag. See the itemcget command for the canvas widget for more information.

pathName fast_canvas select adjust tag index
pathName fast_canvas select from tag index
pathName fast_canvas select to tag index: Implements the given select command on the underlying canvas for the first canvas id that possesses tag.

pathName height ?row? ?value? ?row value...?
pathName height default

With no arguments, returns an even-numbered list of rows and their heights in pixels. A row and its height only appears in this list if the height varies from the default.

With just a single row argument, returns its height, in pixels.

If row value... is specified, each row's height is set to value.

If "default" is specified, then all rows are set to the default row height.

pathName hide get ?col?
pathName hide toggle col ?col...?: hide get returns the list of currently hidden columns. Or if col is specified, returns 1 if is a hidden column and 0 otherwise.
hide toggle toggles the hidden state for all of the specified columns. A hidden column does not appear on the screen, but instead a wider than normal vertical line appears in its place.

pathName icursor ?pos?: With no arguments, returns the index of the insertion cursor within the cell that currently has the input focus. If pos is specified, then the cursor position is set to pos.

pathName index index
pathName index index row
pathName index index col: With no arguments, returns the cell referenced by index. If the keyword "row" is specified, returns the row of the cell referenced by index. If the keyword "col" is specified, returns the column of the cell referenced by index.

pathName insert string: Inserts string at the current insertion point within the cell that currently has the input focus.

pathName minheight row: Returns the minimum height, in pixels, of the given row.

pathName minwidth col ?value?: If value is not specified, returns the minimum width of the column col.
If value is specified, sets the minimum width of the column col to value. But in no case will the minimum be set lower than the value specified by the -mincolwidth option.

pathName nextemptyrow row: Returns the next row in the ss widget past row that contains no data.

pathName redisplay ?-now? ?-trim?

With no arguments, this command causes the data in the ss widget to be redisplayed at idle time.

If "-now" is specified, then the data is redisplayed immediately, rather than at idle time.

If "-trim" is specified, then the number of rows in the ss widget should be trimmed so that the lowest displayed row is the last row that contains data.

Under normal circumstances it should not be necessary to call this command. It is used by widget bindings to handle window reconfiguration, for example.

pathName see index: Scrolls the view so that the cell referenced by index is visible on the screen.

pathName selection cmd arg...

Executes the given selection cmd. Values for cmd and arg... are:

pathName selection anchor index: Begin a selection by placing the "selection anchor" at the cell referenced by index.

pathName selection clear firstindex ?lastindex?: Deselect all cells referenced from firstindex to lastindex. If lastindex iosn't specified, just deselect the cell referenced by firstindex.

pathName selection cleardata: Clears all of the data from the selected cells.

pathName selection includes index: Returns 1 if the selection currently includes the cell referenced by index, or 0 otherwise.

pathName selection present: Returns 1 if a selection exists, or 0 if it does not.

pathName selection set ?-only? firstindex ?lastindex?: If "-only" is specified, then the selection is set to just the cells referenced by the range from firstindex to lastindex inclusive; otherwise, the specified range of cells is added to the current selection.
If lastindex is not specified, then only the cell referenced by firstindex is used.

pathName selection setlist cells: Sets the selection to be the one given by the list of cells in cells.

pathName selrect cmd arg...

Executes the given selection rectangle cmd. The selection rectangle is a "shadow rectangle" that can be used to implement the dragging out of a proposed selection set. Values for cmd and arg... are:

pathName selrect bbox: Returns the "bounding box" of the selection rectangle in the form "row0 col0 row1 col1". The upperleft cell in the selection rectangle is at "row0,col0" and the lower right cell is at "row1,col1".

pathName selrect draw topleftcell bottomrightcell color tag: Draws the selection rectangle so that topleftcell and bottomrightcell define its bounding box. Color the rectangle boundrary with color. The underlying canvas will tag the rectangle glyph with the given tag.

pathName set index ?value?: Sets the cell at index so that it displays the given value. If no value is specified, returns the value of the cell referenced by index.

pathName textselection clear
pathName textselection get
pathName textselection set index from to: If "clear" is specified, clears the current text selection. If "get" is specified, returns the range of characters that are currently in the text selection. If "set" is specified, sets the text selection to be from the from-th character, to the to-th character, in the cell referenced by index.

pathName trim: Causes rows to be trimmed from the bottom of the spreadsheet, if they contain no data and won't cause the spreadsheet to fall underneath the configured minimum number of rows.

pathName viewport: Returns the width and height, in pixels, of the part of the spreadsheet that is currently visible on the screen.

pathName width ?col? ?value ?col value...?
pathName width default

With no arguments, returns a list of columns and their widths, in pixels. Only those columns whose widths differ from the configured width are returned in the list.

With one col argument, returns the width of col, in pixels.

If at least one col value pair is specified, sets the width of each columm col to be value pixels wide.

pathName xview
pathName xview leftcol
pathName xview moveto fraction
pathName xview moveto number what

With no arguments, returns a list of two values: the fractional percentage of the entire screen width that represents the leftmost part of the screen, and the fractional percentage of the entire screen width representing the rightmost part of the screen.

With one argument, scrolls the screen so that leftcol is the (non-title) column at the far left of the screen.

For "moveto", makes it so that fraction is the fractional part of the screen that is offscreen to the left (rounding to the nearest spreadsheet non-title column boundary).

For "scroll", horizontally scrolls the page number pages or units. What is either "pages" or "units".

pathName yview
pathName yview toprow
pathName yview moveto fraction
pathName yview moveto number what

With no arguments, returns a list of two values: the fractional percentage of the entire screen width that represents the uppermost part of the screen, and the fractional percentage of the entire screen width representing the lowest part of the screen.

With one argument, scrolls the screen so that toprow is the (non-title) row at the top of the screen.

For "moveto", makes it so that fraction is the fractional part of the screen that is offscreen above the screen (rounding to the nearest spreadsheet non-title row boundary).

For "scroll", vertically scrolls the page number pages or units. What is either "pages" or "units".

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.

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

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

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

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

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

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

[9] Control-leftarrow and Control-rightarrow move the insertion cursor to the left most and rightmost index within the cell.

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

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

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

[13] Moving the mouse while Button-1 is pressed while you are over a border in the title row or the title column will cause interactive resizing of that row or column to occur.

[14] Pressing Tab will cause the active cell to move to the right.

[15] Pressing Shift-Tab will cause the active cell to move to the left.

[16] Pressing the Return key will cause the active cell to move downward.

[17] Pressing the PageDown or Next key will cause the widget to be scrolled down one page. The active cell is moved down one page as well.

[18] Pressing the PageUp or Prior key will cause the widget to be scrolled down one page. The active cell is moved down one page as well.

[19] Pressing most other keys will cause the character to be entered at the insertion position in the active cell.

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 the ss widget can be changed by defining new bindings for individual widgets, or by redefining the class bindings. The default bindings are contained in the ss.tcl file included in the distribution.

EXAMPLES

To create a simple spreadsheet widget:

  % ss .ss
  % .ss configure -rows 10 -cols 10 -variable ::v
  % pack .ss -expand 1 -fill both

To set the value at cell (1,1) to the string "foo":

  % set ::v(1,1) foo