QPlace Class

Detailed Description

A place is a point of interest, it could be a favorite restaurant, a park or someone's home. A QPlace object represents a place by acting as a container for various information about that place.

This information can be divided into 2 broad classifications

• Details
• Rich content

The place details consist of properties of the place, such as the name, location, contact information and so on. When a place is returned during a search, these details are filled in. Sometimes in order to save bandwidth, there are further details about the place that can be retrieved on an individual place by place basis, if the user is interested. The QPlace::detailsFetched() function can be queried to see if all available details have been fetched, and if not, QPlaceManager::getPlaceDetails() can be used to retrieve them. Precisely which details are populated during a search and which need to be fetched individually may vary from provider to provider. See plugin documentation for more details.

The rich content of a place consists of items such as images, reviews and editorials. Potentially there may be many rich content items, so they are treated separately from the place details. They can be retrieved in a paged fashion via QPlaceManager::getPlaceContent(). If necessary, the content may be assigned to a place so it can act as a convenient container.

Contact Information

The contact information of a place is based around a common set of contact types. To retrieve all the phone numbers of a place, one would do:

 if (place.contactTypes().contains(QPlaceContactDetail::Phone)) {
     foreach (const QPlaceContactDetail &number, place.contactDetails(QPlaceContactDetail::Phone))
         qDebug() << number.label() << ":" << number.value();
 }

The contact types are string values by design to allow for providers to introduce new contact types.

For convenience there are a set of functions which return the value of the first contact detail of each type.

• QPlace::primaryPhone()
• QPlace::primaryEmail()
• QPlace::primaryWebsite()
• QPlace::primaryFax()

Extended Attributes

Places may have additional attributes which are not covered in the formal API. Similar to contacts attributes are based around a common set of attribute types. To retrieve an extended attribute one would do:

 if (place.extendedAttributeTypes().contains(QPlaceAttribute::OpeningHours))
     qDebug() << place.extendedAttribute(QPlaceAttribute::OpeningHours).text();

The attribute types are string values by design to allow providers to introduce new attribute types.

Content

The QPlace object is only meant to be a convenient container to hold rich content such as images, reviews and so on. Retrieval of content should happen via QPlaceManager::getPlaceContent().

The content is stored as a QPlaceContent::Collection which contains both the index of the content, as well as the content itself. This enables developers to check whether a particular item has already been retrieved and if not, then request that content.

Attribution

Places have a field for a rich text attribution string. Some providers may require that the attribution be shown when a place is displayed to a user.

Categories

Different categories may be assigned to a place to indicate that the place is associated with those categories. When saving a place, the only meaningful data is the category id, the rest of the category data is effectively ignored. The category must already exist before saving the place (it is not possible to create a new category, assign it to the place, save the place and expect the category to be created).

Saving 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.