qdeclarativeplace.cpp

Go to the documentation of this file.

// Copyright (C) 2022 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
// Qt-Security score:significant reason:default
 
#include "qdeclarativeplace_p.h"
#include "qdeclarativecontactdetails_p.h"
#include "qdeclarativegeoserviceprovider_p.h"
#include "error_messages_p.h"
 
#include <QtCore/QCoreApplication>
#include <QtCore/QMetaObject>
#include <QtQml/QQmlEngine>
#include <QtQml/QQmlInfo>
#include <QtLocation/QGeoServiceProvider>
#include <QtLocation/QPlaceAttribute>
#include <QtLocation/QPlaceManager>
#include <QtLocation/QPlaceDetailsReply>
#include <QtLocation/QPlaceReply>
#include <QtLocation/QPlaceIdReply>
#include <QtLocation/QPlaceContactDetail>
 
QT_BEGIN_NAMESPACE
 
/*!
    \qmltype Place
    \nativetype QDeclarativePlace
    \inqmlmodule QtLocation
    \ingroup qml-QtLocation5-places
    \ingroup qml-QtLocation5-places-data
    \since QtLocation 5.5
 
    \brief The Place type represents a location that is a position of interest.
 
    The Place type represents a physical location with additional metadata describing that
    location.  Contrasted with \l Location, \l Address, and
    \l [QtPositioning]{geoCoordinate} type, which are used to describe where a
    location is.
    The basic properties of a Place are its \l name and \l location.
 
    Place objects are typically obtained from a search model and will generally only have their
    basic properties set. The \l detailsFetched property can be used to test if further property
    values need to be fetched from the \l Plugin. This can be done by invoking the \l getDetails()
    method.  Progress of the fetching operation can be monitored with the \l 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 \l contactDetails property.  Convenience properties
    for obtaining the primary \l {primaryPhone}{phone}, \l {primaryFax}{fax},
    \l {primaryEmail}{email} and \l {primaryWebsite}{website} are also available.
 
    Each place is assigned zero or more \l categories.  Categories are typically used when
    searching for a particular kind of place, such as a restaurant or hotel.  Some places have a
    \l ratings object, which gives an indication of the quality of the place.
 
    Place metadata is provided by a \l supplier who may require that an \l attribution message be
    displayed to the user when the place details are viewed.
 
    Places have an associated \l 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
    \l editorialModel property.  Reviews of the place are available from the \l reviewModel
    property.  A gallery of pictures of the place can be accessed using the \l imageModel property.
 
    Places may have additional attributes which are not covered in the formal API.  The
    \l extendedAttributes property provides access to these.  The type of extended attributes
    available is specific to each \l Plugin.
 
    A Place is almost always tied to a \l plugin.  The \l plugin property must be set before it is
    possible to call \l save(), \l remove() or \l getDetails().  The \l reviewModel, \l imageModel
    and \l editorialModel are only valid then the \l plugin property is set.
 
    \section2 Saving a Place
 
    If the \l Plugin supports it, the Place type can be used to save a place.  First create a new
    Place and set its properties:
 
    \snippet declarative/places.qml Place savePlace def
 
    Then invoke the \l save() method:
 
    \snippet declarative/places.qml Place savePlace
 
    The \l 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 \l placeId property is set, the backend will update an existing place otherwise it will
    create a new place.  On success the \l placeId property will be updated with the identifier of the newly
    saved place.
 
    \section3 Caveats
    \input place-caveats.qdocinc
 
    \section3 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 \l {Favorites}{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 \l copyFrom() method to copy the details of the original place.
    Using \l 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 \l copyFrom method:
 
    \snippet declarative/places.qml Place save to different plugin
 
    \section2 Removing a Place
 
    To remove a place, ensure that a Place object with a valid \l placeId property exists and call
    its \l remove() method.  The \l 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.
 
    \section2 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.
 
    \snippet declarative/places.qml Place favorite
 
    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.
 
    \snippet declarative/places.qml Place saveFavorite
 
    The following demonstrates favorite removal:
 
    \snippet declarative/places.qml Place removeFavorite 1
    \dots
    \snippet declarative/places.qml Place removeFavorite 2
 
    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.
 
    \sa PlaceSearchModel
*/
 
QDeclarativePlace::QDeclarativePlace(QObject *parent)
:   QObject(parent),
    m_extendedAttributes(QQmlPropertyMap::create(this)),
    m_contactDetails(new QDeclarativeContactDetails(this))
{
    connect(m_contactDetails, &QDeclarativeContactDetails::valueChanged,
            this, &QDeclarativePlace::contactsModified);
 
    setPlace(QPlace());
}
 
QDeclarativePlace::QDeclarativePlace(const QPlace &src, QDeclarativeGeoServiceProvider *plugin, QObject *parent)
:   QObject(parent),
    m_extendedAttributes(QQmlPropertyMap::create(this)),
    m_contactDetails(new QDeclarativeContactDetails(this)),
    m_plugin(plugin)
{
    Q_ASSERT(plugin);
 
    connect(m_contactDetails, &QDeclarativeContactDetails::valueChanged,
            this, &QDeclarativePlace::contactsModified);
 
    setPlace(src);
}
 
QDeclarativePlace::~QDeclarativePlace()
{
}
 
// From QQmlParserStatus
void QDeclarativePlace::componentComplete()
{
    m_complete = true;
}
 
/*!
    \qmlproperty Plugin Place::plugin
 
    This property holds the \l Plugin that provided this place which can be used to retrieve more information about the service.
*/
void QDeclarativePlace::setPlugin(QDeclarativeGeoServiceProvider *plugin)
{
    if (m_plugin == plugin)
        return;
 
    m_plugin = plugin;
    if (m_complete)
        emit pluginChanged();
 
    if (m_plugin->isAttached()) {
        pluginReady();
    } else {
        connect(m_plugin, &QDeclarativeGeoServiceProvider::attached,
                this, &QDeclarativePlace::pluginReady);
    }
}
 
void QDeclarativePlace::pluginReady()
{
    QGeoServiceProvider *serviceProvider = m_plugin->sharedGeoServiceProvider();
    QPlaceManager *placeManager = serviceProvider->placeManager();
    if (!placeManager || serviceProvider->error() != QGeoServiceProvider::NoError) {
        setStatus(Error, QCoreApplication::translate(CONTEXT_NAME, PLUGIN_ERROR)
                         .arg(m_plugin->name()).arg(serviceProvider->errorString()));
        return;
    }
}
 
QDeclarativeGeoServiceProvider *QDeclarativePlace::plugin() const
{
    return m_plugin;
}
 
/*!
    \qmlproperty ReviewModel Place::reviewModel
 
    This property holds a model which can be used to retrieve reviews about the place.
*/
QDeclarativePlaceReviewModel *QDeclarativePlace::reviewModel()
{
    if (!m_reviewModel) {
        m_reviewModel = new QDeclarativePlaceReviewModel(this);
        m_reviewModel->setPlace(this);
    }
 
    return m_reviewModel;
}
 
/*!
    \qmlproperty ImageModel Place::imageModel
 
    This property holds a model which can be used to retrieve images of the place.
*/
QDeclarativePlaceImageModel *QDeclarativePlace::imageModel()
{
    if (!m_imageModel) {
        m_imageModel = new QDeclarativePlaceImageModel(this);
        m_imageModel->setPlace(this);
    }
 
    return m_imageModel;
}
 
/*!
    \qmlproperty EditorialModel Place::editorialModel
 
    This property holds a model which can be used to retrieve editorial descriptions of the place.
*/
QDeclarativePlaceEditorialModel *QDeclarativePlace::editorialModel()
{
    if (!m_editorialModel) {
        m_editorialModel = new QDeclarativePlaceEditorialModel(this);
        m_editorialModel->setPlace(this);
    }
 
    return m_editorialModel;
}
 
/*!
    \internal
*/
void QDeclarativePlace::setPlace(const QPlace &src)
{
    QPlace previous = m_src;
    m_src = src;
 
    if (previous.categories() != m_src.categories()) {
        synchronizeCategories();
        emit categoriesChanged();
    }
 
    if (m_location && m_location->parent() == this) {
        m_location->setLocation(m_src.location());
    } else if (!m_location || m_location->parent() != this) {
        m_location = new QDeclarativeGeoLocation(m_src.location(), this);
        emit locationChanged();
    }
 
    if (previous.ratings() != m_src.ratings())
        emit ratingsChanged();
    if (previous.supplier() != m_src.supplier())
        emit supplierChanged();
    if (previous.icon() != m_src.icon())
        emit iconChanged();
    if (previous.name() != m_src.name())
        emit nameChanged();
    if (previous.placeId() != m_src.placeId())
        emit placeIdChanged();
    if (previous.attribution() != m_src.attribution())
        emit attributionChanged();
    if (previous.detailsFetched() != m_src.detailsFetched())
        emit detailsFetchedChanged();
    if (previous.primaryPhone() != m_src.primaryPhone())
        emit primaryPhoneChanged();
    if (previous.primaryFax() != m_src.primaryFax())
        emit primaryFaxChanged();
    if (previous.primaryEmail() != m_src.primaryEmail())
        emit primaryEmailChanged();
    if (previous.primaryWebsite() != m_src.primaryWebsite())
        emit primaryWebsiteChanged();
 
    if (m_reviewModel && m_src.totalContentCount(QPlaceContent::ReviewType) >= 0) {
        m_reviewModel->initializeCollection(m_src.totalContentCount(QPlaceContent::ReviewType),
                                            m_src.content(QPlaceContent::ReviewType));
    }
    if (m_imageModel && m_src.totalContentCount(QPlaceContent::ImageType) >= 0) {
        m_imageModel->initializeCollection(m_src.totalContentCount(QPlaceContent::ImageType),
                                           m_src.content(QPlaceContent::ImageType));
    }
    if (m_editorialModel && m_src.totalContentCount(QPlaceContent::EditorialType) >= 0) {
        m_editorialModel->initializeCollection(m_src.totalContentCount(QPlaceContent::EditorialType),
                                               m_src.content(QPlaceContent::EditorialType));
    }
 
    pullExtendedAttributes();
    synchronizeContacts();
}
 
QPlace QDeclarativePlace::place() const
{
    // The properties handled explicirly here are not stored in m_src, but
    // but are instead stored in QDeclarative* objects which we need to update
    // explicitly.
 
    QPlace result = m_src;
 
    // Categories
    QList<QPlaceCategory> categories;
    for (QDeclarativeCategory *value : std::as_const(m_categories))
        categories.append(value->category());
 
    result.setCategories(categories);
 
    // Location
    result.setLocation(m_location ? m_location->location() : QGeoLocation());
 
    //contact details
    QList<QPlaceContactDetail> cppDetails;
    for (const QString &key : m_contactDetails->keys()) {
        cppDetails.clear();
        if (m_contactDetails->value(key).typeId() == QMetaType::QVariantList) {
            const QVariantList detailsVarList = m_contactDetails->value(key).toList();
            for (const QVariant &detailVar : detailsVarList)
                cppDetails.append(detailVar.value<QPlaceContactDetail>());
        } else {
            cppDetails.append(m_contactDetails->value(key).value<QPlaceContactDetail>());
        }
        result.setContactDetails(key, cppDetails);
    }
 
    return result;
}
 
/*!
    \qmlproperty QtPositioning::Location Place::location
 
    This property holds the location of the place which can be used to retrieve the coordinate,
    address and the bounding box.
*/
void QDeclarativePlace::setLocation(QDeclarativeGeoLocation *location)
{
    if (m_location == location)
        return;
 
    if (m_location && m_location->parent() == this)
        delete m_location;
 
    m_location = location;
    emit locationChanged();
}
 
QDeclarativeGeoLocation *QDeclarativePlace::location() const
{
    return m_location;
}
 
/*!
    \qmlproperty Ratings Place::ratings
 
    This property holds ratings of the place.  The ratings provide an indication of the quality of a
    place.
*/
void QDeclarativePlace::setRatings(const QPlaceRatings &rating)
{
    if (m_src.ratings() != rating) {
        m_src.setRatings(rating);
        emit ratingsChanged();
    }
}
 
QPlaceRatings QDeclarativePlace::ratings() const
{
    return m_src.ratings();
}
 
/*!
    \qmlproperty Supplier Place::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.
*/
void QDeclarativePlace::setSupplier(const QPlaceSupplier &supplier)
{
    if (m_src.supplier() != supplier) {
        m_src.setSupplier(supplier);
        emit supplierChanged();
    }
}
 
QPlaceSupplier QDeclarativePlace::supplier() const
{
    return m_src.supplier();
}
 
/*!
    \qmlproperty Icon Place::icon
 
    This property holds a graphical icon which can be used to represent the place.
*/
QPlaceIcon QDeclarativePlace::icon() const
{
    return m_src.icon();
}
 
void QDeclarativePlace::setIcon(const QPlaceIcon &icon)
{
    if (m_src.icon() != icon) {
        m_src.setIcon(icon);
        emit iconChanged();
    }
}
 
/*!
    \qmlproperty string Place::name
 
    This property holds the name of the place which can be used to represent the place.
*/
void QDeclarativePlace::setName(const QString &name)
{
    if (m_src.name() != name) {
        m_src.setName(name);
        emit nameChanged();
    }
}
 
QString QDeclarativePlace::name() const
{
    return m_src.name();
}
 
/*!
    \qmlproperty string Place::placeId
 
    This property holds the unique identifier of the place.  The place identifier is only meaningful to the
    \l Plugin that generated it and is not transferable between \l {Plugin}{Plugins}.  The place id
    is not guaranteed to be universally unique, but unique within the \l Plugin that generated it.
 
    If only the place identifier is known, all other place data can fetched from the \l Plugin.
 
    \snippet declarative/places.qml Place placeId
*/
void QDeclarativePlace::setPlaceId(const QString &placeId)
{
    if (m_src.placeId() != placeId) {
        m_src.setPlaceId(placeId);
        emit placeIdChanged();
    }
}
 
QString QDeclarativePlace::placeId() const
{
    return m_src.placeId();
}
 
/*!
    \qmlproperty string Place::attribution
 
    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.
*/
void QDeclarativePlace::setAttribution(const QString &attribution)
{
    if (m_src.attribution() != attribution) {
        m_src.setAttribution(attribution);
        emit attributionChanged();
    }
}
 
QString QDeclarativePlace::attribution() const
{
    return m_src.attribution();
}
 
/*!
    \qmlproperty bool Place::detailsFetched
 
    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
    \l getDetails() method.
 
    \sa getDetails()
*/
bool QDeclarativePlace::detailsFetched() const
{
    return m_src.detailsFetched();
}
 
/*!
    \qmlproperty enumeration Place::status
 
    This property holds the status of the place.  It can be one of:
 
    \table
        \row
            \li Place.Ready
            \li No error occurred during the last operation, further operations may be performed on
               the place.
        \row
            \li Place.Saving
            \li The place is currently being saved, no other operation may be performed until
               complete.
        \row
            \li Place.Fetching
            \li The place details are currently being fetched, no other operations may be performed
               until complete.
        \row
            \li Place.Removing
            \li The place is currently being removed, no other operations can be performed until
               complete.
        \row
            \li Place.Error
            \li An error occurred during the last operation, further operations can still be
               performed on the place.
    \endtable
 
    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.
 
    \snippet declarative/places.qml Place checkStatus
    \dots
    \snippet declarative/places.qml Place checkStatus handler
 
*/
void QDeclarativePlace::setStatus(Status status, const QString &errorString)
{
    Status originalStatus = m_status;
    m_status = status;
    m_errorString = errorString;
 
    if (originalStatus != m_status)
        emit statusChanged();
}
 
QDeclarativePlace::Status QDeclarativePlace::status() const
{
    return m_status;
}
 
/*!
    \internal
*/
void QDeclarativePlace::finished()
{
    if (!m_reply)
        return;
 
    if (m_reply->error() == QPlaceReply::NoError) {
        switch (m_reply->type()) {
        case (QPlaceReply::IdReply) : {
            QPlaceIdReply *idReply = qobject_cast<QPlaceIdReply *>(m_reply);
 
            switch (idReply->operationType()) {
            case QPlaceIdReply::SavePlace:
                setPlaceId(idReply->id());
                break;
            case QPlaceIdReply::RemovePlace:
                break;
            default:
                //Other operation types shouldn't ever be received.
                break;
            }
            break;
        }
        case (QPlaceReply::DetailsReply): {
            QPlaceDetailsReply *detailsReply = qobject_cast<QPlaceDetailsReply *>(m_reply);
            setPlace(detailsReply->place());
            break;
        }
        default:
            //other types of replies shouldn't ever be received.
            break;
        }
 
        m_errorString.clear();
 
        m_reply->deleteLater();
        m_reply = nullptr;
 
        setStatus(QDeclarativePlace::Ready);
    } else {
        QString errorString = m_reply->errorString();
 
        m_reply->deleteLater();
        m_reply = nullptr;
 
        setStatus(QDeclarativePlace::Error, errorString);
    }
}
 
/*!
    \internal
*/
void QDeclarativePlace::contactsModified(const QString &key, const QVariant &)
{
    primarySignalsEmission(key);
}
 
/*!
    \internal
*/
void QDeclarativePlace::cleanupDeletedCategories()
{
    for (QDeclarativeCategory * category : m_categoriesToBeDeleted) {
        if (category->parent() == this)
            delete category;
    }
    m_categoriesToBeDeleted.clear();
}
 
/*!
    \qmlmethod void Place::getDetails()
 
    This method starts fetching place details.
 
    The \l status property will change to Place.Fetching while the fetch is in progress.  On
    success the object's properties will be updated, \l status will be set to Place.Ready and
    \l detailsFetched will be set to true.  On error \l status will be set to Place.Error.  The
    \l errorString() method can be used to get the details of the error.
*/
void QDeclarativePlace::getDetails()
{
    QPlaceManager *placeManager = manager();
    if (!placeManager)
        return;
 
    m_reply = placeManager->getPlaceDetails(placeId());
    connect(m_reply, &QPlaceReply::finished, this, &QDeclarativePlace::finished);
    setStatus(QDeclarativePlace::Fetching);
}
 
/*!
    \qmlmethod void Place::save()
 
    This method performs a save operation on the place.
 
    The \l status property will change to Place.Saving while the save operation is in progress.  On
    success the \l status will be set to Place.Ready.  On error \l status will be set to Place.Error.
    The \l errorString() method can be used to get the details of the error.
 
    If the \l placeId property was previously empty, it will be assigned a valid value automatically
    during a successful save operation.
 
    Note that a \l 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 \l PlaceSearchModel is successfully saved,
    it will be followed by a fetch of place details, leading to a sequence of state changes
    of \c Saving, \c Ready, \c Fetching, \c Ready.
 
*/
void QDeclarativePlace::save()
{
    QPlaceManager *placeManager = manager();
    if (!placeManager)
        return;
 
    m_reply = placeManager->savePlace(place());
    connect(m_reply, &QPlaceReply::finished, this, &QDeclarativePlace::finished);
    setStatus(QDeclarativePlace::Saving);
}
 
/*!
    \qmlmethod void Place::remove()
 
    This method performs a remove operation on the place.
 
    The \l status property will change to Place.Removing while the save operation is in progress.
    On success \l status will be set to Place.Ready.  On error \l status will be set to
    Place.Error.  The \l errorString() method can be used to get the details of the error.
*/
void QDeclarativePlace::remove()
{
    QPlaceManager *placeManager = manager();
    if (!placeManager)
        return;
 
    m_reply = placeManager->removePlace(place().placeId());
    connect(m_reply, &QPlaceReply::finished, this, &QDeclarativePlace::finished);
    setStatus(QDeclarativePlace::Removing);
}
 
/*!
    \qmlmethod string Place::errorString()
 
    Returns a string description of the error of the last operation.  If the last operation
    completed successfully then the string is empty.
*/
QString QDeclarativePlace::errorString() const
{
    return m_errorString;
}
 
/*!
    \qmlproperty string Place::primaryPhone
 
    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:
 
 
    \snippet declarative/places.qml Place primaryPhone
*/
QString QDeclarativePlace::primaryPhone() const
{
    return primaryValue(QPlaceContactDetail::Phone);
}
 
/*!
    \qmlproperty string Place::primaryFax
 
    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
 
    \snippet declarative/places.qml Place primaryFax
*/
QString QDeclarativePlace::primaryFax() const
{
    return primaryValue(QPlaceContactDetail::Fax);
}
 
/*!
    \qmlproperty string Place::primaryEmail
 
    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
 
    \snippet declarative/places.qml Place primaryEmail
*/
QString QDeclarativePlace::primaryEmail() const
{
    return primaryValue(QPlaceContactDetail::Email);
}
 
/*!
    \qmlproperty string Place::primaryWebsite
 
    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
 
    \snippet declarative/places.qml Place primaryWebsite
*/
 
QUrl QDeclarativePlace::primaryWebsite() const
{
    return QUrl(primaryValue(QPlaceContactDetail::Website));
}
 
/*!
    \qmlproperty ExtendedAttributes Place::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.
*/
QQmlPropertyMap *QDeclarativePlace::extendedAttributes() const
{
    return m_extendedAttributes;
}
 
/*!
    \qmlproperty ContactDetails Place::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 \l contactDetail objects.
*/
QDeclarativeContactDetails *QDeclarativePlace::contactDetails() const
{
    return m_contactDetails;
}
 
/*!
    \qmlproperty list<Category> Place::categories
 
    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 \l plugin.
*/
QQmlListProperty<QDeclarativeCategory> QDeclarativePlace::categories()
{
    return QQmlListProperty<QDeclarativeCategory>(this,
                                                          0, // opaque data parameter
                                                          category_append,
                                                          category_count,
                                                          category_at,
                                                          category_clear);
}
 
/*!
    \internal
*/
void QDeclarativePlace::category_append(QQmlListProperty<QDeclarativeCategory> *prop,
                                                  QDeclarativeCategory *value)
{
    QDeclarativePlace *object = static_cast<QDeclarativePlace *>(prop->object);
 
    if (object->m_categoriesToBeDeleted.contains(value))
        object->m_categoriesToBeDeleted.removeAll(value);
 
    if (!object->m_categories.contains(value)) {
        object->m_categories.append(value);
        QList<QPlaceCategory> list = object->m_src.categories();
        list.append(value->category());
        object->m_src.setCategories(list);
 
        emit object->categoriesChanged();
    }
}
 
/*!
    \internal
*/
qsizetype QDeclarativePlace::category_count(QQmlListProperty<QDeclarativeCategory> *prop)
{
    return static_cast<QDeclarativePlace *>(prop->object)->m_categories.count();
}
 
/*!
    \internal
*/
QDeclarativeCategory *QDeclarativePlace::category_at(QQmlListProperty<QDeclarativeCategory> *prop,
                                                     qsizetype index)
{
    QDeclarativePlace *object = static_cast<QDeclarativePlace *>(prop->object);
    QDeclarativeCategory *res = NULL;
    if (object->m_categories.count() > index && index > -1) {
        res = object->m_categories[index];
    }
    return res;
}
 
/*!
    \internal
*/
void QDeclarativePlace::category_clear(QQmlListProperty<QDeclarativeCategory> *prop)
{
    QDeclarativePlace *object = static_cast<QDeclarativePlace *>(prop->object);
    if (object->m_categories.isEmpty())
        return;
 
    for (auto *category : std::as_const(object->m_categories)) {
        if (category->parent() == object)
            object->m_categoriesToBeDeleted.append(category);
    }
 
    object->m_categories.clear();
    object->m_src.setCategories(QList<QPlaceCategory>());
    emit object->categoriesChanged();
    QMetaObject::invokeMethod(object, "cleanupDeletedCategories", Qt::QueuedConnection);
}
 
/*!
    \internal
*/
void QDeclarativePlace::synchronizeCategories()
{
    qDeleteAll(m_categories);
    m_categories.clear();
    for (const QPlaceCategory &value : m_src.categories()) {
        QDeclarativeCategory *declarativeValue = new QDeclarativeCategory(value, m_plugin, this);
        m_categories.append(declarativeValue);
    }
}
 
/*!
    \qmlproperty enumeration Place::visibility
 
    This property holds the visibility of the place.  It can be one of:
 
    \table
        \row
            \li Place.UnspecifiedVisibility
            \li The visibility of the place is unspecified, the default visibility of the \l Plugin
               will be used.
        \row
            \li Place.DeviceVisibility
            \li The place is limited to the current device.  The place will not be transferred off
               of the device.
        \row
            \li Place.PrivateVisibility
            \li 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.
        \row
            \li Place.PublicVisibility
            \li The place is public.
    \endtable
 
    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.
*/
QDeclarativePlace::Visibility QDeclarativePlace::visibility() const
{
    return static_cast<QDeclarativePlace::Visibility>(m_src.visibility());
}
 
void QDeclarativePlace::setVisibility(Visibility visibility)
{
    if (static_cast<QDeclarativePlace::Visibility>(m_src.visibility()) == visibility)
        return;
 
    m_src.setVisibility(static_cast<QLocation::Visibility>(visibility));
    emit visibilityChanged();
}
 
/*!
    \qmlproperty Place Place::favorite
 
    This property holds the favorite instance of a place.
*/
QDeclarativePlace *QDeclarativePlace::favorite() const
{
    return m_favorite;
}
 
void QDeclarativePlace::setFavorite(QDeclarativePlace *favorite)
{
 
    if (m_favorite == favorite)
        return;
 
    if (m_favorite && m_favorite->parent() == this)
        delete m_favorite;
 
    m_favorite = favorite;
    emit favoriteChanged();
}
 
/*!
    \qmlmethod void Place::copyFrom(Place original)
 
    Copies data from an \a 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.
*/
void QDeclarativePlace::copyFrom(QDeclarativePlace *original)
{
    QPlaceManager *placeManager = manager();
    if (!placeManager)
        return;
 
    setPlace(placeManager->compatiblePlace(original->place()));
}
 
/*!
    \qmlmethod void Place::initializeFavorite(Plugin destinationPlugin)
 
    Creates a favorite instance for the place which is to be saved into the
    destination plugin \a destinationPlugin. This method does nothing if the
    favorite property is not \c null.
*/
void QDeclarativePlace::initializeFavorite(QDeclarativeGeoServiceProvider *plugin)
{
    if (m_favorite == 0) {
        QDeclarativePlace *place = new QDeclarativePlace(this);
        place->setPlugin(plugin);
        place->copyFrom(this);
        setFavorite(place);
    }
}
 
/*!
    \internal
*/
void QDeclarativePlace::pullExtendedAttributes()
{
    const QStringList keys = m_extendedAttributes->keys();
    for (const QString &key : keys)
        m_extendedAttributes->clear(key);
 
    const QStringList attributeTypes = m_src.extendedAttributeTypes();
    for (const QString &attributeType : attributeTypes) {
        m_extendedAttributes->insert(attributeType,
            QVariant::fromValue(m_src.extendedAttribute(attributeType)));
    }
 
    emit extendedAttributesChanged();
}
 
/*!
    \internal
*/
void QDeclarativePlace::synchronizeContacts()
{
    //clear out contact data
    for (const QString &contactType : m_contactDetails->keys()) {
        const QList<QVariant> contacts = m_contactDetails->value(contactType).toList();
        for (const QVariant &var : contacts) {
            QObject *obj = var.value<QObject *>();
            if (obj->parent() == this)
                delete obj;
        }
        m_contactDetails->insert(contactType, QVariantList());
    }
 
    //insert new contact data from source place
    for (const QString &contactType : m_src.contactTypes()) {
        const QList<QPlaceContactDetail> sourceContacts = m_src.contactDetails(contactType);
        QVariantList declContacts;
        for (const QPlaceContactDetail &sourceContact : sourceContacts)
            declContacts.append(QVariant::fromValue(sourceContact));
        m_contactDetails->insert(contactType, declContacts);
    }
    primarySignalsEmission();
}
 
/*!
    \internal
    Helper function to emit the signals for the primary___()
    fields.  It is expected that the values of the primary___()
    functions have already been modified to new values.
*/
void QDeclarativePlace::primarySignalsEmission(const QString &type)
{
    if (type.isEmpty() || type == QPlaceContactDetail::Phone) {
        if (m_prevPrimaryPhone != primaryPhone()) {
            m_prevPrimaryPhone = primaryPhone();
            emit primaryPhoneChanged();
        }
        if (!type.isEmpty())
            return;
    }
 
    if (type.isEmpty() || type == QPlaceContactDetail::Email) {
        if (m_prevPrimaryEmail != primaryEmail()) {
            m_prevPrimaryEmail = primaryEmail();
            emit primaryEmailChanged();
        }
        if (!type.isEmpty())
            return;
    }
 
    if (type.isEmpty() || type == QPlaceContactDetail::Website) {
        if (m_prevPrimaryWebsite != primaryWebsite()) {
            m_prevPrimaryWebsite = primaryWebsite();
            emit primaryWebsiteChanged();
        }
        if (!type.isEmpty())
            return;
    }
 
    if (type.isEmpty() || type == QPlaceContactDetail::Fax) {
        if (m_prevPrimaryFax != primaryFax()) {
            m_prevPrimaryFax = primaryFax();
            emit primaryFaxChanged();
        }
    }
}
 
/*!
    \internal
    Helper function to return the manager, this manager is intended to be used
    to perform the next operation.  If a an operation is currently underway
    then return a null pointer.
*/
QPlaceManager *QDeclarativePlace::manager()
{
    if (m_status != QDeclarativePlace::Ready && m_status != QDeclarativePlace::Error)
        return nullptr;
 
    if (m_reply) {
        m_reply->abort();
        m_reply->deleteLater();
        m_reply = nullptr;
    }
 
    if (!m_plugin) {
           qmlWarning(this) << QStringLiteral("Plugin is not assigned to place.");
           return nullptr;
    }
 
    QGeoServiceProvider *serviceProvider = m_plugin->sharedGeoServiceProvider();
    if (!serviceProvider)
        return nullptr;
 
    QPlaceManager *placeManager = serviceProvider->placeManager();
 
    if (!placeManager) {
        setStatus(Error, QCoreApplication::translate(CONTEXT_NAME, PLUGIN_ERROR)
                         .arg(m_plugin->name()).arg(serviceProvider->errorString()));
        return nullptr;
    }
 
    return placeManager;
}
 
/*!
    \internal
*/
QString QDeclarativePlace::primaryValue(const QString &contactType) const
{
    QVariant value = m_contactDetails->value(contactType);
    if (value.userType() == qMetaTypeId<QJSValue>())
        value = value.value<QJSValue>().toVariant();
 
    if (value.userType() == QMetaType::QVariantList) {
        QVariantList detailList = m_contactDetails->value(contactType).toList();
        if (!detailList.isEmpty())
            return detailList.at(0).value<QPlaceContactDetail>().value();
    } else if (value.metaType() == QMetaType::fromType<QPlaceContactDetail>()) {
        return value.value<QPlaceContactDetail>().value();
    }
 
    return QString();
}
 
QT_END_NAMESPACE