Integrating Python and QML

Qt v4.7 introduced QML as a means of declaratively describing a user interface and using JavaScript as a scripting language within QML. It is possible to write complete standalone QML applications, or to combine them with C++.

PyQt supports the integration of Python and QML as far as it can - given the limitations of the QML implementation.

There are three types of QML application:

• Pure applications that are written entirely in QML and can be run using the qmlviewer tool provided with Qt. PyQt fully supports this type of application. The examples provided by qtdemo.py under the Qt Declarative Examples heading are all of this type.
• QML allows QObject instances to be used in QML applications. QML code is able to call an object’s slots and has read and write access to the object’s properties. QML code can also respond to changes to the value of a property. PyQt fully supports the use objects created in Python in this way. The minehunt.py example under the Demonstrations heading of qtdemo.py is an example of this type of application.
• QML also allows QObject sub-classes to be used in QML applications so that new instances are created from QML. PyQt does not support this. The reason is that QML uses information generated at compile time (specifically it uses QObject::staticMetaObject) rather than information created dynamically at run time (i.e. QObject::metaObject()). This approach is fine for a static language like C++ but causes problems for languages such as Python that allow types to created dynamically. This limitation doesn’t place any restriction on the functionality of a Python/QML application, it only places restrictions on how that application is written.

QML can implement JavaScript functions and define signals. PyQt allows both of these to be accessed transparently from Python. The following is a simple example application that displays the current date and time when the user clicks on it.

The following is the QML (in the message.qml) that defines the user interface:

import Qt 4.7

Rectangle {
    signal messageRequired;

    function updateMessage(text) {
        messageText.text = text
    }

    anchors.fill: parent; color: "black"

    Text {
        id: messageText
        anchors.centerIn: parent; color: "white"
    }

    MouseArea {
        anchors.fill: parent
        onClicked: messageRequired()
    }
}

This defines a signal messageRequired which is emitted when the user clicks on the mouse area. It also implements a function updateMessage() which updates the message being displayed.

The following is the Python code that implements the application logic:

import sys

from PyQt4.QtCore import QDateTime, QObject, QUrl, pyqtSignal
from PyQt4.QtGui import QApplication
from PyQt4.QtDeclarative import QDeclarativeView


# This class will emit the current date and time as a signal when
# requested.
class Now(QObject):

    now = pyqtSignal(str)

    def emit_now(self):
        formatted_date = QDateTime.currentDateTime().toString()
        self.now.emit(formatted_date)


app = QApplication(sys.argv)

now = Now()

# Create the QML user interface.
view = QDeclarativeView()
view.setSource(QUrl('message.qml'))
view.setResizeMode(QDeclarativeView.SizeRootObjectToView)

# Get the root object of the user interface.  It defines a
# 'messageRequired' signal and JavaScript 'updateMessage' function.  Both
# can be accessed transparently from Python.
rootObject = view.rootObject()

# Provide the current date and time when requested by the user interface.
rootObject.messageRequired.connect(now.emit_now)

# Update the user interface with the current date and time.
now.now.connect(rootObject.updateMessage)

# Provide an initial message as a prompt.
rootObject.updateMessage("Click to get the current date and time")

# Display the user interface and allow the user to interact with it.
view.setGeometry(100, 100, 400, 240)
view.show()

app.exec_()

Hopefully the comments in the code are sufficient explanation. The important things to note are that the signal and JavaScript function appear as appropriate attributes of the root object QDeclarativeItem returned by the rootObject() method of QDeclarativeView and can be connected to and called respectively.