← Back to branch summary

~ubuntu-branches/ubuntu/quantal/qtmobility/quantal

« back to all changes in this revision

Viewing changes to doc/src/examples/declarative-sfw-notes.qdoc

  • Committer: Bazaar Package Importer
  • Author(s): Jonathan Riddell
  • Date: 2010-11-16 16:18:07 UTC
  • mfrom: (1.1.3 upstream)
  • Revision ID: james.westby@ubuntu.com-20101116161807-k2dzt2nyse975r3l
Tags: 1.1.0-0ubuntu1
* New upstream release
* Syncronise with Debian, no remaining changes

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/examples/declarative-sfw-notes.qdoc
8
8
**
9
9
** $QT_BEGIN_LICENSE:LGPL$
10
10
** Commercial Usage
11
 
** Licensees holding valid Qt Commercial licenses may use this file in
12
 
** accordance with the Qt Solutions Commercial License Agreement provided
13
 
** with the Software or, alternatively, in accordance with the terms
 
11
** Licensees holding valid Qt Commercial licenses may use this file in 
 
12
** accordance with the Qt Commercial License Agreement provided with
 
13
** the Software or, alternatively, in accordance with the terms
14
14
** contained in a written agreement between you and Nokia.
15
15
**
16
16
** GNU Lesser General Public License Usage
33
33
** ensure the GNU General Public License version 3.0 requirements will be
34
34
** met: http://www.gnu.org/copyleft/gpl.html.
35
35
**
36
 
** Please note Third Party Software included with Qt Solutions may impose
37
 
** additional restrictions and it is the user's responsibility to ensure
38
 
** that they have met the licensing requirements of the GPL, LGPL, or Qt
39
 
** Solutions Commercial license and the relevant license of the Third
40
 
** Party Software they are using.
41
 
**
42
36
** If you are unsure which license is appropriate for your use, please
43
37
** contact the sales department at qt-sales@nokia.com.
44
38
** $QT_END_LICENSE$
50
44
 
51
45
\title Declarative Service Framework Notes Manager
52
46
 
 
47
\bold {Execution}
 
48
 
 
49
This example requires the example Notes Manager service to be pre-registered in order 
 
50
for the application to obtain the default interface. This can be done by using the 
 
51
service framework command line tool to add the corresponding service XML file:
 
52
 
 
53
\list
 
54
    \o ./servicefw add notesmanagerservice.xml
 
55
\endlist
 
56
 
 
57
There are 2 ways to run the example:
 
58
\list
 
59
    \o ./qmlnotes (only method for Symbian)
 
60
    \o qmlviewer declarative-sfw-notes.qml
 
61
\endlist
 
62
 
 
63
The XML files for all example services can be found in the QtMobility build directory
 
64
under install/bin/xmldata
 
65
 
 
66
\bold {Explanation}
 
67
 
53
68
This example demonstrates how to use the \l{notesmanagerplugin}{Notes Manager service plugin}
54
69
to implement a notes managing application with QML as the declarative user-interface.  There
55
70
is also a non-QML counterpart which demonstrates an identical application using standard Qt
56
71
user-interface tools.  See \l{sfw-notes}{Service Framework Notes Manager} for more details.
57
72
 
58
 
 
59
 
\bold {Explanation}
60
 
 
61
73
The QServiceManager and QServiceInterfaceDescriptor API are provided to QML through the use
62
 
of a plugin-based system. The resulting class is referred to as QDeclarativeService, which
63
 
provides users with the ability of accessing services by loading the interfaces specified
64
 
using the QML element 'Service'.
 
74
of a plugin-based system that allows users to describe a service as a QML element called 
 
75
\l Service.  The service framework QML plugin also acces to an instance of the service from
 
76
within QML so that clients can make metacalls on the service object.
65
77
 
66
78
This example demonstrates how QML can be used to completely control the logic of the 
67
 
application, using a combination of declarative elements and Javascript in the QML file. To run
68
 
the application refer to the README file supplied which
69
 
includes instructions on how to setup and run the QML file demonstrating service framework 
70
 
capabilities.
 
79
application, using a combination of declarative elements and Javascript code.  To run the 
 
80
application refer to the above execution instructions on how to setup and run the example.
71
81
 
72
 
There is also  another service framework example that demonstrates how to use the QML library 
73
 
plugin browse a list of services to select for dialing usage. See 
 
82
There is also another service framework example that demonstrates how to use the QML library 
 
83
plugin browse a list of services to select for dialing usage.  See 
74
84
\l{declarative-sfw-dialer}{Declarative Service Framework Dialer} for a detailed explanation.
75
85
 
76
86
The section below explains how QML can be used to emulate to exact functionality of the
79
89
 
80
90
\bold {QML File}
81
91
 
82
 
The very first step is to import our registered types with the following:
83
 
\snippet declarative-sfw-notes/declarative-sfw-notes.qml 0
84
 
 
85
 
Now to obtain the default service with a specific interface name from within QML we can
86
 
use the Service wrapper item as follows:
87
 
\snippet declarative-sfw-notes/declarative-sfw-notes.qml 6
88
 
 
89
 
In most cases we will need the service to be available to all parts of the QML file, meaning
90
 
the actual QObject returned from the service wrapper needs to be a global property.
91
 
\snippet declarative-sfw-notes/declarative-sfw-notes.qml 1
92
 
 
93
 
The interfaceName property of the Service item has READ and WRITE methods which can be used
94
 
to obtain a new service instance and check if there was a valid default service.
95
 
\snippet declarative-sfw-notes/declarative-sfw-notes.qml 2
 
92
The very first step is to import our QtMobility Service Framework QML plugin library which
 
93
containts the required QML elements:
 
94
\snippet declarative-sfw-notes/content-sfw-notes/Main.qml 0
 
95
 
 
96
In most cases we will need the service instance to be available to all parts of the QML file,
 
97
meaning that we should declare a global variant for the QObject returned from the service
 
98
instance. It is also good practice to initialise this value to 0.
 
99
\snippet declarative-sfw-notes/content-sfw-notes/Main.qml 1
 
100
 
 
101
Now we can initiate our \l Service element with a default interface name and obtain the
 
102
service instance to our global object variable in the component on-completion section.
 
103
\snippet declarative-sfw-notes/content-sfw-notes/Main.qml 6
 
104
 
 
105
Although a default instance is obtained, the application allows for manually specifying
 
106
the Service::interfaceName property of the \l Service element to check if there was a 
 
107
valid default service at this interface name. Similarly, if there is a valid descriptor 
 
108
then the service instance can be obtained and we can call the initialise code of our
 
109
notes manager.
 
110
\snippet declarative-sfw-notes/content-sfw-notes/Main.qml 2
 
111
 
 
112
Connecting signals from our service object requires the following code. Note the use
 
113
of the ignoreUnknownSignals property which removes warnings for connecting unknown signals
 
114
before QML has obtained its QObject service instance.
 
115
\snippet declarative-sfw-notes/content-sfw-notes/Main.qml 7
96
116
 
97
117
With a valid reference which points to the service plugin class we can now invoke methods 
98
118
directly from the Notes Manager plugin. The example below shows how to obtain a list of
99
119
notes and delete one from the notes manager database through QML.
100
 
\snippet declarative-sfw-notes/declarative-sfw-notes.qml 3
 
120
\snippet declarative-sfw-notes/content-sfw-notes/Main.qml 3
101
121
 
102
122
The Notes Manager plugin also provides readable functions which return the values of a
103
123
single note and can be utilized to display on the UI as follows:
104
 
\snippet declarative-sfw-notes/declarative-sfw-notes.qml 4
105
 
\snippet declarative-sfw-notes/declarative-sfw-notes.qml 5
106
 
 
 
124
\snippet declarative-sfw-notes/content-sfw-notes/Main.qml 4
 
125
\snippet declarative-sfw-notes/content-sfw-notes/Main.qml 5
107
126
*/