×
Namespaces

Variants
Actions
Revision as of 05:49, 14 February 2014 by hamishwillee (Talk | contribs)

Qt

From Nokia Developer Wiki
Jump to: navigation, search

Warning.pngWarning: 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.

Qt is the recommended native framework creating apps for Symbian and Meego Harmattan (Nokia N9). You will find that Qt greatly reduces your coding effort, through intuitive APIs that deliver more functionality from less code. When it comes to your app's UI, the declarative, JavaScript-like QML language within Qt Quick and tools such as Qt Quick Components enable you to create compelling UIs faster than you thought possible. And better still, you only need one core code-base to address the 180 million Qt-powered Symbian and Nokia N9 phones in consumers hands today. Qt enables code reuse that allows you to build and deploy versions of your apps for desktop platforms too. And you will find all of this is possible without compromising your apps performance because Qt is a framework, not a runtime.

This article provides a getting started tutorial, along with links to: the SDK, related documentation, examples, and other resources.

Contents

Qt SDK

Everything you need to start develop in Qt is provided in the Qt SDK, which can be downloaded from:


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


Documentation

In addition to the API documentation in Qt Creator (Help > Qt Reference Documentation), see the other relevant documentation resources:


Code Examples


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.

Figure 2: The setup wizard opens; this may take a while on slower PCs.
Figure 3: Select the installation directory.
Figure 4: Accept the license agreement.
Figure 5: Select a Start Menu location in which to place the SDK's shortcuts.
Figure 6: The download and installation progress of each component can be monitored.

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.

Figure 7: Once installation is complete, click Finish to launch the Qt Creator IDE.
Figure 8: Qt Creator having been successfully launched.


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.

Figure 9: Select New File or Project from the File menu.
Figure 10: Select the Qt Quick Application template.

Click Choose to add a name and select the location for the project. Click Next.

Figure 11: Select Qt Quick Components for Symbian as the application type and click Next
Figure 12: Select the targets for the project. In this section you'll run the application using the Qt Simulator, so make sure that the simulator target is selected. If you want to deploy the application to a Symbian phone (which you do in the next step), select the Symbian target also.

Note.pngNote: If you want to add targets later, you can do so in the Projects view, which is accessible from the left-hand toolbar.

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.

Figure 13: The new project has been created.

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.

Figure 14: The buttons in the left-hand toolbar and the Compile Output log are shown.

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).

Tip.pngTip: When you have multiple projects open in Qt Creator, make sure the correct project is active using the Project bar of the pop-up menu.

Figure 15: The target selection menu.


Click the green run button (see Figure 14).

Figure 16: The Qt Simulator is launched with the template application running.

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.

Figure 17: Qt Simulator Control window.

Note.pngNote: 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.

Prerequisites

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.

Note.pngNote: If Nokia Suite has problems installing the *.sis files, you can either copy the *.sis file from your computer to the phone in USB storage mode or send the file via a Bluetooth connection. Then install the file on the phone using, for example, the file manager application.

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).

Figure 18: The Symbian Build Settings view is shown.


Note.pngNote: If you didn't add a Symbian target in the project creation phase in Step 2, the Symbian Device tab will not be visible. To add the target now, click '+' and select Symbian in the drop-down menu.

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).

Figure 19: The certificate can be defined in the Create SIS Package section. In this picture the details tab is opened.


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.


Figure 20: Whenever the phone is connected to the PC, this notification appears to confirm that debugging is enabled.


Note.pngNote: If debugging was not enabled automatically, launch the CODA application from the RnD Tools folder in the application menu of your Symbian phone and use Settings to configure the connection. You can also define whether you want to enable debugging automatically on connect (USB Plug and Play).

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.

Figure 21: The Symbian Device Debug build is selected. Compile Output shows a successful build.

Note.pngNote: You can create the Release build of the application in a similar fashion.

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.

Figure 22: The application is running on the phone.

Note.pngNote: The build SIS package can be now located in the root folder of the project.

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.

Prerequisites

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).

Figure 23: Developer mode view in settings.

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.

Note.pngNote: {{{1}}}

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.

Figure 24: SDK Connectivity tool displaying the generated password required for the USB connection.

Leave the SDK Connectivity tool running and open the Linux phone settings (shown in figure 25) from Qt SDK (Tools -> Options -> Linux Devices tab).

Figure 25: Linux Devices settings view.


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.

Figure 26: Enter the name for your configuration in the General Information dialogue.

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).

Figure 27: Select a password to protect the private key.

Finally, proceed to the Key Deployment dialogue (see figure 28).

Figure 28: Enter the password generated by the SDK Connectivity tool into Key Deployment dialogue and click Deploy Key.

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).

Figure 29: Key was successfully deployed.

A phone configuration test is automatically run after the setup (see figure 30).

Figure 30: The phone configuration test that is run automatically after completing setup.

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).

Figure 31: Selecting Qt Quick Components for Harmattan.


Figure 32: Selecting the Harmattan target.

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).

Figure 33: The Harmattan build settings.

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.

Figure 34: The Harmattan run settings.


Click Edit to get back to the editing view. Click the hammer button to build the application.

Figure 35: A successful build.


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.

Figure 36: The application running on the Nokia N9.

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.

Learn Qt

Learning how to code Qt applications is easy, no matter which programming background you have. Qt Quick consists of a declarative QML language and JavaScript. QML syntax is easy and especially handy when developing UIs and using animations. Together with JavaScript for application logic it's fast to develop complete applications. However, in many cases C++ may be a better option, C++ programmers will find Qt it fast to learn as there are few Qt-specific idioms and coding conventions. To learn more about Qt Quick principles go to Help > Qt Reference Documentation > What is Qt > Qt Quick. To achieve a platform look and feel in Symbian and Harmattan, we recommend using Qt Quick Components (Components for Symbian / Components for Harmattan). Read more on the available components in the SDK documentation by going to Help > Qt Quick Components for Symbian.

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

2209 page views in the last 30 days.

Was this page helpful?

Your feedback about this content is important. Let us know what you think.

 

Thank you!

We appreciate your feedback.

×