• tksheet is a Python tkinter table and treeview widget written in pure python.
• It is licensed under theMIT 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 than7.0.0 then you will need the documentationhere instead.
  • In tksheet versions >=7.0.2 the current version will be at the top of the file__init__.py.

• Word wrap - Tabs and multiple spaces are rendered as a single space.
• Mac OS has both<2> and<3> bound for right click.
• When usingedit_validation() to validate cell edits and pasting into the sheet:
  • If the sheets rows are expanded then the row numbers under the keyrow andloc are data indexes whereas the column numbers are displayed indexes.
  • If the sheets columns are expanded then the column numbers under the keycolumn andloc are data indexes whereas the row numbers are displayed indexes.
  • This is only relevant when there are hidden rows or columns and you're usingedit_validation() and you're using the event data keysrow,column orloc in your boundedit_validation() function and you're using paste and the sheet can be expanded by paste.
• There may be some issues with toggle select mode and deselection.

Some examples of things that are not possible with tksheet:

• Due to the limitations of the Tkinter Canvas right-to-left (RTL) languages are not supported.
• Cell merging.
• Changing font for individual cells.
• 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 linepip install tksheet

#To install using pippipinstalltksheet#To update using pippipinstalltksheet--upgrade

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

• Versions<7.0.0 require a Python version of3.7 or higher.
• Versions>=7.0.0 require a Python version of3.8 or higher.

Like other tkinter widgets you need only theSheet()s parent as an argument to initialize aSheet() e.g.

sheet=Sheet(my_frame_widget)

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

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

fromtksheetimportSheetimporttkinterastkclassdemo(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"forcinrange(50)]forrinrange(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.

fromtksheetimportSheet,num2alphaimporttkinterastkclassdemo(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 widgetself.frame,# optional: set the Sheets data at initializationdata=[[f"Row{r}, Column{c}\nnewline1\nnewline2"forcinrange(20)]forrinrange(100)],theme="light green",height=520,width=1000,        )# enable various bindingsself.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:# #bind-and-validate-user-cell-editsself.sheet.edit_validation(self.validate_edits).bind("<<SheetModified>>",self.sheet_modified)# add some new commands to the in-built right click menu# setting dataself.sheet.popup_menu_add_command("Say Hello",self.say_hello,index_menu=False,header_menu=False,empty_space_menu=False,        )# getting dataself.sheet.popup_menu_add_command("Print some data",self.print_data,empty_space_menu=False,        )# overwrite Sheet dataself.sheet.popup_menu_add_command("Reset Sheet data",self.reset)# set the headerself.sheet.popup_menu_add_command("Set header data",self.set_header,table_menu=False,index_menu=False,empty_space_menu=False,        )# set the indexself.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")defvalidate_edits(self,event):# print (event)ifevent.eventname.endswith("header"):returnevent.value+" edited header"elifevent.eventname.endswith("index"):returnevent.value+" edited index"else:ifnotevent.value:return"EMPTY"returnevent.value[:3]defsay_hello(self):current_selection=self.sheet.get_currently_selected()ifcurrent_selection:box= (current_selection.row,current_selection.column)# set cell data, end user Undo enabled# more information at:# #setting-sheet-dataself.sheet[box].options(undo=True).data="Hello World!"# highlight the cell for 2 secondsself.highlight_area(box)defprint_data(self):forboxinself.sheet.get_all_selection_boxes():# get user selected area sheet data# more information at:# #getting-sheet-datadata=self.sheet[box].dataforrowindata:print(row)defreset(self):# overwrites sheet data, more information at:# #setting-sheet-dataself.sheet.set_sheet_data([[f"Row{r}, Column{c}\nnewline1\nnewline2"forcinrange(20)]forrinrange(100)])# reset header and indexself.sheet.headers([])self.sheet.index([])defset_header(self):self.sheet.headers(            [f"Header{(letter:=num2alpha(i))} -{i+1}\nHeader{letter} 2nd line!"foriinrange(20)]        )defset_index(self):self.sheet.set_index_width()self.sheet.row_index(            [f"Index{(letter:=num2alpha(i))} -{i+1}\nIndex{letter} 2nd line!"foriinrange(100)]        )defsheet_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:# #event-data# highlight the modified cells brieflyifevent.eventname.startswith("move"):forboxinself.sheet.get_all_selection_boxes():self.highlight_area(box)else:forboxinevent.selection_boxes:self.highlight_area(box)defhighlight_area(self,box,time=800):# highlighting an area of the sheet# more information at:# #highlighting-cellsself.sheet[box].bg="indianred1"self.after(time,lambda:self.clear_highlight(box))defclear_highlight(self,box):self.sheet[box].dehighlight()app=demo()app.mainloop()

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

def__init__(parent:tk.Misc,name:str="!sheet",show_table:bool=True,show_top_left:bool|None=None,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[Any]=None,header:None|list[Any]=None,row_index:None|list[Any]=None,index:None|list[Any]=None,default_header:Literal["letters","numbers","both"]|None="letters",default_row_index:Literal["letters","numbers","both"]|None="numbers",data_reference:None|Sequence[Sequence[Any]]=None,data:None|Sequence[Sequence[Any]]=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: E501startup_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=16,set_all_heights_and_widths:bool=False,zoom:int=100,align:str="nw",header_align:str="n",row_index_align:str|None=None,index_align:str="n",displayed_columns:list[int]|None=None,all_columns_displayed:bool=True,displayed_rows:list[int]|None=None,all_rows_displayed:bool=True,to_clipboard_dialect:csv.Dialect=csv.excel_tab,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",13ifUSER_OS=="darwin"else11,"normal",    ),header_font:tuple[str,int,str]=FontTuple("Calibri",13ifUSER_OS=="darwin"else11,"normal",    ),index_font:tuple[str,int,str]=FontTuple("Calibri",13ifUSER_OS=="darwin"else11,"normal",    ),# currently has no effectpopup_menu_font:tuple[str,int,str]=FontTuple("Calibri",13ifUSER_OS=="darwin"else11,"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="2",rounded_boxes:bool=True,alternate_color:str="",allow_cell_overflow:bool=False,# "" no wrap, "w" word wrap, "c" char wraptable_wrap:Literal["","w","c"]="c",index_wrap:Literal["","w","c"]="c",header_wrap:Literal["","w","c"]="c",sort_key:Callable=natural_sort_key,tooltips:bool=False,user_can_create_notes:bool=False,note_corners:bool=False,tooltip_width:int=210,tooltip_height:int=210,tooltip_hover_delay:int=1200,# colorsoutline_thickness:int=0,theme:str="light blue",outline_color:str=theme_light_blue["outline_color"],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_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"],vertical_scroll_borderwidth:int=1,horizontal_scroll_borderwidth:int=1,vertical_scroll_gripcount:int=0,horizontal_scroll_gripcount:int=0,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 widthvertical_scroll_arrowsize:str|int="",horizontal_scroll_arrowsize:str|int="",**kwargs,)->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 anint the columns will automatically resize to fit the width of the window, theint value being the minimum of each column in pixels.
• auto_resize_rows (int,None) if set as anint the rows will automatically resize to fit the height of the window, theint value being the minimum height of each row in pixels.
• startup_select selects cells, rows or columns at initialization by using atuple e.g.(0, 0, "cells") for cell A0 or(0, 5, "rows") for rows 0 to 5.
• data_reference anddata are essentially the same.
• row_index andindex are the same,index takes priority, same as withheaders andheader.
• 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 beints.
• auto_resize_row_index eitherTrue,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.
• Ifshow_selected_cells_border isFalse then the colors fortable_selected_box_cells_fg /table_selected_box_rows_fg /table_selected_box_columns_fg will be used for the currently selected cells background.
• Only setshow_top_left toTrue if you want to always show the top left rectangle of the sheet. Leave asNone to only show it when both the index and header are showing.
• For help withtreeview mode seehere.

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

• scrollbar_theme_inheritance andscrollbar_show_arrows will only work onSheet() initialization, not withset_options()

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

For the colors of specific parts of the table such as gridlines and backgrounds use the functionset_options(), keyword arguments specific to sheet colors are listed below. All the otherset_options() arguments can be foundhere.

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_bgtop_left_fgtop_left_fg_highlighttable_bgtable_grid_fgtable_fgtable_selected_box_cells_fgtable_selected_box_rows_fgtable_selected_box_columns_fgtable_selected_cells_border_fgtable_selected_cells_bgtable_selected_cells_fgtable_selected_rows_border_fgtable_selected_rows_bgtable_selected_rows_fgtable_selected_columns_border_fgtable_selected_columns_bgtable_selected_columns_fgheader_bgheader_border_fgheader_grid_fgheader_fgheader_selected_cells_bgheader_selected_cells_fgheader_selected_columns_bgheader_selected_columns_fgindex_bgindex_border_fgindex_grid_fgindex_fgindex_selected_cells_bgindex_selected_cells_fgindex_selected_rows_bgindex_selected_rows_fgresizing_line_fgdrag_and_drop_bgoutline_thicknessoutline_colorframe_bgpopup_menu_fontpopup_menu_fgpopup_menu_bgpopup_menu_highlight_bgpopup_menu_highlight_fg# scroll barsvertical_scroll_backgroundhorizontal_scroll_backgroundvertical_scroll_troughcolorhorizontal_scroll_troughcolorvertical_scroll_lightcolorhorizontal_scroll_lightcolorvertical_scroll_darkcolorhorizontal_scroll_darkcolorvertical_scroll_bordercolorhorizontal_scroll_bordercolorvertical_scroll_active_bghorizontal_scroll_active_bgvertical_scroll_not_active_bghorizontal_scroll_not_active_bgvertical_scroll_pressed_bghorizontal_scroll_pressed_bgvertical_scroll_active_fghorizontal_scroll_active_fgvertical_scroll_not_active_fghorizontal_scroll_not_active_fgvertical_scroll_pressed_fghorizontal_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 abovefunction 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 onSheet() initialization, others can be changed whenever usingset_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
    • WhenFalse 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 usingset_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 theSheet() initialization keyword argumentalternate_color (str) or
• Use theset_options() function with the keyword argumentalternate_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.

Refresh the table.

refresh(redraw_header:bool=True,redraw_row_index:bool=True)->Sheet

Refresh the table.

redraw(redraw_header:bool=True,redraw_row_index:bool=True)->Sheet

Refresh after idle (prevents multiple redraws).

set_refresh_timer(redraw:bool=True,index:bool=True,header:bool=True,)->Sheet

set_options(redraw:bool=True,**kwargs)->Sheet

Key word arguments available forset_options() (values are defaults):

"popup_menu_fg":"#000000","popup_menu_bg":"#FFFFFF","popup_menu_highlight_bg":"#DCDEE0","popup_menu_highlight_fg":"#000000","index_hidden_rows_expander_bg":"#747775","header_hidden_columns_expander_bg":"#747775","header_bg":"#FFFFFF","header_border_fg":"#C4C7C5","header_grid_fg":"#C4C7C5","header_fg":"#444746","header_editor_bg":"#FFFFFF","header_editor_fg":"#444746","header_editor_select_bg":"#cfd1d1","header_editor_select_fg":"#000000","header_selected_cells_bg":"#D3E3FD","header_selected_cells_fg":"black","index_bg":"#FFFFFF","index_border_fg":"#C4C7C5","index_grid_fg":"#C4C7C5","index_fg":"black","index_editor_bg":"#FFFFFF","index_editor_fg":"black","index_editor_select_bg":"#cfd1d1","index_editor_select_fg":"#000000","index_selected_cells_bg":"#D3E3FD","index_selected_cells_fg":"black","top_left_bg":"#F9FBFD","top_left_fg":"#d9d9d9","top_left_fg_highlight":"#747775","table_bg":"#FFFFFF","table_grid_fg":"#E1E1E1","table_fg":"black","table_editor_bg":"#FFFFFF","table_editor_fg":"black","table_editor_select_bg":"#cfd1d1","table_editor_select_fg":"#000000","table_selected_box_cells_fg":"#0B57D0","table_selected_box_rows_fg":"#0B57D0","table_selected_box_columns_fg":"#0B57D0","table_selected_cells_border_fg":"#0B57D0","table_selected_cells_bg":"#E6EFFD","table_selected_cells_fg":"black","resizing_line_fg":"black","drag_and_drop_bg":"#0B57D0","outline_color":"gray2","header_selected_columns_bg":"#0B57D0","header_selected_columns_fg":"#FFFFFF","index_selected_rows_bg":"#0B57D0","index_selected_rows_fg":"#FFFFFF","table_selected_rows_border_fg":"#0B57D0","table_selected_rows_bg":"#E6EFFD","table_selected_rows_fg":"black","table_selected_columns_border_fg":"#0B57D0","table_selected_columns_bg":"#E6EFFD","table_selected_columns_fg":"black","tree_arrow_fg":"black","selected_cells_tree_arrow_fg":"black","selected_rows_tree_arrow_fg":"#FFFFFF","vertical_scroll_background":"#FFFFFF","horizontal_scroll_background":"#FFFFFF","vertical_scroll_troughcolor":"#f9fbfd","horizontal_scroll_troughcolor":"#f9fbfd","vertical_scroll_lightcolor":"#FFFFFF","horizontal_scroll_lightcolor":"#FFFFFF","vertical_scroll_darkcolor":"gray50","horizontal_scroll_darkcolor":"gray50","vertical_scroll_relief":"flat","horizontal_scroll_relief":"flat","vertical_scroll_troughrelief":"flat","horizontal_scroll_troughrelief":"flat","vertical_scroll_bordercolor":"#f9fbfd","horizontal_scroll_bordercolor":"#f9fbfd","vertical_scroll_active_bg":"#bdc1c6","horizontal_scroll_active_bg":"#bdc1c6","vertical_scroll_not_active_bg":"#DADCE0","horizontal_scroll_not_active_bg":"#DADCE0","vertical_scroll_pressed_bg":"#bdc1c6","horizontal_scroll_pressed_bg":"#bdc1c6","vertical_scroll_active_fg":"#bdc1c6","horizontal_scroll_active_fg":"#bdc1c6","vertical_scroll_not_active_fg":"#DADCE0","horizontal_scroll_not_active_fg":"#DADCE0","vertical_scroll_pressed_fg":"#bdc1c6","horizontal_scroll_pressed_fg":"#bdc1c6","popup_menu_font":FontTuple("Calibri",13ifUSER_OS=="darwin"else11,"normal",),"table_font":FontTuple("Calibri",13ifUSER_OS=="darwin"else11,"normal",),"header_font":FontTuple("Calibri",13ifUSER_OS=="darwin"else11,"normal",),"index_font":FontTuple("Calibri",13ifUSER_OS=="darwin"else11,"normal",),# edit header"edit_header_label":"Edit header","edit_header_accelerator":"","edit_header_image":tk.PhotoImage(data=ICON_EDIT),"edit_header_compound":"left",# edit index"edit_index_label":"Edit index","edit_index_accelerator":"","edit_index_image":tk.PhotoImage(data=ICON_EDIT),"edit_index_compound":"left",# edit cell"edit_cell_label":"Edit cell","edit_cell_accelerator":"","edit_cell_image":tk.PhotoImage(data=ICON_EDIT),"edit_cell_compound":"left",# cut"cut_label":"Cut","cut_accelerator":"Ctrl+X","cut_image":tk.PhotoImage(data=ICON_CUT),"cut_compound":"left",# copy"copy_label":"Copy","copy_accelerator":"Ctrl+C","copy_image":tk.PhotoImage(data=ICON_COPY),"copy_compound":"left",# copy plain"copy_plain_label":"Copy text","copy_plain_accelerator":"Ctrl+Insert","copy_plain_image":tk.PhotoImage(data=ICON_COPY),"copy_plain_compound":"left",# paste"paste_label":"Paste","paste_accelerator":"Ctrl+V","paste_image":tk.PhotoImage(data=ICON_PASTE),"paste_compound":"left",# delete"delete_label":"Delete","delete_accelerator":"Del","delete_image":tk.PhotoImage(data=ICON_CLEAR),"delete_compound":"left",# clear contents"clear_contents_label":"Clear contents","clear_contents_accelerator":"Del","clear_contents_image":tk.PhotoImage(data=ICON_CLEAR),"clear_contents_compound":"left",# del columns"delete_columns_label":"Delete columns","delete_columns_accelerator":"","delete_columns_image":tk.PhotoImage(data=ICON_DEL),"delete_columns_compound":"left",# insert columns left"insert_columns_left_label":"Insert columns left","insert_columns_left_accelerator":"","insert_columns_left_image":tk.PhotoImage(data=ICON_ADD),"insert_columns_left_compound":"left",# insert columns right"insert_columns_right_label":"Insert columns right","insert_columns_right_accelerator":"","insert_columns_right_image":tk.PhotoImage(data=ICON_ADD),"insert_columns_right_compound":"left",# insert single column"insert_column_label":"Insert column","insert_column_accelerator":"","insert_column_image":tk.PhotoImage(data=ICON_ADD),"insert_column_compound":"left",# del rows"delete_rows_label":"Delete rows","delete_rows_accelerator":"","delete_rows_image":tk.PhotoImage(data=ICON_DEL),"delete_rows_compound":"left",# insert rows above"insert_rows_above_label":"Insert rows above","insert_rows_above_accelerator":"","insert_rows_above_image":tk.PhotoImage(data=ICON_ADD),"insert_rows_above_compound":"left",# insert rows below"insert_rows_below_label":"Insert rows below","insert_rows_below_accelerator":"","insert_rows_below_image":tk.PhotoImage(data=ICON_ADD),"insert_rows_below_compound":"left",# insert single row"insert_row_label":"Insert row","insert_row_accelerator":"","insert_row_image":tk.PhotoImage(data=ICON_ADD),"insert_row_compound":"left",# sorting# labels"sort_cells_label":"Sort Asc.","sort_cells_x_label":"Sort row-wise Asc.","sort_row_label":"Sort values Asc.","sort_column_label":"Sort values Asc.","sort_rows_label":"Sort rows Asc.","sort_columns_label":"Sort columns Asc.",# reverse labels"sort_cells_reverse_label":"Sort Desc.","sort_cells_x_reverse_label":"Sort row-wise Desc.","sort_row_reverse_label":"Sort values Desc.","sort_column_reverse_label":"Sort values Desc.","sort_rows_reverse_label":"Sort rows Desc.","sort_columns_reverse_label":"Sort columns Desc.",# accelerators"sort_cells_accelerator":"","sort_cells_x_accelerator":"","sort_row_accelerator":"","sort_column_accelerator":"","sort_rows_accelerator":"","sort_columns_accelerator":"",# reverse accelerators"sort_cells_reverse_accelerator":"","sort_cells_x_reverse_accelerator":"","sort_row_reverse_accelerator":"","sort_column_reverse_accelerator":"","sort_rows_reverse_accelerator":"","sort_columns_reverse_accelerator":"",# images"sort_cells_image":tk.PhotoImage(data=ICON_SORT_ASC),"sort_cells_x_image":tk.PhotoImage(data=ICON_SORT_ASC),"sort_row_image":tk.PhotoImage(data=ICON_SORT_ASC),"sort_column_image":tk.PhotoImage(data=ICON_SORT_ASC),"sort_rows_image":tk.PhotoImage(data=ICON_SORT_ASC),"sort_columns_image":tk.PhotoImage(data=ICON_SORT_ASC),# compounds"sort_cells_compound":"left","sort_cells_x_compound":"left","sort_row_compound":"left","sort_column_compound":"left","sort_rows_compound":"left","sort_columns_compound":"left",# reverse images"sort_cells_reverse_image":tk.PhotoImage(data=ICON_SORT_DESC),"sort_cells_x_reverse_image":tk.PhotoImage(data=ICON_SORT_DESC),"sort_row_reverse_image":tk.PhotoImage(data=ICON_SORT_DESC),"sort_column_reverse_image":tk.PhotoImage(data=ICON_SORT_DESC),"sort_rows_reverse_image":tk.PhotoImage(data=ICON_SORT_DESC),"sort_columns_reverse_image":tk.PhotoImage(data=ICON_SORT_DESC),# reverse compounds"sort_cells_reverse_compound":"left","sort_cells_x_reverse_compound":"left","sort_row_reverse_compound":"left","sort_column_reverse_compound":"left","sort_rows_reverse_compound":"left","sort_columns_reverse_compound":"left",# select all"select_all_label":"Select all","select_all_accelerator":"Ctrl+A","select_all_image":tk.PhotoImage(data=ICON_SELECT_ALL),"select_all_compound":"left",# undo"undo_label":"Undo","undo_accelerator":"Ctrl+Z","undo_image":tk.PhotoImage(data=ICON_UNDO),"undo_compound":"left",# redo"redo_label":"Redo","redo_accelerator":"Ctrl+Shift+Z","redo_image":tk.PhotoImage(data=ICON_REDO),"redo_compound":"left",# bindings"rc_bindings": ["<2>","<3>"]ifUSER_OS=="darwin"else ["<3>"],"copy_bindings": [f"<{ctrl_key}-c>",f"<{ctrl_key}-C>",],"copy_plain_bindings": [f"<{ctrl_key}-Insert>",],"cut_bindings": [f"<{ctrl_key}-x>",f"<{ctrl_key}-X>",],"paste_bindings": [f"<{ctrl_key}-v>",f"<{ctrl_key}-V>",],"undo_bindings": [f"<{ctrl_key}-z>",f"<{ctrl_key}-Z>",],"redo_bindings": [f"<{ctrl_key}-Shift-z>",f"<{ctrl_key}-Shift-Z>",],"delete_bindings": ["<Delete>",],"select_all_bindings": [f"<{ctrl_key}-a>",f"<{ctrl_key}-A>",f"<{ctrl_key}-Shift-space>",],"select_columns_bindings": ["<Control-space>",],"select_rows_bindings": ["<Shift-space>",],"row_start_bindings": ["<Command-Left>","<Home>",]ifUSER_OS=="darwin"else ["<Home>"],"table_start_bindings": [f"<{ctrl_key}-Home>",],"tab_bindings": ["<Tab>",],"up_bindings": ["<Up>",],"right_bindings": ["<Right>",],"down_bindings": ["<Down>",],"left_bindings": ["<Left>",],"shift_up_bindings": ["<Shift-Up>",],"shift_right_bindings": ["<Shift-Right>",],"shift_down_bindings": ["<Shift-Down>",],"shift_left_bindings": ["<Shift-Left>",],"prior_bindings": ["<Prior>",],"next_bindings": ["<Next>",],"find_bindings": [f"<{ctrl_key}-f>",f"<{ctrl_key}-F>",],"find_next_bindings": [f"<{ctrl_key}-g>",f"<{ctrl_key}-G>",],"find_previous_bindings": [f"<{ctrl_key}-Shift-g>",f"<{ctrl_key}-Shift-G>",],"toggle_replace_bindings": [f"<{ctrl_key}-h>",f"<{ctrl_key}-H>",],"escape_bindings": ["<Escape>",],# other"vertical_scroll_borderwidth":1,"horizontal_scroll_borderwidth":1,"vertical_scroll_gripcount":0,"horizontal_scroll_gripcount":0,"vertical_scroll_arrowsize":"","horizontal_scroll_arrowsize":"","set_cell_sizes_on_zoom":False,"auto_resize_columns":None,"auto_resize_rows":None,"to_clipboard_dialect":csv.excel_tab,"to_clipboard_delimiter":"\t","to_clipboard_quotechar":'"',"to_clipboard_lineterminator":"\n","from_clipboard_delimiters": ["\t"],"show_dropdown_borders":False,"show_default_header_for_empty":True,"show_default_index_for_empty":True,"default_header_height":"1","default_row_height":"1","default_column_width":120,"default_row_index_width":70,"default_row_index":"numbers","default_header":"letters","page_up_down_select_row":True,"paste_can_expand_x":False,"paste_can_expand_y":False,"paste_insert_column_limit":None,"paste_insert_row_limit":None,"arrow_key_down_right_scroll_page":False,"cell_auto_resize_enabled":True,"auto_resize_row_index":True,"max_undos":30,"column_drag_and_drop_perform":True,"row_drag_and_drop_perform":True,"empty_horizontal":50,"empty_vertical":50,"selected_rows_to_end_of_window":False,"horizontal_grid_to_end_of_window":False,"vertical_grid_to_end_of_window":False,"show_vertical_grid":True,"show_horizontal_grid":True,"display_selected_fg_over_highlights":False,"show_selected_cells_border":True,"edit_cell_tab":"right","edit_cell_return":"down","editor_del_key":"forward","treeview":False,"treeview_indent":"2","rounded_boxes":True,"alternate_color":"","allow_cell_overflow":False,"table_wrap":"c","header_wrap":"c","index_wrap":"c","min_column_width":1,"max_column_width":float("inf"),"max_header_height":float("inf"),"max_row_height":float("inf"),"max_index_width":float("inf"),"show_top_left":None,"sort_key":natural_sort_key,"tooltips":False,"user_can_create_notes":False,"note_corners":False,"tooltip_width":int=210,"tooltip_height":int=210,"tooltip_hover_delay":int=1200,

Notes:

• The parameters ending in_image taketk.PhotoImage or an empty string"" as types.
• The parameters ending in_compound take one of the following:"left", "right", "bottom", "top", "none", None.
• sort_key isCallable - a function.
• A dictionary can be provided toset_options() instead of using the keyword arguments, e.g.:

kwargs= {"copy_bindings": ["<Control-g>","<Control-G>",    ],"cut_bindings": ["<Control-c>","<Control-C>",    ],}sheet.set_options(**kwargs)

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

• value (iterable,int,Any) ifc is left asNone then it attempts to set the whole header as thevalue (converting a generator to a list). Ifvalue isint it sets the header to display the row with that position.
• c (iterable,int,None) if bothvalue andc are iterables it assumesc is an iterable of positions andvalue is an iterable of values and attempts to set each value to each position. Ifc isint it attempts to set the value at that position.

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

• Using an integerint for argumentnewheaders 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.
• Leavingnewheaders asNone and using theindex argument returns the existing header value in that index.
• Leaving all arguments as default e.g.headers() returns existing headers.

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

• value (iterable,int,Any) ifr is left asNone then it attempts to set the whole index as thevalue (converting a generator to a list). Ifvalue isint it sets the index to display the row with that position.
• r (iterable,int,None) if bothvalue andr are iterables it assumesr is an iterable of positions andvalue is an iterable of values and attempts to set each value to each position. Ifr isint it attempts to set the value at that position.

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

• Using an integerint for argumentnewindex 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.
• Leavingnewindex asNone and using theindex argument returns the existing row index value in that index.
• Leaving all arguments as default e.g.row_index() returns the existing row index.

You can set table, header and index text wrapping either atSheet() initialization or usingset_options().

Make use of the following parameters:

• table_wrap
• index_wrap
• header_wrap

With one of the following arguments:

• "" - For no text wrapping.
• "c" - For character wrapping.
• "w" - For word wrapping.

Examples:

# for word wrap at initializationmy_sheet=Sheet(parent,table_wrap="w")# for character wrap using set_options()my_sheet.set_options(table_wrap="c")

This setting only works for cells that are not center (north) aligned. Cell text can be set to overflow adjacent empty cells in the table like so:

Examples:

# for word wrap at initializationmy_sheet=Sheet(parent,allow_cell_overflow=True)# for character wrap using set_options()my_sheet.set_options(allow_cell_overflow=True)

• Set it toFalse to disable it.
• It is only available as a global setting for the table, not on a cell by cell basis.

enable_bindings(*bindings:Binding,menu:bool=True)

Parameters:

• bindings (str) options are (rc stands for right click):
  • "all" # enables all bindings withsingle_select mode, except the bindings that have to be specifically enabled by name.
  • "single_select" # normal selection mode
  • "toggle_select" # has issues but to enable a selection mode where cell/row/column selection is toggled
  • "drag_select" # to allow mouse click and drag selection of cells/rows/columns
    • "select_all" # drag_select also enables select_all
  • "column_drag_and_drop" /"move_columns" # to allow drag and drop of columns
  • "row_drag_and_drop" /"move_rows" # to allow drag and drop of rows
  • "column_select" # to allow column selection
  • "row_select" # to allow row selection
  • "column_width_resize" # for resizing columns
  • "double_click_column_resize" # for resizing columns to row text width
  • "row_width_resize" # to resize the index width
  • "column_height_resize" # to resize the header height
  • "arrowkeys" # all arrowkeys including page up and down
  • "up" # individual arrow key
  • "down" # individual arrow key
  • "left" # individual arrow key
  • "right" # individual arrow key
  • "prior" # page up
  • "next" # page down
  • "row_height_resize" # to resize rows
  • "double_click_row_resize" # for resizing rows to row text height
  • "right_click_popup_menu" /"rc_popup_menu" /"rc_menu" # for the in-built table context menu
  • "rc_select" # for selecting cells using right click
  • "rc_insert_column" # for a menu option to add columns
  • "rc_delete_column" # for a menu option to delete columns
  • "rc_insert_row" # for a menu option to add rows
  • "rc_delete_row" # for a menu option to delete rows
  • "sort_cells"
  • "sort_row"
  • "sort_column" /"sort_col"
  • "sort_rows"
  • "sort_columns" /"sort_cols"
  • "copy" # for copying to clipboard
  • "cut" # for cutting to clipboard
  • "paste" # for pasting into the table
  • "delete" # for clearing cells with the delete key
  • "undo" # for undo and redo
  • "edit_cell" # allow table cell editing
  • "find" # for a pop-up find window (does not find in index or header)
  • "replace" # additional functionality for the find window, replace and replace all
  • *"ctrl_click_select" /"ctrl_select" # for selecting multiple non-adjacent cells/rows/columns
  • *"edit_header" # allow header cell editing
  • *"edit_index" # allow index cell editing
  • *has to be specifically enabled - See Notes.
• menu(bool) whenTrue adds the related functionality to the in-built popup menu. Only applicable for edit bindings such as Cut, Copy, Paste and Delete which have both a keyboard binding and a menu entry.

Notes:

• You can change the Sheets key bindings for functionality such as copy, paste, up, down etc. Instructions can be foundhere.
• Note that the following functionalities are not enabled using"all" and have to be specifically enabled:
  • "ctrl_click_select" /"ctrl_select"
  • "edit_header"
  • "edit_index"
• 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 functionset_options().

Example:

• sheet.enable_bindings() to enable everything except"ctrl_select","edit_index","edit_header".

disable_bindings(*bindings:Binding)

Notes:

• Uses the same arguments asenable_bindings().

This function allows you to bindvery 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 editssee here.

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

There are several ways to use this function:

• bindings as astr andfunc as eitherNone or a function. UsingNone as an argument forfunc will effectively unbind the function.
  • extra_bindings("edit_cell", func=my_function)
• bindings as aniterable ofstrs andfunc as eitherNone or a function. UsingNone as an argument forfunc will effectively unbind the function.
  • extra_bindings(["all_select_events", "copy", "cut"], func=my_function)
• bindings as aniterable oflists ortuples with length of two, e.g.
  • extra_bindings([(binding, function), (binding, function), ...]) In this example you could also useNone in the place offunction to unbind the binding.
  • In this case the argfunc is totally ignored.
• For"end_..." events the bound function is run before the value is set.
• To unbind a function either setfunc argument toNone or leave it as default e.g.extra_bindings("begin_copy") to unbind"begin_copy".
• Even though undo/redo edits or adds or deletes rows/columns the bound functions for those actions will not be called. Undo/redo must be specifically bound in order for a function to be called.

bindings (str) options:

Undo/Redo:

• "begin_undo", "begin_ctrl_z"
• "ctrl_z", "end_undo", "end_ctrl_z", "undo"

Editing Individual Cells:

• "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"

Editing or Copying Multiple Cells:

• "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_delete_key", "begin_delete"
• "delete_key", "end_delete", "end_delete_key", "delete"
• "replace_all"

Moving:

• "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_sort_cells"
• "sort_cells", "end_sort_cells"
• "begin_sort_rows"
• "sort_rows", "end_sort_rows"
• "begin_sort_columns"
• "sort_columns", "end_sort_columns"

Deleting:

• "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"

Adding:

• "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", "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", "add_rows"

Resizing rows/columns:

• "row_height_resize"
• "column_width_resize"

Selection:

• "cell_select"
• "all_select"
• "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"

Event collections:

• "all_select_events", "select", "selectevents", "select_events"
• "all_modified_events", "sheetmodified", "sheet_modified" "modified_events", "modified"
• "bind_all"
• "unbind_all"

Further Notes:

• 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, examplehere.

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

for (row,column),old_valueinevent.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:

• A function bound usingextra_bindings() will receive event data with one of the following["eventname"] keys:

  • "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"
  • "select"
  • "resize"
  • *"begin_move_rows"
  • *"end_move_rows"
  • *"begin_move_columns"
  • *"end_move_columns"

• *is also used as the event name for sorting rows/columns events.

• EventDataDicts will otherwise have one of the following event names:

  • "edit_table" when a user has cut, paste, delete or made 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 OR sorted columns.
  • "move_rows" when a user has dragged and dropped OR sorted rows.
  • "select"
  • "resize"

• These event names would be used for"<<SheetModified>>" bound events for example.

• For events"begin_move_columns"/"begin_move_rows" the point where columns/rows will be moved to will be under theevent_data key"value".

• Key["sheetname"] is thename 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 adict withtuple keys of(data row index: int, data column index: int) and the values will be the cell values at that locationprior to the change. Thedict 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 adict with keys ofint: data column index and the values will be the cell values at that locationprior to the change. Thedict 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 adict with keys ofint: data row index and the values will be the cell values at that locationprior to the change. Thedict 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 adict with the following keys:

  • {"data": {old data index: new data index, ...}, "displayed": {old displayed index: new displayed index, ...}}
    • "data" will be adict 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 adict 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 thedict 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 usingSheet.data_r().
  • For events"begin_move_rows" the point where rows will be moved to will be under theevent_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 adict with the following keys:

  • {"data": {old data index: new data index, ...}, "displayed": {old displayed index: new displayed index, ...}}
    • "data" will be adict 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 adict 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 thedict 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 usingSheet.data_c().
  • For events"begin_move_columns" the point where columns will be moved to will be under theevent_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 adict with the following keys:

  • {"data_index": int, "displayed_index": int, "num": int, "displayed": []}
    • "data_index" is anint representing the row where the rows were added in the data.
    • "displayed_index" is anint 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 a copied list of theSheet()s displayed rows immediately prior to the change.
    • If no rows have been added thedict 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 adict with the following keys:

  • {"data_index": int, "displayed_index": int, "num": int, "displayed": []}
    • "data_index" is anint representing the column where the columns were added in the data.
    • "displayed_index" is anint 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 a copied list of theSheet()s displayed columns immediately prior to the change.
    • If no columns have been added thedict 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 adict. Thisdict 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 thedict 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 adict. Thisdict 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 thedict 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 adict. Thisdict 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 thedict 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 adict. Thisdict 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 thedict 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 adict. Thisdict will look like the following:

  • {[column data index]: column width, [column data index]: column width, ...}
  • If no columns have been deleted then thedict 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 adict. Thisdict will look like the following:

  • {[row data index]: row height, [row data index]: row height, ...}
  • If no rows have been deleted then thedict 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 alist. Thislist 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 alist. Thislist stores the displayed rows (the rows that are showing when others are hidden) immediately prior to the change.

• Key["named_spans"] Thisdict serves as storage for theSheet()s named spans. Each value in thedict is a pickledspan object.

• Key["options"] This serves as storage for theSheet()s options such as highlights, formatting, alignments, dropdown boxes, check boxes etc. It is adict where the values are the sheets internal cell/row/column optionsdicts.

• Key["selection_boxes"] the value of this is all selection boxes on the sheet in the form of adict 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 areints and the selection box type is astr either"cells","rows" or"columns".
  • Thedict will be empty if there is nothing selected.

• Key["selected"] the value of this when there is something selected on the sheet is anamedtuple. The values of which can be foundhere.

  • When nothing is selected or the event is not relevant to the currently selected box, such as a resize event it will be an emptytuple.

• 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 astr either"cells","rows" or"columns".
  • If no box is in the process of being created then this will be a an emptytuple.
  • See here for an example.

• Key["data"] -dict[tuple[int, int], Any] - changed from only being used by paste, now stores adict of cell coordinates and values that make up a table edit event of more than one cell.

• 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 hittingReturn. It also used by"begin_move_columns"/"begin_move_rows" - the point where columns/rows will be moved to will be under theevent_data key"value".

• Key["loc"] is for cell editing events to show the displayed (not data) coordinates of the event. It will beeither:

  • A tuple of(int displayed row index, int displayed column index) in the case of editing table cells.
  • A singleint in the case of editing index/header cells.

• Key["row"] is for cell editing events to show the displayed (not data) row numberint of the event. If the event was not a cell editing event or a header cell was edited the value will beNone.

• Key["column"] is for cell editing events to show the displayed (not data) column numberint of the event. If the event was not a cell editing event or an index cell was edited the value will beNone.

• Key["resized"]["rows"] is for row height resizing events, it will be adict 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 emptydict.

• Key["resized"]["columns"] is for column width resizing events, it will be adict 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 emptydict.

• Key["widget"] will contain the widget which emitted the event, either theMainTable(),ColumnHeaders() orRowIndex() which are alltk.Canvas widgets.

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

Edit validation

This function will be called for every cell edit in an action.

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 likethis orNone which unbinds the function.

Notes:

• If your bound function returnsNone then that specific cell edit will not be performed.
• For examples of this function seehere andhere.

Bulk edit validation

This function will be called at the end of an action and delay any edits until after validation.

bulk_table_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 likethis orNone which unbinds the function.

Notes:

• See the below example for more information on usage.

Example:

fromtksheetimportSheetimporttkinterastkfromtypingimportAnyclassdemo(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}"forcinrange(3)]forrinrange(3)],        )self.sheet.enable_bindings()self.sheet.bulk_table_edit_validation(self.validate)self.frame.grid(row=0,column=0,sticky="nswe")self.sheet.grid(row=0,column=0,sticky="nswe")defvalidate(self,event:dict)->Any:"""        Whatever keys and values are left in event["data"]        when the function returns are the edits that will be made        An example below shows preventing edits if the proposed edit        contains a space        But you can also modify the values, or add more key, value        pairs to event["data"]        """not_valid=set()for (r,c),valueinevent.data.items():if" "invalue:not_valid.add((r,c))event.data= {k:vfork,vinevent.data.items()ifknotinnot_valid}app=demo()app.mainloop()

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,image:tk.PhotoImage|Literal[""]="",compound:Literal["top","bottom","left","right","none"]|None=None,accelerator:str|None=None,)->Sheet

Notes:

• Either creates or overwrites an existing menu command.

Example:

self.sheet.popup_menu_add_command(label="Test insert rows",func=self.my_fn,image=tk.PhotoImage(file="filepath_to_img.png"),compound="left",)

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

• Iflabel isNone then it removes all.

basic_bindings(enable:bool=False)->Sheet

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

cut(event:Any=None)->Sheetcopy(event:Any=None)->Sheetpaste(event:Any=None)->Sheetdelete(event:Any=None)->Sheetundo(event:Any=None)->Sheetredo(event:Any=None)->Sheetzoom_in()->Sheetzoom_out()->Sheet

@propertydefevent()->EventDataDict

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

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

• With theSheet.bind() function you can bind things in the usual way you would in tkinter and they will bind to all thetksheet canvases.
• There are also the following specialtksheet 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 bytksheet.
• 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 datadict 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 adict argument which will be the same asthe 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 made 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.
    • "sort_rows" when rows have been re-ordered by sorting.
    • "sort_columns" when columns have been re-ordered by sorting.
  • "<<SheetRedrawn>>" emitted whenever the sheet GUI was refreshed (redrawn). The data for this event will be different than the usual event data, it is:
    • {"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 theeventname"copy".
  • "<<Cut>>"
  • "<<Paste>>"
  • "<<Delete>>" emitted when a Sheet delete key function was performed.
  • "<<SelectAll>>"
  • "<<Undo>>"
  • "<<Redo>>"

Example:

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

Example forevent_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 thebind() 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.

Please note that due to the limitations of the Tkinter Canvas tksheet doesn’t support right-to-left (RTL) languages.

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

# edit header"edit_header_label":"Edit header","edit_header_accelerator":"","edit_header_image":tk.PhotoImage(data=ICON_EDIT),"edit_header_compound":"left",# edit index"edit_index_label":"Edit index","edit_index_accelerator":"","edit_index_image":tk.PhotoImage(data=ICON_EDIT),"edit_index_compound":"left",# edit cell"edit_cell_label":"Edit cell","edit_cell_accelerator":"","edit_cell_image":tk.PhotoImage(data=ICON_EDIT),"edit_cell_compound":"left",# cut"cut_label":"Cut","cut_accelerator":"Ctrl+X","cut_image":tk.PhotoImage(data=ICON_CUT),"cut_compound":"left",# copy"copy_label":"Copy","copy_accelerator":"Ctrl+C","copy_image":tk.PhotoImage(data=ICON_COPY),"copy_compound":"left",# copy plain"copy_plain_label":"Copy text","copy_plain_accelerator":"Ctrl+Insert","copy_plain_image":tk.PhotoImage(data=ICON_COPY),"copy_plain_compound":"left",# paste"paste_label":"Paste","paste_accelerator":"Ctrl+V","paste_image":tk.PhotoImage(data=ICON_PASTE),"paste_compound":"left",# delete"delete_label":"Delete","delete_accelerator":"Del","delete_image":tk.PhotoImage(data=ICON_CLEAR),"delete_compound":"left",# clear contents"clear_contents_label":"Clear contents","clear_contents_accelerator":"Del","clear_contents_image":tk.PhotoImage(data=ICON_CLEAR),"clear_contents_compound":"left",# del columns"delete_columns_label":"Delete columns","delete_columns_accelerator":"","delete_columns_image":tk.PhotoImage(data=ICON_DEL),"delete_columns_compound":"left",# insert columns left"insert_columns_left_label":"Insert columns left","insert_columns_left_accelerator":"","insert_columns_left_image":tk.PhotoImage(data=ICON_ADD),"insert_columns_left_compound":"left",# insert columns right"insert_columns_right_label":"Insert columns right","insert_columns_right_accelerator":"","insert_columns_right_image":tk.PhotoImage(data=ICON_ADD),"insert_columns_right_compound":"left",# insert single column"insert_column_label":"Insert column","insert_column_accelerator":"","insert_column_image":tk.PhotoImage(data=ICON_ADD),"insert_column_compound":"left",# del rows"delete_rows_label":"Delete rows","delete_rows_accelerator":"","delete_rows_image":tk.PhotoImage(data=ICON_DEL),"delete_rows_compound":"left",# insert rows above"insert_rows_above_label":"Insert rows above","insert_rows_above_accelerator":"","insert_rows_above_image":tk.PhotoImage(data=ICON_ADD),"insert_rows_above_compound":"left",# insert rows below"insert_rows_below_label":"Insert rows below","insert_rows_below_accelerator":"","insert_rows_below_image":tk.PhotoImage(data=ICON_ADD),"insert_rows_below_compound":"left",# insert single row"insert_row_label":"Insert row","insert_row_accelerator":"","insert_row_image":tk.PhotoImage(data=ICON_ADD),"insert_row_compound":"left",# sorting# labels"sort_cells_label":"Sort Asc.","sort_cells_x_label":"Sort row-wise Asc.","sort_row_label":"Sort values Asc.","sort_column_label":"Sort values Asc.","sort_rows_label":"Sort rows Asc.","sort_columns_label":"Sort columns Asc.",# reverse labels"sort_cells_reverse_label":"Sort Desc.","sort_cells_x_reverse_label":"Sort row-wise Desc.","sort_row_reverse_label":"Sort values Desc.","sort_column_reverse_label":"Sort values Desc.","sort_rows_reverse_label":"Sort rows Desc.","sort_columns_reverse_label":"Sort columns Desc.",# accelerators"sort_cells_accelerator":"","sort_cells_x_accelerator":"","sort_row_accelerator":"","sort_column_accelerator":"","sort_rows_accelerator":"","sort_columns_accelerator":"",# reverse accelerators"sort_cells_reverse_accelerator":"","sort_cells_x_reverse_accelerator":"","sort_row_reverse_accelerator":"","sort_column_reverse_accelerator":"","sort_rows_reverse_accelerator":"","sort_columns_reverse_accelerator":"",# images"sort_cells_image":tk.PhotoImage(data=ICON_SORT_ASC),"sort_cells_x_image":tk.PhotoImage(data=ICON_SORT_ASC),"sort_row_image":tk.PhotoImage(data=ICON_SORT_ASC),"sort_column_image":tk.PhotoImage(data=ICON_SORT_ASC),"sort_rows_image":tk.PhotoImage(data=ICON_SORT_ASC),"sort_columns_image":tk.PhotoImage(data=ICON_SORT_ASC),# compounds"sort_cells_compound":"left","sort_cells_x_compound":"left","sort_row_compound":"left","sort_column_compound":"left","sort_rows_compound":"left","sort_columns_compound":"left",# reverse images"sort_cells_reverse_image":tk.PhotoImage(data=ICON_SORT_DESC),"sort_cells_x_reverse_image":tk.PhotoImage(data=ICON_SORT_DESC),"sort_row_reverse_image":tk.PhotoImage(data=ICON_SORT_DESC),"sort_column_reverse_image":tk.PhotoImage(data=ICON_SORT_DESC),"sort_rows_reverse_image":tk.PhotoImage(data=ICON_SORT_DESC),"sort_columns_reverse_image":tk.PhotoImage(data=ICON_SORT_DESC),# reverse compounds"sort_cells_reverse_compound":"left","sort_cells_x_reverse_compound":"left","sort_row_reverse_compound":"left","sort_column_reverse_compound":"left","sort_rows_reverse_compound":"left","sort_columns_reverse_compound":"left",# select all"select_all_label":"Select all","select_all_accelerator":"Ctrl+A","select_all_image":tk.PhotoImage(data=ICON_SELECT_ALL),"select_all_compound":"left",# undo"undo_label":"Undo","undo_accelerator":"Ctrl+Z","undo_image":tk.PhotoImage(data=ICON_UNDO),"undo_compound":"left",# redo"redo_label":"Redo","redo_accelerator":"Ctrl+Shift+Z","redo_image":tk.PhotoImage(data=ICON_REDO),"redo_compound":"left",

Example:

# changing the copy label to the spanish for Copysheet.set_options(copy_label="Copiar",copy_image=tk.PhotoImage(file="filepath_to_img.png"),copy_compound="left")

Notes:

• To remove theCopy plain right click menu option when copy is enabled you can overwrite it, e.g.

fromtksheetimport (ICON_COPY,Sheet,ctrl_key,)# ...self.sheet.set_options(copy_plain_label="Copy",copy_plain_accelerator="Ctrl+C",copy_plain_image=tk.PhotoImage(data=ICON_COPY),copy_plain_compound="left",copy_plain_bindings=[f"<{ctrl_key}-c>",f"<{ctrl_key}-C>",    ],)

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

copy_bindingscut_bindingspaste_bindingsundo_bindingsredo_bindingsdelete_bindingsselect_all_bindingsselect_columns_bindingsselect_rows_bindingsrow_start_bindingstable_start_bindingstab_bindingsup_bindingsright_bindingsdown_bindingsleft_bindingsshift_up_bindingsshift_right_bindingsshift_down_bindingsshift_left_bindingsprior_bindingsnext_bindingsfind_bindingsfind_next_bindingsfind_previous_bindingsescape_bindingstoggle_replace_bindings

The argument must be alist oftkinter bindingstrs. In the below example the binding for copy is changed to"<Control-e>" and"<Control-E>".

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

The default values for these bindings can be found in the tksheet filesheet_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__importannotationsimporttkinterastkfromtksheetimportSheetclassdemo(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}"forcinrange(5)]forrinrange(5)],        )self.sheet.enable_bindings()self.sheet.grid(row=0,column=0,sticky="nswe")self.bind_all("<Key>",self.any_key)defany_key(self,event:tk.Event)->None:"""        Establish that the Control key is held down        """ctrl= (event.state&4>0)ifnotctrl: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()

Intksheet versions >7 there are functions which utilise an object namedSpan. These objects are a subclass ofdict but with various additions and dot notation attribute access.

Spans basically represent ancontiguous area of the sheet. They can beone of threekinds:

• "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 theSheet() 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 ashighlight,format, etc.

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

You can create a span by:

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

or

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

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:Callable|None=None,undo:bool=True,emit_event:bool=False,widget:Any=None,expand:None|str=None,formatter_options:dict|None=None,**kwargs,)->Span"""Create a span / get an existing span by nameReturns the created span"""

Parameters:

• key you do not have to provide an argument forkey, if no argument is provided then the span will be a full sheet span. Otherwisekey can be the following types which are type hinted asCreateSpanTypes:
  • 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 ofrow, column e.g.sheet.span(0, 0)
  • Sequence[Sequence[int | None, int | None], Sequence[int | None, int | None]] representingsheet.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.gsheet.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) whenTrue will make all functions used with the span target the main table as well as the header/index if those areTrue.
• index (bool) whenTrue will make all functions used with the span target the index as well as the table/header if those areTrue.
• header (bool) whenTrue will make all functions used with the span target the header as well as the table/index if those areTrue.
• tdisp (bool) is used by data getting functions that utilize spans and whenTrue 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 whenTrue 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 whenTrue 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. WhenTrue:
  • 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 either0 or1 or2.
  • 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 theconvert function will be as it was before normally returning (afterndim has potentially modified it).
• undo (bool) is used by data modifying functions that utilize spans. WhenTrue and if undo is enabled for the sheet then the end user will be able to undo/redo the modification.
• emit_event whenTrue and when using data setting functions that utilize spans causes a"<<SheetModified>> event to occur if it has been bound, seehere for more information on binding this event.
• widget (Any) 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 eitherNone 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 tablex axis.
  • "down" expand the span downwards to the bottom of the tabley axis.
• formatter_options (dict,None) must be eitherNone ordict. If providing adict it must be the same structure as used in format functions, seehere for more information. Used to turn the span into a format type span which:
  • When usingget_data() will format the returned data.
  • When usingset_data() will format the data being set butNOT create a new formatting rule on the sheet.
• **kwargs you can provide additional keyword arguments to the function for example those used inspan.highlight() orspan.dropdown() which are used when applying a named span to a table.

Notes:

• To create a named span seehere.

When creating a span using the below methods:

• strs use excel syntax and the indexing rule of up toAND including.
• ints use python syntax and the indexing rule of up to butNOT including.

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

If you need to convert python indexes into column letters you can use the functionnum2alpha importable fromtksheet:

fromtksheetimport (Sheet,num2alphaasn2a,)# column index five as a lettern2a(5)

span=sheet[0,0]# cell A1span=sheet[(0,0)]# cell A1span=sheet["A1:C1"]# cells A1, B1, C1span=sheet[0,0,1,3]# cells A1, B1, C1span=sheet[(0,0,1,3)]# cells A1, B1, C1span=sheet[(0,0), (1,3)]# cells A1, B1, C1span=sheet[((0,0), (1,3))]# cells A1, B1, C1span=sheet["A1:2"]span=sheet[0,0,2,None]"""["A1:2"]All the cells starting from (0, 0)expanding down to include row 1but not including cells beyond row1 and expanding out to include allcolumns    A   B   C   D1   x   x   x   x2   x   x   x   x34..."""span=sheet["A1:B"]span=sheet[0,0,None,2]"""["A1:B"]All the cells starting from (0, 0)expanding out to include column 1but not including cells beyond column1 and expanding down to include allrows    A   B   C   D1   x   x2   x   x3   x   x4   x   x..."""

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

span=sheet[None,0,None,1]# first columnspan=sheet["A"]# first columnspan=sheet[None,0,None,2]# only first two columnsspan=sheet["A:B"]# only first two columnsspan=sheet[None,2,None,None]# from the third columnspan=sheet["C:"]# from the third columnspan=sheet[None,0,None,None]# entire sheetspan=sheet["A:"]# entire sheet

Header only span

span=sheet[None,0,None,1].options(table=False,header=True)# first column header only

Index only span

span=sheet[0].options(table=False,index=True)# first row index only

The same arguments as shown forcell,row andcolumn span creation using square brackets can also be used for creating spans using theSheet.span() function. e.g:

• span = sheet.span(0, 0) # cell A1
• span = sheet.span(0) # first row
• span = sheet.span(None, 0, None, 1) # first column

More examples below:

"""EXAMPLES USING span()""""""USING NO ARGUMENTS"""sheet.span()# entire sheet, in this case not including header or index"""USING ONE ARGUMENTstr or int or slice()"""# with one argument you can use the same string syntax used for square bracket span creationsheet.span("A1")sheet.span(0)# row at python index 0, all columnssheet.span(slice(0,2))# rows at python indexes 0 and 1, all columnssheet.span(":")# entire sheet"""USING TWO ARGUMENTSint | None, int | Noneor(int | None, int | None), (int | None, int | None)"""sheet.span(0,0)# row 0, column 0 - the first cellsheet.span(0,None)# row 0, all columnssheet.span(None,0)# column 0, all rowssheet.span((0,0), (1,1))# row 0, column 0 - the first cellsheet.span((0,0), (None,2))# rows 0 - end, columns 0 and 1"""USING FOUR ARGUMENTSint | None, int | None, int | None, int | None"""sheet.span(0,0,1,1)# row 0, column 0 - the first cellsheet.span(0,0,None,2)# rows 0 - end, columns 0 and 1

""" 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>"]

Spans have a few@property functions:

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

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 tksheetprint (sheet[num2alpha(0)].kind)# prints "column"

span.rowsspan.columns

Returns aSpanRange object. The below examples are forspan.rows but you can usespan.columns for the spans columns exactly the same way.

# use as an iteratorspan=sheet.span("A1:C4")forrowinspan.rows:pass# use as a reversed iteratorforrowinreversed(span.rows):pass# check row membershipspan=sheet.span("A1:C4")print (2inspan.rows)# prints True# check span.rows equality, also can do not equalspan=self.sheet["A1:C4"]span2=self.sheet["1:4"]print (span.rows==span2.rows)# prints True# check lenspan=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:Any=None,expand:str|None=None,formatter_options:dict|None=None,**kwargs,)->Span

Note that ifNone is used for any of the following parameters then thatSpans attribute will be unchanged:

• type_ (str,None) if notNone 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) whenTrue will make all functions used with the span target the main table as well as the header/index if those areTrue.
• index (bool,None) whenTrue will make all functions used with the span target the index as well as the table/header if those areTrue.
• header (bool,None) whenTrue will make all functions used with the span target the header as well as the table/index if those areTrue.
• tdisp (bool,None) is used by data getting functions that utilize spans and whenTrue 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 whenTrue 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 whenTrue 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. WhenTrue:
  • 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 either0 or1 or2.
  • 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 theconvert function will be as it was before normally returning (afterndim has potentially modified it).
• undo (bool,None) is used by data modifying functions that utilize spans. WhenTrue 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. WhenTrue causes a"<<SheetModified>> event to occur if it has been bound, seehere for more information.
• widget (Any) 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 eitherNone 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 tablex axis.
  • "down" expand the span downwards to the bottom of the tabley axis.
• formatter_options (dict,None) must be eitherNone ordict. If providing adict it must be the same structure as used in format functions, seehere for more information. Used to turn the span into a format type span which:
  • When usingget_data() will format the returned data.
  • When usingset_data() will format the data being set butNOT create a new formatting rule on the sheet.
• **kwargs you can provide additional keyword arguments to the function for example those used inspan.highlight() orspan.dropdown() which are used when applying a named span to a table.
• This function returns the span instance itself (self).

# entire sheetspan=sheet["A1"].options(expand="both")# column Aspan=sheet["A1"].options(expand="down")# row 0span=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 positiveint.
• from_c (int) represents which column the span starts at, must be a positiveint.
• upto_r (int,None) represents which row the span ends at, must be a positiveint orNone.None means always up to and including the last row.
• upto_c (int,None) represents which column the span ends at, must be a positiveint orNone.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) whenTrue will make all functions used with the span target the main table as well as the header/index if those areTrue.
• index (bool) whenTrue will make all functions used with the span target the index as well as the table/header if those areTrue.
• header (bool) whenTrue will make all functions used with the span target the header as well as the table/index if those areTrue.
• tdisp (bool) is used by data getting functions that utilize spans and whenTrue 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 whenTrue 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 whenTrue 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. WhenTrue:
  • 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 either0 or1 or2.
  • 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 theconvert function will be as it was before normally returning (afterndim has potentially modified it).
• undo (bool) is used by data modifying functions that utilize spans. WhenTrue 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. WhenTrue causes a"<<SheetModified>> event to occur if it has been bound, seehere for more information.
• widget (Any) 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 adict containing keyword arguments relevant for functions such asspan.highlight() orspan.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 Aspan=self.sheet("A")span.upto_c=None# span now adds to sheets undo stack when using data modifying functions that use spansspan=self.sheet("A")span.undo=True

Formats table data, see the help onformatting 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:Any=None,redraw:bool=True,**kwargs,)->Span

Example:

# using square bracketssheet[:].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) asint 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, seeNamed 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 blacksheet["A"].highlight(bg="red",fg="black")# the same but after having saved a spanmy_span=sheet["A"]my_span.highlight(bg="red",fg="black")

Method 2 example using.bg/.fg:

# highlights column A background red, text color blacksheet["A"].bg="red"sheet["A"].fg="black"# the same but after having saved a spanmy_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, seeNamed 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 seehere.

span.dropdown(values:list= [],set_value:Any=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, seeNamed 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 whenTrue edits the underlying cell data to eitherchecked ifchecked is abool or tries to convert the existing cell data to abool.
• checked is the initial creation value to set the box to, ifNone then andedit_data isTrue then it will try to convert the underlying cell data to abool.
• 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 beTrue orFalse.

Notes:

• To get the current checkbox value either:
  • Get the cell data, more informationhere.
  • Use the parametercheck_function with a function of your own creation to be called when the checkbox is set by the user.

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, seeNamed 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

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

Create/delete notes for cells, rows or columns for parts of the table that are covered by the span. Seehere for more information on Notes.

span.note(note:str|None=None,readonly:bool=True)->Span

• Usingspan.note() orspan.note(None) deletes any existing notes for the span.

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 alignmentsheet["D"].align("right")# the same but after having saved a spanmy_span=sheet["D"]my_span.align("right")

Method 2 example using.align =:

# column D right text alignmentsheet["D"].align="right"# the same but after having saved a spanmy_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, seeNamed 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) WhenTrue if undo is enabled for the end user they will be able to undo the clear change.
• emit_event whenTrue causes a"<<SheetModified>> event to occur if it has been bound, seehere for more information.

Example:

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

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

tag(*tags)->Span

Notes:

• Ifspan.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")

Removeall tags from cells, rows or columns depending on the spans kind, more information on tagshere.

untag()->Span

Notes:

• Ifspan.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, 4sheet[2:5].untag()

The attributespan.transposed (bool) is used by data getting and setting functions that utilize spans. WhenTrue:- 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 alreadyTrue this makes itFalse and vice versa.

span=sheet["A:D"].transpose()# this span is now transposedprint (span.transposed)# prints Truespan.transpose()# this span is no longer transposedprint (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 eitherNone 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 inspan.kwargs and then created by using aSheet() function. Like spans, named spans are alsocontiguous 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 wouldNOT 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 withNones or the start of0 and no end or end ofNone.

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 followingtype_s:"format","highlight","dropdown","checkbox","readonly","align".
• Relevant keyword arguments e.g. if thetype_ is"highlight" then arguments forsheet.highlight() foundhere.

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 sheetReturns the span"""

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

Examples of creating named spans:

# Will highlight rows 3 up to and including 5span1=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 insertedspan2=self.sheet.span(":",# you don't have to provide a `type_` when using the `formatter_kwargs` argumentformatter_options=int_formatter(),)self.sheet.named_span(span2)

del_named_span(name:str)

Example, creating and deleting a span:

# span covers the entire sheetself.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 existself.sheet.del_named_span("this name doesnt exist")# ValueError: Span 'this name doesnt exist' does not exist.

Sets theSheets internal dict of named spans:

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

• UsingNone 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

ASpan object (more informationhere) is returned when using square brackets on aSheet like so:

span=self.sheet["A1"]

You can also usesheet.span():

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

The above spans represent the cellA1 - row 0, column 0.

A reserved span attribute nameddata can then be used to retrieve the data for cellA1, 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 usespan.value to the same effect.

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

• table (bool) whenTrue will make all functions used with the span target the main table as well as the header/index if those areTrue.
• index (bool) whenTrue will make all functions used with the span target the index as well as the table/header if those areTrue.
• header (bool) whenTrue will make all functions used with the span target the header as well as the table/index if those areTrue.
• tdisp (bool) whenTrue the function retrieves screen displayed data for the table, not underlying cell data.
• idisp (bool) whenTrue the function retrieves screen displayed data for the index, not underlying cell data.
• hdisp (bool) whenTrue 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. WhenTrue:
  • Returned sublists fromdata 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 either0 or1 or2.
  • 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 theconvert function will be as it was before normally returning (afterndim has potentially modified it).
• widget (Any) 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.