Qt for Python/Connecting QML Signals

This page describes a few alternative approaches for connecting signals between QML and PySide. Simple illustrative examples about the signal connectivity are also provided in the pyside-setup repository.

Connecting signals from QML to Python

Connecting a signal from QML to Python is the most common use case. This allows for example connecting button clicks and other user interface events in QML to the backend logic written in Python.

There are multiple alternative methods for connecting QML signals to Python. The methods are not mutually exclusive; any of them can be used in a single program (and even for a single signal, if need be).

Explicitly calling a Python slot from QML

If the Python object is exposed to QML using

setContextProperty

, you can call any slot of the object explicitly from QML, as shown in qmltopy1. First, you define a class in Python, inheriting from QObject:

class Console(QtCore.QObject):
    @QtCore.Slot(str)
    def outputStr(self, s):
        print(s)

Then, the Python object is instantiated and connected to the QML context:

con = Console()
view = QtDeclarative.QDeclarativeView()
context = view.rootContext()
context.setContextProperty("con", con)

After this, the object is accessible in QML and any slot can be called just like a function:

MouseArea {
 onClicked: {
 con.outputStr("Hello, world!")
 }
}

Returning a value from a slot

It is possible for slots to return values to the QML caller (see example qmltopy2). In this case, the Python slot needs to define an explicit return type:

@QtCore.Slot(result=int)
def val(self):
    self.r = self.r + 10
    return self.r

Then the Python object is exposed to QML, after which it can be called just like a function:

onClicked: {
    helloText.rotation = rotatevalue.val()
}

Connecting signals from QML to Python using a top-level QML signal

If you prefer to handle the signal connection in Python, the simplest way to do it is to declare a top-level signal in QML and connect that to a Python slot as shown in example qmltopy3.

First, in the top-level QML item, declare the signal:

Rectangle {
    id: page

    signal textRotationChanged(double rot)

    […]

Then, in some other QML item, make some other signal handler emit this signal:

onRotationChanged: textRotationChanged(rotation)

Finally, in Python, acquire the QML root object and connect the signal:

root = view.rootObject()
root.textRotationChanged.connect(sayThis)

This approach has the benefit of hiding the Python class behaviour from QML. On the other hand, this approach requires the Python code to have some knowledge of the QML item contents.

Connecting a signal from a specific QML item to Python.

It is also possible to acquire a specific QML item and connect a signal directly to it as illustrated in example qmltopy4.

In principle, this approach doesn't require any extra consideration in QML. Unfortunately, in practice it may be difficult to find the proper QML items without assigning them object names:

MouseArea {
    id: buttonMouseArea
    objectName: "buttonMouseArea"
    anchors.fill: parent
}

Then, in Python, it is simple to find the desired item using

findChild

and connect a signal to it:

button = root.findChild(QtCore.QObject,"buttonMouseArea")
button.clicked.connect(lambda: sayThis("clicked button (signal directly connected)"))

Although initially tempting, this approach ties the QML and Python codebases pretty tightly to each other. Also, having to define the object names in QML makes the approach less than optimal.

Connecting signals from Python to QML

It is also possible to connect signals from Python to QML when e.g. changes in the model data need to be reflected in the UI. Example pytoqml1 illustrates how to do that.

First, a function is defined in QML:

function updateRotater() {
    rotater.angle = rotater.angle + 45
}

QML functions appear as slots in Python, so it's a simple matter to connect a signal to them:

timer.timeout.connect(root.updateRotater)

This allows for fairly clean and straightforward delivery of signals from Python to QML.