1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
|
/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia. For licensing terms and
** conditions see http://qt.digia.com/licensing. For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example dialer
\title Service Framework using QML Example
\ingroup serviceframework-examples
\brief This example demonstrates the usage of the Service Framework's QML API.
\b {Execution}
This example requires the example dialer services to be registered in order
for the application to discover and load the services. This can be done by using the
service framework command line tool to add the corresponding service XML file:
\list
\li servicefw add landlinedialerplugin.xml
\li servicefw add remotedialerservice.xml
\li servicefw dbusservice removedialerservice.xml dialer_service
\endlist
These deployment commands will register the remote IPC-based service, and the Landline dialer plugin. The last
line features the ability to create an autostarting file for D-Bus if the platform supports the QtDBus module.
To run the example
\list
\li dialer
\endlist
The XML files for all example services can be found in the Qt build directory
under examples/qtsystems/serviceframework/xmldata.
For Maemo and Linux platforms using D-Bus as the underlying IPC mechanism, the
autostart feature can be initialised by running the service framework tool:
\code
servicefw dbusservice xmldata/remotedialerservice.xml dialer_service
\endcode
For other platforms that fall use QLocalSocket, then if the services
binary can be found in your path it'll auto start the service.
\b {Explanation}
This example should demonstrate how to use the Service Framework to
access a list of services in a QML context. A library plugin provides QML with elements
that can reference a single service or a list of services, called 'Service' and
'ServiceList' respectively.
\target guidesign
The GUI looks like following picture:
\image DialerServiceGUI.png "GUI"
The following steps outline how to make a QML based application using the Service Framework technology.
It is assumed that QtMobility has been successfully built and environment variables have been set
as per \l {Installation Guide}.
\b {Service Framework in QML:}
To include the Service Framework QML plugin we need to import it as follows:
\snippet serviceframework/dialer/content/DialerList.qml 4
\b {The Services:}
The services are implemented as a sevices and a shared library and can be register in the service framework.
After the service is registered it can be used in different applications.
In our case we'll access the services over an application that is based on QML scripting.
We will be able to change between different services and call their properties,
receiving their signals and so forth.
In this example we've implemented a service called
Voipdialer and a plugin Landlinedialer.
You can find the projects for these:
remotedialerservice
Those projects will create a service.
The service needs to be available over the Service Framework,
we need to register it.
In our example this will be done manually by using the servicefw tool. Refer to the project
README for further details.
As you can see we register the services using a xml file.
This xml file basically contains all information to register the shared library in the
Service Framework environment.
For more information please read more about the Qt Service Framework
\l {service-frameworks.html#adding-and-removing-of-services}{XML Format}
The QServiceManager creates an instance of a plugin service over a QServicePluginInterface.
For each plugin services we provide a Plugin.
\snippet serviceframework/voipdialerplugin/voipdialerplugin.h 0
The Q_INTERFACES macro tells Qt which interfaces the class implements.
Sevice plugins need to implement the QServicePluginInterface.
In our case we only need to overwrite the virtual function createInstance.
\snippet serviceframework/voipdialerplugin/voipdialerplugin.cpp 0
As you can see the createInstance function create the appropriate dialer object
and returns it.
The Q_PLUGIN_METADATA macro provides the necessary implementation for a plugin.
See \l{How to Create Qt Plugins} for more details.
The last thing we need to provide in our services are the states, properties, signals and slots that we
want to access in out QML script later.
\target voipdialer_h 0
\snippet serviceframework/voipdialerplugin/voipdialer.h 0
\b {Service access on the QML side}
The QML elements are implemented in 4 different qml scripting files
\l {guidesign}{ see GUI design}.
The first step is to use our ServiceWrapperList to specify the interface and minimum version (optional) through QML item
context, which will produce a list of ServiceWrapper objects.
\snippet serviceframework/dialer/content/DialerList.qml 5
In the DialerList.qml file the services property is assigned to the ListView model property.
\snippet serviceframework/dialer/content/DialerList.qml 0
To show the items of the model property we need to create a delegate component and assign it to the ListView
Delegate property:
\snippet serviceframework/dialer/content/DialerList.qml 1
In this component you can define how you want to draw one ListView item.
You can access inside of this component the current ListWiew item by using the variable modelData.
In our example we are using two text lines. Furthermore we can define whats happening if we click
on a ListView item by using the MouseRegion.
\target DialerList_qml_2
\snippet serviceframework/dialer/content/DialerList.qml 2
Another component can be created for highliting a list item:
\snippet serviceframework/dialer/content/DialerList.qml 3
\b {Service signals and function calls on the QML site}
In sfw-kinetic-example.qml we define a control named DialScreen and implement
the function onDial and onHangup.
As you can see in the onDial event we call the service function dialNumber and
the onHangup calls hangup.
Both function are implemented in the service \l {voipdialer_h_0} { (see voipdialer header file).}
\snippet serviceframework/dialer/dialer.qml 0
In DialScreen.qml the dial and the hangup signals are defined.
The hangup signal will be emitted if the HangUpButton was clicked:
\snippet serviceframework/dialer/content/DialScreen.qml 1
The dial signal will be emitted if the CallButton was clicked:
\snippet serviceframework/dialer/content/DialScreen.qml 2
Now we need to connect the stateChanged signal form the services with an event handler on the QML site.
This is done in our main declarative file:
\snippet serviceframework/dialer/dialer.qml 1
The DialScreen.currentDialer is assigned during a ListView item click in the
\l {DialerList_qml_2}{ ServiceList.qml file}.
*/
|
