path: root/doc/src/qml-maps.qdoc

/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \group qml-QtLocation5-maps
    \title QML Maps Plugin
    QML Support for the Qt Location API.
*/


/*!
\page qml-location5-maps.html
\title QML Maps
\previouspage {qtlocation-module.html}{QtLocation Module}

\brief Maps is the section QtQuick Location that deals with maps,
their contents and navigation through the maps. ???

\section1 Overview

The \l Map element 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 \l 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 \l {MapItem}s. The item's position is defined
by a \l {Coordinate::}{coordinate} which includes latitude, longitude and elevation. The item
is then displayed automatically after it is added to the Map. Interaction with
the added items, and the \l Map itself, is handled by \l MapMouseArea when items are
added as children of the \l {MapItem}s or \l Map.

\section2 Position

The basic element of position information is the \l 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 \l Coordinate element may also be held within a \l {QtLocation5::Location}{Location}
element, this will also have information on a bounding box size to determine
sufficient proximity to the location and a location address.

\section2 Geocoding

\l {http://en.wikipedia.org/wiki/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 \l GeoCodeModel element.

The following code examples are a small part of the \c map component in the
\l {Declarative Map Viewer Example}{MapViewer QML example}. The snippets
demonstrate the declaration of the \l GeocodeModel component.

In the snippet we see that the \c geocodeModel property contains the plugin
and two signal handlers. One for changes in status (\c onStatusChanged ) and
the other to update the centering of the Map element (\c onLocationsChanged ).

\qml
    property GeocodeModel geocodeModel: 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
            }

        }
    }
\endqml


\qml
    MapItemView {
        model: geocodeModel
        delegate: pointDelegate
    }
\endqml


These geocoding features are called from a higher level piece of code. In this
snippet we see an \c onGoButtonClicked signal handler that extracts the address
from the user interface and then creates a query for the \l GeocodeModel to
process and determine the geographical coordinates.


\qml
        Address {
            id: geocodeAddress
        }

        onGoButtonClicked: {
            // manage the UI state transitions
            page.state = ""
            messageDialog.state = ""

            // fill out the Address element
            geocodeAddress.street = dialogModel.get(0).inputText
            geocodeAddress.district = dialogModel.get(1).inputText
            geocodeAddress.city = dialogModel.get(2).inputText
            geocodeAddress.county = dialogModel.get(3).inputText
            geocodeAddress.state = dialogModel.get(4).inputText
            geocodeAddress.countryCode = dialogModel.get(5).inputText
            geocodeAddress.country = dialogModel.get(6).inputText
            geocodeAddress.postalCode = dialogModel.get(7).inputText

            // send the geocode request
            map.geocodeModel.clear()
            map.geocodeModel.query = geocodeAddress
            map.geocodeModel.update()
        }
\endqml


\section2 Navigation

A very important function of the \l Map element 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 \e maneuver. The \e segments contain information about
the time and distance to the end of the segment. The \e maneuvers contain information
about what to do next, how to get onto the next segment, if there is one. So
a \e maneuver contains navigational information, e.g. "turn right now".

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

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

\table 60%
    \row
        \li \l {RouteQuery::}{numberAlternativeRoutes}
        \li The number of alternative routes
    \row
        \li \l {RouteQuery::}{travelModes}
        \li Travel modes
    \row
        \li \l {RouteQuery::}{routeOptimizations}
        \li Required route optimizations
    \row
        \li \l {RouteQuery::}{segmentDetails}
        \li Level of detail in segments
    \row
        \li \l {RouteQuery::}{maneuverDetails}
        \li Level of detail in maneuvers between segments
    \row
        \li \l {RouteQuery::}{waypoints}
        \li A list of waypoints
    \row
        \li \l {RouteQuery::}{excludedAreas}
        \li A list of excluded areas that the route must not cross
    \row
        \li \l {RouteQuery::}{featureTypes}
        \li Relevant map features, e.g. highway, ferry
\endtable


In the following example a default RouteQuery is declared, later to be defined
by some user input, and used in \c routeModel as the query. The \c routeInfoModel
is a \l ListModel that can be updated using an \c update() function that we will
look at later.

\qml
    property RouteQuery routeQuery: RouteQuery {}
    property RouteModel routeModel: RouteModel {
        plugin : map.plugin
        query: routeQuery
        onStatusChanged:{
            if (status == RouteModel.Ready){
                if (count == 1) { routeInfoModel.update()}
            }
            else if (status == RouteModel.Error){
                clearAll()
                map.routeError()
            }
        }
        function clearAll(){
            clear()
            routeInfoModel.update()
        }
    }
\endqml

The user enters, via a dialog, 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.

\qml
    function calculateRoute(){
        map.routeQuery.clearWaypoints();
        map.center = startCoordinate
        map.routeQuery.addWaypoint(startCoordinate)
        map.routeQuery.addWaypoint(endCoordinate)
        map.routeQuery.travelModes = routeDialog.travelMode
        map.routeQuery.routeOptimizations = routeDialog.routeOptimization

        for (var i=0; i<9; i++) {
            map.routeQuery.setFeatureWeight(i, 0)
        }

        for (var i=0; i<routeDialog.features.length; i++) {
            map.routeQuery.setFeatureWeight(routeDialog.features[i], RouteQuery.AvoidFeatureWeight)
        }

        map.routeModel.update();
    }
\endqml



The \c routeInfoModel \l ListModel is used to grab the results of the query and construct
a suitable list for display. The ListModel \c routeInfoModel contains an
\c update() function 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.

\qml
    ListModel{
        id: routeInfoModel
        property string travelTime
        property string distance

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

    MapItemView {
        model: routeModel
        delegate: routeDelegate
    }
\endqml

For more information on the example see the \l {Declarative Map Viewer Example}.


\section2  Zoom, Pinch and Flickable

The \l 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 \l Map element.

\qml
    zoomLevel: (maximumZoomLevel - minimumZoomLevel)/2


    // Enable pinch gestures to zoom in and out
    pinch.activeGestures: MapPinch.ZoomGesture
    pinch.enabled: true

    // And flicking gestures for quick panning
    flick.enabled: true
    flick.deceleration: 3000
\endqml

Zoom can also be controlled by other elements like sliders, as shown in the
example, by implementing the \c onValueChanged handler to update the Map
\l {QtLocation5::Map::}{zoomLevel}.





\section1 Elements

\section3 Positioning
\annotatedlist qml-QtLocation5-positioning

\section3 Maps
\annotatedlist qml-QtLocation5-maps

\section3 Geocoding
\annotatedlist qml-QtLocation5-geocoding

\section3 Routing
\annotatedlist qml-QtLocation5-routing



\section1 Example

The above snippets are taken from the \l {Declarative Map Viewer Example}.

*/