diff options
Diffstat (limited to 'src/location/doc/src/examples/declarative-mapviewer.qdoc')
| -rw-r--r-- | src/location/doc/src/examples/declarative-mapviewer.qdoc | 193 |
1 files changed, 193 insertions, 0 deletions
diff --git a/src/location/doc/src/examples/declarative-mapviewer.qdoc b/src/location/doc/src/examples/declarative-mapviewer.qdoc new file mode 100644 index 00000000..6fbec0e9 --- /dev/null +++ b/src/location/doc/src/examples/declarative-mapviewer.qdoc @@ -0,0 +1,193 @@ +/**************************************************************************** +** +** Copyright (C) 2013 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$ +** +****************************************************************************/ + +/*! + \example declarative/mapviewer + \title Map Viewer (QML) + \ingroup qtlocation-examples + + \brief The Map Viewer example shows how to display and interact with a map, + search for an address, and find driving directions. + + This is a large example covering many basic uses of maps, positioning, and + navigation services in Qt Location. This page is divided into sections + covering each of these areas of functionality with snippets from the code. + + The Map Viewer example can work with any of the available geo services plugins. However, some + plugins may require additional \l {QtLocation5::PluginParameter}{plugin parameters} in order to + function correctly. \l {QtLocation5::PluginParameter}{Plugin parameters} can be passed on the + command line using the \c {--plugin} argument, which takes the form: + + \code + --plugin.<parameter name> <parameter value> + \endcode + + Refer to the documentation for each of the geo services plugins for details on what plugin + parameters they support. The Nokia services plugin supplied with Qt requires an \e app_id and + \e token pair. See "\l {Qt Location Nokia Plugin}" for details. + + QML types shown in this example: + + \list + \li Displaying a map + \list + \li \l{QtLocation5::Map}{Map} + \li \l{QtLocation5::MapGestureArea}{MapGestureArea} + \li \l{coordinate} + \endlist + \li Finding an address + \list + \li \l{QtLocation5::GeocodeModel}{GeocodeModel} + \li \l{QtLocation5::MapItemView}{MapItemView} + \li \l{QtLocation5::MapCircle}{MapCircle} + \endlist + \li Directions and travel routes + \list + \li \l{QtLocation5::RouteModel}{RouteModel} + \li \l{QtLocation5::MapRoute}{MapRoute} + \endlist + \endlist + + \image ../images/example-mapviewer.png + + \section2 Displaying a Map + + Drawing a map on-screen is accomplished using the Map type, as shown + below. + + \snippet mapviewer/content/map/MapComponent.qml top + \snippet mapviewer/content/map/MapComponent.qml coord + \snippet mapviewer/content/map/MapComponent.qml end + + In this example, we give the map an initial center \l {coordinate} + with a set latitude and longitude. We also set the initial zoom level to 50% (halfway between + the maximum and minimum). + + The calls to "pinch" and "flick" are used to enable gestures on the map. + The flick gesture is also sometimes known as "kinetic panning", and provides + a more intuitive feel for panning the map both on touch screens and with + a mouse. + + As we do not specify a plugin for supplying map data, the platform default + will be used. This is typically the "nokia" plugin, which provides data from + Nokia services. Additional licensing conditions do apply to the use of this data, + please see the documentation for further details. + + \section2 Finding an Address (Geocoding) + + To locate a certain address or place on the map uses a process called + geocoding. In order to perform a geocode operation, we first need to adjust + our Map object to be able to receive the result. + + Receiving results of geocoding is done through a GeocodeModel, which is + typically instantiated as a property of the Map component: + + \snippet mapviewer/content/map/MapComponent.qml geocodemodel0 + \snippet mapviewer/content/map/MapComponent.qml geocodemodel1 + + Then, to display the contents of the GeocodeModel we use a MapItemView: + + \snippet mapviewer/content/map/MapComponent.qml geocodeview + + MapItemView uses an object called a "delegate" to act as a template for the + items it creates. This can contain any map object desired, but in this case + we show a MapCircle: + + \snippet mapviewer/content/map/MapComponent.qml pointdel0 + \snippet mapviewer/content/map/MapComponent.qml pointdel1 + + With these three objects, we have enough to receive Geocode responses and + display them on our Map. The final piece is to send the actual Geocode + request. + + In this example, we have a utility component called Dialog which we use + to display the user interface requesting geocoding parameters. You can + create a similar component yourself using Dialog.qml in this example + as a reference, or drive the process using any other UI you wish. + + To send a geocode request, first we create an Address object, and fill it + in with the desired parameters. Then we set "map.geocodeModel.query" to + the filled in Address, and call update() on the GeocodeModel. + + \snippet mapviewer/mapviewer.qml geocode0 + \snippet mapviewer/mapviewer.qml geocode1 + \snippet mapviewer/mapviewer.qml geocode2 + + \section2 Directions and Travel Routes + + Similar to the GeocodeModel, Qt Location also features the RouteModel type, + which allows information about routes (for example driving directions) between two + or more points, to be received and used with a Map. + + Here again, we instantiate the RouteModel as a property of our Map: + + \snippet mapviewer/content/map/MapComponent.qml routemodel0 + \snippet mapviewer/content/map/MapComponent.qml routemodel3 + + To display the contents of a model to the user, we need a view. Once again + we will use a MapItemView, to display the Routes as objects on the Map: + + \snippet mapviewer/content/map/MapComponent.qml routeview + + To act as a template for the objects we wish the view to create, we create + a delegate component: + + \snippet mapviewer/content/map/MapComponent.qml routedelegate0 + \snippet mapviewer/content/map/MapComponent.qml routedelegate1 + + With the model, view and delegate now complete, the only missing component + is some kind of control over the model to begin the Route request process. + In the simplest case, we can fill out a Route request using two already + available \l {coordinate}{coordinates}, which we store inside the RouteDialog + component: + + \snippet mapviewer/mapviewer.qml routedialog0 + \snippet mapviewer/mapviewer.qml routedialog1 + + In the next snippet, we show how to set up the request object and instruct + the model to update. We also instruct the map to center on the start + coordinate for our routing request. + + \snippet mapviewer/mapviewer.qml routerequest0 + \snippet mapviewer/mapviewer.qml routerequest1 + + This is all that is required to display a Route on the Map. However, it is + also useful to be able to retrieve the written directions and explanation + of the travel route. In the example, these are displayed in the pull-out + on the left-hand side of the map. To create this pull-out's contents, we + use a standard \l {Models and Views in Qt Quick#ListModel}{ListModel} and + \l {ListView} pair. The data in the \l {Models and Views in Qt Quick#ListModel}{ListModel} is + built from the routeModel's output: + + \snippet mapviewer/content/map/MapComponent.qml routeinfomodel + + Inside the RouteModel, we add an + \l{QtLocation5::RouteModel::status}{onStatusChanged} handler, which + calls the \c{update()} function we defined on the model: + + \snippet mapviewer/content/map/MapComponent.qml routemodel1 +*/ |