The RouteModel type provides access to routes. More...

Import Statement: import QtLocation 5.3
Since: Qt Location 5.0



Detailed Description

The RouteModel type is used as part of a model/view grouping to retrieve geographic routes from a backend provider. Routes include data about driving directions between two points, walking directions with multiple waypoints, and various other similar concepts. It functions much like other Model types in QML (see for example ListModel and XmlListModel), and interacts with views such as MapItemView, and ListView.

Like RouteModel can do any useful work.

Once the plugin is set, create a autoUpdate is disabled.

The data stored and returned in the RouteModel consists of Route objects, as a list with the role name "routeData". See the documentation for Route for further details on its structure and contents.

Example Usage

The following snippet is two-part, showing firstly the declaration of objects, and secondly a short piece of procedural code using it. We set the routeModel's update once the query is set up, to avoid useless extra requests halfway through the set up of the query.

Plugin {
id: aPlugin
name: "nokia"
RouteQuery {
id: aQuery
RouteModel {
id: routeModel
plugin: aPlugin
query: aQuery
autoUpdate: false
aQuery.travelModes = ...

Property Documentation

autoUpdate : bool

This property controls whether the Model automatically updates in response to changes in its attached RouteQuery. The default value of this property is false.

If setting this value to 'true', note that any change at all in the query property will trigger a new request to be sent. If you are adjusting many properties of the RouteQuery with autoUpdate enabled, this can generate large numbers of useless (and later discarded) requests.

count : int

This property holds how many routes the model currently has. Amongst other uses, you can use this value when accessing routes via the QtLocation::RouteModel::get -method.

error : enumeration

This read-only property holds the latest error value of the routing request.

  • RouteModel.NoError - No error has occurred
  • RouteModel.EngineNotSetError - The plugin/service provider used does not support routing
  • RouteModel.CommunicationError - An error occurred while communicating with the service provider
  • RouteModel.ParseError - The response from the service provider was in an unrecognizable format
  • RouteModel.UnsupportedOptionError - The requested operation or one of the options for the operation are not supported by the service provider.
  • RouteModel.UnknownError - An error occurred which does not fit into any of the other categories

errorString : string

This read-only property holds the textual presentation of latest routing error. If no error has occurred or the model has been reset, an empty string is returned.

An empty string may also be returned if an error occurred which has no associated textual representation.

measurementSystem : Locale::MeasurementSystem

This property holds the measurement system which will be used when calculating the route. This property is changed when the plugin changes.

If setting this property it must be set after the plugin property is set.

plugin : Plugin

This property holds the plugin that providers the actual routing service. Note that all plugins do not necessarily provide routing (could for example provide only geocoding or maps).

A valid plugin must be set before the RouteModel can perform any useful operations.

See also Plugin.

query : RouteQuery

This property holds the data of the route request. The primary data are the waypoint coordinates and possible further preferences (means of traveling, things to avoid on route etc).

status : enumeration

This read-only property holds the current status of the model.

Method Documentation


Cancels any outstanding requests and clears errors. Model status will be set to either RouteModel.Ready.


Returns the Route at given index. Use count property to check the amount of routes available. The routes are indexed from zero, so the accessible range is 0...(count - 1).

If you access out of bounds, a zero (null object) is returned and a warning is issued.


Resets the model. All route data is cleared, any outstanding requests are aborted and possible errors are cleared. Model status will be set to RouteModel.Null


Instructs the autoUpdate is disabled, to force a refresh when the query has been changed.