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
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
|
/****************************************************************************
**
** 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$
**
****************************************************************************/
/*!
\page location-plugin-jsondb.html
\title Qt Location JsonDb plugin (technical preview only)
\previouspage {Qt Location Module}
\ingroup QtLocation-plugins
\brief Local store for user defined favorite places.
\section1 Overview
Included with Qt Location is a plugin which stores places in a Qt Json Database
(also known as JsonDb). This plugin is intended to be used as a local store for
user defined favorite places.
The JsonDb GeoServices plugin can be loaded by using the plugin key "places_jsondb".
Note that in order to use this plugin, the JsonDb daemon must be running in the
background.
This plugin is provided as a technical preview only, there is no guarantee that
data integrity is maintined when upgrading to the official plugin release. This plugin
has a build dependency on Qt JsonDb.
\section1 Parameters
The following table lists optional parameters that can be passed to the Nokia plugin.
\table
\header
\li Parameter
\li Description
\row
\li places.partition
\li Specifies which JsonDb partition to store Places and Categories. If no partition is specified, the default
partition is used.
\endtable
\section1 Places
The Nokia JsonDb provider accesses places stored locally on device.
It provides read/write access to the place repository. The specific
capabilities are outlined below:
\section2 Capabilities
\table
\row
\li Storage
\li local
\row
\li Read/Write
\li read/write
\row
\li Icons
\li yes
\row
\li Search term suggestions
\li no
\row
\li Recommendations
\li no
\row
\li Category structure
\li Hierarchical
\row
\li (Rich) Content images
\li no
\row
\li (Rich) Content reviews
\li no
\row
\li (Rich) Content editorials
\li no
\row
\li All details fetched during search
\li yes
\row
\li Paging offset index
\li yes
\row
\li Paging limit
\li yes
\row
\li Distance relevance hint
\li yes
\row
\li Lexical name relevance hint
\li yes
\row
\li Extended Attributes
\li no
\row
\li Notifications for added/removed places/categories
\li yes
\row
\li visibility scopes
\li device
\row
\li favorites matching/(usable as favoritesPlugin)
\li yes
\endtable
\section2 Plugin Specific Behaviors
\section3 Search
The following list shows what core place data is returned during a place search:
\list
\li name
\li location
\li contact information
\li icon
\li categories
\endlist
The JsonDb plugin does not support any other details so all
available details are fetched during a search. The JsonDb plugin
does not support saving of any other details.
\section3 Icons
\section4 Parameter Reference
The JsonDbPlugin supports the following icon parameter values
\table
\header
\li Key
\li Value
\row
\li smallUrl
\li Holds the URL for the small icon
\row
\li smallSize
\li Holds the dimensions of the small icon
\row
\li smallSourceUrl
\li Holds the source URL from which the small icon is to be copied/downloaded from.
\row
\li mediumUrl
\li Holds the URL for the medium sized icon.
\row
\li mediumSize
\li Holds the dimensions of the medium sized icon.
\row
\li mediumSourceUrl
\li Holds the source URL from which the medium icon is to be copied/downloaded from.
\row
\li largeUrl
\li Holds the URL for the large icon.
\row
\li largeSize
\li Holds the dimensions of the large icon.
\row
\li largeSourceUrl
\li Holds the source URL from which the large icon is to be copied/downloaded from.
\row
\li fullscreenUrl
\li Holds the URL for the fullscreen icon.
\row
\li fullscreenSize
\li Holds the dimensions of the fullscreen icon.
\row
\li fullscreenSourceUrl
\li Holds the source URL from which the fullscreen icon is to be copied/downloaded from.
\endtable
In C++ the value of the URLs must always be a QUrl.
In QML the values of the URLs may be url or string types.
\section4 Typical Usage
During a typical place search, the icon parameters might be populated like so
\code
smallUrl: file:///foo/bar/icon_s.png
smallSize: QSize(20,20)
largeUrl: file:///foo/bar/icon_l.png
largeSize: QSize(50,50)
\endcode
Only small and large icons were available in this case. Note that for a given size URL, its dimensions will also be populated.
These URLs and dimensions are used by the JsonDb plugin to determine the correct URL to return when QPlaceIcon::url() or \l {QtLocation5::Icon::url()} {Icon::url()}
is called.
If we wish to change the icons we, can simply specify a different set of parameter values and then save the place or category containing the icon.
\code
smallUrl: file:///opt/icons/new_icon_small.png
(smallSize: QSize(20,20)) //optional
largeUrl: file:///opt/icons/new_icon_large.png
(largeSize: QSize(50,50)) // optional
\endcode
All we need to do is set the URLs to where the new icon image is. The size typically does not need to be specified
since it is generally automatically calculated. In some cases where the size cannot be calculated, for example if the
specified URL cannot currently be accessed, it is necessary to specify a recommended size.
If the size of the image can be calculated and a size is also specified, then the specified size is ignored.
\section4 Copying/Downloading Icons to a Specified Destination
When saving icons, we use the source parameters to hold the URL of the source image we are copying from
\code
smallSourceUrl: http://www.example.com/icon_s.png
smallUrl: file:///bar/icon_small.png
(smallSize: QSize(20,20) //optional
\endcode
Using the parameters above will copy the icon from \c smallSourceUrl to the \c smallUrl. The smallSourceUrl can be a remote or local URL,
but the smallUrl must be local. If the smallUrl already exists, it is overwritten, otherwise it is created.
\c smallSize typically does not need to be set since an attempt will be made to calculate the icon's size. In some cases where the size cannot be calculated, for example if the
specified URL cannot currently be accessed, it is necessary to specify a recommended size.
If the size of the image can be calculated and a size is also specified, then the specified size is ignored.
\section4 Copying/Downloading Icons Without a Specified Destination
It is possible to copy icons, when a place or category is saved and not have to
specify a destination. In this case, a data URL will be created for the icon
in the underlying database. A data URL contains the icon image embedded
into the URL itself. A destination size is chosen for the icon depending
on it's calculated size.
\code
//input parameters
smallSourceUrl: http://www.example.com/icon_small.png
//(1) Result if the source icon's actual size corresponded to small
smallUrl: data:image/png;base64,iVBORw0K….
smallSize: QSize(20,20)
//(2) Result if the source icon's actual size corresponded to medium
mediumUrl: data:image/png;base64,iVBORw0K….
mediumSize: QSize(30,30)
\endcode
The above shows that for a given input source URL, an appropriate destination is chosen for the data URL.
The icon will not necessarily be placed into smallUrl, since the size is calculated and a destination
chosen. The image at the sourceUrl must always been accessible so that the data URL can be generated,
consequently this prerequisite also means that a size need not be specified since can always be calculated.
This behavior of automatically choosing a destination is necessary because when an icon from a different plugin is saved,
it isn't known whether there is only one URL by the JsonDb plugin. When creating a compatible place from another
plugin, the JsonDbPlugin tries to get the URLs for the standard small, medium and large sizes. It is possible
however that all these may end up being the same URL. The JsonDb plugn filters out these duplicates and chooses
an appropriate destination based on size.
\code
//The resultant place's icon after calling QPlaceManager::compatiblePlace()
smallSourceUrl: http://www.example.com/foo.png
mediumSourceUrl: http://www.example.com/foo.png
largeSourceUrl: http://www.example.com/foo.png
//on save, the plugin filters out the duplicates and determines an appropriate size
//in this case the data URL for the large size has been created.
largeUrl: data:image/png;base64,qVyOZw0p...
largeSize: QSize(50,50)
\endcode
The fullscreen icon is never retrieved and converted into a data URL because data URLs are only meant
for small icon images.
\section3 Visibility Scope
The JsonDb plugin only supports places of the QLocation::PrivateVisibility scope.
Specifying the QLocation::UnspecifiedVisibility when saving a place will default
to the QLocation::PrivateVisibility scope.
\section3 Favorites Matching Parameters
The JsonDb plugin can be used as a favorites store and thus supports the following
parameters.
\table
\header
\li key
\li value
\row
\li "alternativeId" (aka QPlaceMatchRequest::AlternativeId)
\li alternative identifier attribute type, of the form "x_id_<provider name>" for example "x_id_nokia"
\row
\li "proximity"
\li The distance (m) allowed between places in order to be considered a match.
\endtable
*/
|
