QML Maps

Overview

The Map type allows the display of a map and placing objects within the map. Various points of interest can be defined and added to the map for display. Also the Map has features to control how the map is displayed. With the Map item you can center the map, zoom, pinch and make the item flickable.

The places to be added to the map are MapItems. The item's position is defined by a coordinate which includes latitude, longitude and altitude. The item is then displayed automatically after it is added to the Map.

Position on map

All position APIs are part of the QtPositioning module. The basic piece of position information is the coordinate. A coordinate encapsulates data for the latitude, longitude and altitude of the location. Altitude is in meters. It also has a method to determine distance to another coordinate. The coordinate type may also be held within a Location element, this will also have information on a bounding box size to determine sufficient proximity to the location and a location address.

Here is an example of a client that uses a position source to center a map on the current position:

Rectangle {

    import QtPositioning 5.2
    import QtLocation 5.3
    ...

    Map {
        id: map
        // initialize map
        ...
    }

    PositionSource {
        onPositionChanged: {
            // center the map on the current position
            map.center = position.coordinate
        }
    }
}

Geocoding

Geocoding is the derivation of geographical coordinates (latitude and longitude) from other geographical references to the locations. For example, this can be a street address. Reverse geocoding is also possible with a street address being used to determine a geographical coordinate. Geocoding is performed by using the GeocodeModel type.

The following code examples are a small part of the map component in the Map Viewer (QML) example. The snippets demonstrate the declaration of the GeocodeModel component.

In the snippet we see that the [QML]{GeocodeModel} contains the plugin and two signal handlers. One for changes in status onStatusChanged and the other to update the centering of the Map object onLocationsChanged.

GeocodeModel {
    id: geocodeModel
    plugin: map.plugin
    onStatusChanged: {
        if ((status == GeocodeModel.Ready) || (status == GeocodeModel.Error))
            map.geocodeFinished()
    }
    onLocationsChanged:
    {
        if (count == 1) {
            map.center.latitude = get(0).coordinate.latitude
            map.center.longitude = get(0).coordinate.longitude
        }
    }
}

MapItemView {
    model: geocodeModel
    delegate: pointDelegate
}

The geocoding features are called from a higher level piece of code. In this snippet we see an Address object filled with the desired parameters.

Address {
    id :fromAddress
    street: "Sandakerveien 116"
    city: "Oslo"
    country: "Norway"
    state : ""
    postalCode: "0484"
}

The Address is later used in a query for the GeocodeModel to process and determine the geographical coordinates.

// send the geocode request
geocodeModel.query = fromAddress
geocodeModel.update()

Navigation

A very important function of the Map type is navigation from one place to a destination with possible waypoints along the route. The route will be divided up into a series of segments. At the end of each segment is a vertex called a maneuver. The segments contain information about the time and distance to the end of the segment. The maneuvers contain information about what to do next, how to get onto the next segment, if there is one. So a maneuver contains navigational information, for example "turn right now".

To find a suitable route we will need to use a RouteQuery to define the selection criteria and adding any required waypoints. The RouteModel should return a list of RouteSegments that defines the route to the destination complete with navigation advice at the joins between segments, called RouteManeuvers

There are many options that you can add to the query to narrow the criteria. The RouteQuery properties can include

numberAlternativeRoutes	The number of alternative routes
travelModes	Travel modes
routeOptimizations	Required route optimizations
segmentDetail	Level of detail in segments
maneuverDetail	Level of detail in maneuvers between segments
waypoints	A list of waypoints
excludedAreas	A list of excluded areas that the route must not cross
featureTypes	Relevant map features, for example highway, ferry

In the following example a default RouteQuery is declared within RouteModel.

RouteModel {
    id: routeModel
    plugin : map.plugin
    query:  RouteQuery {
        id: routeQuery
    }
    onStatusChanged: {
        if (status == RouteModel.Ready) {
            switch (count) {
            case 0:
                // technically not an error
                map.routeError()
                break
            case 1:
                map.showRouteList()
                break
            }
        } else if (status == RouteModel.Error) {
            map.routeError()
        }
    }
}

The user enters some information such as the starting point of the route, some waypoints and the destination. All of these locations are waypoints so the locations from start to finish will be entered as a sequence of waypoints. Then other query properties can be set that may be specific to this trip.

// clear away any old data in the query
routeQuery.clearWaypoints();

// add the start and end coords as waypoints on the route
routeQuery.addWaypoint(startCoordinate)
routeQuery.addWaypoint(endCoordinate)
routeQuery.travelModes = RouteQuery.CarTravel
routeQuery.routeOptimizations = RouteQuery.FastestRoute

routeModel.update();

The routeInfoModel ListModel is used to grab the results of the query and construct a suitable list for display.

ListView {
    interactive: true
    model: ListModel { id: routeInfoModel }
    header: RouteListHeader {}
    delegate:  RouteListDelegate{
        routeIndex.text: index + 1
        routeInstruction.text: instruction
        routeDistance.text: distance
    }
}

The ListModel routeInfoModel can be filled with values using a code, that loops through the segments extracting the segment length, instruction text and distance to the next instruction. The extracted data is formatted for display as it is retrieved.

routeInfoModel.clear()
if (routeModel.count > 0) {
    for (var i = 0; i < routeModel.get(0).segments.length; i++) {
        routeInfoModel.append({
            "instruction": routeModel.get(0).segments[i].maneuver.instructionText,
             "distance": Helper.formatDistance(routeModel.get(0).segments[i].maneuver.distanceToNextInstruction)
        });
    }
}

For more information on the example see the Map Viewer (QML) example.

Zoom, Pinch and Flickable

The Map item also supports user interface interactions with the map using tactile and mouse gestures. That is features such as swiping to pan, pinching to zoom.

Enabling and configuring pinch and flickable is easy within the Map type.

Map {
    id: map
    // Enable pan, flick, and pinch gestures to zoom in and out
    gesture.acceptedGestures: MapGestureArea.PanGesture | MapGestureArea.FlickGesture | MapGestureArea.PinchGesture | MapGestureArea.RotationGesture | MapGestureArea.TiltGesture
    gesture.flickDeceleration: 3000
    gesture.enabled: true
}

Zoom can also be controlled by other objects like sliders, with binding to the Map zoomLevel.

QML Types

Maps

CameraCapabilities	Type holds information about the camera capabilities for a specific map type
DynamicParameter	(previously MapParameter ) type represents a parameter for a Map element, or other elements used in a Map (such as map items, etc.). This type provides a mean to specify plugin-dependent optional dynamic parameters that allow a plugin to extend the runtime API of the module
Map	Type displays a map
MapCircle	Type displays a geographic circle on a Map
MapCircleObject	Displays a circle on a Map
MapCopyrightNotice	Item displays the current valid copyright notice for a Map element
MapGestureArea	Type provides Map gesture interaction
MapIconObject	Displays an icon on a Map
MapItemGroup	Type is a container for map items
MapItemView	Used to populate Map from a model
MapObjectView	Used to populate Map with map objects from a model
MapPinchEvent	Type provides basic information about pinch event
MapPolygon	Type displays a polygon on a Map
MapPolygonObject	Displays a polygon on a Map
MapPolyline	Type displays a polyline on a map
MapPolylineObject	Displays a polyline on a Map
MapQuickItem	Type displays an arbitrary Qt Quick object on a Map
MapRectangle	Type displays a rectangle on a Map
MapRoute	Type displays a Route on a Map
MapRouteObject	Displays a geographical route on a Map
MapType	Type holds information about a map type
Navigator	Type offers functionalities to perform turn-by-turn navigation

Geocoding

GeocodeModel

Type provides support for searching operations related to geographic information

Routing

Route	Type represents one geographical route
RouteLeg	Type represents a leg of a Route, that is the portion of a route between one waypoint and the next
RouteManeuver	Type represents the information relevant to the point at which two RouteSegments meet
RouteModel	Type provides access to routes
RouteQuery	Type is used to provide query parameters to a RouteModel
RouteSegment	Type represents a segment of a Route
Waypoint	Type provides a mean to specify a waypoint in a RouteQuery in a more detailed way than by using a simple coordinate

Example

The above snippets are taken from the Map Viewer (QML) example.