tktable.table

The Table widget, a Python wrapper of the Tcl/Tk Tktable widget.

tktable.table.TableIndex

A table index: “row,col” (e.g. “2,3”), or a special one such as “active”, “anchor”, “end”, “origin”, “topleft”, “bottomright” or “@x,y” (the cell at pixel x,y).

tktable.table.RowCol: TypeAlias = int | str

A row or column number.

exception tktable.table.CannotUseError

Bases: RuntimeError

The exception raised when you cannot use the Table because of missing dependencies.

class tktable.table.TableEvent

Bases: Event

The event given to the callbacks of a Table (browsecommand, command, validatecommand, …).

Its attributes are Tktable’s %-substitutions.

r: int

The row of the cell.

c: int

The column of the cell.

C: str

The index of the cell, “r,c”.

i: int

1 if the cell is being written to, 0 if it is being read.

s: str

The current value of the cell.

S: str

The new value of the cell (e.g. what validatecommand should accept or reject).

W: Misc | None

The widget, if known.

class tktable.table.Table(master=None, **kw)

Bases: Widget

A table (spreadsheet-like) widget.

The keyword arguments are the options of the Tktable widget, without the leading “-”, e.g. Table(root, rows=10, cols=5, variable=array_var).

Raises:

CannotUseError – if Tktable cannot be loaded.

Parameters:

• master (Misc | None)

• kw (Any)

activate(index)

Set the active cell to the one indicated by index.

Parameters:

index (str)

Return type:

None

bbox(first, last=None)

Return 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 tuple is returned.

Parameters:

• first (str)

• last (str | None)

Return type:

tuple[int, …]

clear(option, first=None, last=None)

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

Parameters:

• option (str)

• first (str | None)

• last (str | None)

Return type:

None

clear_cache(first=None, last=None)

Clear the specified section of the cache, if the table has been keeping one.

Parameters:

• first (str | None)

• last (str | None)

Return type:

None

clear_sizes(first=None, last=None)

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

Parameters:

• first (str | None)

• last (str | None)

Return type:

None

clear_tags(first=None, last=None)

Clear the specified area of tags (all row, column and cell tags).

Parameters:

• first (str | None)

• last (str | None)

Return type:

None

clear_all(first=None, last=None)

Perform all of the above clear functions on the specified area.

Parameters:

• first (str | None)

• last (str | None)

Return type:

None

curselection(value=None)

With no arguments, it returns the sorted indices of the currently selected cells. Otherwise it sets all the selected cells to the given value if there is an associated ArrayVar and the state is not disabled.

Parameters:

value (str | None)

Return type:

Any

curvalue(value=None)

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.

Parameters:

value (str | None)

Return type:

Any

delete_active(index1, index2=None)

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.

Parameters:

• index1 (int | str)

• index2 (int | str | None)

Return type:

None

delete_cols(index, count=None, switches=None)

Delete count columns (1 by default) starting at column index.

Parameters:

• index (int | str)

• count (int | None)

• switches (tuple[str, ...] | None)

Return type:

None

delete_rows(index, count=None, switches=None)

Delete count rows (1 by default) starting at row index.

Parameters:

• index (int | str)

• count (int | None)

• switches (tuple[str, ...] | None)

Return type:

None

get(first, last=None)

Returns the value of the cells specified by the table indices first and (optionally) last.

Parameters:

• first (str)

• last (str | None)

Return type:

Any

height(row=None, **kwargs)

If row and kwargs are not given, a dict describing all rows for which a height has been set is returned. If row is given, the height of that row is returned. If kwargs is given, then it sets the key/value pairs, where key is a row and value represents the height for the row.

Parameters:

• row (int | str | None)

• kwargs (int)

Return type:

dict[str, str] | int | None

hidden(*args)

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.

Parameters:

args (str)

Return type:

Any

icursor(arg=None)

If arg is not specified, return the location of the insertion cursor in the active cell. Otherwise, set 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.

Parameters:

arg (int | str | None)

Return type:

Any

index(index, rc=None)

Return the integer cell coordinate that corresponds to index in the form row, col. If rc is specified, it must be either ‘row’ or ‘col’ so only the row or column index is returned.

Parameters:

• index (str)

• rc (str | None)

Return type:

Any

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.

Parameters:

• index (int | str)

• value (str)

Return type:

None

insert_cols(index, count=None, switches=None)

Insert count columns (1 by default) after column index.

Parameters:

• index (int | str)

• count (int | None)

• switches (tuple[str, ...] | None)

Return type:

None

insert_rows(index, count=None, switches=None)

Insert count rows (1 by default) after row index.

Parameters:

• index (int | str)

• count (int | None)

• switches (tuple[str, ...] | None)

Return type:

None

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

Return type:

None

scan_mark(x, y)

Record x and y and the current view, for a later scan_dragto().

Parameters:

• x (int)

• y (int)

Return type:

None

scan_dragto(x, y)

Scroll the view by 10 times the distance between x,y and the last scan_mark().

Parameters:

• x (int)

• y (int)

Return type:

None

see(index)

Scroll the view so that the cell index is visible.

Parameters:

index (str)

Return type:

None

selection_anchor(index)

Set the selection anchor to the cell index.

Parameters:

index (str)

Return type:

None

selection_clear(first, last=None)

Deselect the cells from first to last; first can be “all”.

Parameters:

• first (str)

• last (str | None)

Return type:

None

selection_includes(index)

Return whether the cell index is selected.

Parameters:

index (str)

Return type:

bool

selection_set(first, last=None)

Select the cells from first to last.

Parameters:

• first (str)

• last (str | None)

Return type:

None

set(*args, rc=None, index=None, **kwargs)

If rc is specified (either ‘row’ or ‘col’) then it is assumes that args (if given) represents values which will be set into the subsequent columns (if row is specified) or rows (for col). If index is not None and args is not given, then it will return the value(s) for the cell(s) specified.

If kwargs is given, assumes that each key in kwargs is a index in this table and sets the specified index to the associated value. Table validation will not be triggered via this method.

Note that the table must have an associated array (defined through the variable option) in order to this work.

Parameters:

• args (Any)

• rc (str | None)

• index (str | None)

• kwargs (Any)

Return type:

Any

spans(index=None, **kwargs)

Manipulate row/col spans.

When called with no arguments, all known spans are returned as a dict. When called with only the index, the span for that index only is returned, if any. Otherwise kwargs is assumed to contain keys/values pairs used to set spans. A span starts at the row,col defined by a key and continues for the specified number of rows,cols specified by its value. A span of 0,0 unsets any span on that cell.

Parameters:

• index (str | None)

• kwargs (str)

Return type:

Any

tag_cell(tagname, *args)

Apply the tag to the given cells, or return the cells with the tag.

Parameters:

• tagname (str)

• args (str)

Return type:

Any

tag_cget(tagname, option)

Return the value of the tag’s option (without the leading “-“).

Parameters:

• tagname (str)

• option (str)

Return type:

Any

tag_col(tagname, *args)

Apply the tag to the given columns, or return the columns with the tag.

Parameters:

• tagname (str)

• args (int | str)

Return type:

Any

tag_configure(tagname, option=None, **kwargs)

Query or modify options associated with the tag given by tagname.

If no option is specified, a dict describing all of the available options for tagname is returned. If option is specified, then the command returns a list describing the one named option. Lastly, if kwargs is given then it corresponds to option-value pairs that should be modified.

Parameters:

• tagname (str)

• option (str | None)

• kwargs (Any)

Return type:

Any

tag_delete(tagname)

Delete the tag.

Parameters:

tagname (str)

Return type:

None

tag_exists(tagname)

Return whether the tag exists.

Parameters:

tagname (str)

Return type:

bool

tag_includes(tagname, index)

Return whether the cell index has the tag.

Parameters:

• tagname (str)

• index (str)

Return type:

bool

tag_lower(tagname, belowthis=None)

Lower the tag’s priority below the tag belowthis, or to the lowest.

Parameters:

• tagname (str)

• belowthis (str | None)

Return type:

None

tag_names(pattern=None)

Return the names of the tags, optionally only those matching pattern.

Parameters:

pattern (str | None)

Return type:

Any

tag_raise(tagname, abovethis=None)

Raise the tag’s priority above the tag abovethis, or to the highest.

Parameters:

• tagname (str)

• abovethis (str | None)

Return type:

None

tag_row(tagname, *args)

Apply the tag to the given rows, or return the rows with the tag.

Parameters:

• tagname (str)

• args (int | str)

Return type:

Any

validate(index)

Explicitly validates the specified index based on the current callback set for the validatecommand option. Return 0 or 1 based on whether the cell was validated.

Parameters:

index (str)

Return type:

Any

property version: Any

Return tktable’s package version.

width(column=None, **kwargs)

If column and kwargs are not given, a dict describing all columns for which a width has been set is returned. If column is given, the width of that column is returned. If kwargs is given, then it sets the key/value pairs, where key is a column and value represents the width for the column.

Parameters:

• column (int | str | None)

• kwargs (int)

Return type:

dict[str, str] | int | None

window_cget(index, option)

Return the value of the option of the embedded window at index.

Parameters:

• index (str)

• option (str)

Return type:

Any

window_configure(index, option=None, **kwargs)

Query or modify options associated with the embedded window given by index. This should also be used to add a new embedded window into the table.

If no option is specified, a dict describing all of the available options for index is returned. If option is specified, then the command returns a list describing the one named option. Lastly, if kwargs is given then it corresponds to option-value pairs that should be modified.

Parameters:

• index (str)

• option (str | None)

• kwargs (Any)

Return type:

Any

window_delete(*indexes)

Remove the embedded windows at the given indexes.

Parameters:

indexes (str)

Return type:

None

window_move(index_from, index_to)

Move the embedded window at index_from to index_to.

Parameters:

• index_from (str)

• index_to (str)

Return type:

None

window_names(pattern=None)

Return the indexes of the embedded windows, optionally only those matching pattern.

Parameters:

pattern (str | None)

Return type:

Any

xview(index=None)

If index is not given a tuple containing two fractions is returned, each fraction is between 0 and 1. Together they describe the horizontal span that is visible in the window.

If index is given the view in the window is adjusted so that the column given by index is displayed at the left edge of the window.

Parameters:

index (int | str | None)

Return type:

tuple[float, …] | None

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. The fraction parameter must be a fraction between 0 and 1.

Parameters:

fraction (float)

Return type:

None

xview_scroll(*L)

Shift the view in the window left or right according to number and what. The ‘number’ parameter must be an integer. The ‘what’ parameter 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.

Parameters:

L (Any)

Return type:

None

yview(index=None)

If index is not given a tuple containing two fractions is returned, each fraction is 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. 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.

If index is given the view in the window is adjusted so that the row given by index is displayed at the top of the window.

Parameters:

index (int | str | None)

Return type:

tuple[float, …] | None

yview_moveto(fraction)

Adjusts the view in the window so that the element given by fraction appears at the top of the window. The fraction parameter must be a fraction between 0 and 1.

Parameters:

fraction (float)

Return type:

None

yview_scroll(*L)

Adjust the view in the window up or down according to number and what. The ‘number’ parameter must be an integer. The ‘what’ parameter must be either units or pages or an abbreviation of one of these.

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.

Parameters:

L (Any)

Return type:

None

tktable.table.TableCallback

The type of a Table callback, e.g. for browsecommand or validatecommand.

alias of Callable[[TableEvent], Any]