Please note that as of October 24, 2014, the Nokia Developer Wiki will no longer be accepting user contributions, including new entries, edits and comments, as we begin transitioning to our new home, in the Windows Phone Development Wiki. We plan to move over the majority of the existing entries. Thanks for all your past and future contributions.
Warning: The Symbian Signed program closed on January 1, 2014 and it is no longer possible to publish Qt apps (or other content) for Symbian and MeeGo on Nokia Store. It is possible to self-sign content for basic capabilities and continue to use existing DevCerts. For more information see this blog.
This article provides a getting started tutorial, along with links to: the SDK, related documentation, examples, and other resources.
Everything you need to start develop in Qt is provided in the Qt SDK, which can be downloaded from:
- Qt SDK Windows x86 offline (1.2.1)
- Qt SDK Linux64 x86 offline (1.2.1)
- Qt SDK Linux32 x86 offline (1.2.1)
- Qt SDK - Mac64 offline (v1.1.2)
- Other versions for Linux and Windows are currently uploading
Other Qt-relevant tools include:
- Nokia Smart Installer for Symbian - saves you from having to bundle the Qt framework in your apps' SIS files. When your app includes Smart Installer, as it's installed by the user a check is made for the presence of the required Qt packages. If any Qt packages are not present Smart Installer downloads and installs them. The Qt SDK 1.1 includes an updated version of Nokia Smart Installer for Symbian that delivers the Qt 4.7 and Qt Mobility 1.1 APIs.
- Symbian home page tools list
In addition to the API documentation in Qt Creator (Help > Qt Reference Documentation), see the other relevant documentation resources:
- Qt SDK 1.2 Documentation (doc.qt.digia.com) - this is the latest release compatible with Symbian and MeeGo Harmattan devices
- Meego 1.2 Harmattan Developer Documentation
- Category:Qt (Wiki)
- Qt Code Examples (Official Nokia Developer Example Code)
- Portal:Qt Code Examples (Community contributed articles with code)
Getting Started Tutorial
The Qt SDK is the easy-to-install and use development environment for creating outstanding Qt apps for Symbian phones and the Nokia N9. In this tutorial you'll find out how to download, install, and use the Qt SDK 1.2.1 to create and deploy your apps.
Download and installation
To download the latest Qt SDK, go to #Qt SDK in this article.
Each installer is available in an offline version which includes the entire Qt SDK.
Once you have downloaded your choice of installer run it in the usual way to install it on your computer.
Once the installation is complete, the setup wizard will prompt you to launch Qt Creator and the Qt SDK. The SDK includes Symbian and Nokia N9 development tutorials that describe how to configure the debugging and deployment environment for each target. You won't need them at this point; you can find them later in the <QtSDK_install_path>\readme directory.
At this point, no further configuration is needed, because the Qt SDK contains everything you need.
See the next tab to create a new project with Qt Creator.
This section shows how to create and test your code.
Create a project
With Qt Creator open, confirm your installation was successful by creating a new project using a project template.
Click Choose to add a name and select the location for the project. Click Next.
In the next dialogue you can change the application icon, but for now click Next. In the final dialogue all the files, which will be added to the new project, are shown. You can also manage the project in version control system using Qt SDK. Click Finish to complete the project creation.
To build and run the project, click the build button (the button with a hammer icon) in the bottom left-hand toolbar (see Figure 14). The build progress bar in the toolbar turns green once the project has been built successfully. If you want to see the compilation progress, open the Compile Output log.
Run the application in the Qt Simulator
Next, run the application in the simulator. Click the device icon in the left-hand toolbar to select the target. A pop-up menu displays (see Figure 15). Click Qt Simulator to choose it as the target (the active target has a blue background colour).
Click the green run button (see Figure 14).
Next to the simulator there is a Qt Simulator Control window (see figure 17), in which you can change the simulator settings. In the Model menu you can, for example, toggle the orientation and choose from the various device configurations. In the Sensors menu you can simulate device sensor behaviours. For more information on the simulator features, see Qt Creator Help.
Note: The simulator doesn't support the Symbian and Harmattan platform macros. For example, screen-size settings made for Symbian and Harmattan targets don't apply in the simulator. However, you can use the Q_WS_SIMULATOR macro to differentiate the code for the simulator. You can read more about the use of environment macros on the Nokia Developer Wiki.
Now you have successfully run your application in the Qt Simulator. In the next two steps, you will configure a phone and test the application on it.
The configuration for Symbian and Harmattan targets differs, so separate deployment instructions have been provided for these targets (see the next tabs!)
This section describes how to build an application for a Symbian target and deploy it to a Symbian phone. To enable convenient deployment and debugging of the application onto a Symbian phone, you need to install a debugging application on the phone and you may also need to install the Qt package.
Debugging is only supported on the Windows operating system (32- and 64-bit versions). In addition to a compatible version of Windows, you need the following:
- Symbian phone with a USB cable.
- Qt SDK.
- Nokia Suite.
Set up the Symbian phone
Connect the Symbian phone to the PC using the USB cable delivered with your phone. If you haven't previously used the phone with Nokia Suite, all the drivers required are installed automatically when you make the first connection: installation takes approximately one minute.
Install Qt on the phone
You do not need to complete this step for Symbian Belle phones, as they have Qt installed in their firmware.
For any other Symbian phone, you need a program (such as Nokia Suite) that can install *.sis files. To install Qt, use the shortcut that the Qt SDK created in the Start Menu (Start Menu > All Programs > Qt SDK > Symbian Anna Qt 4.7.4 > Install Qt 4.7.4 for Symbian Anna on device) and follow the steps shown on your screen.
As an alternative, use Windows Explorer to find the Qt installation package by navigating to <QtSDK_install_path>\Symbian\sis\Symbian<version>\Qt\<version> and selecting qt<version>.sis.
Install CODA on-device debugging agent on the phone
Use the shortcut in the Start Menu to install the CODA on-device debugging agent (StartMenu > All Programs > Qt SDK > Symbian Anna Qt 4.7.4 > Install CODA (Debug Agent) on Symbian Anna device).
As an alternative, you can navigate to <QtSDK_install_path>\Symbian\sis\common\CODA and install the .sis file using Nokia Suite or by copying it to the phone.
Set up Qt Creator
Now that you have installed the CODA application on the phone, check the Symbian Build and Run settings in Qt Creator. Use the left-hand toolbar to go to the Projects view. Then go to the Symbian Device tab and open the Build tab (see Figure 18).
Make sure that you have selected Debug in the 'Edit build configuration' drop-down menu.
The Qt Version drop-down menu should display Qt 4.7.4 for Symbian Anna (Qt SDK). If it doesn't, click Manage to change the selection.
Make sure that the project you created in Step 2 is active and then click Run under the Symbian Device tab. Also confirm that the phone is connected to the PC with the USB cable and the device on Serial port drop-down menu displays the COM port (see Figure 19).
Symbian platform security mandates the signing of applications. Most of the applications (such as the template application used here) can be self-signed. The Qt SDK automatically self-signs the application installation packages with a default certificate and key pair (shown in Figure 19).
If an application needs sensitive capabilities, such as reading phone data, it has to be signed with your own Publisher ID, which verifies the identity of the application's vendor. In general, this is needed for commercially released applications but also for such applications undergoing development and testing. The custom certificate can be used for a project by clicking the Details button for Create SIS Package and adding the certificate and key files. If you are new to platform security, read more about the fundamentals and implications for application signing in Nokia Developer Wiki's Platform Security article.
You have now completed all the configuration of the build and your phones, so debugging is now enabled whenever you have your phone is connected to your PC.
Build the application for the Symbian Debug target
Select 'Symbian Device' as a target in the left-hand toolbar (see Figure 21). Make sure that Debug is selected in Build and that the correct project is active.
To build all open projects, click the hammer icon in the bottom left-hand corner or use the CTRL+SHIFT+B keyboard shortcut. To build the active project only, use CTRL+B. You can follow the build progress under the Compile Output tab and will see that a self-signed *.sis file has been created automatically. Once the build and the installation package are ready, the text 'The process "<QtSDK_install_path>\...\epoc32\tools\make.exe" exited normally' appears.
Deploy and run the application on the phone
You are now ready to deploy and run the application on the phone. Click the green Run button or use the CTRL+R shortcut.
Optional: To add breakpoints and examine the code line by line, click the Debug button instead. See Qt Creator Help for more information on how to add breakpoints in Qt Creator.
Under the Application Output tab, you can see that the installation file has been deployed and installed on the phone and the application has started.
Now you have successfully deployed the application to the Symbian phone. In the next step, you will deploy a similar application to Nokia N9. Finally, you can find out more about Qt application development by examining useful documentation, code, and learning resources.
This section describes building the application for a Harmattan target and deploying the application on a Nokia N9. To enable the convenient deployment and debugging of the application on the Nokia N9, you need to install software on the phone to enable USB and WLAN connections with the Qt SDK. Some configuration is required in Qt Creator also.
To build and run Qt applications on the Nokia N9, you need the following:
- a Nokia N9 with USB cable.
- Qt SDK.
- a computer running 32- and 64-bit Linux or 32- and 64-bit Windows. Note that Qt Creator uses the Maemo Application Development and Debugging Environment (MADDE) to build, deploy and debug your applications. Unfortunately this environment is not available for Apple Mac OS X.
Set up the Nokia N9 and Qt Creator
To develop for the Nokia N9, you must first enable the developer mode on the device: To do this open 'Settings' from the application menu and select 'Security' from the list of settings. Then navigate to 'Developer mode' view and enable the mode by flicking the switch in the menu item. Accept all possible requests. The phone will download and install all the necessary tools required for application development. Additional tools can be installed manually in 'Developer mode' view (see figure 23).
Connecting the phone to PC
You can connect your Nokia N9 to your development PC using a USB or WLAN connection.
You need to use the SDK Connectivity tool, which was automatically installed when the developer mode was enabled, to create the phone-side endpoint for a USB or WLAN connection.
Connect the phone to you PC with the USB cable and select 'SDK mode' from the dialogue shown by the phone. Launch the SDK Connectivity tool and tap the USB button in the application's main page. The application will then display the 'Connectivity Details' page, which contains the password required to establish the first connection with the Qt SDK (see figure 24). Note that a new password is generated every time the SDK Connectivity tool is used and valid only when the tool is running.
Leave the SDK Connectivity tool running and open the Linux phone settings (shown in figure 25) from Qt SDK (Tools -> Options -> Linux Devices tab).
Click Add, select Device with MADDE support in the displayed dialogue and click Start Wizard. Name the configuration (see figure 26) and click Next. In most cases there's no need to change the IP address, but for trouble shooting please refer to the MeeGo 1.2 Harmattan Developer Library.
Next you can set up key-based authentication of the connection between the phone and the Qt SDK. This is recommended as it frees you from needing to use password every time you connect your phone to the PC. To do this, you must first create a new key: Select No in the Device Status Check dialogue and click Next. In the Existing Keys Check dialogue, select the create new keys option. You will then be prompted for the location of the new key pair, and for a password to encrypt your private key (see figure 27).
Finally, proceed to the Key Deployment dialogue (see figure 28).
Once you have deployed the key using the password generated by the SDK Connectivity, you should see a dialogue notifying you of the successful deployment (see figure 29).
A phone configuration test is automatically run after the setup (see figure 30).
You have now successfully connected your Nokia N9 to Qt SDK. Next you will use the project template to create a new Qt Quick application for Nokia N9.
Build, deploy and run the application on the phone
The steps for creating a project are similar to the ones you followed in Step 2, except that we will use Qt Quick Components for Harmattan and select the Harmattan target for the deployment (see figures 31 and 32).
With the project created, verify that the Harmattan build and run settings are set correctly. Click Projects to open the Projects view. You should see the build settings of the Harmattan target (see figure 33). The build configuration should be Harmattan Target (Qt SDK) Release and the Qt version Harmattan Target (Qt SDK).
The run settings (see figure 34) should have the configuration for your phone selected. In the Run Settings view you can manage the version number and the packaging information of your application.
Click Edit to get back to the editing view. Click the hammer button to build the application.
Now you are ready to deploy the application. Click Run to package the application and install it to the phone. The Debian package containing the built application can be located in the root folder of the project.
Now you have successfully deployed the application to your Nokia N9. Find out more about Qt application development by examining useful documentation, code, and learning resources in the next step
You have successfully created your first project in the Qt SDK and tested it in the Qt Simulator as well as on a Symbian phone or the Nokia N9. You can now continue with the following steps:
Examine the Qt Creator and Qt Simulator features
Even if you are familiar with the Qt Creator IDE, it's a good idea to open Help and navigate to Qt Creator. There you will find a comprehensive manual describing how to create and manage projects that enables you to create C++ and Qt Quick applications, and details on how to use Qt Designer to create UIs easily.
You can also learn how to use the advanced features of the Qt Simulator, by going to Qt Simulator section.
There are also heaps of useful resources at http://qt.digia.com/
Use Qt Reference Documentation to find information on available the APIs
When you are ready to start developing an application, API documentation is available for you in Qt Creator: go to Help > Qt Reference Documentation for comprehensive documentation, including tutorials and example applications.
Examine code examples
A full set of Qt cross-platform examples is available in the <QtSDK_install_path >\Examples directory. In addition, a selection of advanced, mobile-optimised example applications is available for download at Qt Code Examples (Nokia Developer Example Code) (many of these examples are also hosted as Nokia Developer Projects). All example applications come with a full source that you can examine and utilise in your own applications.
In addition, there are a large number of community-contributed articles with code: Portal:Qt Code Examples
Use mobile features
The Qt Mobility API provides a set of interfaces — such as Messaging, Contacts, and Location — to enable mobile use cases. The Mobility API is available in two flavours: as QML bindings, for easy access from a Qt Quick application, and as C++ APIs. For in-depth API documentation, go to Help > Qt Mobility Project Reference Documentation in Qt Creator. You can also check out the online documentation.
Expand with platform features
Even though the Qt APIs offer are a comprehensive set of features for richly functional applications targeted at the Symbian and MeeGo 1.2 Harmattan platforms, in some applications there may be a need for additional platform features that are not part of Qt or the Qt Mobility API. In these cases you have the option to use Symbian and Harmattan platform APIs from Qt Creator. Symbian C++ API documentation is available in Help > Symbian Reference Documentation for Qt. For Harmattan documentation, go to the MeeGo 1.2 Harmattan Developer Library.
Get help and technical support
Technical help and expertise can be obtained through the Qt discussion boards