PySide and PyQt ¶

PySide and PyQt are both Python packages wrapping the popular Qt UI toolkit. They are quite similar but have different licenses and so which one you choose will be down to your own preference. Both work equally well with PyXLL.

User interfaces developed using Qt 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 PySide or PyQt. It is only intended to instruct you on how to use PySide and PyQt with the Custom Task Pane feature of PyXLL. You should refer to the relevant package documentation for details of how to use each package.

Both PySide and PyQt can be installed using pip or conda, for example:

> pip install pyside6
# or
> pip install pyqt6
# or
> conda install pyside6
# or
> conda install "pyqt>=6"

Typically you will only want to install one or the other, and you should install it using pip or conda and not both.

You can find more information about PySide and PyQt on the websites, https://wiki.qt.io/Qt_for_Python and https://www.riverbankcomputing.com/software/pyqt/ respectively.

Note

Qt6 support was added in PyXLL 5.1, for both PySide6 and PyQt6.

Any of PySide2, PySide6, PyQt5 and PyQt6 can be used with PyXLL.

A Python Qt widget in an Excel custom task pane

Creating a Qt Widget ¶

One of the main classes in Qt is the QWidget class. To create your own user interface it is this QWidget 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 Qt widget. If you run this code as a Python script then you will see the widget being shown.

from PySide6 import QtWidgets
# or from PyQt6 import QtWidgets
import sys

class ExampleWidget(QtWidgets.QWidget):

    def __init__(self):
        super().__init__()
        self.initUI()

    def initUI(self):
        """Initialize the layout and child controls for this widget."""
        # Give the widget a title
        self.setWindowTitle("Example Qt Widget")

        # Create a "Layout" object to help layout the child controls.
        # A QVBoxLayout lays out controls vertically.
        vbox = QtWidgets.QVBoxLayout(self)

        # Create a QLineEdit control and add it to the layout
        self.line_edit = QtWidgets.QLineEdit(self)
        vbox.addWidget(self.line_edit)

        # Create a QLabel control and add it to the layout
        self.label = QtWidgets.QLabel(self)
        vbox.addWidget(self.label)

        # Connect the 'textChanged' event to our 'onChanged' method
        self.line_edit.textChanged.connect(self.onChanged)

        # Set the layout for this widget
        self.setLayout(vbox)

    def onChanged(self, text):
        """Called when the QLineEdit's text is changed"""
        # Set the text from the QLineEdit control onto the label control
        self.label.setText(text)
        self.label.adjustSize()

if __name__ == "__main__":
    # Create the Qt Application
    app = QtWidgets.QApplication(sys.argv)

    # Create our example widget and show it
    widget = ExampleWidget()
    widget.show()

    # Run the Qt app
    sys.exit(app.exec_())

When you run this code you will see our example widget being display, and as you enter text into the line edit control the label below will be updated.

Next we’ll see how we can use this widget in Excel.

Creating a Custom Task Pane from a Qt Widget ¶

To show a QWidget in Excel using PyXLL we use the create_ctp function.

As above, before we can create the widget we have to make sure the QApplication has been initialized. Unlike the above script, our function may be called many times and so we don’t want to create a new application each time and so we check to see if one already exists.

The QApplication object must still exist when we call create_ctp. If it has gone out of scope and been released then it will cause problems later so always make sure to keep a reference to it.

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 ExampleWidget control from the example above.

from pyxll import xl_menu, create_ctp, CTPDockPositionFloating
from PySide6 import QtWidgets
# or from PyQt5 import QtWidgets

@xl_menu("Example Qt CTP")
def example_qt_ctp():
    # Before we can create a Qt widget the Qt App must have been initialized.
    # Make sure we keep a reference to this until create_ctp is called.
    app = QtWidgets.QApplication.instance()
    if app is None:
        app = QtWidgets.QApplication([])

    # Create our example Qt widget from the code above
    widget = ExampleWidget()

    # 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 widget rather than the
    # default of having it docked to the right.
    create_ctp(widget,
               width=400,
               height=400,
               position=CTPDockPositionFloating)

When we add this code to PyXLL and reload the new menu function “Example Qt CTP” will be available, and when that menu function is run the ExampleWidget 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.

« Custom Task Panes

wxPython »