Here, I’ll show you how I think the best practice of building QML components is. It seems so simple, maybe even trivial. But I have met a lot of code that doesn’t follow it, and seen the problems that follow. QML is still so new, that best practice isn’t common knowledge. And in many cases, best practice haven’t even been discovered yet.

Let me give a quick example that shows the problem: You have created a Button component with all the bells and whistles such a component needs. You chose to build it using a Rectangle, so the border is handled by an existing component. Reuse is always a good and popular choice.

Here is some of the code of how the Button could be done:

Button.qml:
Rectangle {
    id: button
    border.width: 1
    signal clicked()
    property alias text: buttonText.text
    Text {
        id: buttonText
        anchors.centerIn: parent
    }
    ...
}

You now declare a Button, set the size and the text, and that’s it. However, you might also want to have a different border, so this is what we do in the UI QML file:

Ui.qml:
Rectangle {
    width: 360
    height: 360
    Button {
        anchors.centerIn: parent
        text: "Hello World"
        width: 100
        height: 30
        border.width: 2
        border.color: "blue"
    }
    ...

Now, here’s the problem: If you decide to expand the Button with other choices of how it can look, you will have a problem. For example, you might want to offer a BorderImage for the way the Button looks. But with the current use of a Rectangle, you can’t do this without modifying the code that uses this Button.

This is exactly the problem encapsulation solves: It allows you to make local changes to your component without modifying all the code that uses it.

The simple solution of the Button is to make it an Item that has a Rectangle. In OO terms, this changes from inheritance to aggregation.

My solution for creating QML components is to nearly always base them on Item, and expose whatever properties I want. The interface to my components is the sum of properties, functions and signals. How I choose to implement the component itself is an implementation detail, and should not be available to other components.

For a simple example, suppose we have a system where a bunch of Text items should always follow a shared style. If the style changes, all text must follow. In fact, the only thing the users of the text item can set, is the text itself.

This could clearly be done with Text directly:

StyledText.qml:
Text {
    // Event handlers to set the Style parts here:
    ...
}

This a valid choice, we simply need to tell ourselves that we shouldn’t set the color, size etc. directly, but allow the central style code to set it. And this is of course doomed. Some day, we hire a new coder, or forget ourselves. Whatever the reason, we will break the rules.

The proper solution is to encapsulate the component and hide the implementation behind the Item:

StyledText.qml:
Item {
    property alias text: textItem.text
    Text {
        anchors.fill: parent
        // Event handlers to set the Style parts here:
        ...
    }
}

It seems so simple, but I have seen a bunch of QML code that doesn’t do this. Every time you start modifying the code of components, you wonder what you break. And this only becomes much more valuable with real components that have much more complexity than the simple example code I have here.

If you follow this pattern instead, you will create robust and encapsulated components with no properties accessible by accident.

The solution is quite standard and have been published in other blogs as well. But all of those I’ve seen miss one or two features. Which is quite a lot for a class this small. And this is also a cute little test for some nice Qt code, so I thought I’d publish my own version of this class.

The basic idea is simple, you want to have an object that controls blocking signals. So the code you write will be something like this:

{
    SignalBlocker blocker(targetObject);
    targetObject->doSomethingThatEmitsASignal();
}

Sometimes people ask why not just do the following?

targetObject->blockSignals(true);
targetObject->doSomethingThatEmitsASignal();
targetObject->blockSignals(false);

There are three problems with this. The first problem is that the signals might already be blocked, and this code will unblock them. This is one of the problems most SignalBlocker implementations I’ve seen miss.

The second problem is that doSomethingThatEmitsASignal() might throw an exception. If this happens, the signals will stay blocked. But with an object, the destructor will be called even in the case of an exception.

Finally, the doSomethingThatEmitsASignal() could end with delete this, so the code doing the unblocking must handle the case where the target object has been deleted. QPointer is the right solution for this, since it listens to the destroyed() signal. And no, that is never blocked. This problem is also not caught by the SignalBlocker implementations I’ve seen.

So the full SignalBlocker implementation should be something like this:

/**
 * Small helper class that blocks all signals from an object for the lifetime of this object.
 * it is safe against deletion of the object before deletion of this.
 *
 * This class was written by Bo Thorsen of Fionia Software <bo@fioniasoftware.dk>.
 * The code is in the public domain.
 */
class SignalBlocker {
public:
    explicit SignalBlocker(QObject* object) : mObject(object) {
        mWasBlocked = object->signalsBlocked();
        object->blockSignals(true);
    }

    ~SignalBlocker() {
        if (mObject && !mWasBlocked)
            mObject->blockSignals(false);
    }

private:
    // Disabled
    SignalBlocker(const SignalBlocker&);
    SignalBlocker& operator=(const SignalBlocker&);

    QPointer<QObject> mObject;
    bool mWasBlocked;
};

The last couple of months have been spent with heavily multithreaded Qt code. Fun, yes, but also challenging. I have always had three rules about multithreading: 1: Don’t do it! 2: Don’t do it! 3: Don’t do it yet. Threaded code is harder to build and debug, and with event driven applications you rarely need to use it.

But in some cases multithreading is necessary. One example was my last customer. They had an application that had threads talking to hardware. This is a perfectly good example of something that certainly fits well in a separate thread.

When the hardware did something, they generated a work request. This was a QThread subclass that they called start on, and let it do it’s thing, and deleted the thread on completion. Not an unreasonable approach, but as they were generating around 10 threads per second, I did not like it. This is a textbook example of what QThreadPool is for.

I made a change on some of the work requests so they used QThreadPool instead. The modification to the code is minimal. Instead of subclassing QThread, they should subclass QRunnable. And then QThreadPool should run and delete the thread instead of the thread itself handling that.

First results were surprising: The work request time increased instead of going down. I told them not to worry, because the time of an individual request is not really what is interesting, the effect on the whole system is more important. In some use cases this is not true, but the new work request time handling was still well within their requirements.

So, the question remains whether I was right or not. Will a thread pool implementation use less total cpu time than a QThread based implementation? To answer this question, I wrote a small test benchmark. The code is very simple, but it does produce a pretty heavy load when run. As mentioned above, you can download it here.

Each work request makes a list of 1000 integers and then sorts them. Simple piece of work, and not something the compiler can do any tricks on. This simple function is just called by my QThread and QRunnable subclasses in the run() method.

static QList<int> doWork() {
    QList<int> numbers;

    // Fill the list with some numbers
    const int numberSize = 1000;
    int currentNumber = 0;
    for (int i = 0; i < numberSize; ++i) {
        currentNumber = (currentNumber + 367) & 1023;
        numbers << currentNumber;
    }

    qSort(numbers);
    return numbers;
}

The tests do a number of iterations and on each iteration creates a number of threads and then goes to sleep for a bit, giving the worker threads some time for their work. With the numbers below, all was run with creating 25 worker threads on each iteration and sleeping for 10ms between each iteration. At the end, the QThread implementation deletes all the thread instances because QThreadPool does this automatically.

This is the loop that creates the worker threads and executes them. After this code, it deletes the threads and waits for all of them to finish.

void ThreadStarter::run() {
    QList<QThread*> threads;
    threads.reserve(mIterations * mThreadsPerIteration);

    for (int i = 0; i < mIterations; ++i) {
        for (int t = 0; t < mThreadsPerIteration; ++t) {
            if (mType == Thread) {
                WorkThread* thread = new WorkThread;
                thread->start();
                threads << thread;
            } else {
                WorkRunnable* runnable = new WorkRunnable;
                QThreadPool::globalInstance()->start(runnable);

                // Mimic the same work as with threads
                threads << 0;
            }
        }

        msleep(mSleepTime);
    }
    ...

I ran this with a growing number of iterations. The table below shows the number of iterations, the time for the thread based implementation to run, and finally the time for the threadpool implementation:

i: 10 thread ms: 107 runnable ms: 102
i: 20 thread ms: 215 runnable ms: 206
i: 30 thread ms: 322 runnable ms: 311
i: 40 thread ms: 429 runnable ms: 407
i: 50 thread ms: 546 runnable ms: 507
i: 60 thread ms: 651 runnable ms: 610
i: 70 thread ms: 765 runnable ms: 713
i: 80 thread ms: 860 runnable ms: 812
i: 90 thread ms: 966 runnable ms: 912
i: 100 thread ms: 1084 runnable ms: 1022
i: 110 thread ms: 1181 runnable ms: 1119
i: 120 thread ms: 1289 runnable ms: 1218
i: 130 thread ms: 1404 runnable ms: 1318
i: 140 thread ms: 1505 runnable ms: 1420
i: 150 thread ms: 1624 runnable ms: 1521
i: 160 thread ms: 1722 runnable ms: 1622
i: 170 thread ms: 1842 runnable ms: 1728
i: 180 thread ms: 1944 runnable ms: 1823
i: 190 thread ms: 2043 runnable ms: 1924

As you can see, the conclusion is completely clear: In every case, the thread pool implementation is faster than the QThread implementation. So even though each worker thread could finish faster with the thread implementation, the total system time is higher. This is relevant when the machine gets heavily loaded (as it did for my customer), because then you need the threads to take up as little total time as possible.

I have run this with other numbers of threads generated and sleeping time, and on different machines. The conclusion have always been the same. Not a single time has the QThread approach been the fastest.

There is another benefit to the thread pool based approach that has nothing to do with speed. This is the problem of deletion of the worker threads. It’s not trivial to figure out how to delete the thread object, once it’s done. Of course, a connect from finished() to deleteLater() usually does the trick. Unless you do something like thread->moveToThread(thread) and call exec() in the run method. With the thread pool approach it’s trivial, since the pool will by default just delete the worker thread object when it’s done.

So, my recommendation stands: Unless you have a really good reason not to, you should use a thread pool for worker threads.

In my application, I have a lot of Text objects that have the same font, color etc. so I have put those in a TTText.qml. In this, I also have the tool tip property, which is the only thing I will show here:

import QtQuick 1.0

Text {
    property string toolTip
    // ...
    ToolTip { toolTip: parent.toolTip }
}

The idea here is simply to have a toolTip property directly on the TTText object. I could have chosen to use it with myText.toolTip.text instead, but by using a property directly on the Text object, I have encapsulated the tool tip inside it.

First attempt at a ToolTip.qml is a very simple one:

import QtQuick 1.0

Item {
    anchors.fill: parent

    property string toolTip
    property bool showToolTip: false

    Rectangle {
        id: toolTipRectangle

        anchors.horizontalCenter: parent.horizontalCenter
        anchors.top: parent.bottom
        width: toolTipText.width + 4
        height: toolTipText.height + 4
        z: 200

        visible: toolTip != "" && showToolTip

        color: "#ffffaa"
        border.color: "#0a0a0a"

        Text {
            id: toolTipText
            text: toolTip
            color: "black"
            anchors.centerIn: parent
        }
    }

    MouseArea {
        id: mouseArea
        anchors.fill: parent
        onEntered: showToolTip = true
        onExited: showToolTip = false
        hoverEnabled: true
    }
}

The MouseArea is the first piece needed. This is the part that tells when the user hovers the mouse over the text. When this is the case, it sets the showToolTip to true, which the tool tip rectangle uses to know when it should show itself.

This is actually enough to have working tool tips on your items. But it’s a bit rough: It just goes visible as soon as the mouse enters the item holding the ToolTip.

First thing I want to add is a fade in and fade out. I do this by changing the viewing of the tool tip from using the visible property to the opacity and do an animation on the property changes.

The second thing is that I want the tool tip to wait a bit before it pops up, so it doesn’t show itself when I just move the mouse over the holding item. This is done with a timer that is started by the MouseArea enter event. When the timer fires, it sets the opacity to 1.

With these two changes we have a nice and usable tool tip item. If you want to, you can add properties to change the way the tool tip looks, the timer duration or the animation duration etc.

Here is the final version:

import QtQuick 1.0

Item {
    anchors.fill: parent

    property string toolTip
    property bool showToolTip: false

    Rectangle {
        id: toolTipRectangle

        anchors.horizontalCenter: parent.horizontalCenter
        anchors.top: parent.bottom
        width: toolTipText.width + 4
        height: toolTipText.height + 4
        z: 200

        opacity: toolTip != "" && showToolTip ? 1 : 0

        color: "#ffffaa"
        border.color: "#0a0a0a"

        Text {
            id: toolTipText
            text: toolTip
            color: "black"
            anchors.centerIn: parent
        }

        Behavior on opacity {
            PropertyAnimation {
                easing.type: Easing.InOutQuad
                duration: 250
            }
        }
    }

    MouseArea {
        id: mouseArea
        anchors.fill: parent
        onEntered: showTimer.start()
        onExited: { showToolTip = false; showTimer.stop(); }
        hoverEnabled: true
    }

    Timer {
        id: showTimer
        interval: 250
        onTriggered: showToolTip = true;
    }
}

I have a pet project that involves a poker table. This is done with a list model that has a list of seats with the name, stack size etc. exposed as custom roles. In this example, I only use the “name” role in a Text item. The real application has a Seat custom item that uses all the roles.

I have a C++ implementation of the table (exported to the QML as PokerTable in the Poker module), which draws the table and calculates the seat positions. My goal now is to create the seat items on the correct positions. There is another C++ class that implements the hand model.

The first step is to just show that the model works. I do this with the standard Row positioner and a Repeater for the model:

import QtQuick 1.0
import Poker 1.0

Item {
    PokerTable {
        id: table
        anchors.fill: parent

        Row {
            anchors.centerIn: parent

            Repeater {
                model: handModel
                Text { text: name }
            }
        }
    }
}

With this simple QML, I can see my table with the player names placed next to each other in the center of the table. So far so good.

Next step is to implement a simple positioner, that shows how this actually works:

import QtQuick 1.0
import Poker 1.0

Item {
    PokerTable {
        id: table
        anchors.fill: parent

        Item {
            id: seatView

            anchors.fill: parent

            onChildrenChanged: updatePositions();

            Repeater {
                model: handModel
                Text { text: name }
            }

            function updatePositions() {
                for (var i = 0; i < seatView.children.length; ++i) {
                    seatView.children[i].pos = Qt.point(i * 50, i * 5);
                }
            }
        }
    }
}

This code calculates the positions for each of the seats, when children are added or removed. The position calculations do not make any sense, they just show an effect where you can be sure that it works.

In my case, I want the table class to calculate the seat positions, because I don’t want to copy those calculations to another place. But it might be that the above code pattern is all you need to implement your own positioner, if you can code it in javascript.

A couple of final touches are also needed. First, I’ll add (but not show here) a signal from the table class that can be emitted when the positions change for other reasons – resizing, for example.

The updatePositions() function will be called every time a child is added. I can have ten seats, so my function will be called when the first child have been added, then when the second, etc. That means it’s a bad idea to do the real calculations when new seats will be added immediately after. There are several ways to fix this. You could add a zero time timer that is restarted when the signal fires and will run the update function as it’s done. In my case, I already have the seat count exported as a property on my table, so I’ll check that the seat count is the same as the number of children before doing any work.

You might need to handle that the repeater is also a child of the view. I do this by setting an object name on the repeater and skip this child.

For the actual positions of the seats, I add this function in my C++ table class:

Q_INVOKABLE QPointF seatPosition(int seat) const;

Now I can do the proper positioning in the QML slot:

function updatePositions() {
    if (seatView.children.length == table.seats + 1) {
        var index = 0;
        for (var i = 0; i < seatView.children.length; ++i) {
            if (seatView.children[i].objectName != "repeater") {
                seatView.children[i].pos = table.seatPosition(index++);
        }
    }
}

So there you have it, a simple custom positioner that you can modify to place the view items in any kind of positioning you want.

Over the last month, I’ve been working for Swiss company Poken, implementing an application for the Nokia C7. It’s a great tool to “Collect people, places and things, with a touch” as they phrase it.

One of the things I had to do here was a simple task: Allow the user to set his birthday. Which naturally means using QCalendarWidget. The problem was that the navigation bar for choosing the year or month sucks on small touch screens. So I wrote a small class that uses QCalendarWidget but adds a usable chooser bar.

The DatePicker widget is shown in a modal dialog. The result can be seen in this screenshot (click for a larger image):

The new bar is four buttons for changing the year and month and a label in the middle to show the current date. The code for it is very simple. The widgets are done in designer, and the code is pretty much just this:

QDate DatePicker::currentDate() const {
    return ui->calendar->selectedDate();
}

void DatePicker::setCurrentDate(const QDate &d) {
    QDate date = d;
    if (!date.isValid())
        date = QDate::currentDate();
    ui->calendar->setSelectedDate(date);
    ui->calendar->showSelectedDate();
    on_calendar_clicked(date);
}

// The other four buttons are handled the same way as this
void DatePicker::on_yearBackButton_clicked() {
    QDate date = currentDate();
    date = date.addYears(-1);
    setCurrentDate(date);
}

void DatePicker::on_calendar_clicked(const QDate &date) {
    ui->dateLabel->setText(date.toString(Qt::SystemLocaleDate));
}

This is a small and, admittedly, somewhat trivial problem. But the general problem of Qt being too desktop oriented is real. This blog entry is an attempt to show (without getting buried in code details) that if you get just a little bit creative, the Qt widgets still work well on embedded systems like the Nokia phones.

Thank you Poken for giving me permission to use their code as an example.

Switching to use the mouse to press the eval button is obviously completely unacceptable, so I had a standard keyboard shortcut on the eval button. However, it seems more and more “standard” to use Ctrl+Return in text edits when the edit is done and should be handled, so I found myself pressing this a couple of times.

Implementing this for QPlainTextEdit can be done in many ways. One would be to subclass it and handle the keyboard events directly. If you have to subclass it anyway, that’s a nice option. But in this case, the UI was done in designer and I wasn’t already subclassing it.

Another way would be to create an eventFilter. This is of course one of those “if you only have a hammer, all problems are just nails”. Event filters are so easy to use, very powerful and able to do the trick, and one of the biggest hammers you’ll find in Qt. In this case, I would implement a class like this:

class CtrlEnterKeyPressFilter : public QObject {
public:
    CtrlEnterKeyPressFilter(QWidget* widget, QPushButton* button)
        : QObject(widget), mButton(button)
    {
        widget->installEventFilter(this);
    }

protected:
    bool eventFilter(QObject*, QEvent* event) {
        if ((event->type() == QEvent::KeyPress
                || event->type() == QEvent::KeyRelease) && mButton)
        {
            // This might be one for us
            QKeyEvent *keyEvent = static_cast<QKeyEvent*>(event);
            if (keyEvent->key() == Qt::Key_Return &&
                    keyEvent->modifiers() == Qt::ControlModifier)
            {
                // Ctrl + return pressed
                if (event->type() == QEvent::KeyRelease) {
                    mButton->click();
                }

                // This event has been handled
                return true;
            }
        }

        return false;
    }

private:
    QPointer<QPushButton> mButton;
};

However, my favourite way to implement this is to use a QAction and set a keyboard shortcut on that:

QAction* action = new QAction(d->ui.input);
action->setAutoRepeat(false);
action->setShortcut(tr("Ctrl+Return"));
connect(action, SIGNAL(triggered()), d->ui.eval, SLOT(click()));
d->ui.input->addAction(action);

This is a simple and clean solution that does the trick for you.

All the code mentioned in this blog post is from my Qt example application FS-editor. This is a complete (but small) text editor implemented to show the code I talk about in this blog.

First of all, you have to implement a way for the user to choose the current language. This would normally be done in a preferences or settings dialog. In FS-editor, I have just added a menu with the available languages, but for most applications that would be too prominent a position for such a rarely used set of actions.

Changing the current language is done by deleting the previously installed translator objects and loading the new ones. In FS-editor there is this function, that takes one of the language codes (en, da, etc.):

void LibUI::Translation::installTranslator(const QString& code) {
    QDir translationsPath(findTranslationsPath());

    const QList<QTranslator*> oldTranslators(findChildren<QTranslator*>());

    if (code == "en") {
        // English means no translator installed
        qDeleteAll(oldTranslators);
    } else if (translationsPath.isReadable()) {
        // Try loading the new translation
        QScopedPointer<QTranslator>
        appTranslator(new QTranslator(this));
        QScopedPointer<QTranslator>
        qtTranslator(new QTranslator(this));
        if (appTranslator->load("fseditor_" + code, translationsPath.absolutePath())
            && qtTranslator->load("qt_" + code, translationsPath.absolutePath()))
        {
            // Delete the old translators
            qDeleteAll(oldTranslators);

            // Install the new ones
            QCoreApplication::instance()->installTranslator(appTranslator.take());
            QCoreApplication::instance()->installTranslator(qtTranslator.take());
        }
    }
}

One thing to notice in this is that I load both my own translations and the Qt translations. The Qt translations handles all user visible strings from Qt – dialogs, for example.

Installing the new translators is not enough. You need to catch the language change for changing all the user visible strings. This should be done by listening to the LanguageChange event:

void LibUI::MainWindow::changeEvent(QEvent* event) {
    if (event->type() == QEvent::LanguageChange) {
        languageChange();
    }
    QWidget::changeEvent(event);
}

Using the changeEvent is the best way to avoid too tight coupling of code for receiving the information about a language change. I prefer this over a manual connect to a language switch signal, which in large applications will give you the dreaded spaghetti code.

When you have caught the language change, you need to update all your user visible strings. This means labels, buttons, tab text, window captions, etc. Every single string that the user can see has to be updated with a tr(“…”) call. The exception to this is modal dialogs, because the user doesn’t have access to the language switch when one of these is up. The exception to this exception could be the settings dialog, although I disagree that this dialog should be modal.

You also need to switch all keyboard shortcuts. You must never assume that there is the same set of shortcuts for other languages. And you should call retranslateUi on the designer generated code.

One final bit is fixing some of the Qt actions. In FS-editor I use the Qt undo/redo framework, and the text on the undo and redo actions does not automatically update itself on language change. I do this manually:

QSharedPointer<QAction> action(d->undoGroup.createUndoAction(0));
d->undoAction->setText(action->text());
action = QSharedPointer<QAction>(d->undoGroup.createRedoAction(0));
d->redoAction->setText(action->text());

At startup time, you should figure out what language to show. If the user set this in the preferences, you should store and use this choice, of course. But on the first startup, it’s normal to try and load the language of the OS itself. A call to QLocale::system().name() will give you the language code to use. On my system, the editor starts up in Danish.

With all these steps implemented, you should have complete language switching done.

In FS-editor, you can see how all this is put together in a real application. The interesting bits (at least in this context) are found in the files source/libui/translation.cpp and source/libui/mainwindow.cpp.

To view the contents of a subtree, you can use this simple function:

void printDomNode(const QDomNode& node) {
QDomDocument d("debugxml");
d.appendChild(node);
qDebug() << "Text XML:" << d.toString();
}

You will get the open XML tag at first, but since this is for debugging purposes, I never bothered to write the code to get rid of it. This trick is so small that I don't have it stored anywhere, I just rewrite the function whenever I need to do it.

The only problem with this: It destroys the XML tree. Even though the node is a const ref, this code will still destroy the tree it comes from. I personally think this is a completely unacceptable Qt bug.

Some of these problems are actually serious. For example this one in e32cmn.inl:

inline SVendorId::operator const TVendorId&() const
{ /* coverity[return_local_addr] */ return (const TVendorId&)iId; }

This returns a reference to a temporary. Nice.

The fix for the warnings in e32cmn.inl is to change the C-style warnings to this:

inline SVendorId::operator const TVendorId&() const
{ /* coverity[return_local_addr] */ return reinterpret_cast<const TVendorId&>(iId); }

It’s not pretty, but it’s silent.

After this, you have to remove a “/**” that is inside another comment, and comment out an empty enum declaration.

Finally, you have to add some compiler flags to get rid of the remaining warnings. In our current build, we have these lines in the .pro file:

symbian {
QMAKE_CXXFLAGS += -Wall -fdiagnostics-show-option -Wno-parentheses -Wno-invalid-offsetof -Wno-psabi -Wclobbered -Wempty-body -Wignored-qualifiers -Wmissing-field-initializers -Wsign-compare -Wtype-limits -Wunused-parameter
}

The -Wno-psabi switch is only available on gcce 4.4.1. The first SDK version to ship this was 1.1-beta. If you have an earlier version, remove this flag.

With these fixes, the project I’m working on at the moment (Poken), compiles without a single warning from the SDK.

I normally only publish things on this blog that’s my own work. However, credit for most of this goes to Razvan and his blog entry. But the question of how to get rid of those compiler warnings keeps popping up everywhere, so I thought it was time to remind people. Also, it’s not possible to comment on his blog to add the parts he doesn’t have, so I have published an updated version of this. So please, keep in mind that this blog entry is really Razvans work.