- Qt 6.9
- Qt Location
- Qt Location Examples
- Minimal Map (QML)
- Qt 6.9.2 Reference Documentation

# Minimal Map (QML)

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 <QGuiApplication>
     #include <QQmlApplicationEngine>

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.

     int main(int argc, char *argv[])
     {
         QGuiApplication app(argc, argv);

         QQmlApplicationEngine engine;
         engine.load(QUrl(QStringLiteral("qrc:/main.qml")));

         return app.exec();
     }

#### 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 {
             id: mapPlugin
             name: "osm"
         }

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

             PinchHandler {
                 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 {
                 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 {
                 id: drag
                 target: null
                 onTranslationChanged: (delta) => map.pan(-delta.x, -delta.y)
             }
             Shortcut {
                 enabled: map.zoomLevel < map.maximumZoomLevel
                 sequence: StandardKey.ZoomIn
                 onActivated: map.zoomLevel = Math.round(map.zoomLevel + 1)
             }
             Shortcut {
                 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