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
|
/****************************************************************************
**
** 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$
**
****************************************************************************/
/*!
\group qml-location-plugin
\title QML Location Plugin
QML Support for the QtMobility Project Location API.
*/
/*!
\page qml-location-plugin.html
\title Location QML Plugin
\brief A QML plugin for the QtMobility Project Location API.
\section1 Overview
The Location API gives users of the QtMobility Project the capability to write applications that understand a geographical location and movement of the position coordinates. Backend services can be called by the API to detect landmarks and display appropriate information. The QML Location Plugin delivers these capabilities in an easy to use form.
\section1 Positioning
\section2 Coordinate
The \l Coordinate is a basic unit of geographical information. The \l Coordinate element includes properties to hold the coordinate values for \l {Coordinate::latitude}{latitude}, \l {Coordinate::longitude}{longitude} and \l {Coordinate::altitude}{altitude}.
\section2 Position
The three dimensional position of an object such as a mobile device can be specified by giving the latitude, longitude and altitude. That is the values held in the Coordinate element. Additionally for computation of future positions we would like to know if the object is moving, what \l {Position::speed}{speed} it is doing and what is the \l {Position::timestamp}{timestamp} of the last position data. Position therefore includes values for \l {Coordinate::latitude}{latitude}, \l {Coordinate::longitude}{longitude}, \l {Coordinate::altitude}{altitude}, \l {Position::speed}{speed} and a \l {Position::timestamp}{timestamp}. \l Position also takes responsibility for validation of sensible values for these properties: just as there is a \l {Coordinate::latitude}{latitude} there is a property \l {Position::latitudeValid}{latitudeValid}. Similarly for the other properties with the exception of the timestamp.
\section2 PositionSource
We have a Position element, a Coordinate element but where do we get the
data from? It is a good idea to be able to indicate alternative sources.
Perhaps instead of directly picking up GPS satellites you want to do
some testing using a datafile. We may also need to manage our
interaction with the source.
The \l PositionSource element provides the developer with control,
within the limits allowed by the platform, of the source of the
geographical data. The positional data can be sourced from a logfile
which is in NMEA format.
\l {http://en.wikipedia.org/wiki/NMEA}{NMEA} is a common text-based protocol for specifying navigational data. For convenience, the \l {PositionSource::nmeaSource}{nmeaSource} property is provided to enable QML applications to read NMEA data from a log file, the source will emit updates according to the time stamp of each NMEA sentence to produce a "replay" of the recorded data.
\section2 Positioning Elements
\annotatedlist qml-location-plugin
\section1 Maps
The Map element can be used be used to display a map of the world. The
bulk of the functionality is provided by a mapping plugin described
by the plugin element associated with the Map.
Various map objects can be added to the map. These map objects are
specified in terms of coordinates and meters.
Interaction with the map objects is done via the MapMouseArea item.
\section2 Map Elements
While the Maps elements were already available as an early preview in QtMobility 1.1
the elements received considerable API and behavior changes in QtMobility 1.2. Therefore
the elements are \bold{no longer available as 1.1 import}. QML applications \bold{have to change}
their import statement to 1.2. Applications using any Map element in QtMobility 1.2
via a QML 1.1 import will fail to work.
Applications wanting to target QtMobility 1.1 and 1.2 at the same time must deploy
two different QML import statements based on the QtMobility version being used.
\annotatedlist qml-location-maps
\section1 Landmarks
Most maps have landmarks. Useful markers identified in the landscape either as destinations
or things that are noteworthy. In QtMobility the QML Location plugin supports
Landmarks on maps using the Location API. Landmarks can be imported into
the application and populate the map with associated position data, meta-data
and icon representations.
The main element is \l Landmark. Using \l Landmark we can specify the name,
phone number, some descriptive text, the radius of the landmark, the URL
for the representative icon and a URL for the real landmark.
This is simple but insufficient. We also need to be able to search for
landmarks, to categorize them, and importantly navigate to them.
Other plugin elements now come to our aid.
In order to search for Landmarks we need to set up filters that can be
used to define our search criteria.
For example, we can set up a filter to locate a particular landmark by
name using the \l LandmarkNameFilter
\snippet doc/src/snippets/declarative/declarative-landmark.qml Landmark name filter
We can also search by proximity. That is, are we within a defined range
of any landmarks? Here is an example that uses a filter tied into the
current device location
\snippet doc/src/snippets/declarative/declarative-landmark.qml Landmark proximity filter
\l PositionSource refreshes the coordinate once per second (1000 milliseconds)
and this new location is used to determine if the coordinate is within a
given radius of any landmark coordinate during the search. The result would
be a list of landmarks that are within the given radius, 1500 meters,
of our location.
If we want to combine filters the API gives us elements that can be combined
in a set-like way to create unions (logical OR) and intersections (logical AND)
of the results of different filters. In the examples above we had a
\l LandmarkNameFilter and we had a \l LandmarkProximityFilter. If we want
to combine them so that the result would show when the device is within
the desired radius then we use a \l LandmarkUnionFilter to combine the
two previous filters
\snippet doc/src/snippets/declarative/declarative-landmark.qml LandmarkModel union filter
Generating a list of results for a filter is done by means of a \l LandmarkModel
element. This encapsulates the list of results and gives us desirable
features such as control over the sortOrder and sortBy functionality. Here
is a sample use of the element to provide a list of up to 50 items found
to be within a specified distance defined in the \i proximityFilter
\snippet doc/src/snippets/declarative/declarative-map.qml LandmarkModel proximity filter
\note The \l {LandmarkAbstractModel::autoUpdate}{autoUpdate} property is
a boolean. It enables the model to be updated if any signals are
emitted that would change the model. For instance, a change in the
contents of a filter.
Landmarks can be organized into categories similar to tagging. New categories
cannot be defined at the QML level, they are either supplied by the backend database
or new ones are defined at the C++ layer. Landmarks are associated with
various categories by using the \l LandmarkCategoryModel element. This
element contains a Landmark element and a list of \l LandmarkCategory instances.
Searches can be made using a \l LandmarkCategoryFilter. The
\l LandmarkCategoryModel is first used to specify which \l Landmark we
are interested in, then the \l {LandmarkCategoryModel::categories}{categories}
property is populated with the categories associated with that landmark.
\section2 Landmark Elements
\annotatedlist qml-location-landmarks
*/
|
