Location QML Plugin

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.

Positioning

Coordinate

The Coordinate is a basic unit of geographical information. The Coordinate element includes properties to hold the coordinate values for latitude, longitude and altitude.

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 speed it is doing and what is the timestamp of the last position data. Position therefore includes values for latitude, longitude, altitude, speed and a timestamp. Position also takes responsibility for validation of sensible values for these properties: just as there is a latitude there is a property latitudeValid. Similarly for the other properties with the exception of the timestamp.

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 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.

NMEA is a common text-based protocol for specifying navigational data. For convenience, the 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.

Positioning Elements

QML Address Element	The Address element presents an address.
QML BoundingBox Element	The QGeoBoundingBox class defines a rectangular geographic area.
QML Coordinate Element	The Coordinate element holds various positional data, such as latitude, longitude and altitude.
QML Place Element	The A Place element presents basic information about a place.
QML Position Element	The Position element holds various positional data, such as coordinate (longitude, latitude, altitude) and speed.
QML PositionSource Element	The PositionSource element allows you to get information about your current position.

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.

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 no longer available as 1.1 import. QML applications 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.

QML Map Element	The Map element displays a map.
QML MapCircle Element	The MapCircle element displays a circle on a map.
QML MapGroup Element	The MapGroup element aggregates a set of map objects.
QML MapImage Element	The MapImage element displays an image on a map.
QML MapMouseArea Element	The MapMouseArea item enables simple mouse handling.
QML MapMouseEvent Element	The MapMouseEvent object provides information about a mouse event.
QML MapObjectView Element	The MapObjectView is used to populate Map from a model.
QML MapPolygon Element	The MapPolygon element displays a polygon on a map.
QML MapPolyline Element	The MapPolyline element displays a polyline on a map.
QML MapRectangle Element	The MapRectangle element displays a rectangle on a map.
QML MapText Element	The MapText element displays text on a map.
QML Plugin Element	The Plugin element describes a Location based services plugin.
QML PluginParameter Element	The PluginParameter element describes the parameter to a Plugin.

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 Landmark. Using 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 LandmarkNameFilter

 LandmarkNameFilter {
     id: landmarkFilterUndercity
     name: "Undercity"
 }

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

 PositionSource {
     id: myPosition
     updateInterval: 1000
 }
 LandmarkProximityFilter {
     id: landmarkFilterMyCurrentLocation
     center: myPosition.position.coordinate
     radius: 1500
 }

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 LandmarkNameFilter and we had a 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 LandmarkUnionFilter to combine the two previous filters

 LandmarkUnionFilter {
     id: landmarkUnionFilterNameAndProximity
     LandmarkNameFilter {
         name: "Nimbin"
     }
     LandmarkProximityFilter {
         center: myPosition.position.coordinate
         radius: 1500
     }
 }

Generating a list of results for a filter is done by means of a 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 proximityFilter

 LandmarkModel {
     id: landmarkModelNear
     autoUpdate: true
     filter: proximityFilter
     limit: 50
     onModelChanged: {
         console.log("Near landmark model changed, landmark count: " + count)
     }
 }

Note: The 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 LandmarkCategoryModel element. This element contains a Landmark element and a list of LandmarkCategory instances.

Searches can be made using a LandmarkCategoryFilter. The LandmarkCategoryModel is first used to specify which Landmark we are interested in, then the categories property is populated with the categories associated with that landmark.

Landmark Elements

QML Landmark Element	The Landmark element presents one landmark.
QML LandmarkAbstractModel Element	The LandmarkAbstractModel element is an uncreatable / uninstantiable base element for LandmarkModel and LandmarkCategoryModel. It defines many common properties for the two models.
QML LandmarkBoxFilter Element	The LandmarkBoxFilter element specifies a box (rectangle) filter for landmark model.
QML LandmarkCategory Element	The LandmarkCategory element presents one landmark category.
QML LandmarkCategoryFilter Element	The LandmarkCategoryFilter element specifies a category filter for landmark model.
QML LandmarkCategoryModel Element	The LandmarkCategoryModel element provides access to categories.
QML LandmarkIntersectionFilter Element	The LandmarkIntersectionFilter element specifies an insection of landmark filters.
QML LandmarkModel Element	The LandmarkModel element provides access to landmarks.
QML LandmarkNameFilter Element	The LandmarkNameFilter element specifies a name filter for landmark model.
QML LandmarkProximityFilter Element	The LandmarkProximityFilter element specifies a proximity filter for landmark model.
QML LandmarkUnionFilter Element	The LandmarkUnionFilter element specifies a union of landmark filters.