Porting a Qt widget app

Qt widget apps use classes that inherit from QWidget to construct UI elements and controls. Qt widget apps differ from Qt Quick apps in a few ways. Qt widget apps are typically written in C++, whereas Qt Quick apps are written in QML and JavaScript, with the possibility of extending functionality using C++ based plug-ins. The rendering engines between Qt widget and Qt Quick apps also differ: Qt widgets use QtGui and Qt Quick use the QtDeclarative paint engine.

This section describes how to port a Qt widget application to BlackBerry 10 without making major changes to your code. If you want to port a Qt Quick application, see Porting a Qt Quick app. If you want to rebuild or change part of your application using Cascades, switch to the Cascades focus by using the focus switcher in the upper-left corner of this page.

For this example, we'll be porting the animatedtiles sample application that comes packaged with the Qt 4.8.4 desktop libraries. This sample app consists of a single screen and five buttons. Users can tap a button to display a pattern created using an image asset on the screen. You can download a binary installer for the Qt 4.8.4 libraries if you don't have them already. After you've installed the libraries, you can find the sample application at <Qt installation directory>\examples\animation\animatedtiles.

Setting up the project

The first step to porting a Qt widget application is to open your existing project in Qt Creator. Navigate to the location of your existing application and open the associated .pro file. On the Configure Project screen, ensure that your kit is selected and click Configure Project.

After you open the project in Qt Creator, your project view should look like this:


Screen showing the project view in Qt Creator.

Next, we add a bar-descriptor.xml file to the project. Right-click the root project folder in the Projects view and select Add New. In the New File dialog, select BlackBerry under Files and Classes, choose Application descriptor, and click Choose. In the New File wizard, you can also change information about the project, but for this example we just want to use the default settings. Click Next > Next > Finished.

After you add the bar-descriptor.xml to the project, you need to define the name, description, publisher, and copyright information in the bar-descriptor.xml file. After you enter these values, define the project path. In the bar-descriptor.xml file, change the PROJECTPATH to animatedtiles. Save your work.


Screen showing the values that you need to enter in the bar-descriptor.xml file.

If your app uses features such as shared files, the camera, and networking, you may need to set app permissions in the bar-descriptor.xml file. For more information, see App permissions.

After you change the project path, build and run the app. You will end up with an app that looks like this:

Screen showing a first attempt at running a Qt widget app on a BlackBerry 10 device.

Although the app is running, it doesn't look as good as it can. Let's tweak the app to fix that.

Tweaking the UI

When you port your Qt widget application, pay close attention to the following things:

  • Window and font sizes
  • Screen orientation
  • Location of controls

In this example, the first issue we should address is correcting the display size for the app.

In the Sources folder for the project, open main.cpp. At line 213, there's an if statement that checks the OS of the device and displays the screen size depending on the OS of the device.

#ifdef Q_OS_SYMBIAN
    view->showMaximized();
#else
    view->show();
#endif

For this example, let's assume that your users will want to view the application in full screen. Remove the if statement and specify that you want the view to be maximized at all times:

view->showFullScreen();

Save your work and run the app again:

Screen showing a ported Qt widget app running in full screen on a BlackBerry 10 device.

Now that the app is displayed in full screen, let's address the location of the buttons.

Because we want the buttons to be easy to reach in a portrait orientaton, let's move them down to the bottom of the screen. In main.cpp, the position of the buttons is set using the following line:

buttonParent->setPos(200, 200);

Change the location of the buttons as follows:

buttonParent->setPos(0, 500);

Next, let's change the button layout to make better use of the space at the bottom of the screen. In main.cpp, find the following code and change the values as follows:

ellipseButton->setPos(-300, 0);
figure8Button->setPos(-150, 0);
randomButton->setPos(0, 0);
tiledButton->setPos(150, 0);
centeredButton->setPos(300, 0);

Finally, update the image assets of the project by copying new files into the images folder of the project workspace. Build and run the application:

Screen showing a finished Qt widget app running on a BlackBerry 10 device.

That's it! From here, your next step is to sign and distribute the app on BlackBerry World.

Last modified: 2013-12-21

comments powered by Disqus