Minimal Map (QML) | Qt Location (original) (raw)

The minimum code to display a map using Qt Quick.

Minimal Map demonstrates how to use the Map item to render a map. It shows the minimum amount of code needed to display the map, and can be used as a basis for further experimentation.

Running the Example

To run the example from Qt Creator, open the Welcome mode and select the example from Examples. For more information, see Qt Creator: Tutorial: Build and run.

C++ Code

In main.cpp we use only the QGuiApplication and QQmlApplicationEngine classes.

#include #include

In the main function, we first instantiate a QGuiApplication object. Then we create a QQmlApplicationEngine and tell it to load main.qml from the Qt Resource System.

Finally, QGuiApplication::exec() launches the main event loop.

QML Code

In main.qml, we import the QtLocation QML module and its depending QtPositioning QML module. Next, we create the top level window, set a sensible default size, and make it visible. The window will be filled by a Map item showing the map.

import QtQuick import QtLocation import QtPositioning

Window { width: Qt.platform.os == "android" ? Screen.width : 512 height: Qt.platform.os == "android" ? Screen.height : 512 visible: true title: map.center + " zoom " + map.zoomLevel.toFixed(3) + " min " + map.minimumZoomLevel + " max " + map.maximumZoomLevel

[Plugin](qml-qtlocation-plugin.html) {
    id: mapPlugin
    name: "osm"
}

[Map](qml-qtlocation-map.html) {
    id: map
    anchors.fill: parent
    plugin: mapPlugin
    center: QtPositioning.coordinate(59.91, 10.75) // Oslo
    zoomLevel: 14
    property geoCoordinate startCentroid

    [PinchHandler](qml-qtquick-pinchhandler.html) {
        id: pinch
        target: null
        onActiveChanged: if (active) {
            map.startCentroid = map.toCoordinate(pinch.centroid.position, false)
        }
        onScaleChanged: (delta) => {
            map.zoomLevel += Math.log2(delta)
            map.alignCoordinateToPoint(map.startCentroid, pinch.centroid.position)
        }
        onRotationChanged: (delta) => {
            map.bearing -= delta
            map.alignCoordinateToPoint(map.startCentroid, pinch.centroid.position)
        }
        grabPermissions: PointerHandler.TakeOverForbidden
    }
    [WheelHandler](qml-qtquick-wheelhandler.html) {
        id: wheel
        // workaround for QTBUG-87646 / QTBUG-112394 / QTBUG-112432:
        // Magic Mouse pretends to be a trackpad but doesn't work with PinchHandler
        // and we don't yet distinguish mice and trackpads on Wayland either
        acceptedDevices: Qt.platform.pluginName === "cocoa" || Qt.platform.pluginName === "wayland"
                         ? PointerDevice.Mouse | PointerDevice.TouchPad
                         : PointerDevice.Mouse
        rotationScale: 1/120
        property: "zoomLevel"
    }
    [DragHandler](qml-qtquick-draghandler.html) {
        id: drag
        target: null
        onTranslationChanged: (delta) => map.pan(-delta.x, -delta.y)
    }
    [Shortcut](qml-qtquick-shortcut.html) {
        enabled: map.zoomLevel < map.maximumZoomLevel
        sequence: StandardKey.ZoomIn
        onActivated: map.zoomLevel = Math.round(map.zoomLevel + 1)
    }
    [Shortcut](qml-qtquick-shortcut.html) {
        enabled: map.zoomLevel > map.minimumZoomLevel
        sequence: StandardKey.ZoomOut
        onActivated: map.zoomLevel = Math.round(map.zoomLevel - 1)
    }
}

}

The Plugin item is necessary to define the map provider we are going to use. The example can work with any of the available geo services plugins. However, some plugins may require additional plugin parameters in order to function correctly and we can use PluginParameter to specify them. In this example, we use the osm plugin, which is a Qt Location Open Street Map Plugin and does not require any parameters.

In the Map item, we refer to the plugin we use and we set the center and the zoomLevel of the map.

Requirements

The example requires a working internet connection to download OpenStreetMap map tiles. An optional system proxy should be picked up automatically.

Example project @ code.qt.io

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.