GeocodeModel QML Type

The GeocodeModel type provides support for searching operations related to geographic information. More...

Import Statement:	import QtLocation 5.14
Since:	QtLocation 5.5

• List of all members, including inherited members

Properties

• autoUpdate : bool
• bounds : geoshape
• count : int
• error : enumeration
• errorString : string
• limit : int
• offset : int
• plugin : Plugin
• query : QVariant
• status : enumeration

Signals

• locationsChanged()

Methods

• void cancel()
• Location get(index)
• void reset()
• void update()

Detailed Description

The GeocodeModel type is used as part of a model/view grouping to match addresses or search strings with geographic locations. How the geographic locations generated are used or displayed is decided by any Views attached to the GeocodeModel (for example a MapItemView or ListView).

Like Map and RouteModel, all the data for a GeocodeModel to work comes from a services plugin. This is contained in the plugin property, and this must be set before the GeocodeModel can do any useful work.

Once the plugin is set, the query property can be used to specify the address or search string to match. If autoUpdate is enabled, the Model will update its output automatically. Otherwise, the update method may be used. By default, autoUpdate is disabled.

The data stored and returned in the GeocodeModel consists of Location objects, as a list with the role name "locationData". See the documentation for Location 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 geocodeModel's autoUpdate property to false, and call update once the query is set up. In this case, as we use a string value in query, only one update would occur, even with autoUpdate enabled. However, if we provided an Address object we may inadvertently trigger multiple requests whilst setting its properties.

Plugin {
    id: aPlugin
}

GeocodeModel {
    id: geocodeModel
    plugin: aPlugin
    autoUpdate: false
}

{
    geocodeModel.query = "53 Brandl St, Eight Mile Plains, Australia"
    geocodeModel.update()
}

Property Documentation

autoUpdate : bool

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

If setting this value to 'true' and using an Address or coordinate as the query, note that any change at all in the object's properties will trigger a new request to be sent. If you are adjusting many properties of the object whilst autoUpdate is enabled, this can generate large numbers of useless (and later discarded) requests.

bounds : geoshape

This property holds the bounding area used to limit the results to those within the area. This is particularly useful if query is only partially filled out, as the service will attempt to (reverse) geocode all matches for the specified data.

Accepted types are georectangle and geocircle.

count : int

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

error : enumeration

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

• GeocodeModel.NoError - No error has occurred.
• GeocodeModel.CombinationError - An error occurred while results where being combined from multiple sources.
• GeocodeModel.CommunicationError - An error occurred while communicating with the service provider.
• GeocodeModel.EngineNotSetError - The model's plugin property was not set or there is no geocoding manager associated with the plugin.
• GeocodeModel.MissingRequiredParameterError - A required parameter was not specified.
• GeocodeModel.ParseError - The response from the service provider was in an unrecognizable format.
• GeocodeModel.UnknownError - An error occurred which does not fit into any of the other categories.
• GeocodeModel.UnknownParameterError - The plugin did not recognize one of the parameters it was given.
• GeocodeModel.UnsupportedOptionError - The requested operation is not supported by the geocoding provider. This may happen when the loaded engine does not support a particular geocoding request such as reverse geocoding.

errorString : string

This read-only property holds the textual presentation of the latest geocoding 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.

limit : int

This property holds the maximum number of results. The limit and offset values are only applicable with free string geocoding (that is they are not considered when using addresses or coordinates in the search query).

If limit is -1 the entire result set will be returned, otherwise at most limit results will be returned. The limit and offset results can be used together to implement paging.

offset : int

This property tells not to return the first 'offset' number of the results. The limit and offset values are only applicable with free string geocoding (that is they are not considered when using addresses or coordinates in the search query).

The limit and offset results can be used together to implement paging.

plugin : Plugin

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

See also Plugin.

query : QVariant

This property holds the data of the geocoding request. The property accepts three types of queries which determine both the data and the type of action to be performed:

• Address - Geocoding (address to coordinate)
• coordinate - Reverse geocoding (coordinate to address)
• string - Geocoding (address to coordinate)

status : enumeration

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

• GeocodeModel.Null - No geocode requests have been issued or reset has been called.
• GeocodeModel.Ready - Geocode request(s) have finished successfully.
• GeocodeModel.Loading - Geocode request has been issued but not yet finished
• GeocodeModel.Error - Geocoding error has occurred, details are in error and errorString

Signal Documentation

locationsChanged()

This signal is emitted when locations in the model have changed.

See also count.

Method Documentation

void cancel()

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

Location get(index)

Returns the Location at given index. Use count property to check the amount of locations available. The locations 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.

void reset()

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

void update()

Instructs the GeocodeModel to update its data. This is most useful when autoUpdate is disabled, to force a refresh when the query has been changed.