The QPlace class represents a set of data about a place. More...
Header: | #include <QPlace> |
qmake: | QT += location |
Since: | Qt 5.6 |
QPlace() | |
QPlace(const QPlace &other) | |
~QPlace() | |
void | appendContactDetail(const QString &contactType, const QPlaceContactDetail &detail) |
QString | attribution() const |
QList<QPlaceCategory> | categories() const |
QList<QPlaceContactDetail> | contactDetails(const QString &contactType) const |
QStringList | contactTypes() const |
QPlaceContent::Collection | content(QPlaceContent::Type type) const |
bool | detailsFetched() const |
QPlaceAttribute | extendedAttribute(const QString &attributeType) const |
QStringList | extendedAttributeTypes() const |
QPlaceIcon | icon() const |
void | insertContent(QPlaceContent::Type type, const QPlaceContent::Collection &content) |
bool | isEmpty() const |
QGeoLocation | location() const |
QString | name() const |
QString | placeId() const |
QString | primaryEmail() const |
QString | primaryFax() const |
QString | primaryPhone() const |
QUrl | primaryWebsite() const |
QPlaceRatings | ratings() const |
void | removeContactDetails(const QString &contactType) |
void | removeExtendedAttribute(const QString &attributeType) |
void | setAttribution(const QString &attribution) |
void | setCategories(const QList<QPlaceCategory> &categories) |
void | setCategory(const QPlaceCategory &category) |
void | setContactDetails(const QString &contactType, QList<QPlaceContactDetail> details) |
void | setContent(QPlaceContent::Type type, const QPlaceContent::Collection &content) |
void | setDetailsFetched(bool fetched) |
void | setExtendedAttribute(const QString &attributeType, const QPlaceAttribute &attribute) |
void | setIcon(const QPlaceIcon &icon) |
void | setLocation(const QGeoLocation &location) |
void | setName(const QString &name) |
void | setPlaceId(const QString &identifier) |
void | setRatings(const QPlaceRatings &rating) |
void | setSupplier(const QPlaceSupplier &supplier) |
void | setTotalContentCount(QPlaceContent::Type type, int totalCount) |
void | setVisibility(QLocation::Visibility visibility) |
QPlaceSupplier | supplier() const |
int | totalContentCount(QPlaceContent::Type type) const |
QLocation::Visibility | visibility() const |
bool | operator!=(const QPlace &other) const |
QPlace & | operator=(const QPlace &other) |
bool | operator==(const QPlace &other) const |
The QPlace class represents a set of data about a place.
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
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.
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.
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.
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.
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.
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).
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:
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.
Constructs an empty place object.
Constructs a copy of other.
[protected]
QPlace::QPlace(const QSharedDataPointer<QPlacePrivate> &dd)Constructs an place object using dd as private implementation.
Destroys this place.
Appends a contact detail of a specified contactType.
See QPlaceContactDetail for a list of common contact types.
Returns a rich text attribution string of the place. Note, some providers may have a requirement where the attribution must be shown whenever a place is displayed to an end user.
See also setAttribution().
Returns categories that this place belongs to.
See also setCategories().
Returns a list of contact details of the specified contactType.
See QPlaceContactDetail for a list of common contact types.
See also setContactDetails().
Returns the type of contact details this place has.
See QPlaceContactDetail for a list of common contact types.
Returns a collection of content associated with a place. This collection is a map with the key being the index of the content object and value being the content object itself.
The type specifies which kind of content is to be retrieved.
See also setContent().
[protected]
QSharedDataPointer<QPlacePrivate>
&QPlace::d()Returns the d-pointer.
Returns true if the details of this place have been fetched, otherwise returns false.
See also setDetailsFetched().
Returns the exteded attribute corresponding to the specified attributeType. If the place does not have that particular attribute type, a default constructed QPlaceExtendedAttribute is returned.
See also setExtendedAttribute().
Returns the types of extended attributes that this place has.
Returns the icon of the place.
See also setIcon().
Adds a collection of content of the given type to the place. Any index in content that already exists is overwritten.
Returns a boolean indicating whether the all the fields of the place are empty or not.
Returns the location of the place.
See also setLocation().
Returns the name of the place.
See also setName().
Returns the identifier of the place. The place identifier is only meaningful to the QPlaceManager that generated it and is not transferable between managers. The place identifier is not guaranteed to be universally unique, but unique for the manager that generated it.
See also setPlaceId().
Returns the primary email address for this place. This convenience function accesses the first contact detail of the email type. If no email addresses exist, then an empty string is returned.
Returns the primary fax number for this place. This convenience function accesses the first contact detail of the fax type. If no fax details exist, then an empty string is returned.
Returns the primary phone number for this place. This accesses the first contact detail of the phone number type. If no phone details exist, then an empty string is returned.
Returns the primary website of the place. This convenience function accesses the first contact detail of the website type. If no websites exist, then an empty string is returned.
Returns an aggregated rating of the place.
See also setRatings().
Removes all the contact details of a given contactType.
The contactType is no longer returned when QPlace::contactTypes() is called.
Remove the attribute of attributeType from the place.
The attribute will no longer be listed by QPlace::extendedAttributeTypes()
Sets the attribution string of the place.
See also attribution().
Sets the categories that this place belongs to.
See also categories().
Sets a single category that this place belongs to.
Sets the contact details of a specified contactType.
If details is empty, then the contactType is removed from the place such that it is no longer returned by QPlace::contactTypes().
See QPlaceContactDetail for a list of common contact types.
See also contactDetails().
Sets a collection of content for the given type.
See also content().
Sets whether the details of this place have been fetched or not.
See also detailsFetched().
Assigns an attribute of the given attributeType to a place. If the given attributeType already exists in the place, then it is overwritten.
If attribute is a default constructed QPlaceAttribute, then the attributeType is removed from the place which means it will not be listed by QPlace::extendedAttributeTypes().
See also extendedAttribute().
Sets the icon of the place.
See also icon().
Sets the location of the place.
See also location().
Sets the name of the place.
See also name().
Sets the identifier of the place.
See also placeId().
Sets the aggregated rating of the place.
See also ratings().
Sets the supplier of this place to supplier.
See also supplier().
Sets the totalCount of content objects of the given type.
See also totalContentCount().
Sets the visibility of the place to visibility.
See also visibility().
Returns the supplier of this place.
See also setSupplier().
Returns the total count of content objects of the given type. This total count indicates how many the manager/provider should have available. (As opposed to how many objects this place instance is currently assigned).
A negative count indicates that the total number of items is unknown. By default the total content count is set to 0.
See also setTotalContentCount().
Returns the visibility of the place.
The default visibility of a new place is set to QtLocatin::Unspecified visibility. If a place is saved with unspecified visibility the backend chooses an appropriate default visibility to use when saving.
See also setVisibility().
Returns true if other is not equal to this place, otherwise returns false.
Assigns other to this place and returns a reference to this place.
Returns true if other is equal to this place, otherwise returns false.