• About tksheet
• Installation and Requirements
• Basic Initialization
• Usage Examples
• Initialization Options

• Sheet Appearance
• Alternate Row Colors
• Header and Index

• Bindings and Functionality
• tkinter and tksheet Events
• Sheet Languages and Bindings

• Span Objects
• Named Spans

• Getting Sheet Data
• Setting Sheet Data

• Highlighting Cells
• Dropdown Boxes
• Check Boxes
• Data Formatting
• Readonly Cells
• Text Font and Alignment
• Getting Cell Properties

• Getting Selected Cells
• Modifying Selected Cells
• Row Heights and Column Widths
• Identifying Bound Event Mouse Position
• Scroll Positions and Cell Visibility

• Hiding Columns
• Hiding Rows
• Hiding Sheet Elements
• Sheet Height and Width

• Cell Text Editor
• Sheet Options and Other Functions

• Treeview Mode
• Progress Bars
• Tags

• Example Loading Data from Excel
• Example Custom Right Click and Text Editor Validation
• Example Displaying Selections
• Example List Box
• Example Header Dropdown Boxes and Row Filtering
• Example ReadMe Screenshot Code
• Example Saving tksheet as a csv File
• Example Using and Creating Formatters
• Contributing

• tksheet is a Python tkinter table widget written in pure python.
• It is licensed under the MIT license.
• It works by using tkinter canvases and moving lines, text and rectangles around for only the visible portion of the table.
• If you are using a version of tksheet that is older than 7.0.0 then you will need the documentation here instead.
  • In tksheet versions >= 7.0.2 the current version will be at the top of the file __init__.py.

Some examples of things that are not possible with tksheet:

• Cell merging
• Cell text wrap
• Changing font for individual cells
• Different fonts for index and table
• Mouse drag copy cells
• Cell highlight borders
• At the present time the type hinting in tksheet is only meant to serve as a guide and not to be used with type checkers.

tksheet is available through PyPi (Python package index) and can be installed by using Pip through the command line pip install tksheet

#To install using pip
pip install tksheet

#To update using pip
pip install tksheet --upgrade

Alternatively you can download the source code and inside the tksheet directory where the pyproject.toml file is located use the command line pip install -e .

• Versions < 7.0.0 require a Python version of 3.7 or higher.
• Versions >= 7.0.0 require a Python version of 3.8 or higher.

Like other tkinter widgets you need only the Sheet()s parent as an argument to initialize a Sheet() e.g.

sheet = Sheet(my_frame_widget)

• my_frame_widget would be replaced by whatever widget is your Sheet()s parent.

As an example, this is a tkinter program involving a Sheet() widget

from tksheet import Sheet
import tkinter as tk


class demo(tk.Tk):
    def __init__(self):
        tk.Tk.__init__(self)
        self.grid_columnconfigure(0, weight = 1)
        self.grid_rowconfigure(0, weight = 1)
        self.frame = tk.Frame(self)
        self.frame.grid_columnconfigure(0, weight = 1)
        self.frame.grid_rowconfigure(0, weight = 1)
        self.sheet = Sheet(self.frame,
                           data = [[f"Row {r}, Column {c}\nnewline1\nnewline2" for c in range(50)] for r in range(500)])
        self.sheet.enable_bindings()
        self.frame.grid(row = 0, column = 0, sticky = "nswe")
        self.sheet.grid(row = 0, column = 0, sticky = "nswe")


app = demo()
app.mainloop()

This is to demonstrate some of tksheets functionality.

• The functions which return the Sheet itself (have -> Sheet) can be chained with other Sheet functions.
• The functions which return a Span (have -> Span) can be chained with other Span functions.

from tksheet import Sheet, num2alpha
import tkinter as tk


class demo(tk.Tk):
    def __init__(self):
        tk.Tk.__init__(self)
        self.grid_columnconfigure(0, weight=1)
        self.grid_rowconfigure(0, weight=1)
        self.frame = tk.Frame(self)
        self.frame.grid_columnconfigure(0, weight=1)
        self.frame.grid_rowconfigure(0, weight=1)

        # create an instance of Sheet()
        self.sheet = Sheet(
            # set the Sheets parent widget
            self.frame,
            # optional: set the Sheets data at initialization
            data=[[f"Row {r}, Column {c}\nnewline1\nnewline2" for c in range(20)] for r in range(100)],
            theme="light green",
            height=520,
            width=1000,
        )
        # enable various bindings
        self.sheet.enable_bindings("all", "edit_index", "edit_header")

        # set a user edit validation function
        # AND bind all sheet modification events to a function
        # chained as two functions
        # more information at:
        # https://github.com/ragardner/tksheet/wiki/Version-7#validate-user-cell-edits
        self.sheet.edit_validation(self.validate_edits).bind("<<SheetModified>>", self.sheet_modified)

        # add some new commands to the in-built right click menu
        # setting data
        self.sheet.popup_menu_add_command(
            "Say Hello",
            self.say_hello,
            index_menu=False,
            header_menu=False,
            empty_space_menu=False,
        )
        # getting data
        self.sheet.popup_menu_add_command(
            "Print some data",
            self.print_data,
            empty_space_menu=False,
        )
        # overwrite Sheet data
        self.sheet.popup_menu_add_command("Reset Sheet data", self.reset)
        # set the header
        self.sheet.popup_menu_add_command(
            "Set header data",
            self.set_header,
            table_menu=False,
            index_menu=False,
            empty_space_menu=False,
        )
        # set the index
        self.sheet.popup_menu_add_command(
            "Set index data",
            self.set_index,
            table_menu=False,
            header_menu=False,
            empty_space_menu=False,
        )

        self.frame.grid(row=0, column=0, sticky="nswe")
        self.sheet.grid(row=0, column=0, sticky="nswe")

    def validate_edits(self, event):
        # print (event)
        if event.eventname.endswith("header"):
            return event.value + " edited header"
        elif event.eventname.endswith("index"):
            return event.value + " edited index"
        else:
            if not event.value:
                return "EMPTY"
            return event.value[:3]

    def say_hello(self):
        current_selection = self.sheet.get_currently_selected()
        if current_selection:
            box = (current_selection.row, current_selection.column)
            # set cell data, end user Undo enabled
            # more information at:
            # https://github.com/ragardner/tksheet/wiki/Version-7#setting-sheet-data
            self.sheet[box].options(undo=True).data = "Hello World!"
            # highlight the cell for 2 seconds
            self.highlight_area(box)

    def print_data(self):
        for box in self.sheet.get_all_selection_boxes():
            # get user selected area sheet data
            # more information at:
            # https://github.com/ragardner/tksheet/wiki/Version-7#getting-sheet-data
            data = self.sheet[box].data
            for row in data:
                print(row)

    def reset(self):
        # overwrites sheet data, more information at:
        # https://github.com/ragardner/tksheet/wiki/Version-7#setting-sheet-data
        self.sheet.set_sheet_data([[f"Row {r}, Column {c}\nnewline1\nnewline2" for c in range(20)] for r in range(100)])
        # reset header and index
        self.sheet.headers([])
        self.sheet.index([])

    def set_header(self):
        self.sheet.headers(
            [f"Header {(letter := num2alpha(i))} - {i + 1}\nHeader {letter} 2nd line!" for i in range(20)]
        )

    def set_index(self):
        self.sheet.set_index_width()
        self.sheet.row_index(
            [f"Index {(letter := num2alpha(i))} - {i + 1}\nIndex {letter} 2nd line!" for i in range(100)]
        )

    def sheet_modified(self, event):
        # uncomment below if you want to take a look at the event object
        # print ("The sheet was modified! Event object:")
        # for k, v in event.items():
        #     print (k, ":", v)
        # print ("\n")

        # otherwise more information at:
        # https://github.com/ragardner/tksheet/wiki/Version-7#event-data

        # highlight the modified cells briefly
        if event.eventname.startswith("move"):
            for box in self.sheet.get_all_selection_boxes():
                self.highlight_area(box)
        else:
            for box in event.selection_boxes:
                self.highlight_area(box)

    def highlight_area(self, box, time=800):
        # highlighting an area of the sheet
        # more information at:
        # https://github.com/ragardner/tksheet/wiki/Version-7#highlighting-cells
        self.sheet[box].bg = "indianred1"
        self.after(time, lambda: self.clear_highlight(box))

    def clear_highlight(self, box):
        self.sheet[box].dehighlight()


app = demo()
app.mainloop()

These are all the initialization parameters, the only required argument is the sheets parent, every other parameter has default arguments.

def __init__(
    parent: tk.Misc,
    name: str = "!sheet",
    show_table: bool = True,
    show_top_left: bool = True,
    show_row_index: bool = True,
    show_header: bool = True,
    show_x_scrollbar: bool = True,
    show_y_scrollbar: bool = True,
    width: int | None = None,
    height: int | None = None,
    headers: None | list[object] = None,
    header: None | list[object] = None,
    row_index: None | list[object] = None,
    index: None | list[object] = None,
    default_header: Literal["letters", "numbers", "both"] | None = "letters",
    default_row_index: Literal["letters", "numbers", "both"] | None = "numbers",
    data_reference: None | Sequence[Sequence[object]] = None,
    data: None | Sequence[Sequence[object]] = None,
    # either (start row, end row, "rows"), (start column, end column, "rows") or
    # (cells start row, cells start column, cells end row, cells end column, "cells")  # noqa: E501
    startup_select: tuple[int, int, str] | tuple[int, int, int, int, str] = None,
    startup_focus: bool = True,
    total_columns: int | None = None,
    total_rows: int | None = None,
    default_column_width: int = 120,
    default_header_height: str | int = "1",
    default_row_index_width: int = 70,
    default_row_height: str | int = "1",
    min_column_width: int = 1,
    max_column_width: float = float("inf"),
    max_row_height: float = float("inf"),
    max_header_height: float = float("inf"),
    max_index_width: float = float("inf"),
    after_redraw_time_ms: int = 20,
    set_all_heights_and_widths: bool = False,
    zoom: int = 100,
    align: str = "w",
    header_align: str = "center",
    row_index_align: str | None = None,
    index_align: str = "center",
    displayed_columns: list[int] = [],
    all_columns_displayed: bool = True,
    displayed_rows: list[int] = [],
    all_rows_displayed: bool = True,
    to_clipboard_delimiter: str = "\t",
    to_clipboard_quotechar: str = '"',
    to_clipboard_lineterminator: str = "\n",
    from_clipboard_delimiters: list[str] | str = ["\t"],
    show_default_header_for_empty: bool = True,
    show_default_index_for_empty: bool = True,
    page_up_down_select_row: bool = True,
    paste_can_expand_x: bool = False,
    paste_can_expand_y: bool = False,
    paste_insert_column_limit: int | None = None,
    paste_insert_row_limit: int | None = None,
    show_dropdown_borders: bool = False,
    arrow_key_down_right_scroll_page: bool = False,
    cell_auto_resize_enabled: bool = True,
    auto_resize_row_index: bool | Literal["empty"] = "empty",
    auto_resize_columns: int | None = None,
    auto_resize_rows: int | None = None,
    set_cell_sizes_on_zoom: bool = False,
    font: tuple[str, int, str] = FontTuple(
        "Calibri",
        13 if USER_OS == "darwin" else 11,
        "normal",
    ),
    header_font: tuple[str, int, str] = FontTuple(
        "Calibri",
        13 if USER_OS == "darwin" else 11,
        "normal",
    ),
    index_font: tuple[str, int, str] = FontTuple(
        "Calibri",
        13 if USER_OS == "darwin" else 11,
        "normal",
    ),  # currently has no effect
    popup_menu_font: tuple[str, int, str] = FontTuple(
        "Calibri",
        13 if USER_OS == "darwin" else 11,
        "normal",
    ),
    max_undos: int = 30,
    column_drag_and_drop_perform: bool = True,
    row_drag_and_drop_perform: bool = True,
    empty_horizontal: int = 50,
    empty_vertical: int = 50,
    selected_rows_to_end_of_window: bool = False,
    horizontal_grid_to_end_of_window: bool = False,
    vertical_grid_to_end_of_window: bool = False,
    show_vertical_grid: bool = True,
    show_horizontal_grid: bool = True,
    display_selected_fg_over_highlights: bool = False,
    show_selected_cells_border: bool = True,
    edit_cell_tab: Literal["right", "down", ""] = "right",
    edit_cell_return: Literal["right", "down", ""] = "down",
    editor_del_key: Literal["forward", "backward", ""] = "forward",
    treeview: bool = False,
    treeview_indent: str | int = "5",
    rounded_boxes: bool = True,
    alternate_color: str = "",
    # colors
    outline_thickness: int = 0,
    outline_color: str = theme_light_blue["outline_color"],
    theme: str = "light blue",
    frame_bg: str = theme_light_blue["table_bg"],
    popup_menu_fg: str = theme_light_blue["popup_menu_fg"],
    popup_menu_bg: str = theme_light_blue["popup_menu_bg"],
    popup_menu_highlight_bg: str = theme_light_blue["popup_menu_highlight_bg"],
    popup_menu_highlight_fg: str = theme_light_blue["popup_menu_highlight_fg"],
    table_grid_fg: str = theme_light_blue["table_grid_fg"],
    table_bg: str = theme_light_blue["table_bg"],
    table_fg: str = theme_light_blue["table_fg"],
    table_editor_bg: str = theme_light_blue["table_editor_bg"],
    table_editor_fg: str = theme_light_blue["table_editor_fg"],
    table_editor_select_bg: str = theme_light_blue["table_editor_select_bg"],
    table_editor_select_fg: str = theme_light_blue["table_editor_select_fg"],
    table_selected_box_cells_fg: str = theme_light_blue["table_selected_box_cells_fg"],
    table_selected_box_rows_fg: str = theme_light_blue["table_selected_box_rows_fg"],
    table_selected_box_columns_fg: str = theme_light_blue["table_selected_box_columns_fg"],
    table_selected_cells_border_fg: str = theme_light_blue["table_selected_cells_border_fg"],
    table_selected_cells_bg: str = theme_light_blue["table_selected_cells_bg"],
    table_selected_cells_fg: str = theme_light_blue["table_selected_cells_fg"],
    table_selected_rows_border_fg: str = theme_light_blue["table_selected_rows_border_fg"],
    table_selected_rows_bg: str = theme_light_blue["table_selected_rows_bg"],
    table_selected_rows_fg: str = theme_light_blue["table_selected_rows_fg"],
    table_selected_columns_border_fg: str = theme_light_blue["table_selected_columns_border_fg"],
    table_selected_columns_bg: str = theme_light_blue["table_selected_columns_bg"],
    table_selected_columns_fg: str = theme_light_blue["table_selected_columns_fg"],
    resizing_line_fg: str = theme_light_blue["resizing_line_fg"],
    drag_and_drop_bg: str = theme_light_blue["drag_and_drop_bg"],
    index_bg: str = theme_light_blue["index_bg"],
    index_border_fg: str = theme_light_blue["index_border_fg"],
    index_grid_fg: str = theme_light_blue["index_grid_fg"],
    index_fg: str = theme_light_blue["index_fg"],
    index_editor_bg: str = theme_light_blue["index_editor_bg"],
    index_editor_fg: str = theme_light_blue["index_editor_fg"],
    index_editor_select_bg: str = theme_light_blue["index_editor_select_bg"],
    index_editor_select_fg: str = theme_light_blue["index_editor_select_fg"],
    index_selected_cells_bg: str = theme_light_blue["index_selected_cells_bg"],
    index_selected_cells_fg: str = theme_light_blue["index_selected_cells_fg"],
    index_selected_rows_bg: str = theme_light_blue["index_selected_rows_bg"],
    index_selected_rows_fg: str = theme_light_blue["index_selected_rows_fg"],
    index_hidden_rows_expander_bg: str = theme_light_blue["index_hidden_rows_expander_bg"],
    header_bg: str = theme_light_blue["header_bg"],
    header_border_fg: str = theme_light_blue["header_border_fg"],
    header_grid_fg: str = theme_light_blue["header_grid_fg"],
    header_fg: str = theme_light_blue["header_fg"],
    header_editor_bg: str = theme_light_blue["header_editor_bg"],
    header_editor_fg: str = theme_light_blue["header_editor_fg"],
    header_editor_select_bg: str = theme_light_blue["header_editor_select_bg"],
    header_editor_select_fg: str = theme_light_blue["header_editor_select_fg"],
    header_selected_cells_bg: str = theme_light_blue["header_selected_cells_bg"],
    header_selected_cells_fg: str = theme_light_blue["header_selected_cells_fg"],
    header_selected_columns_bg: str = theme_light_blue["header_selected_columns_bg"],
    header_selected_columns_fg: str = theme_light_blue["header_selected_columns_fg"],
    header_hidden_columns_expander_bg: str = theme_light_blue["header_hidden_columns_expander_bg"],
    top_left_bg: str = theme_light_blue["top_left_bg"],
    top_left_fg: str = theme_light_blue["top_left_fg"],
    top_left_fg_highlight: str = theme_light_blue["top_left_fg_highlight"],
    vertical_scroll_background: str = theme_light_blue["vertical_scroll_background"],
    horizontal_scroll_background: str = theme_light_blue["horizontal_scroll_background"],
    vertical_scroll_troughcolor: str = theme_light_blue["vertical_scroll_troughcolor"],
    horizontal_scroll_troughcolor: str = theme_light_blue["horizontal_scroll_troughcolor"],
    vertical_scroll_lightcolor: str = theme_light_blue["vertical_scroll_lightcolor"],
    horizontal_scroll_lightcolor: str = theme_light_blue["horizontal_scroll_lightcolor"],
    vertical_scroll_darkcolor: str = theme_light_blue["vertical_scroll_darkcolor"],
    horizontal_scroll_darkcolor: str = theme_light_blue["horizontal_scroll_darkcolor"],
    vertical_scroll_relief: str = theme_light_blue["vertical_scroll_relief"],
    horizontal_scroll_relief: str = theme_light_blue["horizontal_scroll_relief"],
    vertical_scroll_troughrelief: str = theme_light_blue["vertical_scroll_troughrelief"],
    horizontal_scroll_troughrelief: str = theme_light_blue["horizontal_scroll_troughrelief"],
    vertical_scroll_bordercolor: str = theme_light_blue["vertical_scroll_bordercolor"],
    horizontal_scroll_bordercolor: str = theme_light_blue["horizontal_scroll_bordercolor"],
    vertical_scroll_borderwidth: int = 1,
    horizontal_scroll_borderwidth: int = 1,
    vertical_scroll_gripcount: int = 0,
    horizontal_scroll_gripcount: int = 0,
    vertical_scroll_active_bg: str = theme_light_blue["vertical_scroll_active_bg"],
    horizontal_scroll_active_bg: str = theme_light_blue["horizontal_scroll_active_bg"],
    vertical_scroll_not_active_bg: str = theme_light_blue["vertical_scroll_not_active_bg"],
    horizontal_scroll_not_active_bg: str = theme_light_blue["horizontal_scroll_not_active_bg"],
    vertical_scroll_pressed_bg: str = theme_light_blue["vertical_scroll_pressed_bg"],
    horizontal_scroll_pressed_bg: str = theme_light_blue["horizontal_scroll_pressed_bg"],
    vertical_scroll_active_fg: str = theme_light_blue["vertical_scroll_active_fg"],
    horizontal_scroll_active_fg: str = theme_light_blue["horizontal_scroll_active_fg"],
    vertical_scroll_not_active_fg: str = theme_light_blue["vertical_scroll_not_active_fg"],
    horizontal_scroll_not_active_fg: str = theme_light_blue["horizontal_scroll_not_active_fg"],
    vertical_scroll_pressed_fg: str = theme_light_blue["vertical_scroll_pressed_fg"],
    horizontal_scroll_pressed_fg: str = theme_light_blue["horizontal_scroll_pressed_fg"],
    scrollbar_theme_inheritance: str = "default",
    scrollbar_show_arrows: bool = True,
    # changing the arrowsize (width) of the scrollbars
    # is not working with 'default' theme
    # use 'clam' theme instead if you want to change the width
    vertical_scroll_arrowsize: str | int = "",
    horizontal_scroll_arrowsize: str | int = "",
) -> None

• name setting a name for the sheet is useful when you have multiple sheets and you need to determine which one an event came from.
• auto_resize_columns (int, None) if set as an int the columns will automatically resize to fit the width of the window, the int value being the minimum of each column in pixels.
• auto_resize_rows (int, None) if set as an int the rows will automatically resize to fit the height of the window, the int value being the minimum height of each row in pixels.
• startup_select selects cells, rows or columns at initialization by using a tuple e.g. (0, 0, "cells") for cell A0 or (0, 5, "rows") for rows 0 to 5.
• data_reference and data are essentially the same.
• row_index and index are the same, index takes priority, same as with headers and header.
• startup_select either (start row, end row, "rows"), (start column, end column, "rows") or (start row, start column, end row, end column, "cells"). The start/end row/column variables need to be ints.
• auto_resize_row_index either True, False or "empty".
  • "empty" it will only automatically resize if the row index is empty.
  • True it will always automatically resize.
  • False it will never automatically resize.
• If show_selected_cells_border is False then the colors for table_selected_box_cells_fg/table_selected_box_rows_fg/table_selected_box_columns_fg will be used for the currently selected cells background.
• For help with treeview mode see here.

You can change most of these settings after initialization using the set_options() function.

• scrollbar_theme_inheritance and scrollbar_show_arrows will only work on Sheet() initialization, not with set_options()

To change the colors of individual cells, rows or columns use the functions listed under highlighting cells.

For the colors of specific parts of the table such as gridlines and backgrounds use the function set_options(), keyword arguments specific to sheet colors are listed below. All the other set_options() arguments can be found here.

Use a tkinter color or a hex string e.g.

my_sheet_widget.set_options(table_bg="black")
my_sheet_widget.set_options(table_bg="#000000")
my_sheet_widget.set_options(horizontal_scroll_pressed_bg="red")

set_options(
top_left_bg
top_left_fg
top_left_fg_highlight

table_bg
table_grid_fg
table_fg
table_selected_box_cells_fg
table_selected_box_rows_fg
table_selected_box_columns_fg
table_selected_cells_border_fg
table_selected_cells_bg
table_selected_cells_fg
table_selected_rows_border_fg
table_selected_rows_bg
table_selected_rows_fg
table_selected_columns_border_fg
table_selected_columns_bg
table_selected_columns_fg

header_bg
header_border_fg
header_grid_fg
header_fg
header_selected_cells_bg
header_selected_cells_fg
header_selected_columns_bg
header_selected_columns_fg

index_bg
index_border_fg
index_grid_fg
index_fg
index_selected_cells_bg
index_selected_cells_fg
index_selected_rows_bg
index_selected_rows_fg

resizing_line_fg
drag_and_drop_bg
outline_thickness
outline_color
frame_bg
popup_menu_font
popup_menu_fg
popup_menu_bg
popup_menu_highlight_bg
popup_menu_highlight_fg

# scroll bars
vertical_scroll_background
horizontal_scroll_background
vertical_scroll_troughcolor
horizontal_scroll_troughcolor
vertical_scroll_lightcolor
horizontal_scroll_lightcolor
vertical_scroll_darkcolor
horizontal_scroll_darkcolor
vertical_scroll_bordercolor
horizontal_scroll_bordercolor
vertical_scroll_active_bg
horizontal_scroll_active_bg
vertical_scroll_not_active_bg
horizontal_scroll_not_active_bg
vertical_scroll_pressed_bg
horizontal_scroll_pressed_bg
vertical_scroll_active_fg
horizontal_scroll_active_fg
vertical_scroll_not_active_fg
horizontal_scroll_not_active_fg
vertical_scroll_pressed_fg
horizontal_scroll_pressed_fg
)

Otherwise you can change the theme using the below function.

change_theme(theme: str = "light blue", redraw: bool = True) -> Sheet

• theme (str) options (themes) are currently "light blue", "light green", "dark", "black", "dark blue" and "dark green".

Scrollbar colors:

The above function and keyword arguments can be used to change the colors of the scroll bars.

Scrollbar relief, size, arrows, etc.

Some scroll bar style options can only be changed on Sheet() initialization, others can be changed whenever using set_options().

• Options that can only be set in the = Sheet(...) initialization:
  • scrollbar_theme_inheritance: str = "default"
    • This is which tkinter theme to inherit the new style from, changing the width of the scroll bar might not work with the "default" theme. If this is the case try using "clam" instead.
  • scrollbar_show_arrows: bool
    • When False the scroll bars arrow buttons on either end will be hidden, this may effect the width of the scroll bar.
• Options that can be set using set_options() also:
  • vertical_scroll_borderwidth: int
  • horizontal_scroll_borderwidth: int
  • vertical_scroll_gripcount: int
  • horizontal_scroll_gripcount: int
  • vertical_scroll_arrowsize: str | int
  • horizontal_scroll_arrowsize: str | int

For basic alternate row colors in the main table either:

• Use the Sheet() initialization keyword argument alternate_color (str) or
• Use the set_options() function with the keyword argument alternate_color

Examples:

set_options(alternate_color="#E2EAF4")

my_sheet = Sheet(parent, alternate_color="gray80")

Note that any cell, row or column highlights will display over alternate row colors.

set_header_data(value: object, c: int | None | Iterator = None, redraw: bool = True) -> Sheet

• value (iterable, int, Any) if c is left as None then it attempts to set the whole header as the value (converting a generator to a list). If value is int it sets the header to display the row with that position.
• c (iterable, int, None) if both value and c are iterables it assumes c is an iterable of positions and value is an iterable of values and attempts to set each value to each position. If c is int it attempts to set the value at that position.

headers(
    newheaders: object = None,
    index: None | int = None,
    reset_col_positions: bool = False,
    show_headers_if_not_sheet: bool = True,
    redraw: bool = True,
) -> object

• Using an integer int for argument newheaders makes the sheet use that row as a header e.g. headers(0) means the first row will be used as a header (the first row will not be hidden in the sheet though), this is sort of equivalent to freezing the row.
• Leaving newheaders as None and using the index argument returns the existing header value in that index.
• Leaving all arguments as default e.g. headers() returns existing headers.

set_index_data(value: object, r: int | None | Iterator = None, redraw: bool = True) -> Sheet

• value (iterable, int, Any) if r is left as None then it attempts to set the whole index as the value (converting a generator to a list). If value is int it sets the index to display the row with that position.
• r (iterable, int, None) if both value and r are iterables it assumes r is an iterable of positions and value is an iterable of values and attempts to set each value to each position. If r is int it attempts to set the value at that position.

row_index(
    newindex: object = None,
    index: None | int = None,
    reset_row_positions: bool = False,
    show_index_if_not_sheet: bool = True,
    redraw: bool = True,
) -> object

• Using an integer int for argument newindex makes the sheet use that column as an index e.g. row_index(0) means the first column will be used as an index (the first column will not be hidden in the sheet though), this is sort of equivalent to freezing the column.
• Leaving newindex as None and using the index argument returns the existing row index value in that index.
• Leaving all arguments as default e.g. row_index() returns the existing row index.

enable_bindings(*bindings)

• bindings (str) options are (rc stands for right click):
  • "all"
  • "single_select"
  • "toggle_select"
  • "drag_select"
    • "select_all"
  • "column_drag_and_drop" / "move_columns"
  • "row_drag_and_drop" / "move_rows"
  • "column_select"
  • "row_select"
  • "column_width_resize"
  • "double_click_column_resize"
  • "row_width_resize"
  • "column_height_resize"
  • "arrowkeys" # all arrowkeys including page up and down
  • "up"
  • "down"
  • "left"
  • "right"
  • "prior" # page up
  • "next" # page down
  • "row_height_resize"
  • "double_click_row_resize"
  • "right_click_popup_menu" / "rc_popup_menu" / "rc_menu"
  • "rc_select"
  • "rc_insert_column"
  • "rc_delete_column"
  • "rc_insert_row"
  • "rc_delete_row"
  • "ctrl_click_select" / "ctrl_select"
  • "copy"
  • "cut"
  • "paste"
  • "delete"
  • "undo"
  • "edit_cell"
  • "edit_header"
  • "edit_index"

Notes:

• You can change the Sheets key bindings for functionality such as copy, paste, up, down etc. Instructions can be found here.
• Control selection is NOT enabled with "all" and has to be specifically enabled.
• Header cell editing is NOT enabled with "all" and has to be specifically enabled.
• Index cell editing is NOT enabled with "all" and has to be specifically enabled.
• To allow table expansion when pasting data which doesn't fit in the table use either:
  • paste_can_expand_x=True, paste_can_expand_y=True in sheet initialization arguments or the same keyword arguments with the function set_options().

Example:

• sheet.enable_bindings() to enable absolutely everything.

disable_bindings(*bindings)

Notes:

• Uses the same arguments as enable_bindings().

This function allows you to bind very specific table functionality to your own functions.

• If you want less specificity in event names you can also bind all sheet modifying events to a single function, see here.
• If you want to validate/modify user cell edits see here.

extra_bindings(
    bindings: str | list | tuple,
    func: Callable | None = None,
) -> Sheet

Notes:

• There are several ways to use this function:
  • bindings as a str and func as either None or a function. Using None as an argument for func will effectively unbind the function.
    • extra_bindings("edit_cell", func=my_function)
  • bindings as an iterable of strs and func as either None or a function. Using None as an argument for func will effectively unbind the function.
    • extra_bindings(["all_select_events", "copy", "cut"], func=my_function)
  • bindings as an iterable of lists or tuples with length of two, e.g.
    • extra_bindings([(binding, function), (binding, function), ...]) In this example you could also use None in the place of function to unbind the binding.
    • In this case the arg func is totally ignored.
• For "end_..." events the bound function is run before the value is set.
• To unbind a function either set func argument to None or leave it as default e.g. extra_bindings("begin_copy") to unbind "begin_copy".

Parameters:

• bindings (str) options are:
  • "begin_copy", "begin_ctrl_c"
  • "ctrl_c", "end_copy", "end_ctrl_c", "copy"
  • "begin_cut", "begin_ctrl_x"
  • "ctrl_x", "end_cut", "end_ctrl_x", "cut"
  • "begin_paste", "begin_ctrl_v"
  • "ctrl_v", "end_paste", "end_ctrl_v", "paste"
  • "begin_undo", "begin_ctrl_z"
  • "ctrl_z", "end_undo", "end_ctrl_z", "undo"
  • "begin_delete_key", "begin_delete"
  • "delete_key", "end_delete", "end_delete_key", "delete"
  • "begin_edit_cell", "begin_edit_table"
  • "end_edit_cell", "edit_cell", "edit_table"
  • "begin_edit_header"
  • "end_edit_header", "edit_header"
  • "begin_edit_index"
  • "end_edit_index", "edit_index"
  • "begin_row_index_drag_drop", "begin_move_rows"
  • "row_index_drag_drop", "move_rows", "end_move_rows", "end_row_index_drag_drop"
  • "begin_column_header_drag_drop", "begin_move_columns"
  • "column_header_drag_drop", "move_columns", "end_move_columns", "end_column_header_drag_drop"
  • "begin_rc_delete_row", "begin_delete_rows"
  • "rc_delete_row", "end_rc_delete_row", "end_delete_rows", "delete_rows"
  • "begin_rc_delete_column", "begin_delete_columns"
  • "rc_delete_column", "end_rc_delete_column","end_delete_columns", "delete_columns"
  • "begin_rc_insert_column", "begin_insert_column", "begin_insert_columns", "begin_add_column","begin_rc_add_column", "begin_add_columns"
  • "rc_insert_column", "end_rc_insert_column", "end_insert_column", "end_insert_columns", "rc_add_column", "end_rc_add_column", "end_add_column", "end_add_columns"
  • "begin_rc_insert_row", "begin_insert_row", "begin_insert_rows", "begin_rc_add_row", "begin_add_row", "begin_add_rows"
  • "rc_insert_row", "end_rc_insert_row", "end_insert_row", "end_insert_rows", "rc_add_row", "end_rc_add_row", "end_add_row", "end_add_rows"
  • "row_height_resize"
  • "column_width_resize"
  • "cell_select"
  • "select_all"
  • "row_select"
  • "column_select"
  • "drag_select_cells"
  • "drag_select_rows"
  • "drag_select_columns"
  • "shift_cell_select"
  • "shift_row_select"
  • "shift_column_select"
  • "ctrl_cell_select"
  • "ctrl_row_select"
  • "ctrl_column_select"
  • "deselect"
  • "all_select_events", "select", "selectevents", "select_events"
  • "all_modified_events", "sheetmodified", "sheet_modified" "modified_events", "modified"
  • "bind_all"
  • "unbind_all"
• func argument is the function you want to send the binding event to.
• Using one of the following "all_modified_events", "sheetmodified", "sheet_modified", "modified_events", "modified" will make any insert, delete or cell edit including pastes and undos send an event to your function.
• For events "begin_move_columns"/"begin_move_rows" the point where columns/rows will be moved to will be accessible by the key named "value".
• For "begin_edit..." events the bound function must return a value to open the cell editor with, example here.

Using extra_bindings() the function you bind needs to have at least one argument which will receive a dict. The values of which can be accessed by dot notation e.g. event.eventname or event.cells.table:

for (row, column), old_value in event.cells.table.items():
    print (f"R{row}", f"C{column}", "Old Value:", old_value)

It has the following layout and keys:

{
    "eventname": "",
    "sheetname": "",
    "cells": {
        "table": {},
        "header": {},
        "index": {},
    },
    "moved": {
        "rows": {},
        "columns": {},
    },
    "added": {
        "rows": {},
        "columns": {},
    },
    "deleted": {
        "rows": {},
        "columns": {},
        "header": {},
        "index": {},
        "column_widths": {},
        "row_heights": {},
        "options": {},
        "displayed_columns": None,
        "displayed_rows": None,
    },
    "named_spans": {},
    "selection_boxes": {},
    "selected": tuple(),
    "being_selected": tuple(),
    "data": [],
    "key": "",
    "value": None,
    "loc": tuple(),
    "row": None,
    "column": None,
    "resized": {
        "rows": {},
        "columns": {},
    },
    "widget": None,
}

Keys:

• Key ["eventname"] will be one of the following:
  • "begin_ctrl_c"
  • "end_ctrl_c"
  • "begin_ctrl_x"
  • "end_ctrl_x"
  • "begin_ctrl_v"
  • "end_ctrl_v"
  • "begin_delete"
  • "end_delete"
  • "begin_undo"
  • "end_undo"
  • "begin_add_columns"
  • "end_add_columns"
  • "begin_add_rows"
  • "end_add_rows"
  • "begin_delete_columns"
  • "end_delete_columns"
  • "begin_delete_rows"
  • "end_delete_rows"
  • "begin_edit_table"
  • "end_edit_table"
  • "begin_edit_index"
  • "end_edit_index"
  • "begin_edit_header"
  • "end_edit_header"
  • "begin_move_rows"
  • "end_move_rows"
  • "begin_move_columns"
  • "end_move_columns"
  • "select"
  • "resize"
• For events "begin_move_columns"/"begin_move_rows" the point where columns/rows will be moved to will be under the event_data key "value".
• Key ["sheetname"] is the name given to the sheet widget on initialization, useful if you have multiple sheets to determine which one emitted the event.
• Key ["cells"]["table"] if any table cells have been modified by cut, paste, delete, cell editors, dropdown boxes, check boxes, undo or redo this will be a dict with tuple keys of (data row index: int, data column index: int) and the values will be the cell values at that location prior to the change. The dict will be empty if no such changes have taken place.
• Key ["cells"]["header"] if any header cells have been modified by cell editors, dropdown boxes, check boxes, undo or redo this will be a dict with keys of int: data column index and the values will be the cell values at that location prior to the change. The dict will be empty if no such changes have taken place.
• Key ["cells"]["index"] if any index cells have been modified by cell editors, dropdown boxes, check boxes, undo or redo this will be a dict with keys of int: data row index and the values will be the cell values at that location prior to the change. The dict will be empty if no such changes have taken place.
• Key ["moved"]["rows"] if any rows have been moved by dragging and dropping or undoing/redoing of dragging and dropping rows this will be a dict with the following keys:
  • {"data": {old data index: new data index, ...}, "displayed": {old displayed index: new displayed index, ...}}
    • "data" will be a dict where the keys are the old data indexes of the rows and the values are the data indexes they have moved to.
    • "displayed" will be a dict where the keys are the old displayed indexes of the rows and the values are the displayed indexes they have moved to.
    • If no rows have been moved the dict under ["moved"]["rows"] will be empty.
    • Note that if there are hidden rows the values for "data" will include all currently displayed row indexes and their new locations. If required and available, the values under "displayed" include only the directly moved rows, convert to data indexes using Sheet.data_r().
  • For events "begin_move_rows" the point where rows will be moved to will be under the event_data key "value".
• Key ["moved"]["columns"] if any columns have been moved by dragging and dropping or undoing/redoing of dragging and dropping columns this will be a dict with the following keys:
  • {"data": {old data index: new data index, ...}, "displayed": {old displayed index: new displayed index, ...}}
    • "data" will be a dict where the keys are the old data indexes of the columns and the values are the data indexes they have moved to.
    • "displayed" will be a dict where the keys are the old displayed indexes of the columns and the values are the displayed indexes they have moved to.
    • If no columns have been moved the dict under ["moved"]["columns"] will be empty.
    • Note that if there are hidden columns the values for "data" will include all currently displayed column indexes and their new locations. If required and available, the values under "displayed" include only the directly moved columns, convert to data indexes using Sheet.data_c().
  • For events "begin_move_columns" the point where columns will be moved to will be under the event_data key "value".
• Key ["added"]["rows"] if any rows have been added by the inbuilt popup menu insert rows or by a paste which expands the sheet then this will be a dict with the following keys:
  • {"data_index": int, "displayed_index": int, "num": int, "displayed": []}
    • "data_index" is an int representing the row where the rows were added in the data.
    • "displayed_index" is an int representing the displayed table index where the rows were added (which will be different from the data index if there are hidden rows).
    • "displayed" is simply a copied list of the Sheet()s displayed rows immediately prior to the change.
    • If no rows have been added the dict will be empty.
• Key ["added"]["columns"] if any columns have been added by the inbuilt popup menu insert columns or by a paste which expands the sheet then this will be a dict with the following keys:
  • {"data_index": int, "displayed_index": int, "num": int, "displayed": []}
    • "data_index" is an int representing the column where the columns were added in the data.
    • "displayed_index" is an int representing the displayed table index where the columns were added (which will be different from the data index if there are hidden columns).
    • "displayed" is simply a copied list of the Sheet()s displayed columns immediately prior to the change.
    • If no columns have been added the dict will be empty.
• Key ["deleted"]["columns"] if any columns have been deleted by the inbuilt popup menu delete columns or by undoing a paste which added columns then this will be a dict. This dict will look like the following:
  • {[column data index]: {[row data index]: cell value, [row data index]: cell value}, [column data index]: {...} ...}
  • If no columns have been deleted then the dict value for ["deleted"]["columns"] will be empty.
• Key ["deleted"]["rows"] if any rows have been deleted by the inbuilt popup menu delete rows or by undoing a paste which added rows then this will be a dict. This dict will look like the following:
  • {[row data index]: {[column data index]: cell value, [column data index]: cell value}, [row data index]: {...} ...}
  • If no rows have been deleted then the dict value for ["deleted"]["rows"] will be empty.
• Key ["deleted"]["header"] if any header values have been deleted by the inbuilt popup menu delete columns or by undoing a paste which added columns and header values then this will be a dict. This dict will look like the following:
  • {[column data index]: header cell value, [column data index]: header cell value, ...}
  • If no columns have been deleted by the mentioned methods then the dict value for ["deleted"]["header"] will be empty.
• Key ["deleted"]["index"] if any index values have been deleted by the inbuilt popup menu delete rows or by undoing a paste which added rows and index values then this will be a dict. This dict will look like the following:
  • {[row data index]: index cell value, [row data index]: index cell value, ...}
  • If no index values have been deleted by the mentioned methods then the dict value for ["deleted"]["index"] will be empty.
• Key ["deleted"]["column_widths"] if any columns have been deleted by the inbuilt popup menu delete columns or by undoing a paste which added columns then this will be a dict. This dict will look like the following:
  • {[column data index]: column width, [column data index]: column width, ...}
  • If no columns have been deleted then the dict value for ["deleted"]["column_widths"] will be empty.
• Key ["deleted"]["row_heights"] if any rows have been deleted by the inbuilt popup menu delete rows or by undoing a paste which added rows then this will be a dict. This dict will look like the following:
  • {[row data index]: row height, [row data index]: row height, ...}
  • If no rows have been deleted then the dict value for ["deleted"]["row_heights"] will be empty.
• Key ["deleted"]["displayed_columns"] if any columns have been deleted by the inbuilt popup menu delete columns or by undoing a paste which added columns then this will be a list. This list stores the displayed columns (the columns that are showing when others are hidden) immediately prior to the change.
• Key ["deleted"]["displayed_rows"] if any rows have been deleted by the inbuilt popup menu delete rows or by undoing a paste which added rows then this will be a list. This list stores the displayed rows (the rows that are showing when others are hidden) immediately prior to the change.
• Key ["named_spans"] This dict serves as storage for the Sheet()s named spans. Each value in the dict is a pickled span object.
• Key ["options"] This serves as storage for the Sheet()s options such as highlights, formatting, alignments, dropdown boxes, check boxes etc. It is a dict where the values are the sheets internal cell/row/column options dicts.
• Key ["selection_boxes"] the value of this is all selection boxes on the sheet in the form of a dict as shown below:
  • For every event except "select" events the selection boxes are those immediately prior to the modification, for "select" events they are the current selection boxes.
  • The layout is always: "selection_boxes": {(start row, start column, up to but not including row, up to but not including column): selection box type}.
    • The row/column indexes are ints and the selection box type is a str either "cells", "rows" or "columns".
  • The dict will be empty if there is nothing selected.
• Key ["selected"] the value of this when there is something selected on the sheet is a namedtuple. The values of which can be found here.
  • When nothing is selected or the event is not relevant to the currently selected box, such as a resize event it will be an empty tuple.
• Key ["being_selected"] if any selection box is in the process of being drawn by holding down mouse button 1 and dragging then this will be a tuple with the following layout:
  • (start row, start column, up to but not including row, up to but not including column, selection box type).
    • The selection box type is a str either "cells", "rows" or "columns".
  • If no box is in the process of being created then this will be a an empty tuple.
  • See here for an example.
• Key ["data"] is primarily used for paste and it will contain the pasted data if any.
• Key ["key"] - str - is primarily used for cell edit events where a key press has occurred. For "begin_edit..." events the value is the actual key which was pressed (or "??" for using the mouse to open a cell). It also might be one of the following for end edit events:
  • "Return" - enter key.
  • "FocusOut" - the editor or box lost focus, perhaps by mouse clicking elsewhere.
  • "Tab" - tab key.
• Key ["value"] is used primarily by cell editing events. For "begin_edit..." events it's the value displayed in he text editor when it opens. For "end_edit..." events it's the value in the text editor when it was closed, for example by hitting Return. It also used by "begin_move_columns"/"begin_move_rows" - the point where columns/rows will be moved to will be under the event_data key "value".
• Key ["loc"] is for cell editing events to show the displayed (not data) coordinates of the event. It will be either:
  • A tuple of (int displayed row index, int displayed column index) in the case of editing table cells.
  • A single int in the case of editing index/header cells.
• Key ["row"] is for cell editing events to show the displayed (not data) row number int of the event. If the event was not a cell editing event or a header cell was edited the value will be None.
• Key ["column"] is for cell editing events to show the displayed (not data) column number int of the event. If the event was not a cell editing event or an index cell was edited the value will be None.
• Key ["resized"]["rows"] is for row height resizing events, it will be a dict with the following layout:
  • {int displayed row index: {"old_size": old_height, "new_size": new_height}}.
  • If no rows have been resized then the value for ["resized"]["rows"] will be an empty dict.
• Key ["resized"]["columns"] is for column width resizing events, it will be a dict with the following layout:
  • {int displayed column index: {"old_size": old_width, "new_size": new_width}}.
  • If no columns have been resized then the value for ["resized"]["columns"] will be an empty dict.
• Key ["widget"] will contain the widget which emitted the event, either the MainTable(), ColumnHeaders() or RowIndex() which are all tk.Canvas widgets.

With this function you can validate or modify most user sheet edits, includes cut, paste, delete (including column/row clear), dropdown boxes and cell edits.

edit_validation(func: Callable | None = None) -> Sheet

Parameters:

• func (Callable, None) must either be a function which will receive a tksheet event dict which looks like this or None which unbinds the function.

Notes:

• If your bound function returns None then that specific cell edit will not be performed.
• For examples of this function see here and here.

popup_menu_add_command(
    label: str,
    func: Callable,
    table_menu: bool = True,
    index_menu: bool = True,
    header_menu: bool = True,
    empty_space_menu: bool = True,
) -> Sheet

popup_menu_del_command(label: str | None = None) -> Sheet

• If label is None then it removes all.

basic_bindings(enable: bool = False) -> Sheet

These functions are links to the Sheets own functionality. Functions such as cut() rely on whatever is currently selected on the Sheet.

cut(event: object = None) -> Sheet
copy(event: object = None) -> Sheet
paste(event: object = None) -> Sheet
delete(event: object = None) -> Sheet
undo(event: object = None) -> Sheet
redo(event: object = None) -> Sheet
zoom_in() -> Sheet
zoom_out() -> Sheet

@property
def event() -> EventDataDict

• e.g. last_event_data = sheet.event
• Will be empty EventDataDict if there is no last event.

focus_set(
    canvas: Literal[
        "table",
        "header",
        "row_index",
        "index",
        "topleft",
        "top_left",
    ] = "table",
) -> Sheet

• With the Sheet.bind() function you can bind things in the usual way you would in tkinter and they will bind to all the tksheet canvases.
• There are also the following special tksheet events you can bind:

bind(
    event: str,
    func: Callable,
    add: str | None = None,
)

Parameters:

• add may or may not work for various bindings depending on whether they are already in use by tksheet.
• Note that while a bound event after a paste/undo/redo might have the event name "edit_table" it also might have added/deleted rows/columns, refer to the docs on the event data dict for more information.
• event the emitted events are:
  • "<<SheetModified>>" emitted whenever the sheet was modified by the end user by editing cells or adding or deleting rows/columns. The function you bind to this event must be able to receive a dict argument which will be the same as the event data dict but with less specific event names. The possible event names are listed below:
    • "edit_table" when a user has cut, paste, delete or any cell edits including using dropdown boxes etc. in the table.
    • "edit_index" when a user has edited a index cell.
    • "edit_header" when a user has edited a header cell.
    • "add_columns" when a user has inserted columns.
    • "add_rows" when a user has inserted rows.
    • "delete_columns" when a user has deleted columns.
    • "delete_rows" when a user has deleted rows.
    • "move_columns" when a user has dragged and dropped columns.
    • "move_rows" when a user has dragged and dropped rows.
  • "<<SheetRedrawn>>" emitted whenever the sheet GUI was refreshed (redrawn). The data for this event will be different than the usual event data, it is simply:
    • {"sheetname": name of your sheet, "header": bool True if the header was redrawn, "row_index": bool True if the index was redrawn, "table": bool True if the the table was redrawn}
  • "<<SheetSelect>>" encompasses all select events and emits the same event as "<<SheetModified>>" but with the event name: "select".
  • "<<Copy>>" emitted when a Sheet copy e.g. <Control-c> was performed and will have the eventname "copy".
  • "<<Cut>>"
  • "<<Paste>>"
  • "<<Delete>>" emitted when a Sheet delete key function was performed.
  • "<<SelectAll>>"
  • "<<Undo>>"
  • "<<Redo>>"

Example:

# self.sheet_was_modified is your function
self.sheet.bind("<<SheetModified>>", self.sheet_was_modified)

Example for event_generate():

self.sheet.event_generate("<<Copy>>")

• Tells the sheet to run its copy function.

With this function you can unbind things you have bound using the bind() function.

unbind(binding: str) -> Sheet

In this section are instructions to change some of tksheets in-built language and bindings:

• The in-built right click menu.
• The in-built functionality keybindings, such as copy, paste etc.

You can change the labels for tksheets in-built right click popup menu by using the set_options() function with any of the following keyword arguments:

edit_header_label
edit_header_accelerator
edit_index_label
edit_index_accelerator
edit_cell_label
edit_cell_accelerator
cut_label
cut_accelerator
cut_contents_label
cut_contents_accelerator
copy_label
copy_accelerator
copy_contents_label
copy_contents_accelerator
paste_label
paste_accelerator
delete_label
delete_accelerator
clear_contents_label
clear_contents_accelerator
delete_columns_label
delete_columns_accelerator
insert_columns_left_label
insert_columns_left_accelerator
insert_column_label
insert_column_accelerator
insert_columns_right_label
insert_columns_right_accelerator
delete_rows_label
delete_rows_accelerator
insert_rows_above_label
insert_rows_above_accelerator
insert_rows_below_label
insert_rows_below_accelerator
insert_row_label
insert_row_accelerator
select_all_label
select_all_accelerator
undo_label
undo_accelerator

Example:

# changing the copy label to the spanish for Copy
sheet.set_options(copy_label="Copiar")

You can change the bindings for tksheets in-built functionality such as cut, copy, paste by using the set_options() function with any the following keyword arguments:

copy_bindings
cut_bindings
paste_bindings
undo_bindings
redo_bindings
delete_bindings
select_all_bindings
tab_bindings
up_bindings
right_bindings
down_bindings
left_bindings
shift_up_bindings
shift_right_bindings
shift_down_bindings
shift_left_bindings
prior_bindings
next_bindings

The argument must be a list of tkinter binding strs. In the below example the binding for copy is changed to "<Control-e>" and "<Control-E>".

# changing the binding for copy
sheet.set_options(copy_bindings=["<Control-e>", "<Control-E>"])

The default values for these bindings can be found in the tksheet file sheet_options.py.

There is limited support in tkinter for keybindings in languages other than english, for example tkinters .bind() function doesn't cooperate with cyrillic characters.

There are ways around this however, see below for a limited example of how this might be achieved:

from __future__ import annotations

import tkinter as tk

from tksheet import Sheet


class demo(tk.Tk):
    def __init__(self) -> None:
        tk.Tk.__init__(self)
        self.grid_columnconfigure(0, weight=1)
        self.grid_rowconfigure(0, weight=1)
        self.sheet = Sheet(
            parent=self,
            data=[[f"{r} {c}" for c in range(5)] for r in range(5)],
        )
        self.sheet.enable_bindings()
        self.sheet.grid(row=0, column=0, sticky="nswe")
        self.bind_all("<Key>", self.any_key)

    def any_key(self, event: tk.Event) -> None:
        """
        Establish that the Control key is held down
        """
        ctrl = (event.state & 4 > 0)
        if not ctrl:
            return
        """
        From here you can use event.keycode and event.keysym to determine
        which key has been pressed along with Control
        """
        print(event.keycode)
        print(event.keysym)
        """
        If the keys are the ones you want to have bound to Sheet functionality
        You can then call the Sheets functionality using event_generate()
        For example:
        """
        # if the key is correct then:
        self.sheet.event_generate("<<Copy>>")


app = demo()
app.mainloop()

In tksheet versions > 7 there are functions which utilise an object named Span. These objects are a subclass of dict but with various additions and dot notation attribute access.

Spans basically represent an contiguous area of the sheet. They can be one of three kinds:

• "cell"
• "row"
• "column"

They can be used with some of the sheets functions such as data getting/setting and creation of things on the sheet such as dropdown boxes.

Spans store:

• A reference to the Sheet() they were created with.
• Variables which represent a particular range of cells and properties for accessing these ranges.
• Variables which represent options for those cells.
• Methods which can modify the above variables.
• Methods which can act upon the table using the above variables such as highlight, format, etc.

Whether cells, rows or columns are affected will depend on the spans kind.

You can create a span by:

• Using the span() function e.g. sheet.span("A1") represents the cell A1

or

• Using square brackets on a Sheet object e.g. sheet["A1"] represents the cell A1

Both methods return the created span object.

span(
    *key: CreateSpanTypes,
    type_: str = "",
    name: str = "",
    table: bool = True,
    index: bool = False,
    header: bool = False,
    tdisp: bool = False,
    idisp: bool = True,
    hdisp: bool = True,
    transposed: bool = False,
    ndim: int = 0,
    convert: object = None,
    undo: bool = False,
    emit_event: bool = False,
    widget: object = None,
    expand: None | str = None,
    formatter_options: dict | None = None,
    **kwargs,
) -> Span
"""
Create a span / get an existing span by name
Returns the created span
"""

Parameters:

• key you do not have to provide an argument for key, if no argument is provided then the span will be a full sheet span. Otherwise key can be the following types which are type hinted as CreateSpanTypes:
  • None
  • str e.g. sheet.span("A1:F1")
  • int e.g. sheet.span(0)
  • slice e.g. sheet.span(slice(0, 4))
  • Sequence[int | None, int | None] representing a cell of row, column e.g. sheet.span(0, 0)
  • Sequence[Sequence[int | None, int | None], Sequence[int | None, int | None]] representing sheet.span(start row, start column, up to but not including row, up to but not including column) e.g. sheet.span(0, 0, 2, 2)
  • Span e.g sheet.span(another_span)
• type_ (str) must be either an empty string "" or one of the following: "format", "highlight", "dropdown", "checkbox", "readonly", "align".
• name (str) used for named spans or for identification. If no name is provided then a name is generated for the span which is based on an internal integer ticker and then converted to a string in the same way column names are.
• table (bool) when True will make all functions used with the span target the main table as well as the header/index if those are True.
• index (bool) when True will make all functions used with the span target the index as well as the table/header if those are True.
• header (bool) when True will make all functions used with the span target the header as well as the table/index if those are True.
• tdisp (bool) is used by data getting functions that utilize spans and when True the function retrieves screen displayed data for the table, not underlying cell data.
• idisp (bool) is used by data getting functions that utilize spans and when True the function retrieves screen displayed data for the index, not underlying cell data.
• hdisp (bool) is used by data getting functions that utilize spans and when True the function retrieves screen displayed data for the header, not underlying cell data.
• transposed (bool) is used by data getting and setting functions that utilize spans. When True:
  • Returned sublists from data getting functions will represent columns rather than rows.
  • Data setting functions will assume that a single sequence is a column rather than row and that a list of lists is a list of columns rather than a list of rows.
• ndim (int) is used by data getting functions that utilize spans, it must be either 0 or 1 or 2.
  • 0 is the default setting which will make the return value vary based on what it is. For example if the gathered data is only a single cell it will return a value instead of a list of lists with a single list containing a single value. A single row will be a single list.
  • 1 will force the return of a single list as opposed to a list of lists.
  • 2 will force the return of a list of lists.
• convert (None, Callable) can be used to modify the data using a function before returning it. The data sent to the convert function will be as it was before normally returning (after ndim has potentially modified it).
• undo (bool) is used by data modifying functions that utilize spans. When True and if undo is enabled for the sheet then the end user will be able to undo/redo the modification.
• emit_event when True and when using data setting functions that utilize spans causes a "<<SheetModified>> event to occur if it has been bound, see here for more information on binding this event.
• widget (object) is the reference to the original sheet which created the span. This can be changed to a different sheet if required e.g. my_span.widget = new_sheet.
• expand (None, str) must be either None or:
  • "table"/"both" expand the span both down and right from the span start to the ends of the table.
  • "right" expand the span right to the end of the table x axis.
  • "down" expand the span downwards to the bottom of the table y axis.
• formatter_options (dict, None) must be either None or dict. If providing a dict it must be the same structure as used in format functions, see here for more information. Used to turn the span into a format type span which:
  • When using get_data() will format the returned data.
  • When using set_data() will format the data being set but NOT create a new formatting rule on the sheet.
• **kwargs you can provide additional keyword arguments to the function for example those used in span.highlight() or span.dropdown() which are used when applying a named span to a table.

Notes:

• To create a named span see here.

When creating a span using the below methods:

• strs use excel syntax and the indexing rule of up to AND including.
• ints use python syntax and the indexing rule of up to but NOT including.

For example python index 0 as in [0] is the first whereas excel index 1 as in "A1" is the first.

If you need to convert python indexes into column letters you can use the function num2alpha importable from tksheet:

from tksheet import (
    Sheet,
    num2alpha as n2a,
)

# column index five as a letter
n2a(5)

"""
EXAMPLES USING SQUARE BRACKETS
"""

span = sheet[0] # first row
span = sheet["1"] # first row

span = sheet[0:2] # first two rows
span = sheet["1:2"] # first two rows

span = sheet[:] # entire sheet
span = sheet[":"] # entire sheet

span = sheet[:2] # first two rows
span = sheet[":2"] # first two rows

""" THESE TWO HAVE DIFFERENT OUTCOMES """
span = sheet[2:] # all rows after and not inlcuding python index 1
span = sheet["2:"] # all rows after and not including python index 0

span = sheet["A"] # first column
span = sheet["A:C"] # first three columns

""" SOME CELL AREA EXAMPLES """
span = sheet[0, 0] # cell A1
span = sheet[(0, 0)] # cell A1
span = sheet["A1:C1"] # cells A1, B1, C1
span = sheet[0, 0, 1, 3] # cells A1, B1, C1
span = sheet[(0, 0, 1, 3)] # cells A1, B1, C1
span = sheet[(0, 0), (1, 3)] # cells A1, B1, C1
span = sheet[((0, 0), (1, 3))] # cells A1, B1, C1

span = sheet["A1:2"]
span = sheet[0, 0, 2, None]
"""
["A1:2"]
All the cells starting from (0, 0)
expanding down to include row 1
but not including cells beyond row
1 and expanding out to include all
columns

    A   B   C   D
1   x   x   x   x
2   x   x   x   x
3
4
...
"""

span = sheet["A1:B"]
span = sheet[0, 0, None, 2]
"""
["A1:B"]
All the cells starting from (0, 0)
expanding out to include column 1
but not including cells beyond column
1 and expanding down to include all
rows

    A   B   C   D
1   x   x
2   x   x
3   x   x
4   x   x
...
"""

""" GETTING AN EXISTING NAMED SPAN """
# you can retrieve an existing named span quickly by surrounding its name in <> e.g.
named_span_retrieval = sheet["<the name of the span goes here>"]

"""
EXAMPLES USING span()
"""

"""
USING NO ARGUMENTS
"""
sheet.span() # entire sheet, in this case not including header or index

"""
USING ONE ARGUMENT

str or int or slice()
"""

# with one argument you can use the same string syntax used for square bracket span creation
sheet.span("A1")
sheet.span(0) # row at python index 0, all columns
sheet.span(slice(0, 2)) # rows at python indexes 0 and 1, all columns
sheet.span(":") # entire sheet

"""
USING TWO ARGUMENTS
int | None, int | None

or

(int | None, int | None), (int | None, int | None)
"""
sheet.span(0, 0) # row 0, column 0 - the first cell
sheet.span(0, None) # row 0, all columns
sheet.span(None, 0) # column 0, all rows

sheet.span((0, 0), (1, 1)) # row 0, column 0 - the first cell
sheet.span((0, 0), (None, 2)) # rows 0 - end, columns 0 and 1

"""
USING FOUR ARGUMENTS
int | None, int | None, int | None, int | None
"""

sheet.span(0, 0, 1, 1) # row 0, column 0 - the first cell
sheet.span(0, 0, None, 2) # rows 0 - end, columns 0 and 1

Spans have a few @property functions:

• span.kind
• span.rows
• span.columns

span.kind

• Returns either "cell", "row" or "column".

span = sheet.span("A1:C4")
print (span.kind)
# prints "cell"

span = sheet.span(":")
print (span.kind)
# prints "cell"

span = sheet.span("1:3")
print (span.kind)
# prints "row"

span = sheet.span("A:C")
print (span.kind)
# prints "column"

# after importing num2alpha from tksheet
print (sheet[num2alpha(0)].kind)
# prints "column"

span.rows
span.columns

Returns a SpanRange object. The below examples are for span.rows but you can use span.columns for the spans columns exactly the same way.

# use as an iterator
span = sheet.span("A1:C4")
for row in span.rows:
    pass
# use as a reversed iterator
for row in reversed(span.rows):
    pass

# check row membership
span = sheet.span("A1:C4")
print (2 in span.rows)
# prints True

# check span.rows equality, also can do not equal
span = self.sheet["A1:C4"]
span2 = self.sheet["1:4"]
print (span.rows == span2.rows)
# prints True

# check len
span = self.sheet["A1:C4"]
print (len(span.rows))
# prints 4

Spans have the following methods, all of which return the span object itself so you can chain the functions e.g. span.options(undo=True).clear().bg = "indianred1"

span.options(
    type_: str | None = None,
    name: str | None = None,
    table: bool | None = None,
    index: bool | None = None,
    header: bool | None = None,
    tdisp: bool | None = None,
    idisp: bool | None  = None,
    hdisp: bool | None  = None,
    transposed: bool | None = None,
    ndim: int | None = None,
    convert: Callable | None = None,
    undo: bool | None = None,
    emit_event: bool | None = None,
    widget: object = None,
    expand: str | None = None,
    formatter_options: dict | None = None,
    **kwargs,
) -> Span

Note: that if None is used for any of the following parameters then that Spans attribute will be unchanged.

• type_ (str, None) if not None then must be either an empty string "" or one of the following: "format", "highlight", "dropdown", "checkbox", "readonly", "align".
• name (str, None) is used for named spans or for identification.
• table (bool, None) when True will make all functions used with the span target the main table as well as the header/index if those are True.
• index (bool, None) when True will make all functions used with the span target the index as well as the table/header if those are True.
• header (bool, None) when True will make all functions used with the span target the header as well as the table/index if those are True.
• tdisp (bool, None) is used by data getting functions that utilize spans and when True the function retrieves screen displayed data for the table, not underlying cell data.
• idisp (bool, None) is used by data getting functions that utilize spans and when True the function retrieves screen displayed data for the index, not underlying cell data.
• hdisp (bool, None) is used by data getting functions that utilize spans and when True the function retrieves screen displayed data for the header, not underlying cell data.
• transposed (bool, None) is used by data getting and setting functions that utilize spans. When True:
  • Returned sublists from data getting functions will represent columns rather than rows.
  • Data setting functions will assume that a single sequence is a column rather than row and that a list of lists is a list of columns rather than a list of rows.
• ndim (int, None) is used by data getting functions that utilize spans, it must be either 0 or 1 or 2.
  • 0 is the default setting which will make the return value vary based on what it is. For example if the gathered data is only a single cell it will return a value instead of a list of lists with a single list containing a single value. A single row will be a single list.
  • 1 will force the return of a single list as opposed to a list of lists.
  • 2 will force the return of a list of lists.
• convert (Callable, None) can be used to modify the data using a function before returning it. The data sent to the convert function will be as it was before normally returning (after ndim has potentially modified it).
• undo (bool, None) is used by data modifying functions that utilize spans. When True and if undo is enabled for the sheet then the end user will be able to undo/redo the modification.
• emit_event (bool, None) is used by data modifying functions that utilize spans. When True causes a "<<SheetModified>> event to occur if it has been bound, see here for more information.
• widget (object) is the reference to the original sheet which created the span. This can be changed to a different sheet if required e.g. my_span.widget = new_sheet.
• expand (str, None) must be either None or:
  • "table"/"both" expand the span both down and right from the span start to the ends of the table.
  • "right" expand the span right to the end of the table x axis.
  • "down" expand the span downwards to the bottom of the table y axis.
• formatter_options (dict, None) must be either None or dict. If providing a dict it must be the same structure as used in format functions, see here for more information. Used to turn the span into a format type span which:
  • When using get_data() will format the returned data.
  • When using set_data() will format the data being set but NOT create a new formatting rule on the sheet.
• **kwargs you can provide additional keyword arguments to the function for example those used in span.highlight() or span.dropdown() which are used when applying a named span to a table.
• This function returns the span instance itself (self).

# entire sheet
span = sheet["A1"].options(expand="both")

# column A
span = sheet["A1"].options(expand="down")

# row 0
span = sheet["A1"].options(
    expand="right",
    ndim=1, # to return a single list when getting data
)

All of a spans modifiable attributes are listed here:

• from_r (int) represents which row the span starts at, must be a positive int.
• from_c (int) represents which column the span starts at, must be a positive int.
• upto_r (int, None) represents which row the span ends at, must be a positive int or None. None means always up to and including the last row.
• upto_c (int, None) represents which column the span ends at, must be a positive int or None. None means always up to and including the last column.
• type_ (str) must be either an empty string "" or one of the following: "format", "highlight", "dropdown", "checkbox", "readonly", "align".
• name (str) used for named spans or for identification. If no name is provided then a name is generated for the span which is based on an internal integer ticker and then converted to a string in the same way column names are.
• table (bool) when True will make all functions used with the span target the main table as well as the header/index if those are True.
• index (bool) when True will make all functions used with the span target the index as well as the table/header if those are True.
• header (bool) when True will make all functions used with the span target the header as well as the table/index if those are True.
• tdisp (bool) is used by data getting functions that utilize spans and when True the function retrieves screen displayed data for the table, not underlying cell data.
• idisp (bool) is used by data getting functions that utilize spans and when True the function retrieves screen displayed data for the index, not underlying cell data.
• hdisp (bool) is used by data getting functions that utilize spans and when True the function retrieves screen displayed data for the header, not underlying cell data.
• transposed (bool) is used by data getting and setting functions that utilize spans. When True:
  • Returned sublists from data getting functions will represent columns rather than rows.
  • Data setting functions will assume that a single sequence is a column rather than row and that a list of lists is a list of columns rather than a list of rows.
• ndim (int) is used by data getting functions that utilize spans, it must be either 0 or 1 or 2.
  • 0 is the default setting which will make the return value vary based on what it is. For example if the gathered data is only a single cell it will return a value instead of a list of lists with a single list containing a single value. A single row will be a single list.
  • 1 will force the return of a single list as opposed to a list of lists.
  • 2 will force the return of a list of lists.
• convert (None, Callable) can be used to modify the data using a function before returning it. The data sent to the convert function will be as it was before normally returning (after ndim has potentially modified it).
• undo (bool) is used by data modifying functions that utilize spans. When True and if undo is enabled for the sheet then the end user will be able to undo/redo the modification.
• emit_event (bool) is used by data modifying functions that utilize spans. When True causes a "<<SheetModified>> event to occur if it has been bound, see here for more information.
• widget (object) is the reference to the original sheet which created the span. This can be changed to a different sheet if required e.g. my_span.widget = new_sheet.
• kwargs a dict containing keyword arguments relevant for functions such as span.highlight() or span.dropdown() which are used when applying a named span to a table.

If necessary you can also modify these attributes the same way you would an objects. e.g.

# span now takes in all columns, including A
span = self.sheet("A")
span.upto_c = None

# span now adds to sheets undo stack when using data modifying functions that use spans
span = self.sheet("A")
span.undo = True

Formats table data, see the help on formatting for more information. Note that using this function also creates a format rule for the affected table cells.

span.format(
    formatter_options: dict = {},
    formatter_class: object = None,
    redraw: bool = True,
    **kwargs,
) -> Span

Example:

# using square brackets
sheet[:].format(int_formatter())

# or instead using sheet.span()
sheet.span(":").format(int_formatter())

These examples show the formatting of the entire sheet (not including header and index) as int and creates a format rule for all currently existing cells. Named spans are required to create a rule for all future existing cells as well, for example those created by the end user inserting rows or columns.

Delete any currently existing format rules for parts of the table that are covered by the span. Should not be used where there are data formatting rules created by named spans, see Named spans for more information.

span.del_format() -> Span

Example:

span1 = sheet[2:4]
span1.format(float_formatter())
span1.del_format()

span.highlight(
    bg: bool | None | str = False,
    fg: bool | None | str = False,
    end: bool | None = None,
    overwrite: bool = False,
    redraw: bool = True,
) -> Span

There are two ways to create highlights using a span:

Method 1 example using .highlight():

# highlights column A background red, text color black
sheet["A"].highlight(bg="red", fg="black")

# the same but after having saved a span
my_span = sheet["A"]
my_span.highlight(bg="red", fg="black")

Method 2 example using .bg/.fg:

# highlights column A background red, text color black
sheet["A"].bg = "red"
sheet["A"].fg = "black"

# the same but after having saved a span
my_span = sheet["A"]
my_span.bg = "red"
my_span.fg = "black"

Delete any currently existing highlights for parts of the sheet that are covered by the span. Should not be used where there are highlights created by named spans, see Named spans for more information.

span.dehighlight() -> Span

Example:

span1 = sheet[2:4].highlight(bg="red", fg="black")
span1.dehighlight()

Creates dropdown boxes for parts of the sheet that are covered by the span. For more information see here.

span.dropdown(
    values: list = [],
    set_value: object = None,
    state: Literal["normal", "readonly", "disabled"] = "normal",
    redraw: bool = True,
    selection_function: Callable | None = None,
    modified_function: Callable | None = None,
    search_function: Callable = dropdown_search_function,
    validate_input: bool = True,
    text: None | str = None,
) -> Span

Example:

sheet["D"].dropdown(
    values=["on", "off"],
    set_value="off",
)

Delete dropdown boxes for parts of the sheet that are covered by the span. Should not be used where there are dropdown box rules created by named spans, see Named spans for more information.

span.del_dropdown() -> Span

Example:

dropdown_span = sheet["D"].dropdown(values=["on", "off"],
                                    set_value="off")
dropdown_span.del_dropdown()

Create check boxes for parts of the sheet that are covered by the span.

span.checkbox(
    edit_data: bool = True,
    checked: bool | None = None,
    state: Literal["normal", "disabled"] = "normal",
    redraw: bool = True,
    check_function: Callable | None = None,
    text: str = "",
) -> Span

Parameters:

• edit_data when True edits the underlying cell data to either checked if checked is a bool or tries to convert the existing cell data to a bool.
• checked is the initial creation value to set the box to, if None then and edit_data is True then it will try to convert the underlying cell data to a bool.
• state can be "normal" or "disabled". If "disabled" then color will be same as table grid lines, else it will be the cells text color.
• check_function can be used to trigger a function when the user clicks a checkbox.
• text displays text next to the checkbox in the cell, but will not be used as data, data will either be True or False.

Example:

sheet["D"].checkbox(
    checked=True,
    text="Switch",
)

Delete check boxes for parts of the sheet that are covered by the span. Should not be used where there are check box rules created by named spans, see Named spans for more information.

span.del_checkbox() -> Span

Example:

checkbox_span = sheet["D"].checkbox(checked=True,
                                    text="Switch")
checkbox_span.del_checkbox()

Create a readonly rule for parts of the table that are covered by the span.

span.readonly(readonly: bool = True) -> Span

• Using span.readonly(False) deletes any existing readonly rules for the span. Should not be used where there are readonly rules created by named spans, see Named spans for more information.

Create a text alignment rule for parts of the sheet that are covered by the span.

span.align(
    align: str | None,
    redraw: bool = True,
) -> Span

• align (str, None) must be either:
  • None - clears the alignment rule
  • "c", "center", "centre"
  • "w", "west", "left"
  • "e", "east", "right"

Example:

sheet["D"].align("right")

There are two ways to create alignment rules using a span:

Method 1 example using .align():

# column D right text alignment
sheet["D"].align("right")

# the same but after having saved a span
my_span = sheet["D"]
my_span.align("right")

Method 2 example using .align = :

# column D right text alignment
sheet["D"].align = "right"

# the same but after having saved a span
my_span = sheet["D"]
my_span.align = "right"

Delete text alignment rules for parts of the sheet that are covered by the span. Should not be used where there are alignment rules created by named spans, see Named spans for more information.

span.del_align() -> Span

Example:

align_span = sheet["D"].align("right")
align_span.del_align()

Clear cell data from all cells that are covered by the span.

span.clear(
    undo: bool | None = None,
    emit_event: bool | None = None,
    redraw: bool = True,
) -> Span

Parameters:

• undo (bool, None) When True if undo is enabled for the end user they will be able to undo the clear change.
• emit_event when True causes a "<<SheetModified>> event to occur if it has been bound, see here for more information.

Example:

# clears column D
sheet["D"].clear()

Tag cells, rows or columns depending on the spans kind, more information on tags here.

tag(*tags) -> Span

Notes:

• If span.kind is "cell" then cells will be tagged, if it's a row span then rows will be and so for columns.

Example:

# tags rows 2, 3, 4 with "hello world"
sheet[2:5].tag("hello world")

Remove all tags from cells, rows or columns depending on the spans kind, more information on tags here.

untag() -> Span

Notes:

• If span.kind is "cell" then cells will be untagged, if it's a row span then rows will be and so for columns.

Example:

# tags rows 2, 3, 4 with "hello" and "bye"
sheet[2:5].tag("hello", "bye")

# removes both "hello" and "bye" tags from rows 2, 3, 4
sheet[2:5].untag()

The attribute span.transposed (bool) is used by data getting and setting functions that utilize spans. When True: - Returned sublists from data getting functions will represent columns rather than rows. - Data setting functions will assume that a single sequence is a column rather than row and that a list of lists is a list of columns rather than a list of rows.

You can toggle the transpotition of the span by using:

span.transpose() -> Span

If the attribute is already True this makes it False and vice versa.

span = sheet["A:D"].transpose()
# this span is now transposed
print (span.transposed)
# prints True

span.transpose()
# this span is no longer transposed
print (span.transposed)
# prints False

Expand the spans area either all the way to the right (x axis) or all the way down (y axis) or both.

span.expand(direction: str = "both") -> Span

• direction (None, str) must be either None or:
  • "table"/"both" expand the span both down and right from the span start to the ends of the table.
  • "right" expand the span right to the end of the table x axis.
  • "down" expand the span downwards to the bottom of the table y axis.

Named spans are like spans but with a type, some keyword arguments saved in span.kwargs and then created by using a Sheet() function. Like spans, named spans are also contiguous areas of the sheet.

Named spans can be used to:

• Create options (rules) for the sheet which will expand/contract when new cells are added/removed. For example if a user were to insert rows in the middle of some already highlighted rows:
  • With ordinary row highlights the newly inserted rows would NOT be highlighted.
  • With named span row highlights the newly inserted rows would also be highlighted.
• Quickly delete an existing option from the table whereas an ordinary span would not keep track of where the options have been moved.

Note that generally when a user moves rows/columns around the dimensions of the named span essentially move with either end of the span:

• The new start of the span will be wherever the start row/column moves.
• The new end of the span will be wherever the end row/column moves. The exceptions to this rule are when a span is expanded or has been created with Nones or the start of 0 and no end or end of None.

For the end user, when a span is just a single row/column (and is not expanded/unlimited) it cannot be expanded but it can be deleted if the row/column is deleted.

For a span to become a named span it needs:

• One of the following type_s: "format", "highlight", "dropdown", "checkbox", "readonly", "align".
• Relevant keyword arguments e.g. if the type_ is "highlight" then arguments for sheet.highlight() found here.

After a span has the above items the following function has to be used to make it a named span and create the options on the sheet:

named_span(span: Span)
"""
Adds a named span to the sheet
Returns the span
"""

• span must be an existing span with:
  • a name (a name is automatically generated upon span creation if one is not provided).
  • a type_ as described above.
  • keyword arguments as described above.

Examples of creating named spans:

# Will highlight rows 3 up to and including 5
span1 = self.sheet.span(
    "3:5",
    type_="highlight",
    bg="green",
    fg="black",
)
self.sheet.named_span(span1)

#  Will always keep the entire sheet formatted as `int` no matter how many rows/columns are inserted
span2 = self.sheet.span(
    ":",
    # you don't have to provide a `type_` when using the `formatter_kwargs` argument
    formatter_options=int_formatter(),
)
self.sheet.named_span(span2)

To delete a named span you simply have to provide the name.

del_named_span(name: str)

Example, creating and deleting a span:

# span covers the entire sheet
self.sheet.named_span(
    self.sheet.span(
        name="my highlight span",
        type_="highlight",
        bg="dark green",
        fg="#FFFFFF",
    )
)
self.sheet.del_named_span("my highlight span")

# ValueError is raised if name does not exist
self.sheet.del_named_span("this name doesnt exist")
# ValueError: Span 'this name doesnt exist' does not exist.

Sets the Sheets internal dict of named spans:

set_named_spans(named_spans: None | dict = None) -> Sheet

• Using None deletes all existing named spans

Get an existing named span:

get_named_span(name: str) -> dict

Get all existing named spans:

get_named_spans() -> dict

A Span object (more information here) is returned when using square brackets on a Sheet like so:

span = self.sheet["A1"]

You can also use sheet.span():

span = self.sheet.span("A1")

The above spans represent the cell A1 - row 0, column 0.

A reserved span attribute named data can then be used to retrieve the data for cell A1, example below:

span = self.sheet["A1"]
cell_a1_data = span.data

The data that is retrieved entirely depends on the area the span represents. You can also use span.value to the same effect.

There are certain other span attributes which have an impact on the data returned, explained below:

• table (bool) when True will make all functions used with the span target the main table as well as the header/index if those are True.
• index (bool) when True will make all functions used with the span target the index as well as the table/header if those are True.
• header (bool) when True will make all functions used with the span target the header as well as the table/index if those are True.
• tdisp (bool) when True the function retrieves screen displayed data for the table, not underlying cell data.
• idisp (bool) when True the function retrieves screen displayed data for the index, not underlying cell data.
• hdisp (bool) when True the function retrieves screen displayed data for the header, not underlying cell data.
• transposed (bool) is used by data getting and setting functions that utilize spans. When True:
  • Returned sublists from data getting functions will represent columns rather than rows.
  • Data setting functions will assume that a single sequence is a column rather than row and that a list of lists is a list of columns rather than a list of rows.
• ndim (int) is used by data getting functions that utilize spans, it must be either 0 or 1 or 2.
  • 0 is the default setting which will make the return value vary based on what it is. For example if the gathered data is only a single cell it will return a value instead of a list of lists with a single list containing a single value. A single row will be a single list.
  • 1 will force the return of a single list as opposed to a list of lists.
  • 2 will force the return of a list of lists.
• convert (None, Callable) can be used to modify the data using a function before returning it. The data sent to the convert function will be as it was before normally returning (after ndim has potentially modified it).
• widget (object) is the reference to the original sheet which created the span (this is the widget that data is retrieved from). This can be changed to a different sheet if required e.g. my_span.widget = new_sheet.

Some more complex examples of data retrieval:

"single cell"
cell_a1_data = self.sheet["A1"].data

"entire sheet including headers and index"
entire_sheet_data = self.sheet["A1"].expand().options(header=True, index=True).data

"header data, no table or index data"
# a list of displayed header cells
header_data = self.sheet["A:C"].options(table=False, header=True).data

# a header value
header_data = self.sheet["A"].options(table=False, hdisp=False, header=True).data

"index data, no table or header data"
# a list of displayed index cells
index_data = self.sheet[:3].options(table=False, index=True).data

# or using sheet.span() a list of displayed index cells
index_data = self.sheet.span(slice(None, 3), table=False, index=True).data

# a row index value
index_data = self.sheet[3].options(table=False, idisp=False, index=True).data

"sheet data as columns instead of rows, with actual header data"
sheet_data = self.sheet[:].transpose().options(hdisp=False, header=True).data

# or instead using sheet.span() with only kwargs
sheet_data = self.sheet.span(transposed=True, hdisp=False, header=True).data

There is also a Sheet() function for data retrieval (it is used internally by the above data getting methods):

sheet.get_data(
    *key: CreateSpanTypes,
) -> object

Examples:

data = self.sheet.get_data("A1")
data = self.sheet.get_data(0, 0, 3, 3)
data = self.sheet.get_data(
    self.sheet.span(":D", transposed=True)
)

This function is useful if you need a lot of sheet data, and produces one row at a time (may save memory use in certain scenarios). It does not use spans.

yield_sheet_rows(
    get_displayed: bool = False,
    get_header: bool = False,
    get_index: bool = False,
    get_index_displayed: bool = True,
    get_header_displayed: bool = True,
    only_rows: int | Iterator[int] | None = None,
    only_columns: int | Iterator[int] | None = None,
) -> Iterator[list[object]]

Parameters:

• get_displayed (bool) if True it will return cell values as they are displayed on the screen. If False it will return any underlying data, for example if the cell is formatted.
• get_header (bool) if True it will return the header of the sheet even if there is not one.
• get_index (bool) if True it will return the index of the sheet even if there is not one.
• get_index_displayed (bool) if True it will return whatever index values are displayed on the screen, for example if there is a dropdown box with text set.
• get_header_displayed (bool) if True it will return whatever header values are displayed on the screen, for example if there is a dropdown box with text set.
• only_rows (None, iterable) with this argument you can supply an iterable of int row indexes in any order to be the only rows that are returned.
• only_columns (None, iterable) with this argument you can supply an iterable of int column indexes in any order to be the only columns that are returned.

@property
data()

• e.g. self.sheet.data
• Doesn't include header or index data.

.MT.data

• You can use this to directly modify or retrieve the main table's data e.g. cell_0_0 = my_sheet_name_here.MT.data[0][0] but only do so if you know what you're doing.

Sheet objects also have some functions similar to lists. Note that these functions do not include the header or index.

Iterate over table rows:

for row in self.sheet:
    print (row)

# and in reverse
for row in reversed(self.sheet):
    print (row)

Check if the table has a particular value (membership):

# returns True or False
search_value = "the cell value I'm looking for"
print (search_value in self.sheet)

• Can also check if a row is in the sheet if a list is used.

get_total_rows(include_index: bool = False) -> int

get_total_columns(include_header: bool = False) -> int

get_value_for_empty_cell(
    r: int,
    c: int,
    r_ops: bool = True,
    c_ops: bool = True,
) -> object

• r_ops/c_ops when both are True it will take into account whatever cell/row/column options exist. When just r_ops is True it will take into account row options only and when just c_ops is True it will take into account column options only.

Fundamentally, there are two ways to set table data:

• Overwriting the entire table and setting the table data to a new object.
• Modifying the existing data.

set_sheet_data(
    data: list | tuple | None = None,
    reset_col_positions: bool = True,
    reset_row_positions: bool = True,
    redraw: bool = True,
    verify: bool = False,
    reset_highlights: bool = False,
    keep_formatting: bool = True,
    delete_options: bool = False,
) -> object

Parameters:

• data (list) has to be a list of lists for full functionality, for display only a list of tuples or a tuple of tuples will work.
• reset_col_positions and reset_row_positions (bool) when True will reset column widths and row heights.
• redraw (bool) refreshes the table after setting new data.
• verify (bool) goes through data and checks if it is a list of lists, will raise error if not, disabled by default.
• reset_highlights (bool) resets all table cell highlights.
• keep_formatting (bool) when True re-applies any prior formatting rules to the new data, if False all prior formatting rules are deleted.
• delete_options (bool) when True all table options such as dropdowns, check boxes, formatting, highlighting etc. are deleted.

Notes:

• This function does not impact the sheet header or index.

@data.setter
data(value: object)

Notes:

• Acts like setting an attribute e.g. sheet.data = [[1, 2, 3], [4, 5, 6]]
• Uses the set_sheet_data() function and its default arguments.

reset(
    table: bool = True,
    header: bool = True,
    index: bool = True,
    row_heights: bool = True,
    column_widths: bool = True,
    cell_options: bool = True,
    undo_stack: bool = True,
    selections: bool = True,
    sheet_options: bool = False,
    redraw: bool = True,
) -> Sheet

Parameters:

• table when True resets the table to an empty list.
• header when True resets the header to an empty list.
• index when True resets the row index to an empty list.
• row_heights when True deletes all displayed row lines.
• column_widths when True deletes all displayed column lines.
• cell_options when True deletes all dropdowns, checkboxes, highlights, data formatting, etc.
• undo_stack when True resets the sheets undo stack to empty.
• selections when True deletes all selection boxes.
• sheet_options when True resets all the sheets options such as colors, font, popup menu labels and many more to default, for a full list of what's reset see the file sheet_options.py.

Notes:

• This function could be useful when a whole new sheet needs to be loaded.

A Span object (more information here) is returned when using square brackets on a Sheet like so:

span = self.sheet["A1"]

You can also use sheet.span():

span = self.sheet.span("A1")

The above span example represents the cell A1 - row 0, column 0. A reserved span attribute named data (you can also use .value) can then be used to modify sheet data starting from cell A1. example below:

span = self.sheet["A1"]
span.data = "new value for cell A1"

# or even shorter:
self.sheet["A1"].data = "new value for cell A1"

# or with sheet.span()
self.sheet.span("A1").data = "new value for cell A1"

If you provide a list or tuple it will set more than one cell, starting from the spans start cell. In the example below three cells are set in the first row, starting from cell B1:

self.sheet["B1"].data = ["row 0, column 1 new value (B1)",
                         "row 0, column 2 new value (C1)",
                         "row 0, column 3 new value (D1)"]

You can set data in column orientation with a transposed span:

self.sheet["B1"].transpose().data = ["row 0, column 1 new value (B1)",
                                     "row 1, column 1 new value (B2)",
                                     "row 2, column 1 new value (B3)"]

When setting data only a spans start cell is taken into account, the end cell is ignored. The example below demonstrates this, the spans end - "B1" is ignored and 4 cells get new values:

self.sheet["A1:B1"].data = ["A1 new val", "B1 new val", "C1 new val", "D1 new val"]

These are the span attributes which have an impact on the data set:

• table (bool) when True will make all functions used with the span target the main table as well as the header/index if those are True.
• index (bool) when True will make all functions used with the span target the index as well as the table/header if those are True.
• header (bool) when True will make all functions used with the span target the header as well as the table/index if those are True.
• transposed (bool) is used by data getting and setting functions that utilize spans. When True:
  • Returned sublists from data getting functions will represent columns rather than rows.
  • Data setting functions will assume that a single sequence is a column rather than row and that a list of lists is a list of columns rather than a list of rows.
• widget (object) is the reference to the original sheet which created the span (this is the widget that data is set to). This can be changed to a different sheet if required e.g. my_span.widget = new_sheet.

Some more complex examples of setting data:

"""
SETTING ROW DATA
"""
# first row gets some new values and the index gets a new value also
self.sheet[0].options(index=True).data = ["index val", "row 0 col 0", "row 0 col 1", "row 0 col 2"]

# or instead using sheet.span() first row gets some new values and the index gets a new value also
self.sheet.span(0, index=True).data = ["index val", "row 0 col 0", "row 0 col 1", "row 0 col 2"]

# first two rows get some new values, index included
self.sheet[0].options(index=True).data = [["index 0", "row 0 col 0", "row 0 col 1", "row 0 col 2"],
                                          ["index 1", "row 1 col 0", "row 1 col 1", "row 1 col 2"]]

"""
SETTING COLUMN DATA
"""
# first column gets some new values and the header gets a new value also
self.sheet["A"].options(transposed=True, header=True).data = ["header val", "row 0 col 0", "row 1 col 0", "row 2 col 0"]

# or instead using sheet.span() first column gets some new values and the header gets a new value also
self.sheet.span("A", transposed=True, header=True).data = ["header val", "row 0 col 0", "row 1 col 0", "row 2 col 0"]

# first two columns get some new values, header included
self.sheet["A"].options(transposed=True, header=True).data = [["header 0", "row 0 col 0", "row 1 col 0", "row 2 col 0"],
                                                              ["header 1", "row 0 col 1", "row 1 col 1", "row 2 col 1"]]

"""
SETTING CELL AREA DATA
"""
# cells B2, C2, B3, C3 get new values
self.sheet["B2"].data = [["B2 new val", "C2 new val"],
                         ["B3 new val", "C3 new val"]]

# or instead using sheet.span() cells B2, C2, B3, C3 get new values
self.sheet.span("B2").data = [["B2 new val", "C2 new val"],
                              ["B3 new val", "C3 new val"]]

"""
SETTING CELL AREA DATA INCLUDING HEADER AND INDEX
"""
self.sheet_span = self.sheet.span(
    header=True,
    index=True,
    hdisp=False,
    idisp=False,
)

# set data for the span which was created above
self.sheet_span.data = [["",  "A",  "B",  "C"]
                        ["1", "A1", "B1", "C1"],
                        ["2", "A2", "B2", "C2"]]

You can also use the Sheet function set_data().

set_data(
    *key: CreateSpanTypes,
    data: object = None,
    undo: bool | None = None,
    emit_event: bool | None = None,
    redraw: bool = True,
) -> EventDataDict

Parameters:

• undo when True adds the change to the Sheets undo stack.
• emit_event when True causes a "<<SheetModified>> event to occur if it has been bound, see here for more information.

Example:

self.sheet.set_data(
    "A1",
    [["",  "A",  "B",  "C"]
     ["1", "A1", "B1", "C1"],
     ["2", "A2", "B2", "C2"]],
)

You can clear cells/rows/columns using a spans clear() function or the Sheets clear() function. Below is the Sheets clear function:

clear(
    *key: CreateSpanTypes,
    undo: bool | None = None,
    emit_event: bool | None = None,
    redraw: bool = True,
) -> EventDataDict

• undo when True adds the change to the Sheets undo stack.
• emit_event when True causes a "<<SheetModified>> event to occur if it has been bound, see here for more information.

insert_row(
    row: list[object] | tuple[object] | None = None,
    idx: str | int | None = None,
    height: int | None = None,
    row_index: bool = False,
    fill: bool = True,
    undo: bool = False,
    emit_event: bool = False,
    redraw: bool = True,
) -> EventDataDict

Parameters:

• Leaving row as None inserts an empty row, e.g. insert_row() will append an empty row to the sheet.
• height is the new rows displayed height in pixels, leave as None for default.
• row_index when True assumes there is a row index value at the start of the row.
• fill when True any provided rows that are shorter than the Sheets longest row will be filled with empty values up to the length of the longest row.
• undo when True adds the change to the Sheets undo stack.
• emit_event when True causes a "<<SheetModified>> event to occur if it has been bound, see here for more information.

insert_column(
    column: list[object] | tuple[object] | None = None,
    idx: str | int | None = None,
    width: int | None = None,
    header: bool = False,
    fill: bool = True,
    undo: bool = False,
    emit_event: bool = False,
    redraw: bool = True,
) -> EventDataDict

Parameters:

• Leaving column as None inserts an empty column, e.g. insert_column() will append an empty column to the sheet.
• width is the new columns displayed width in pixels, leave as None for default.
• header when True assumes there is a header value at the start of the column.
• fill when True any provided columns that are shorter than the Sheets longest column will be filled with empty values up to the length of the longest column.
• undo when True adds the change to the Sheets undo stack.
• emit_event when True causes a "<<SheetModified>> event to occur if it has been bound, see here for more information.

insert_columns(
    columns: list[tuple[object] | list[object]] | tuple[tuple[object] | list[object]] | int = 1,
    idx: str | int | None = None,
    widths: list[int] | tuple[int] | None = None,
    headers: bool = False,
    fill: bool = True,
    undo: bool = False,
    emit_event: bool = False,
    create_selections: bool = True,
    add_row_heights: bool = True,
    push_ops: bool = True,
    redraw: bool = True,
) -> EventDataDict

Parameters:

• columns if int will insert that number of blank columns.
• idx (str, int, None) either str e.g. "A" for 0, int or None for end.
• widths are the new columns displayed widths in pixels, leave as None for default.
• headers when True assumes there are headers values at the start of each column.
• fill when True any provided columns that are shorter than the Sheets longest column will be filled with empty values up to the length of the longest column.
• undo when True adds the change to the Sheets undo stack.
• emit_event when True causes a "<<SheetModified>> event to occur if it has been bound, see here for more information.
• create_selections when True creates a selection box for the newly inserted columns.
• add_row_heights when True creates rows if there are no pre-existing rows.
• push_ops when True increases the indexes of all cell/column options such as dropdown boxes, highlights and data formatting.

insert_rows(
    rows: list[tuple[object] | list[object]] | tuple[tuple[object] | list[object]] | int = 1,
    idx: str | int | None = None,
    heights: list[int] | tuple[int] | None = None,
    row_index: bool = False,
    fill: bool = True,
    undo: bool = False,
    emit_event: bool = False,
    create_selections: bool = True,
    add_column_widths: bool = True,
    push_ops: bool = True,
    redraw: bool = True,
) -> EventDataDict

Parameters:

• rows if int will insert that number of blank rows.
• idx (str, int, None) either str e.g. "A" for 0, int or None for end.
• heights are the new rows displayed heights in pixels, leave as None for default.
• row_index when True assumes there are row index values at the start of each row.
• fill when True any provided rows that are shorter than the Sheets longest row will be filled with empty values up to the length of the longest row.
• undo when True adds the change to the Sheets undo stack.
• emit_event when True causes a "<<SheetModified>> event to occur if it has been bound, see here for more information.
• create_selections when True creates a selection box for the newly inserted rows.
• add_column_widths when True creates columns if there are no pre-existing columns.
• push_ops when True increases the indexes of all cell/row options such as dropdown boxes, highlights and data formatting.

del_row(
    idx: int = 0,
    data_indexes: bool = True,
    undo: bool = False,
    emit_event: bool = False,
    redraw: bool = True,
) -> EventDataDict

Parameters:

• idx is the row to delete.
• data_indexes only applicable when there are hidden rows. When False it makes the idx represent a displayed row and not the underlying Sheet data row. When True the index represent a data index.
• undo when True adds the change to the Sheets undo stack.
• emit_event when True causes a "<<SheetModified>> event to occur if it has been bound, see here for more information.

del_rows(
    rows: int | Iterator[int],
    data_indexes: bool = True,
    undo: bool = False,
    emit_event: bool = False,
    redraw: bool = True,
) -> EventDataDict

Parameters:

• rows can be either int or an iterable of ints representing row indexes.
• data_indexes only applicable when there are hidden rows. When False it makes the rows indexes represent displayed rows and not the underlying Sheet data rows. When True the indexes represent data indexes.
• undo when True adds the change to the Sheets undo stack.
• emit_event when True causes a "<<SheetModified>> event to occur if it has been bound, see here for more information.

del_column(
    idx: int = 0,
    data_indexes: bool = True,
    undo: bool = False,
    emit_event: bool = False,
    redraw: bool = True,
) -> EventDataDict

Parameters:

• idx is the column to delete.
• data_indexes only applicable when there are hidden columns. When False it makes the idx represent a displayed column and not the underlying Sheet data column. When True the index represent a data index.
• undo when True adds the change to the Sheets undo stack.
• emit_event when True causes a "<<SheetModified>> event to occur if it has been bound, see here for more information.

del_columns(
    columns: int | Iterator[int],
    data_indexes: bool = True,
    undo: bool = False,
    emit_event: bool = False,
    redraw: bool = True,
) -> EventDataDict

Parameters:

• columns can be either int or an iterable of ints representing column indexes.
• data_indexes only applicable when there are hidden columns. When False it makes the columns indexes represent displayed columns and not the underlying Sheet data columns. When True the indexes represent data indexes.
• undo when True adds the change to the Sheets undo stack.
• emit_event when True causes a "<<SheetModified>> event to occur if it has been bound, see here for more information.

Expands or contracts the sheet data dimensions.

sheet_data_dimensions(
    total_rows: int | None = None,
    total_columns: int | None = None,
) -> Sheet

Parameters:

• total_rows sets the Sheets number of data rows.
• total_columns sets the Sheets number of data columns.

set_sheet_data_and_display_dimensions(
    total_rows: int | None = None,
    total_columns: int | None = None,
) -> Sheet

Parameters:

• total_rows when int will set the number of the Sheets data and display rows by deleting or adding rows.
• total_columns when int will set the number of the Sheets data and display columns by deleting or adding columns.

total_rows(
    number: int | None = None,
    mod_positions: bool = True,
    mod_data: bool = True,
) -> int | Sheet

Parameters:

• number sets the Sheets number of data rows. When None function will return the Sheets number of data rows including the number of rows in the index.
• mod_positions when True also sets the number of displayed rows.
• mod_data when True also sets the number of data rows.

total_columns(
    number: int | None = None,
    mod_positions: bool = True,
    mod_data: bool = True,
) -> int | Sheet

Parameters:

• number sets the Sheets number of data columns. When None function will return the Sheets number of data columns including the number of columns in the header.
• mod_positions when True also sets the number of displayed columns.
• mod_data when True also sets the number of data columns.

move_row(
    row: int,
    moveto: int,
) -> tuple[dict, dict, dict]

• Note that row and moveto indexes represent displayed indexes and not data. When there are hidden rows this is an important distinction, otherwise it is not at all important. To specifically use data indexes use the function move_rows().

move_column(
    column: int,
    moveto: int,
) -> tuple[dict, dict, dict]

• Note that column and moveto indexes represent displayed indexes and not data. When there are hidden columns this is an important distinction, otherwise it is not at all important. To specifically use data indexes use the function move_columns().

move_rows(
    move_to: int | None = None,
    to_move: list[int] | None = None,
    move_data: bool = True,
    data_indexes: bool = False,
    create_selections: bool = True,
    undo: bool = False,
    emit_event: bool = False,
    move_heights: bool = True,
    redraw: bool = True,
) -> tuple[dict, dict, dict]

Parameters:

• move_to is the new start index for the rows to be moved to.
• to_move is a list of row indexes to move to that new position, they will appear in the same order provided.
• move_data when True moves not just the displayed row positions but the Sheet data as well.
• data_indexes is only applicable when there are hidden rows. When False it makes the move_to and to_move indexes represent displayed rows and not the underlying Sheet data rows. When True the indexes represent data indexes.
• create_selections creates new selection boxes based on where the rows have moved.
• undo when True adds the change to the Sheets undo stack.
• emit_event when True causes a "<<SheetModified>> event to occur if it has been bound, see here for more information.
• move_heights when True also moves the displayed row lines.

Notes:

• The rows in to_move do not have to be contiguous.

move_columns(
    move_to: int | None = None,
    to_move: list[int] | None = None,
    move_data: bool = True,
    data_indexes: bool = False,
    create_selections: bool = True,
    undo: bool = False,
    emit_event: bool = False,
    move_widths: bool = True,
    redraw: bool = True,
) -> tuple[dict, dict, dict]

Parameters:

• move_to is the new start index for the columns to be moved to.
• to_move is a list of column indexes to move to that new position, they will appear in the same order provided.
• move_data when True moves not just the displayed column positions but the Sheet data as well.
• data_indexes is only applicable when there are hidden columns. When False it makes the move_to and to_move indexes represent displayed columns and not the underlying Sheet data columns. When True the indexes represent data indexes.
• create_selections creates new selection boxes based on where the columns have moved.
• undo when True adds the change to the Sheets undo stack.
• emit_event when True causes a "<<SheetModified>> event to occur if it has been bound, see here for more information.
• move_widths when True also moves the displayed column lines.

Notes:

• The columns in to_move do not have to be contiguous.

mapping_move_columns(
    data_new_idxs: dict[int, int],
    disp_new_idxs: None | dict[int, int] = None,
    move_data: bool = True,
    create_selections: bool = True,
    data_indexes: bool = False,
    undo: bool = False,
    emit_event: bool = False,
    redraw: bool = True,
) -> tuple[dict[int, int], dict[int, int], EventDataDict]

Parameters:

• data_new_idxs (dict[int, int]) must be a dict where the keys are the data columns to move as ints and the values are their new locations as ints.
• disp_new_idxs (None | dict[int, int]) either None or a dict where the keys are the displayed columns (basically the column widths) to move as ints and the values are their new locations as ints. If None then no column widths will be moved.
• move_data when True moves not just the displayed column positions but the Sheet data as well.
• data_indexes is only applicable when there are hidden columns. When False it makes the move_to and to_move indexes represent displayed columns and not the underlying Sheet data columns. When True the indexes represent data indexes.
• create_selections creates new selection boxes based on where the columns have moved.
• undo when True adds the change to the Sheets undo stack.
• emit_event when True causes a "<<SheetModified>> event to occur if it has been bound, see here for more information.

Get a mapping (dict) of all old: new column indexes.

full_move_columns_idxs(data_idxs: dict[int, int]) -> dict[int, int]

• e.g. converts {0: 1} to {0: 1, 1: 0} if the maximum Sheet column number is 1.

mapping_move_rows(
    data_new_idxs: dict[int, int],
    disp_new_idxs: None | dict[int, int] = None,
    move_data: bool = True,
    data_indexes: bool = False,
    create_selections: bool = True,
    undo: bool = False,
    emit_event: bool = False,
    redraw: bool = True,
) -> tuple[dict[int, int], dict[int, int], EventDataDict]