QtLocation Place

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

Import Statement: import QtLocation 5.3
Since: Qt Location 5.0

Properties

Methods

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 name and location.

Place objects are typically obtained from a search model and will generally only have their basic properties set. The detailsFetched property can be used to test if further property values need to be fetched from the Plugin . This can be done by invoking the getDetails() method. Progress of the fetching operation can be monitored with 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 contactDetails property. Convenience properties for obtaining the primary phone, fax, email and website are also available.

Each place is assigned zero or more categories . Categories are typically used when searching for a particular kind of place, such as a restaurant or hotel. Some places have a 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 editorialModel property. Reviews of the place are available from the reviewModel property. A gallery of pictures of the place can be accessed using 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 plugin . The plugin property must be set before it is possible to call save(), remove() or getDetails(). The reviewModel, imageModel and 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 is set, the backend will update an existing place otherwise it will create a new place. On success 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 favorites as explained in the Favorites section. However there is another approach which is to create a new place, set its (destination) plugin and then use the copyFrom() method to copy the details of the original place. Using 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 placeId property exists and call its remove() method. The 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

attribution : string

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.

categories : list<Category>

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 .

contactDetails : ContactDetails

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.

detailsFetched : bool

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().

editorialModel : EditorialModel

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

extendedAttributes : ExtendedAttributes

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

favorite : Place

This property holds the favorite instance of a place.

icon : Icon

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

imageModel : ImageModel

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

location : QtPositioning::Location

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

name : string

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

place : QPlace

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

placeId : string

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();
plugin : Plugin

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

primaryEmail : string

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;
primaryFax : string

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;
primaryPhone : string

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;
primaryWebsite : string

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;
ratings : Ratings

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

reviewModel : ReviewModel

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

status : enumeration

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

Place.Ready No error occurred during the last operation, further operations may be performed on the place.
Place.Saving The place is currently being saved, no other operation may be performed until complete.
Place.Fetching The place details are currently being fetched, no other operations may be performed until complete.
Place.Removing The place is currently being removed, no other operations can be performed until complete.
Place.Error An error occurred during the last operation, further operations can still be performed on the place.

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;
}
supplier : Supplier

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

visibility : enumeration

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

Place.UnspecifiedVisibility The visibility of the place is unspecified, the default visibility of the Plugin will be used.
Place.DeviceVisibility The place is limited to the current device. The place will not be transferred off of the device.
Place.PrivateVisibility The place is private to the current user. The place may be transferred to an online service but is only ever visible to the current user.
Place.PublicVisibility The place is public.

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

copyFrom(Place original)

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.

string errorString()

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

void getDetails()

This method starts fetching place details.

The status property will change to Place.Fetching while the fetch is in progress. On success the object’s properties will be updated, status will be set to Place.Ready and detailsFetched will be set to true. On error status will be set to Place.Error. The errorString() method can be used to get the details of the error.

initializeFavorite(Plugin destinationPlugin)

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.

void remove()

This method performs a remove operation on the place.

The status property will change to Place.Removing while the save operation is in progress. On success status will be set to Place.Ready. On error status will be set to Place.Error. The errorString() method can be used to get the details of the error.

void save()

This method performs a save operation on the place.

The status property will change to Place.Saving while the save operation is in progress. On success the status will be set to Place.Ready. On error status will be set to Place.Error. 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 PlaceSearchModel will call 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.