The theory

The actual presentation slides are here and they have some sample code if you’re interested, but off the top of my head, here’s how Cutehacks does it:

1. First of all, they noticed that implementing a state machine in pure QML was not the best idea. To tell you the truth, I was also surprised when first encountering QML states – sure they were very flexible, but the result wasn’t really a formal state machine. In QML you can switch from any state to any other state and even to ones that don’t exist, because the current state is just a name stored in a string property.
2. One solution to the above problem is implementing the state machine in C++. Cutehacks inherited their state machine from the QStateMachine class and declared all the states as private members. That state machine had a signal corresponding to each state that shared that state’s name. e.g: state mFoo matched signal foo() inside the state machine.
3. Each state had an isActive property that was exposed together with the state to QML. In order to make isActive work, they inherited from QState and reimplemented the onEntry and onExit events to toggle the property.

So far we have our own state machine with states and transitions neatly defined in C++ in the constructor, we have signals that can be used to transition between states and each state has an isActive property. How is this connected to QML? Each C++ state was matched with a QML state having the “when” property set to “cppState.isActive”.

It turns out that in QML you can call the signals of any C++ object that has been exposed to QML! So in the UI files when pressing a button you could say something like cppStateMachine.mainState() and then the mainState() signal of the cppStateMachine C++ object would be called. If the current state had a transition to mainState, then the transition would happen, mainState.isActive would become true and the corresponding QML state for mainState would be entered.

Finally, the entire point is that in the QML state you could then change some random QML properties on entry or even run some JavaScript code.

The practice

When coming back from DevDays, I attempted to use this state machine design in a C++/QML app that I was working on. Previously I was using only QML states, but it was reasonably easy to refactor the code to use a C++ state machine in the background. The implementation felt more robust, as I could just take a look in the C++ state machine implementation to see how the app behaved, instead of hunting for the elusive assignments to the “state” property. It was also easier to make changes, since the UI changes were well defined in one place now.

Soon after that, I ran into quite a big issue though… In the app I was working on, transitions were important – for instance when going from A -> B something was supposed to happen, but when going from C -> B, or even B -> A something different had to happen. My first thought was to use the Transition QML element. After adding a few transitions for testing, I noticed that the Transition animations and code were not being executed.

Immediately I suspected that “when” was the problem. If you’ll remember, state transitions were made in a specific way: each QML state had “when” set to the C++ state’s isActive property. In a C++ transition from A -> B, the QML transitions were A -> “”-> B instead of A -> B. The empty string is the default QML state. Since A.isActive became false, the state machine transitioned to the default state automatically. Then it transitioned to B when B.isActive became true.

As one can see QML state machines are quite peculiar…

The way I solved this was by integrating the C++ state machine more tightly with the QML state machine:

1. I removed the isActive property for the C++ states and the “when” property for all QML states.
2. For each qmlState I set its name to cppState.objectName, which is just the the QState’s QObject name.

   State {
              name: cppStateMachine.initState.objectName [...]

3. In MyState::onEntered I emitted a signal called enteredWithObjectName(QString) and passed the objectName() to it.

   void MyState::onEntry(QEvent *event)
   {
       [...]
       emit enteredWithObjectName(objectName());

4. When setting up the state machine, I connected the enteredWithObjectName for each state to the C++ state machine’s stateChanged(QString) signal.

   connect(mInit, SIGNAL(enteredWithObjectName(QString)), SIGNAL(stateChanged(QString)));

5. In QML I wrote a signal handler called onStateChanged and in there I set the QML “state” property to the name parameter passed to the signal.

   Connections {
           target: cppStateMachine
           onStateChanged: {
               console.debug("changing state to " + objectName);
               rootWindow.state = objectName;
           }
       }

The end result was that now transitions were done directly from on state to another without going through the default “” state. When a QML object called cppStateMachine.mainState(), a C++ state transition happened, the C++ state mainState was entered and it emitted its QObject.objectName. The state machine then passed that on to QML and the QML set the state property to that name, effectively triggering a QML state transition. Since each QML state had the same name as the C++ QState object, it worked.

This implementation allowed for a lot of flexibility with state changes. If some transitions were similar, they could be grouped in a QML Transition with from set to ‘*’(star/any state). If there was a special case, from could be set to specialState.objectName, and the QML transition would only execute for that state, while ‘*’ would work for the rest.

The advantage with C++ is that the state machine API is already implemented, but my assumption is that a similar state machine API can be written in JavaScript, so that you could have a pure QML/JS project if that’s what you want. The important ideas when building such an API are to respect the definition of a FSM in your design and to encapsulate operations such as state and transition set up and transition triggers.

New feature highlights:

• kinetic scrolling
• ui improvements
• fixed an account currency selection bug

Ovi download link: http://store.ovi.com/content/58959

This blog post is structured in a Q&A format. The questions are those that I would have liked to have had an answer to when I started Qt Symbian development + some others that I have found interesting to think about.

Q: How hard is it for a Qt desktop developer to make the transition to mobile?

A: Qt is almost the same on Symbian as on other platforms. The Symbian-specific idioms (e.g the dreaded cleanup stack) are hidden from the programmer, but there are new UI concepts and new .pro statements and options. The Symbian build and deployment processes are notable differences that normally won’t give you trouble, but when they do give you trouble you will have to interact with the Symbian side.

Q: I have experience with Symbian C++, how does it compare to Qt?

A: Qt is much easier, you can avoid the cleanup stack, two-phase constructors, descriptors and active objects and the native UI classes. I have talked to people that did Symbian C++, Android and iOS dev. According to them, Symbian C++ is ~2x more time-consuming than the other two, Qt is about the same.

Q: What books / tutorials should I read?

A: Unfortunately, there is no one place where you will find all you need, the info is split between Forum Nokia, the (ex)Symbian Foundation, the Qt bug tracker, the Qt docs and books.

Let’s discuss them one by one:

* Forum Nokia hosts a Wiki and the Qt for Symbian section of the discussion boards. This is the best place to ask questions, because Qt Symbian devs and other experienced people read the boards. Some Wiki articles are part of the Knowledge base and contain info that’s not available elsewhere.

* The Symbian foundation websites had quite a few tidbits of info, but AFAIK those aren’t easily accessible any more because the Symbian Foundation has been merged into Nokia. You had the option of asking more technical Symbian questions on the forums there.

* It’s useful to browse the bug tracker to look out for Symbian bugs and their potential workarounds. Once again, some of this info is not available elsewhere (like a known bugs document).

* The Qt docs contain Symbian-specific sections that you must read. Some classes/functions contain platform notes.

* The “Porting to the Symbian platform” book is useful for a Qt on Symbian newbie since it explains differences between platforms, Symbian stuff such as the security model or PIPS and even contains example ports.

Q: How do I set up my development environment?

A: Just download the latest version of Nokia Qt SDK. There’s a naming problem here, because there’s also a “Qt for Symbian” download package, and a Qt SDK for [your OS]. You need the “Nokia” Qt SDK. Silly, I know, but it has gotten much simpler since the beginning where you had to watch a video to get a dev environment running.

Make sure you use the Qt Creator from the SDK, it has some special Symbian enhancements.

Q: What are the biggest problems that I should expect?

A: The look & feel is not completely adapted to Symbian, and in 4.6.3 there are UI bugs that you have to work around. The Symbian .pro options are not documented enough, and you might have to resort to trial and error.

I think that despite all the available comm channels, Nokia still has a communication problem when it comes to developers. I have gotten good results with the Qt bug tracker and by talking to Nokia devs. On the other hand Ovi store support is only done by e-mail for example and you don’t get a case number for support inquiries or a case history.

Q: How cross-platform is Symbian Qt?

A: Right now it’s probably the most cross-platform framework. I have done Symbian apps that run on Windows or Linux, and this was a major selling point for me. The UI must be carefully designed and will probably be different for each platform, but it’s still Qt and you still use QWidgets.

Q: What phones should I target?

A: Nokia has a lot of smart phone models on the market and most of them support Qt. The important difference is whether they use touch screens or not. You can and should target all the touch screen devices without much trouble. Check the phone stats report published in the Ovi newsletter for hints on popular phones.

Non-touch phones are a different story, and as far as I’ve seen there are few Qt apps targeting them. A potential opportunity, but my own experience indicates that Qt is significantly harder to use on those phones. The UI in particular is troublesome.

Q: Is Symbian Qt ready for commercial use?

A: Yes, but there are a few nuissances.

* You have to use a “Smart installer” when shipping on Ovi. This installer will download Qt if it’s not already available on the target devices (a 6-13MB download). The Smart installer isn’t very user friendly and your Ovi app description must contain a warning that the app might download 13MB of data. Needless to say, the customers can be confused by the message and they can even become upset if it’s a simple app.

* Ovi only allows Qt 4.6.3 which has some annoying bugs on Symbian. Use the bugtracker to see if anything you need is not working and check for workarounds.

Q: Can I ship software with Qt now?

A: You can ship either on Ovi store, on 3rd party stores or on your own website. Ovi supports only Qt 4.6.3 at the moment. If you want to publish outside of Ovi, it is very likely that you will need a Publisher ID and you will have to sign your app. The ID costs about $200 and signing costs $10.

Nokia will take care of signing if you publish on Ovi, but you will not get the signed setup package, it is published directly to the store.

Once the Add-In is installed, open your Qt solution with Visual Studio and select the “Create basic pro file” option from the “Qt” menu item. The Add-In will generate pro and pri files with all the relevant settings from the sln and vcproj files.

If you want to open pro files from Visual Studio instead, just select “Open Qt pro file” from the “Qt” menu and the sln and vcproj files will be created automatically.

Do expect to make minor adjustments to the generated files, as the conversion is not perfect.

Note: This doesn’t work with the VS Express edition, since that version doesn’t support plugins.