/**************************************************************************** ** ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. ** ** $QT_BEGIN_LICENSE:FDL$ ** Commercial License Usage ** Licensees holding valid commercial Qt licenses may use this file in ** accordance with the commercial license agreement provided with the ** Software or, alternatively, in accordance with the terms contained in ** a written agreement between you and Digia. For licensing terms and ** conditions see http://qt.digia.com/licensing. For further information ** use the contact form at http://qt.digia.com/contact-us. ** ** GNU Free Documentation License Usage ** 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. Please review the following information to ensure ** the GNU Free Documentation License version 1.3 requirements ** will be met: http://www.gnu.org/copyleft/fdl.html. ** $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 {index-qtlocation-module.html}{Qt Location Module} \brief Maps deals with maps, their contents and navigation. \section1 Overview The \l 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 \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 {Maps and Navigation (QML)#Putting Objects on a Map (Map Overlay Objects)}{MapItems}. The item's position is defined by a \l {QtLocation5::coordinate}{coordinate} which includes latitude, longitude and altitude. 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 {Maps and Navigation (QML)#Putting Objects on a Map (Map Overlay Objects)}{MapItems} or \l Map. \section2 Position The basic piece of position information is the \l {QtLocation5::coordinate}{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 \l {QtLocation5::coordinate}{coordinate}. The \l {QtLocation5::coordinate}{coordinate} type 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 type. The following code examples are a small part of the \c map component in the \l {Map Viewer (QML)}{Map Viewer (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 object (\c onLocationsChanged ). \snippet examples/declarative/mapviewer/content/map/MapComponent.qml geocodemodel0 \snippet examples/declarative/mapviewer/content/map/MapComponent.qml geocodemodel0 body \snippet examples/declarative/mapviewer/content/map/MapComponent.qml geocodemodel1 \codeline \snippet examples/declarative/mapviewer/content/map/MapComponent.qml geocodeview 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. \snippet examples/declarative/mapviewer/mapviewer.qml geocode1 \section2 Navigation A very important function of the \l Map type 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, for example "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::}{segmentDetail} \li Level of detail in segments \row \li \l {RouteQuery::}{maneuverDetail} \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, for example 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 {Models and Views in Qt Quick#ListModel}{ListModel} that can be updated using an \c update() function that we will look at later. \snippet examples/declarative/mapviewer/content/map/MapComponent.qml routemodel0 \codeline \snippet examples/declarative/mapviewer/content/map/MapComponent.qml routemodel1 \codeline \snippet examples/declarative/mapviewer/content/map/MapComponent.qml routemodel2 \snippet examples/declarative/mapviewer/content/map/MapComponent.qml routemodel3 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. \snippet examples/declarative/mapviewer/mapviewer.qml routerequest0 \codeline \snippet examples/declarative/mapviewer/mapviewer.qml routerequest0 feature weight \codeline \snippet examples/declarative/mapviewer/mapviewer.qml routerequest1 \snippet examples/declarative/mapviewer/mapviewer.qml routedialog1 The \c routeInfoModel \l {Models and Views in Qt Quick#ListModel}{ListModel} is used to grab the results of the query and construct a suitable list for display. The \l {Models and Views in Qt Quick#ListModel}{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. \snippet examples/declarative/mapviewer/content/map/MapComponent.qml routeinfomodel \codeline \snippet examples/declarative/mapviewer/content/map/MapComponent.qml routeview For more information on the example see the \l {Map Viewer (QML)}{Map Viewer (QML)} 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 type. \snippet examples/declarative/mapviewer/content/map/MapComponent.qml top \snippet examples/declarative/mapviewer/content/map/MapComponent.qml end Zoom can also be controlled by other objects like sliders, as shown in the example, by implementing the \c onValueChanged handler to update the Map \l {QtLocation5::Map::}{zoomLevel}. \section1 Types \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 {Map Viewer (QML)}{Map Viewer (QML)} example. */