Tkinter¶

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.

Creating a tk Frame¶

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.

A tkinter frame in an Excel custom task pane

Creating a Custom Task Pane from a tkinter.Frame¶

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.

« wxPython

Other UI Toolkits »