QML Maps

Maps deals with maps, their contents and navigation

Maps deals with maps, their contents and navigation.


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 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 :ref:` <qml-qtlocation-geocodemodel.html-status-prop>` and the other to update the centering of the Map object onLocationsChanged :ref:` <qml-qtlocation-geocodemodel.html-locationsChanged-signal>` .

GeocodeModel {
    id: geocodeModel
    plugin: map.plugin
    onStatusChanged: {
        if ((status == GeocodeModel.Ready) || (status == GeocodeModel.Error))
        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

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





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