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.
The Coordinate is a basic unit of geographical information. The Coordinate element includes properties to hold the coordinate values for latitude, longitude and altitude.
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.
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.
The Address element presents an address. | |
The QGeoBoundingBox class defines a rectangular geographic area. | |
The Coordinate element holds various positional data, such as latitude, longitude and altitude. | |
The A Place element presents basic information about a place. | |
The Position element holds various positional data, such as coordinate (longitude, latitude, altitude) and speed. | |
The PositionSource element allows you to get information about your current position. |
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.
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.
The Map element displays a map. | |
The MapCircle element displays a circle on a map. | |
The MapGroup element aggregates a set of map objects. | |
The MapImage element displays an image on a map. | |
The MapMouseArea item enables simple mouse handling. | |
The MapMouseEvent object provides information about a mouse event. | |
The MapObjectView is used to populate Map from a model. | |
The MapPolygon element displays a polygon on a map. | |
The MapPolyline element displays a polyline on a map. | |
The MapRectangle element displays a rectangle on a map. | |
The MapText element displays text on a map. | |
The Plugin element describes a Location based services plugin. | |
The PluginParameter element describes the parameter to a Plugin. |
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.
The Landmark element presents one landmark. | |
The LandmarkAbstractModel element is an uncreatable / uninstantiable base element for LandmarkModel and LandmarkCategoryModel. It defines many common properties for the two models. | |
The LandmarkBoxFilter element specifies a box (rectangle) filter for landmark model. | |
The LandmarkCategory element presents one landmark category. | |
The LandmarkCategoryFilter element specifies a category filter for landmark model. | |
The LandmarkCategoryModel element provides access to categories. | |
The LandmarkIntersectionFilter element specifies an insection of landmark filters. | |
The LandmarkModel element provides access to landmarks. | |
The LandmarkNameFilter element specifies a name filter for landmark model. | |
The LandmarkProximityFilter element specifies a proximity filter for landmark model. | |
The LandmarkUnionFilter element specifies a union of landmark filters. |