Category:Tools::QtComplex: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
 
(Convert ExpressionEngine links)
 
(5 intermediate revisions by 3 users not shown)
Line 1: Line 1:
=Qt-Complex (1.1.0 Harmattan release)=
{{Delete|reason=Obsolete information}}


[[Image:QtComplexHarmattan06x500.jpg|Qt-Complex in action]]
= Qt-Complex (1.1.0 Harmattan release) =


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 [https://projects.developer.nokia.com/Qt_Complex/wiki '''project wiki pages'''] ''[projects.developer.nokia.com]''.<br /> 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 <span class="caps">QML</span> philosophy Qt-Complex is hyerarchical so you find simple elements (button switch, button, standard toolbar, …) and complex elements that reuses the same base objects.
[[Image:https://projects.developer.nokia.com/Qt_Complex/files/QtComplexHarmattan06x500.jpg|Qt-Complex in action]]


==Other pages in this wiki==
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 [https://projects.developer.nokia.com/Qt_Complex/wiki '''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
* [[QtComplexGeometryTool]] to create device-independent UI designs
Line 11: Line 14:
* [[QtComplexTestApplication]] code dissection
* [[QtComplexTestApplication]] code dissection


==Adding the framework to your project==
== 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 <span class="caps">QML</span> pages and other stuff. The Qt-Quick project can be cloned from the [https://projects.developer.nokia.com/Qt_Complex/browser Qt-Complex repository] ''[projects.developer.nokia.com]'' but the simple way is downloading the bare bone framework from [https://projects.developer.nokia.com/Qt_Complex/downloads/4 '''here'''] ''[projects.developer.nokia.com]''<br /> Supposing that your <span class="caps">QML</span> components are in the folder ''/Development_Folder/MyProject/qml/MyProject'' copy the Qt-Complex main folder in your <span class="caps">QML</span> project root. If your project has also a ''/images'' folder and a ''/components'' folder the result should be the following:
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 [https://projects.developer.nokia.com/Qt_Complex/browser Qt-Complex repository] but the simple way is downloading the bare bone framework from [https://projects.developer.nokia.com/Qt_Complex/downloads/4 '''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<br /> …/qml/MyProject/images/[graphic stuff]<br /> …/qml/MyProject/components/*.qml<br /> …/qml/MyProject/Qt-Complex/*.qml<br /> …/qml/MyProject/Qt-Complex/images<br /> …/qml/MyProject/Qt-Complex/themes/default
…/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===
=== Prerequisites ===


Qt_Complex can be installed in Qt-Quick project created with Qt <span class="caps">SDK</span> 4.7.3 with Qt-Quick components for Symbian and Meego. For more information and installation details read the lab article [http://labs.qt.nokia.com/2011/07/06/ready-made-ui-building-blocks-at-your-service-qt-quick-components-for-symbian-and-meego-1-2-harmattan/ Qt Quick components for Symbian and MeeGo 1.2 Harmattan] ''[labs.qt.nokia.com]''
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 [http://labs.qt.nokia.com/2011/07/06/ready-made-ui-building-blocks-at-your-service-qt-quick-components-for-symbian-and-meego-1-2-harmattan/ 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
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 for Harmattan ====
 
<code>import com.nokia.symbian 1.0<code>
 
==== Import for Symbian (and desktop) ====


====Import for Symbian (and desktop)====
</code>import com.nokia.symbian 1.0</code>


===Framework compatibility===
=== 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:
Qt-Complex is platform independent thus its components works on desktop, Symbian S60 3rd edition and 5th edition, Symbian[[Image:^1 and Symbian|^1 and Symbian]]^3 and on the Harmattan platforms. The framework components was tested on the following physical devices:


* Nokia E7-00
* Nokia E7-00
Line 37: Line 50:
* Macbook with Snow Leopard
* Macbook with Snow Leopard
* Windows 7 and Windows Xp SP3
* Windows 7 and Windows Xp SP3
* Ubuntu 10.4 Lucid
* 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:
 
<code>// Main.qml
 
import QtQuick 1.0
import "Qt-Complex" as Framework
 
Item {
id: screen</code>
 
== Using the framework components in your QML sources ==


===Importing Qt-Complex in your project===
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.


At this point to use the framework components in your project you should declare an ''import'' on top of your <span class="caps">QML</span> sources. Following the folder organization as described above, the result should something like the following example:
<code> // Map view object with navigaton controls
Item {
id: viewmap
width: screen.width;
height: screen.height - basebuttons.height - appTopBanner.height


==Using the framework components in your <span class="caps">QML</span> sources==
// Framework Map starts here
Framework.MapLoader {
id: viewmapLoader
width: viewmap.width; height: viewmap.height;
theme: "default"; obj: "MapView"
}
// Framework Map ends here


Adding the import statement in all the <span class="caps">QML</span> sources where you plan to use the framework it is simple also if the project already exist.
}</code>


===Managing components: the loader===
=== 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.<br /> 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 [https://projects.developer.nokia.com/Qt_Complex/wiki/FrameworkComponents '''component list'''] ''[projects.developer.nokia.com]'' in the project wiki.<br /> 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 <span class="caps">QML</span> 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.
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 [https://projects.developer.nokia.com/Qt_Complex/wiki/FrameworkComponents '''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:
Using the loader instead of the component itself has several advantages:
Line 60: Line 99:


Example1:
Example1:
<code> 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(); }
}</code>


Example2:
Example2:


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 [https://projects.developer.nokia.com/Qt_Complex/wiki/LoaderUsage '''Loader Usage'''] ''[projects.developer.nokia.com]'' at the project wiki.
<code> Framework.Loader {
id: ex2
width: parent.width; height: parent.height
theme: "MyTheme"; obj: "Button"; obj_string: "Text will be here"
onClicked: { manageEvent(); }
}</code>
 
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 [https://projects.developer.nokia.com/Qt_Complex/wiki/LoaderUsage '''Loader Usage'''] at the project wiki.


===Loader parametrization===
=== 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.
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.
<code>// 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 …']
}</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''.
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 ''<span class="caps">QML</span> Loader'' with some extending funcitonalities: its custom properties. The most interesting property of the <span class="caps">QML</span> 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.
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.
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==
== 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. <br /> 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.
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 [https://projects.developer.nokia.com/Qt_Complex/wiki/CreatingTheme '''themes How-to'''] ''[projects.developer.nokia.com]'' in the wiki project page.
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 [https://projects.developer.nokia.com/Qt_Complex/wiki/CreatingTheme '''themes How-to'''] in the wiki project page.


===The ‘theme’ custom property===
=== The 'theme' custom property ===


Calling the loader from your application there are two mandatory custom properties that should be set:<br /> The ''theme'' property is the theme name: this is the subfolder of ''Qt-Complex/themes/'' where you should put your theme images and custom <span class="caps">QML</span> documents. There is a workaround due to a behavior actually unsolved described here http://developer.qt.nokia.com/forums/viewthread/8110<br /> As a matter of fact the ''theme'' property should be set anyway as an explicit string instead of a parameter defined somewhere else.
Calling the loader from your application there are two mandatory custom properties that should be set:
<code>
theme: "theme_name"
obj: "object_to_load"
</code>
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

Latest revision as of 16:24, 18 August 2015

This article is nominated for deletion. Reason: Obsolete information
Please raise your support/opposition to this nomination in the article's discussion page.

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

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

This category currently contains no pages or media.