tkinter is a Python packages that wraps the Tk GUI toolkit.
tkinter is included with Python and so is available to use without needing to install any additional packages.
User interfaces developed using Tk can be hosted in Excel Custom Task Panes as docked or floating windows within Excel. If instead you want the control embedded directly on the Excel worksheet, see ActiveX Controls.
This document is not a guide to use tkinter. It is only intended to instruct you on how to use Tkinter with the Custom Task Pane feature of PyXLL. You should refer to the tkinter documentation for details of how to use tkinter.
You can find more information about tkinter in the Python docs website https://docs.python.org/3/library/tkinter.html.
One of the main classes in tkinter is the Frame
class. To create your own user interface it
is this Frame
class that you will use, and it’s what PyXLL will embed into Excel as
a Custom Task Pane.
The following code demonstrates how to create simple tkinter.Frame
. If you run this
code as a Python script then you will see the frame being shown.
import tkinter as tk
class ExampleFrame(tk.Frame):
def __init__(self, master):
super().__init__(master)
self.initUI()
def initUI(self):
# allow the widget to take the full space of the root window
self.pack(fill=tk.BOTH, expand=True)
# Create a tk.Entry control and place it using the 'grid' method
self.entry_value = tk.StringVar()
self.entry = tk.Entry(self, textvar=self.entry_value)
self.entry.grid(column=0, row=0, padx=10, pady=10, sticky="ew")
# Create a tk.Label control and place it using the 'grid' method
self.label_value = tk.StringVar()
self.label = tk.Label(self, textvar=self.label_value)
self.label.grid(column=0, row=1, padx=10, pady=10, sticky="w")
# Bind write events on the 'entry_value' to our 'onWrite' method
self.entry_value.trace("w", self.onWrite)
# Allow the first column in the grid to stretch horizontally
self.columnconfigure(0, weight=1)
def onWrite(self, *args):
"""Called when the tk.Entry's text is changed"""
# Update the label's value to be the same as the entry value
self.label_value.set(self.entry_value.get())
if __name__ == "__main__":
# Create the root Tk object
root = tk.Tk()
# Give the root window a title
root.title("Tk Example")
# Construct our frame object
ExampleFrame(master=root)
# Run the tk main loop
root.mainloop()
When you run this code you will see our example frame being display, and as you enter text into the text entry control the static text label below will be updated.
Next we’ll see how we can use this frame in Excel.
To show a tkinter.Frame
in Excel using PyXLL we use the create_ctp
function.
As above, before we can create the frame we have to create a root object to add it to. Unlike
the above script, our function may be called many times and so we don’t want to use the tk.Tk
root object. Instead we use a tk.Toplevel
object.
We can create the Custom Task Pane from many different places, but usually it will be from a ribbon function or a menu function.
The following code shows how we would create a custom task pane from an Excel menu
function, using the ExampleFrame
control from the example above.
from pyxll import xl_menu, create_ctp, CTPDockPositionFloating
import tkinter as tk
@xl_menu("Example Tk CTP")
def example_tk_ctp():
# Create the top level Tk window and give it a title
window = tk.Toplevel()
window.title("Tk Example")
# Create our example frame from the code above and add
# it to the top level window.
frame = ExampleFrame(master=window)
# Use PyXLL's 'create_ctp' function to create the custom task pane.
# The width, height and position arguments are optional, but for this
# example we'll create the CTP as a floating window rather than the
# default of having it docked to the right.
create_ctp(window,
width=400,
height=400,
position=CTPDockPositionFloating)
When we add this code to PyXLL and reload the new menu function “Example Tk CTP” will be available, and when that menu function is run the ExampleFrame is opened as a Custom Task Pane in Excel.
Unlike a modal dialog, a Custom Task Pane does not block Excel from functioning. It can be moved and resized, and even docked into the current Excel window in exactly the same way as the native Excel tools.
See the API reference for create_ctp
for more details.