Maps SDK for Qt¶

Current version: 2.0.0-20231026, View Release Notes

The Magic Lane Maps SDK for Qt is a joint effort between KDAB and Magic Lane to bring to the QML world the excellent Magic Lane Maps and Navigation SDK.

With a unique combination of features, Magic Lane Maps and Navigation SDKs make real what developers have long sought:

Global coverage. Up to date OpenStreetMap maps. 3D terrain topography.
Easy to use, lightweight, efficient - runs even on Raspberry Pi.
First class Turn-by-turn navigation optimized for car, pedestrian and bicycle, with optional voice guidance in many languages, each with both male and female voices.
Offline maps available for download. Features such as mapping, searching, routing and turn-by-turn navigation work offline, without an internet connection.

Using the Maps SDK for Qt, you can easily write your own customized navigation app, or navigation module within your app. The QML interface is simple, easy to learn, and you can get your own navigation app up and running with only a few lines of code!

Getting Started¶

This guide is an overview of the main features of the Maps SDK for Qt.

First, get an API key token, see the Getting Started guide.

Qt should be installed to continue.

Maps SDK for Qt should be installed to continue, see the Setup Maps SDK for Qt guide.

If no API Key token is set, you can still test your apps, but a watermark will be displayed, and all the online services including mapping, searching, routing, may slow down after a few minutes.

Setting the token safely

To keep your token safe, it is recommended that you set your token via a C++ property as shown here. Do not set your token as plain text in your .qml files.

The following QML and C++ snippets demonstrate how to set your token via a C++ property:

// QML code
// ...
Component.onCompleted:
{
    //! [Set token safely]
    ServicesManager.settings.token = __my_secret_token;
    //! [Set token safely]

    ServicesManager.settings.allowInternetConnection = true;
    ServicesManager.contentUpdater(ContentItem.Type.RoadMap).autoApplyWhenReady = true;
    ServicesManager.contentUpdater(ContentItem.Type.RoadMap).update();
}
// ...

The __my_secret_token property in the above QML code is set in C++ like this. In the following code, which may be in an example, in main.cpp, replace YOUR_TOKEN with your actual API key token.

// C++ code
QQmlApplicationEngine engine;
//...
//! [Set API Key token safely]
// go to https://developer.magiclane.com to get your token
engine.rootContext()->setContextProperty("__my_secret_token", "YOUR_TOKEN");
//! [Set API Key token safely]

engine.load(url);

You may want to have a look at Setting your API Key to see how to open and configure a project and set your API Key.

To load the GeneralMagic QML module, add the following statement to your .qml files

import GeneralMagic 2.0

See the GeneralMagic QML Types in the API reference.

Mapping¶

A MapView provides a map rendering control, which displays an interactive map. The user can manually pan and zoom the map, or the map can be animated automatically, for example, by the simulator. MapView preferences can be used to configure the map, such as setting the position using longitude, latitude coordinates, or the azimuth rotation of the map with respect to north, or the inclination/view angle. The map view and behavior can be further fine-tuned with MapViewPreferences. MapView::startFollowingPosition is much more efficient to automatically control the camera to follow the current position of the device, especially if it is moving, than controlling the camera from outside.

This example is a complete working “Hello World” qml app which uses MapView to render an interactive map which the user can control using pan and zoom.

Simply create a new Qt Quick Application - Empty project in Qt and replace the contents of main.qml with the code below.

import QtQuick 2.12
import QtQuick.Window 2.12
import GeneralMagic 2.0
Window
{
    visible: true
    width: 640; height: 480
    title: qsTr("Simple Map")
    MapView
    {
        id: mapView
        anchors.fill: parent
        viewAngle: 0 //between 0 (view downward) and 90 (view toward horizon)
        gesturesEnabled: true
    }
    Component.onCompleted:
    {
        ServicesManager.settings.token = __my_secret_token;

        ServicesManager.settings.mapLanguage = CommonSettings.NativeLanguage;
        ServicesManager.settings.allowInternetConnection
          = true; // enable connection to map data server
        ServicesManager.contentUpdater(ContentItem.Type.RoadMap).autoApplyWhenReady = true;
        ServicesManager.contentUpdater(ContentItem.Type.RoadMap).update();
        ServicesManager.logLevel = ServicesManager.Error;
    }
}

There are many properties available such as MapView::gesturesEnabled to enable or disable gestures, or MapView::animationTime to set the duration of animations.

MapView::preferences options, described in MapViewPreferences, include boolean toggles such as MapViewPreferences::cursorVisibility to enable the cursor, MapViewPreferences::show3DBuildings to enable rendering 3D buildings, and many more.

This complete example renders an interactive map centered on a desired location, specified as longitude, latitude coordinates. The mapRotationAngle is 0 for north toward the top of the view, 90 for east toward the top, 180 for south toward the top, and 270 or -90 for west toward the top. The mapInclinationAngle is 0 (view downward toward map) to 90 (view toward horizon).

import QtQuick 2.12
import QtQuick.Window 2.12
import GeneralMagic 2.0
Window
{
    visible: true
    width: 640; height: 480
    title: qsTr("Map Centered on a Location")
    MapView
    {
        id: mapView
        anchors.fill: parent
        gesturesEnabled: true
        Coordinates
        {
            id: initialCenter
            latitude: 44.41
            longitude: 8.92
        }
    }
    Component.onCompleted:
    {
        var mapRotationAngle = 90; //looking east
        var mapInclinationAngle = 60; //looking 30 degrees down from horizon
        mapView.centerOnCoordinates(initialCenter, mapView.maxZoomLevel-63,
          mapRotationAngle, mapInclinationAngle);

        ServicesManager.settings.token = __my_secret_token;

        ServicesManager.settings.mapLanguage = CommonSettings.NativeLanguage;
        ServicesManager.settings.allowInternetConnection
          = true; // enable connection to map data server
        ServicesManager.contentUpdater(ContentItem.Type.RoadMap).autoApplyWhenReady = true;
        ServicesManager.contentUpdater(ContentItem.Type.RoadMap).update();
        ServicesManager.logLevel = ServicesManager.Error;
    }
}

Searching¶

Searching can be performed by using SearchService, and AddressSearchService.

All of the searching methods have a filter property which, used in combination with the search method, finds results matching the specific string query.

SearchService and AddressSearchService both inherit from LandmarkModel, which allows for them to be used as models for any QML view. The landmark attached property will be available in your delegate.

SearchService is the most basic searching method and allows using the SearchService::filter to SearchService::search for a specific string query. SearchService can also return results along a Route specified as input.

AddressSearchService uses a AddressSearchService::DetailLevel as a AddressSearchService::detailToSearch with, and optionally, a AddressSearchService::parentLandmark to search for a string query. It also has AddressSearchPreferences for options such as AddressSearchPreferences::maximumMatches.

Routing¶

This example is a snippet which can be added to the first Mapping example above, “Simple Map”, inside the Window block, at the same level as the MapView block, to make a complete working “Hello World” qml app which uses RoutingService and MapView to render a route on an interactive map which the user can control using pan and zoom. The MapView block in this snippet contains a line that should be added to the existing MapView block in the “Simple Map” example above. There should not be multiple MapView blocks.

Routing uses LandmarkList as waypoints which are set in RoutingService::waypoints and then the RoutingService creates available Route variants which are accessible in RoutingService::routes.

 RoutingService
 {
     preferences
     {
         type: RoutePreferences.Type.Fastest
         transportMode: RoutePreferences.TransportMode.Car
     }
     waypoints: LandmarkList
     {
         Landmark
         {
             name: "start"
             coordinates: Coordinates
             {
                 latitude: 48.849289 //Paris
                 longitude: 2.346027
             }
         }
         Landmark
         {
             name: "stop"
             coordinates: Coordinates
             {
                 latitude: 48.874630 //Paris
                 longitude: 2.331512
             }
         }
     }
     onCompleted:
     {
         mapView.preferences.routeCollection.set(routes);
         mapView.centerOnRoutes(routes);
     }
     Component.onCompleted: update()
 }
 MapView
 {
     // ...
     onRouteSelected: preferences.routeCollection.mainRoute
     = route //add this line to the MapView block in the Mapping example
 }

Commenting out the Paris start and stop coordinates in the example above, and replacing them with

latitude: 37.4184567 //SF bay area route start
longitude: -122.0882378

latitude: 37.8586084 //SF route stop
longitude: -122.5814328

we get this route.

The NavigationService begins navigation with the set parameters along a Route from RoutingService, when NavigationService::active is set to true or NavigationService::start is called.

During navigation, any events related to the journey, such as the destination being reached, are emitted through NavigationListener.

The following snippet shows how to get the current location of the device.

import QtPositioning 5.12 as QPos

QPos.PositionSource
{
    id: positionSource
    active: true
    Component.onCompleted:
    {
         ServicesManager.dataSource.setPositionSource(positionSource);
         ServicesManager.dataSource.loadLastKnownPosition();
    }
    Component.onDestruction: ServicesManager.dataSource.saveLastKnownPosition();
}

The current location can be set in the starting waypoint Landmark block for the route like this, instead of the existing coordinates: Coordinates block, which can be commented out, as the coordinates property should be defined only once in each Landmark.

Landmark
{
    name: "start"
    coordinates: ServicesManager.currentPosition
}

The NavigationService in this snippet can be added to the first Mapping example above, “Simple Map”, inside the Window block, at the same level as the MapView block and the RoutingService block, to make a complete working “Hello World” qml app with routing and navigation.

function distance(meters)
{
  return meters >= 1000 ? (meters / 1000.).toFixed(3)
  + " Km" :  meters.toFixed(0) + " m";
}

NavigationService
{
  id: navigation
  route: mapView.preferences.routeCollection.mainRoute
  simulation: true // change it to false (default) to perform real turn by turn navigation
  onActiveChanged:
  {
    if (active)
    {
      mapView.startFollowingPosition();
      mapView.preferences.routeCollection.clear();
      mapView.preferences.routeCollection.add(
        mapView.preferences.routeCollection.mainRoute);
    }
  }
  navigationListener: NavigationListener
  {
    onWaypointReached: console.log("WaypointReached :" + waypoint.name);
    onDestinationReached: mapView.preferences.routeCollection.clear();
    onNavigationError:
    {
      console.log("NavigationError :" + error);
      mapView.preferences.routeCollection.clear();
    }
    onRouteChanged:
    {
      console.log("RouteUpdated :" + route.summary);
      mapView.preferences.routeCollection.clear();
      mapView.preferences.routeCollection.add(route);
    }
    onNavigationInstructionUpdated:
    {
      nextTurnIcon.iconSource = navigationInstruction.nextTurnDynamicIcon;
      nextTurnInfo.text = navigationInstruction.nextStreetName + " ("
      + distance(navigationInstruction.distanceToNextTurn) + ")";
    }
  }
}

This is some optional debug you can add in the onNavigationInstructionUpdated block shown above to print some interesting statistics in the debug window:

console.log("currentStreetName: " + navigationInstruction.currentStreetName);
console.log("nextStreetName: " + navigationInstruction.nextStreetName);
console.log("distanceToNextTurn: " + navigationInstruction.distanceToNextTurn);
console.log("timeToNextTurn: " + navigationInstruction.timeToNextTurn);
console.log("remainingTravelTime: " + navigationInstruction.remainingTravelTime);
console.log("remainingTravelDistance: " + navigationInstruction.remainingTravelDistance);
console.log("remainingTravelTimeToNextWaypoint: " + navigationInstruction.remainingTravelTimeToNextWaypoint);
console.log("remainingTravelDistanceToNextWaypoint: " + navigationInstruction.remainingTravelDistanceToNextWaypoint);
console.log("traveledDistance: " + navigationInstruction.traveledDistance);
console.log("traveledTime: " + navigationInstruction.traveledTime);

Simulation¶

Continuing from the previous example, we first need to add another import statement at the top.

import QtQuick.Controls 2.12 //for Button

Inside the Window block, add the code for the button, located in the upper left corner of the screen, to start the simulation. While the simulation is running, clicking the button again will stop it, otherwise the simulation stops upon reaching the destination.

Button
{
    enabled: mapView.preferences.routeCollection.mainRoute.valid
    text: navigation.active ? "Stop simulation" : "Start simulation"
    onClicked: navigation.active = !navigation.active
}

These guides enable you to get quickly started using the Maps SDK for Qt to render your first interactive map, then plot a route, simulate navigation along the route, and search for points of interest.

QML Examples¶

Maps SDK for Qt Examples can be downloaded or cloned with Git