QtLocation.Place

The Place type represents a location that is a position of interest. More...

Properties

• attribution : string
• categories : list<Category>
• contactDetails : ContactDetails
• detailsFetched : bool
• editorialModel : EditorialModel
• extendedAttributes : ExtendedAttributes
• favorite : Place
• icon : Icon
• imageModel : ImageModel
• location : QtPositioning::Location
• name : string
• place : QPlace
• placeId : string
• plugin : Plugin
• primaryEmail : string
• primaryFax : string
• primaryPhone : string
• primaryWebsite : string
• ratings : Ratings
• reviewModel : ReviewModel
• status : enumeration
• supplier : Supplier
• visibility : enumeration

Methods

• copyFrom(Place original)
• string errorString()
• void getDetails()
• initializeFavorite(Plugin destinationPlugin)
• void remove()
• void save()

Detailed Description

The Place type represents a physical location with additional metadata describing that location. Contrasted with Location, Address, and coordinate type which are used to describe where a location is. The basic properties of a Place are its location.

Place objects are typically obtained from a search model and will generally only have their basic properties set. The status property, which will be set to Place.Fetching when the details are being fetched.

The Place type has many properties holding information about the location. Details on how to contact the place are available from the website are also available.

Each place is assigned zero or more ratings object, which gives an indication of the quality of the place.

Place metadata is provided by a supplier who may require that an attribution message be displayed to the user when the place details are viewed.

Places have an associated icon which can be used to represent a place on a map or to decorate a delegate in a view.

Places may have additional rich content associated with them. The currently supported rich content include editorial descriptions, reviews and images. These are exposed as a set of models for retrieving the content. Editorial descriptions of the place are available from the imageModel property.

Places may have additional attributes which are not covered in the formal API. The extendedAttributes property provides access to these. The type of extended attributes available is specific to each Plugin.

A Place is almost always tied to a editorialModel are only valid then the plugin property is set.

Saving a Place

If the Plugin supports it, the Place type can be used to save a place. First create a new Place and set its properties:

Place {
id: myPlace
plugin: myPlugin
name: "Brisbane Technology Park"
location: Location {
address: Address {
street: "53 Brandl Street"
city: "Eight Mile Plains"
postalCode: "4113"
country: "Australia"
}
coordinate {
latitude: -27.579646
longitude: 153.100308
}
}
visibility: Place.PrivateVisibility
}

Then invoke the save() method:

    myPlace.save();

The status property will change to Place.Saving and then to Place.Ready if the save was successful or to Place.Error if an error occurs.

If the placeId property will be updated with the identifier of the newly saved place.

Caveats

The Places API is currently designed for only saving core details. Saving rich content like images and reviews or details like supplier and rating is not a supported use case. Typically a manager will generally ignore these fields upon save and may produce a warning message if they are populated.

The Places API only supports saving of the following core details:

• name
• place id
• location
• contact details
• icon
• categories (tag-like names to describe a place)
• visibility scope

It is possible that providers may only support a subset of these. See the plugin documentation for more details.

Saving of properties such as the rating, extended attributes, images, reviews, editorials and supplier is explicitly not supported by the Places API.

Saving Between Plugins

When saving places between plugins, there are a few things to be aware of. Some fields of a place such as the id, categories and icons are plugin specific entities. For example the categories in one manager may not be recognised in another. Therefore trying to save a place directly from one plugin to another is not possible.

It is generally recommended that saving across plugins be handled as saving copyFrom() only copies data that is supported by the destination plugin, plugin specific data such as the place identifier is not copied over. Once the copy is done, the place is in a suitable state to be saved.

The following snippet provides an example of saving a place to a different plugin using the copyFrom method:

place = Qt.createQmlObject('import QtLocation 5.3; Place { }', parent);
place.plugin = destinationPlugin;
place.copyFrom(originalPlace);
place.save();

Removing a Place

To remove a place, ensure that a Place object with a valid status property will change to Place.Removing and then to Place.Ready if the save was successful or to Place.Error if an error occurs.

Favorites

The Places API supports the concept of favorites. Favorites are generally implemented by using two plugins, the first plugin is typically a read-only source of places (origin plugin) and a second read/write plugin (destination plugin) is used to store places from the origin as favorites.

Each Place has a favorite property which is intended to contain the corresponding place from the destination plugin (the place itself is sourced from the origin plugin). Because both the original place and favorite instances are available, the developer can choose which properties to show to the user. For example the favorite may have a modified name which should be displayed rather than the original name.

Text { text: place.favorite ? place.favorite.name : place.name }

The following demonstrates how to save a new favorite instance. A call is made to create/initialize the favorite instance and then the instance is saved.

place.initializeFavorite(destinationPlugin);
//if necessary customizations to the favorite can be made here.
//...
place.favorite.save();

The following demonstrates favorite removal:

place.favorite.remove();
...
//check successful removal of the favorite by monitoring its status.
//once that is done we can assign null to the favorite
place.favorite = null;

The PlaceSearchModel has a favoritesPlugin property. If the property is set, any places found during a search are checked against the favoritesPlugin to see if there is a corresponding favorite place. If so, the favorite property of the Place is set, otherwise the favorite property is remains null.

See also PlaceSearchModel.

Property Documentation

This property holds a rich text attribution string for the place. Some providers may require that the attribution be shown to the user whenever a place is displayed. The contents of this property should be shown to the user if it is not empty.

This property holds the list of categories this place is a member of. The categories that can be assigned to a place are specific to each plugin.

This property holds the contact information for this place, for example a phone number or a website URL. This property is a map of ContactDetail objects.

This property indicates whether the details of the place have been fetched. If this property is false, the place details have not yet been fetched. Fetching can be done by invoking the getDetails() method.

See also getDetails().

This property holds a model which can be used to retrieve editorial descriptions of the place.

This property holds the extended attributes of a place. Extended attributes are additional information about a place not covered by the place's properties.

This property holds the favorite instance of a place.

This property holds a graphical icon which can be used to represent the place.

This property holds a model which can be used to retrieve images of the place.

This property holds the location of the place which can be used to retrieve the coordinate, address and the bounding box.

This property holds the name of the place which can be used to represent the place.

For details on how to use this property to interface between C++ and QML see "Interfaces between C++ and QML Code".

This property holds the unique identifier of the place. The place identifier is only meaningful to the Plugin that generated it and is not transferable between Plugins. The place id is not guaranteed to be universally unique, but unique within the Plugin that generated it.

If only the place identifier is known, all other place data can fetched from the Plugin.

    place.plugin = myPlugin;
place.placeId = "known-place-id";
place.getDetails();

This property holds the Plugin that provided this place which can be used to retrieve more information about the service.

This property holds the primary email address of the place. If no "email" contact detail is defined for this place this property will be an empty string. It is equivalent to

    var primaryEmail;
if (place.contactDetails["email"].length > 0)
primaryEmail = place.contactDetails["email"][0].value;

This property holds the primary fax number of the place. If no "fax" contact detail is defined for this place this property will be an empty string. It is equivalent to

    var primaryFax;
if (place.contactDetails["fax"].length > 0)
primaryFax = place.contactDetails["fax"][0].value;

This property holds the primary phone number of the place. If no "phone" contact detail is defined for this place, this property will be an empty string. It is equivalent to:

    var primaryPhone;
if (place.contactDetails["phone"].length > 0)
primaryPhone = place.contactDetails["phone"][0].value;

This property holds the primary website url of the place. If no "website" contact detail is defined for this place this property will be an empty string. It is equivalent to

    var primaryWebsite;
if (place.contactDetails["website"].length > 0)
primaryWebsite = place.contactDetails["website"][0].value;

This property holds ratings of the place. The ratings provide an indication of the quality of a place.

This property holds a model which can be used to retrieve reviews about the place.

This property holds the status of the place. It can be one of:

The status of a place can be checked by connecting the status property to a handler function, and then have the handler function process the change in status.

place.statusChanged.connect(statusChangedHandler);
...
function statusChangedHandler() {
if (statusChangedHandler.prevStatus === Place.Saving) {
switch (place.status) {
case Place.Ready:
console.log('Save successful');
break;
case Place.Error:
console.log('Save failed');
break;
default:
break;
}
}
statusChangedHandler.prevStatus = place.status;
}

This property holds the supplier of the place data. The supplier is typically a business or organization that collected the data about the place.

This property holds the visibility of the place. It can be one of:

Note that visibility does not affect how the place is displayed in the user-interface of an application on the device. Instead, it defines the sharing semantics of the place.

Method Documentation

Copies data from an original place into this place. Only data that is supported by this place's plugin is copied over and plugin specific data such as place identifier is not copied over.

Returns a string description of the error of the last operation. If the last operation completed successfully then the string is empty.

This method starts fetching place details.

The errorString() method can be used to get the details of the error.

Creates a favorite instance for the place which is to be saved into the destination plugin. This method does nothing if the favorite property is not null.

This method performs a remove operation on the place.

The errorString() method can be used to get the details of the error.

This method performs a save operation on the place.

The errorString() method can be used to get the details of the error.

If the placeId property was previously empty, it will be assigned a valid value automatically during a successful save operation.

Note that a Place::getDetails on any place that it detects an update on. A consequence of this is that whenever a Place from a PlaceSearchModel is successfully saved, it will be followed by a fetch of place details, leading to a sequence of state changes of Saving, Ready, Fetching, Ready.