Qt-Complex (1.1.0 Harmattan release)

Qt-Complex in action

This article is intended as a quick user guide for the Qt-Complex framework installation and usage, 1.1.0 Harmattan release. A complete documentation can be found on the project wiki pages. Qt-Complex is a code package that can be added to any Qt-Quick project - also existing - giving the possibility to manage complex components like Ovi maps navigation, animated toolbars, grouped switches etc. Following the QML philosophy Qt-Complex is hyerarchical so you find simple elements (button switch, button, standard toolbar, …) and complex elements that reuses the same base objects.

Other pages in this wiki

• QtComplexGeometryTool to create device-independent UI designs
• QtComplexComponentsShortcut application notes and useful links
• QtComplexTestApplication code dissection

Adding the framework to your project

Qt-Complex is a opensource package that you should include in your project tree as an independent set of QML pages and other stuff. The Qt-Quick project can be cloned from the Qt-Complex repository but the simple way is downloading the bare bone framework from here Supposing that your QML components are in the folder /Development_Folder/MyProject/qml/MyProject copy the Qt-Complex main folder in your QML project root. If your project has also a /images folder and a /components folder the result should be the following:

…/qml/MyProject/*.qml …/qml/MyProject/images/[graphic stuff] …/qml/MyProject/components/*.qml …/qml/MyProject/Qt-Complex/*.qml …/qml/MyProject/Qt-Complex/images …/qml/MyProject/Qt-Complex/themes/default

Prerequisites

Qt_Complex can be installed in Qt-Quick project created with Qt SDK 4.7.3 with Qt-Quick components for Symbian and Meego. For more information and installation details read the lab article Qt Quick components for Symbian and MeeGo 1.2 Harmattan

To manage the Qt Quick components in your document sources you need to import the component itself (after the installation in you Qt Creator environment). It is needed to manage two different imports if you are developing applications for Harmattan Meego 1.2 or Symbian platofrms due to a known bug as you can find in this forum post: http://developer.qt.nokia.com/forums/viewthread/7971

Import for Harmattan

import com.nokia.symbian 1.0<code>

==== Import for Symbian (and desktop) ====

import com.nokia.symbian 1.0

Framework compatibility

Qt-Complex is platform independent thus its components works on desktop, Symbian S60 3rd edition and 5th edition, Symbian^1 and Symbian^3 and on the Harmattan platforms. The framework components was tested on the following physical devices:

• Nokia E7-00
• Nokia N8
• Nokia E90 (experimental only)
• Nokia N950 (full working integrating page stack navigation)
• Macbook with Snow Leopard
• Windows 7 and Windows Xp SP3
• Ubuntu 10.4 Lucid

Importing Qt-Complex in your project

At this point to use the framework components in your project you should declare an import on top of your QML sources. Following the folder organization as described above, the result should something like the following example:

// Main.qml

import QtQuick 1.0
import "Qt-Complex" as Framework

Item {
 id: screen

Using the framework components in your QML sources

Adding the import statement in all the QML sources where you plan to use the framework it is simple also if the project already exist.

 // Map view object with navigaton controls
 Item {
 id: viewmap
 width: screen.width;
 height: screen.height - basebuttons.height - appTopBanner.height

// Framework Map starts here
 Framework.MapLoader {
 id: viewmapLoader
 width: viewmap.width; height: viewmap.height;
 theme: "default"; obj: "MapView"
 }
 // Framework Map ends here

}

Managing components: the loader

One of the most important features of the Qt-Complex framework is that its components can be integrated and managed directly from your sources. The simple inclusion of the component as shown in the Map view example above is only to give you an idea of what can be done. The framework has a set of predefined components i.e. Button, ButtonIcon, ButtonToolbar, MapView, Switch, Toolbar etc. For a complete list and description of the framework components read the component list in the project wiki. All the objects are built to be parametric and device independent. But it is not all: you don't need to instantiate the components in your QML sources because you use the Loader. This is a component that can be configured through its properties: the same loader is used to manage all the framework components.

Using the loader instead of the component itself has several advantages:

• Components uses memory and device resources only when they are physically loaded.
• Components no more used in the program can be unloaded with the Destroy() method
• The components names are string and can be built with functions.
• Complex objects can instantiate the loader for a variable number of times.
• The loader can be used to dynamically manage your components.

Example1:

 Framework.Loader {
 id: ex1
 width: parent.width; height: parent.height
 theme: "MyTheme"; obj: "ButtonIcon"; obj_string: "Text will be here"
 obj_icon: fwProperties.btnBack
 onClicked: { manageEvent(); }
 }

Example2:

 Framework.Loader {
 id: ex2
 width: parent.width; height: parent.height
 theme: "MyTheme"; obj: "Button"; obj_string: "Text will be here"
 onClicked: { manageEvent(); }
 }

The two examples below shows how to call the loader managing two different components. For more information on loader usage and properties setting please read Loader Usage at the project wiki.

Loader parametrization

As a matter of fact the loader is full transparent to the program logic: it is an intermediate element holding the instance name to manage all the signals of the object that it is pointing to. In the following example you can see how the loader can be parametrized calling one component instead of another or nothing at all.

// Start of MyDocument.qml
Instance {
 id: myInstance

// Set the object to show in the UI based on a program parameter
 function getObjectName() {
 if(decisionFlag  1)
            return "ButtonIcon";
        else
            if(decisionFlag  2)
 return "Button";
 return "";
}

[… your soruce code …]

// The loader shows the object returned by the function
 Framework.Loader {
 id: myloader
 width: Jmain.getBaseCenterBtnWidth(); height: parent.height
 theme: "MyTheme"; obj: getObjectName(); obj_string: "Object text"
 onClicked: { manageEvent(); }
 }

[… your source code …']
}

In this code snippet it is not sure what is the object shown by myLoader at this point: it depends by the value of the decisionFlag.

The framework Loader component is the replacing of the QML Loader with some extending funcitonalities: its custom properties. The most interesting property of the QML Loader is that to destroy a loaded object it is sufficient to set the Loader.obj property to an empty string. Qt-Complex Loader uses this property to destroy the loaded components but instantiating a Loader with the Loader.obj string set to "" (empty string) no object is loaded so nothing is shown.

It is also possible to enable the auto-destruction of the loader setting the destroyAfter flag to true. When this flag is set when the loaded object fires a signal to the calling program the loader is immediately destroyed i.e. in cases where a object should show a condition that occasionally occours in the program flow and can happen only once.

Theming

Qt-Complex supports multiple themes at the same time. The simplest application of theming representing this feature is the usage of the theme property of the Loaders. To add a personalized set of graphic elements you need to create your own theme folder under …/Qt-Complex/themes with the design you need. Files should have the same name you see in the default theme folder. But the most interesting property of the theme management in Qt-Complex is that you can create your own loadable components that should be used only with certain themes and not with others.

Then you can also add to your theme folder - that is not a graphic repository ony - also theme-dependant personalized components or script functions. To know more about theme management in Qt-Complex you can read the themes How-to in the wiki project page.

The 'theme' custom property

Calling the loader from your application there are two mandatory custom properties that should be set:

theme: "theme_name"
obj: "object_to_load"

The theme property is the theme name: this is the subfolder of Qt-Complex/themes/ where you should put your theme images and custom QML documents. There is a workaround due to a behavior actually unsolved described here http://developer.qt.nokia.com/forums/viewthread/8110