From 4beb6dfa7f818ced9aff296728519d4a6590eb5c Mon Sep 17 00:00:00 2001 From: abcd Date: Mon, 14 Nov 2011 11:11:27 +1000 Subject: Cpp Documentation class documentation + plugin documentation Change-Id: I52e9eee45b96c42500108646880f500df9dae55d Reviewed-by: Aaron McCarthy --- .../declarativeplaces/qdeclarativeplace.cpp | 15 ++ src/location/places/qplaceattribute.cpp | 6 +- src/location/places/qplacecategory.cpp | 32 +-- src/location/places/qplacecontactdetail.cpp | 32 ++- src/location/places/qplacecontent.cpp | 88 +++++++- src/location/places/qplacecontent.h | 2 +- src/location/places/qplacecontentreply.cpp | 3 +- src/location/places/qplacecontentrequest.cpp | 10 +- src/location/places/qplacedetailsreply.cpp | 14 +- src/location/places/qplaceeditorial.cpp | 37 ++-- src/location/places/qplaceeditorial.h | 4 + src/location/places/qplaceicon.cpp | 100 ++++++++- src/location/places/qplaceidreply.cpp | 28 ++- src/location/places/qplaceimage.cpp | 39 ++-- src/location/places/qplaceimage.h | 4 + src/location/places/qplacemanager.cpp | 242 ++++++++++++++------- src/location/places/qplacemanager.h | 6 +- src/location/places/qplacemanagerengine.cpp | 222 +++++++++++++++---- src/location/places/qplacemanagerengine.h | 1 - src/location/places/qplacerating.cpp | 35 ++- src/location/places/qplacereply.cpp | 55 +++-- src/location/places/qplacereply.h | 1 - src/location/places/qplacereview.cpp | 64 +++--- src/location/places/qplacereview.h | 5 +- src/location/places/qplacesearchreply.cpp | 8 +- src/location/places/qplacesearchrequest.cpp | 26 ++- src/location/places/qplacesearchresult.cpp | 65 ++++-- src/location/places/qplacesupplier.cpp | 58 +++-- src/location/places/qplacetextpredictionreply.cpp | 5 + src/location/places/qplaceuser.cpp | 33 +-- src/location/qgeoaddress.cpp | 4 +- src/location/qgeoboundingarea.cpp | 8 +- src/location/qgeolocation.cpp | 38 ++-- src/location/qplace.cpp | 124 +++++++++-- src/location/qtlocation.cpp | 13 +- 35 files changed, 1063 insertions(+), 364 deletions(-) (limited to 'src') diff --git a/src/imports/location/declarativeplaces/qdeclarativeplace.cpp b/src/imports/location/declarativeplaces/qdeclarativeplace.cpp index e5578903..cd6e728e 100644 --- a/src/imports/location/declarativeplaces/qdeclarativeplace.cpp +++ b/src/imports/location/declarativeplaces/qdeclarativeplace.cpp @@ -121,6 +121,21 @@ QT_USE_NAMESPACE create a new place. On success the \l placeId property will be updated with the id 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 e.g. + 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. + The typical approach is to either clear the id, categories and icon + or alternatively assign them with appropriate values of the new manager. The plugin + property naturally be needs to be assigned to the new plugin and the visibility scope + may need to be adjusted. + + \snippet snippets/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 diff --git a/src/location/places/qplaceattribute.cpp b/src/location/places/qplaceattribute.cpp index 6851371a..542edf2f 100644 --- a/src/location/places/qplaceattribute.cpp +++ b/src/location/places/qplaceattribute.cpp @@ -69,6 +69,7 @@ bool QPlaceAttributePrivate::operator== (const QPlaceAttributePrivate &other) co \class QPlaceAttribute \inmodule QtLocation \ingroup QtLocation-places + \ingroup QtLocation-places-data \since QtLocation 5.0 \brief The QPlaceAttribute class represents generic attribute information about a place. @@ -85,6 +86,7 @@ bool QPlaceAttributePrivate::operator== (const QPlaceAttributePrivate &other) co \o QPlaceAttribute::Payment \endlist + The above types are used to access and modify attributes in QPlace via: \list \o QPlace::extendedAttribute() @@ -98,13 +100,13 @@ bool QPlaceAttributePrivate::operator== (const QPlaceAttributePrivate &other) co */ /*! - \variable QPlaceAttrubute::OpeningHours + \variable QPlaceAttribute::OpeningHours The constant to specify an opening hours attribute. */ Q_DEFINE_LATIN1_CONSTANT(QPlaceAttribute::OpeningHours, "openingHours"); /*! - \variable QPlaceAttrubute::Payment + \variable QPlaceAttribute::Payment The constant to specify an attribute that defines the methods of payment. */ Q_DEFINE_LATIN1_CONSTANT(QPlaceAttribute::Payment, "payment"); diff --git a/src/location/places/qplacecategory.cpp b/src/location/places/qplacecategory.cpp index 2108076b..55caeb92 100644 --- a/src/location/places/qplacecategory.cpp +++ b/src/location/places/qplacecategory.cpp @@ -71,12 +71,13 @@ QPlaceCategoryPrivate &QPlaceCategoryPrivate::operator=(const QPlaceCategoryPriv \class QPlaceCategory \inmodule QtLocation \ingroup QtLocation-places + \ingroup QtLocation-places-data \since QtLocation 5.0 \brief The QPlaceCategory class represents a category that a \l QPlace can be associated with. Categories are used to search for places based on the categories they are associated with. The - list of available categories can be obtained from \l QPlaceManager. The + list/tree of available categories can be obtained from \l QPlaceManager. The \l QPlaceSearchRequest::setCategories() function can be used to limit the search results to places with the specified categories. @@ -87,11 +88,11 @@ QPlaceCategoryPrivate &QPlaceCategoryPrivate::operator=(const QPlaceCategoryPriv /*! \fn bool QPlaceCategory::operator!=(const QPlaceCategory &other) const - Returns true if \a other is not equal to this place category; otherwise returns false. + Returns true if \a other is not equal to this category; otherwise returns false. */ /*! - Constructs a place category. + Constructs a category. */ QPlaceCategory::QPlaceCategory() : d(new QPlaceCategoryPrivate) @@ -99,7 +100,7 @@ QPlaceCategory::QPlaceCategory() } /*! - Constructs a place category which is a copy of \a other. + Constructs a category which is a copy of \a other. */ QPlaceCategory::QPlaceCategory(const QPlaceCategory &other) :d(other.d) @@ -107,14 +108,14 @@ QPlaceCategory::QPlaceCategory(const QPlaceCategory &other) } /*! - Destroys the place category. + Destroys the category. */ QPlaceCategory::~QPlaceCategory() { } /*! - Assigns \a other to this place category and returns a reference to this place category. + Assigns \a other to this category and returns a reference to this category. */ QPlaceCategory &QPlaceCategory::operator =(const QPlaceCategory &other) { @@ -123,7 +124,7 @@ QPlaceCategory &QPlaceCategory::operator =(const QPlaceCategory &other) } /*! - Returns true if \a other is equal to this place category; otherwise returns false. + Returns true if \a other is equal to this category; otherwise returns false. */ bool QPlaceCategory::operator==(const QPlaceCategory &other) const { @@ -134,8 +135,9 @@ bool QPlaceCategory::operator==(const QPlaceCategory &other) const } /*! - Returns category id. The category id is a string which uniquely identifies this category - within a particular \l QGeoServiceProvider. + Returns the id of the category. The category id is a string which uniquely identifies this category + within a particular \l QPlaceManager. The id is only meaningful to the QPlaceManager + that generated it and is not transferrable between managers. */ QString QPlaceCategory::categoryId() const { @@ -143,7 +145,7 @@ QString QPlaceCategory::categoryId() const } /*! - Sets category id to \a id. + Sets the \a id of the category. */ void QPlaceCategory::setCategoryId(const QString &id) { @@ -151,7 +153,7 @@ void QPlaceCategory::setCategoryId(const QString &id) } /*! - Returns name of category. + Returns the name of category. */ QString QPlaceCategory::name() const { @@ -159,7 +161,7 @@ QString QPlaceCategory::name() const } /*! - Sets place category name to \a name. + Sets the \a name of the category. */ void QPlaceCategory::setName(const QString &name) { @@ -167,7 +169,7 @@ void QPlaceCategory::setName(const QString &name) } /*! - Sets the visibility of the category to \a visibility. + Sets the \a visibility of the category. */ void QPlaceCategory::setVisibility(QtLocation::Visibility visibility) { @@ -183,7 +185,7 @@ QtLocation::Visibility QPlaceCategory::visibility() const } /*! - Returns the icon associated with the place category. + Returns the icon associated with the category. */ QPlaceIcon QPlaceCategory::icon() const { @@ -191,7 +193,7 @@ QPlaceIcon QPlaceCategory::icon() const } /*! - Sets the category icon to \a icon. + Sets the \a icon of the category. */ void QPlaceCategory::setIcon(const QPlaceIcon &icon) { diff --git a/src/location/places/qplacecontactdetail.cpp b/src/location/places/qplacecontactdetail.cpp index a29529b5..b6d04d3f 100644 --- a/src/location/places/qplacecontactdetail.cpp +++ b/src/location/places/qplacecontactdetail.cpp @@ -59,11 +59,35 @@ bool QPlaceContactDetailPrivate::operator== (const QPlaceContactDetailPrivate &o /*! \class QPlaceContactDetail -\brief The QPlaceContactDetail class represents a contact detail such as a phone number or url. +\brief The QPlaceContactDetail class represents a contact detail such as a phone number or website url. \inmodule QtLocation \ingroup QtLocation-places - +\ingroup QtLocation-places-data + +The detail consists of a label and value. The label is a localized string that can be presented +to the end user that describes that detail value which is the actual phone number, email address etc. + +\section2 Contact Types + +The QPlaceContactDetail class defines some constant strings which characterize standard \e {contact types}. +\list + \o QPlaceContactDetail::Phone + \o QPlaceContactDetail::Email + \o QPlaceContactDetail::Website + \o QPlaceContactDetail::Fax +\endlist + +These types are used to access and modify contact details in QPlace via: +\list + \o QPlace::contactDetails() + \o QPlace::setContactDetails() + \o QPlace::appendContactDetail() + \o QPlace::contactTypes() +\endlist + +The \e {contact type} is intended to be a string type so that providers are able to introduce new contact +types if necessary. */ /*! @@ -74,7 +98,7 @@ Q_DEFINE_LATIN1_CONSTANT(QPlaceContactDetail::Phone, "Phone"); /*! \variable QPlaceContactDetail::Email - The constant to specify email contact contact details. + The constant to specify email contact details. */ Q_DEFINE_LATIN1_CONSTANT(QPlaceContactDetail::Email, "Email"); @@ -91,7 +115,7 @@ Q_DEFINE_LATIN1_CONSTANT(QPlaceContactDetail::Website, "Website"); Q_DEFINE_LATIN1_CONSTANT(QPlaceContactDetail::Fax, "Fax"); /*! - Constructs an contact detail. + Constructs a contact detail. */ QPlaceContactDetail::QPlaceContactDetail() : d_ptr(new QPlaceContactDetailPrivate) diff --git a/src/location/places/qplacecontent.cpp b/src/location/places/qplacecontent.cpp index 66bbda74..f8c3460e 100644 --- a/src/location/places/qplacecontent.cpp +++ b/src/location/places/qplacecontent.cpp @@ -70,14 +70,77 @@ bool QPlaceContentPrivate::compare(const QPlaceContentPrivate *other) const && attribution == other->attribution; } -/* Constructs an empty content object */ +/*! + \class QPlaceContent + \inmodule QtLocation + \ingroup QtLocation-places + \ingroup QtLocation-places-data + \since QtLocation 5.0 + + \brief The QPlaceContent class serves as the base class for rich content types. + + Rich content such as \l {QPlaceImage}{images}, \l {QPlaceReview}{reviews} + and \l {QPlaceEditorial}{editorials} inherit + from the QPlaceContent class which contains common properties such as + an attribution string and content contributor, which may take the form of a + \l {QPlaceUser}{user} and/or \l {QPlaceSupplier}{supplier}. It is possible that + a user from a supplier is contributing content, hence both fields could + be filled in simultaneously. + + \bold {Note:} Some providers may \e {require} that the attribution string be displayed + to the user whenever a piece of content is viewed. + + Conversion between QPlaceContent and it's subclasses can be easily performed without + casting. Due to the way it has been implemented, object slicing is not an issue, + the following code is valid: + \snippet snippets/places/requesthandler.h Content conversion + + The rich content of a place is typically made available as paginated items. The ability + to convert between QPlaceContent and it's subclasses means that code which handles + the mechanics of paging can be easily shared for each of the sub types. + + At present the QPlaceContent class is not extensible by 3rd parties. + + Note: The Places API considers content objects to be 'retrieve-only' objects. + Submission of content to a provider is not a supported use case. + \sa QPlaceImage, QPlaceReview, QPlaceEditorial +*/ + +/*! + \typedef QPlaceContent::Collection + Synonym for QMap. The key of the map is an \c int representing the + index of the content. The value is the content object itself. + + The \c {Collection} is intended to be a container where content items, that have been retrieved + as pages, can be stored. This enables a developer to skip pages, e.g. indexes 0-9 may be + stored in the collection, if the user skips to indexes 80-99, these can be stored in the + collection as well. +*/ + +/*! + \enum QPlaceContent::Type + Defines the type of content. + \value NoType + The content object is default constructed, any other content type may be assigned + to this content object. + \value ImageType + The content object is an image. + \value ReviewType + The content object is a review. + \value EditorialType + The content object is an editorial +*/ + +/*! + Constructs an default content object which has no type. +*/ QPlaceContent::QPlaceContent() :d_ptr(0) { } /*! - Constructs a new copy of \a other + Constructs a new copy of \a other. */ QPlaceContent::QPlaceContent(const QPlaceContent &other) :d_ptr(other.d_ptr) @@ -85,7 +148,8 @@ QPlaceContent::QPlaceContent(const QPlaceContent &other) } /*! - Assigns the \a other content object to this + Assigns the \a other content object to this and returns a reference + to this content object. */ QPlaceContent &QPlaceContent::operator=(const QPlaceContent &other) { @@ -94,7 +158,7 @@ QPlaceContent &QPlaceContent::operator=(const QPlaceContent &other) } /*! - Destroys the content object + Destroys the content object. */ QPlaceContent::~QPlaceContent() { @@ -111,7 +175,7 @@ QPlaceContent::Type QPlaceContent::type() const } /*! - Returns true if the content object is equivalent to \a other, + Returns true if this content object is equivalent to \a other, otherwise returns false. */ bool QPlaceContent::operator==(const QPlaceContent &other) const @@ -126,13 +190,17 @@ bool QPlaceContent::operator==(const QPlaceContent &other) const return d_ptr->compare(other.d_ptr); } +/*! + Returns true if this content object is not equivalent to \a other, + otherwise returns false. +*/ bool QPlaceContent::operator!=(const QPlaceContent &other) const { return !(*this == other); } /*! - Returns the supplier of the content. + Returns the supplier who contributed this content. */ QPlaceSupplier QPlaceContent::supplier() const { @@ -142,7 +210,7 @@ QPlaceSupplier QPlaceContent::supplier() const } /*! - Sets the supplier of the content to \a supplier. + Sets the \a supplier of the content. */ void QPlaceContent::setSupplier(const QPlaceSupplier &supplier) { @@ -161,7 +229,7 @@ QPlaceUser QPlaceContent::user() const } /*! - Sets the user who contributed this content. + Sets the \a user who contributed this content. */ void QPlaceContent::setUser(const QPlaceUser &user) { @@ -172,7 +240,7 @@ void QPlaceContent::setUser(const QPlaceUser &user) /*! Returns a rich text attribution string. - Some providers may require that the attribution + \bold {Note}: Some providers may require that the attribution of a particular content item always be displayed when the content item is shown. */ @@ -183,7 +251,7 @@ QString QPlaceContent::attribution() const } /*! - Sets a rich text attribution string for this content item. + Sets a rich text \a attribution string for this content item. */ void QPlaceContent::setAttribution(const QString &attribution) { diff --git a/src/location/places/qplacecontent.h b/src/location/places/qplacecontent.h index c5636219..01a1decf 100644 --- a/src/location/places/qplacecontent.h +++ b/src/location/places/qplacecontent.h @@ -73,7 +73,7 @@ public: NoType = 0, ImageType, ReviewType, - EditorialType, + EditorialType }; QPlaceContent(); diff --git a/src/location/places/qplacecontentreply.cpp b/src/location/places/qplacecontentreply.cpp index 1deb6137..8fa36bf2 100644 --- a/src/location/places/qplacecontentreply.cpp +++ b/src/location/places/qplacecontentreply.cpp @@ -63,13 +63,14 @@ QT_USE_NAMESPACE \class QPlaceContentReply \inmodule QtLocation \ingroup QtLocation-places + \ingroup QtLocation-places-replies \since QtLocation 5.0 \brief The QPlaceContentReply class manages a content retrieval operation started by an instance of QPlaceManager. See \l {Fetching Rich Content} for an example on how to use a content reply. - \sa QPlaceContentRequest + \sa QPlaceContentRequest, QPlaceManager */ /*! diff --git a/src/location/places/qplacecontentrequest.cpp b/src/location/places/qplacecontentrequest.cpp index 12f77dbe..4f5986be 100644 --- a/src/location/places/qplacecontentrequest.cpp +++ b/src/location/places/qplacecontentrequest.cpp @@ -46,8 +46,8 @@ QT_BEGIN_NAMESPACE QPlaceContentRequestPrivate::QPlaceContentRequestPrivate() -: QSharedData(), contentType(QPlaceContent::NoType), - limit(-1), offset(0) + : QSharedData(), contentType(QPlaceContent::NoType), + limit(-1), offset(0) { } @@ -79,6 +79,7 @@ void QPlaceContentRequestPrivate::clear() \class QPlaceContentRequest \inmodule QtLocation \ingroup QtLocation-places + \ingroup QtLocation-places-requests \since QtLocation 5.0 \brief The QPlaceContentRequest class represents the parameters of a content request. @@ -172,6 +173,7 @@ void QPlaceContentRequest::setContentType(QPlaceContent::Type type) A negative value for limit means that it is undefined. It is left up to the backend provider to choose an appropriate number of items to return. + The default limit is -1. */ int QPlaceContentRequest::limit() const { @@ -190,7 +192,9 @@ void QPlaceContentRequest::setLimit(int limit) } /*! - Returns the index of the first item that is to be retrieved. + Returns the offset index of the first item that is to be retrieved. + + The default offset is 0. */ int QPlaceContentRequest::offset() const { diff --git a/src/location/places/qplacedetailsreply.cpp b/src/location/places/qplacedetailsreply.cpp index 32dfa11d..a18f9bb2 100644 --- a/src/location/places/qplacedetailsreply.cpp +++ b/src/location/places/qplacedetailsreply.cpp @@ -59,14 +59,18 @@ QT_USE_NAMESPACE \class QPlaceDetailsReply \inmodule QtLocation \ingroup QtLocation-places + \ingroup QtLocation-places-replies \since QtLocation 5.0 - \brief The QPlaceDetailsReply class manages a place datails operation started by an + \brief The QPlaceDetailsReply class manages a place details fetch operation started by an instance of QPlaceManager. + + See \l {Fetching Place Details} for an example on how to use a details reply. + \sa QPlaceManager */ /*! - Constructs a search reply with a given \a parent. + Constructs a details reply with a given \a parent. */ QPlaceDetailsReply::QPlaceDetailsReply(QObject *parent) : QPlaceReply(new QPlaceDetailsReplyPrivate, parent) @@ -74,7 +78,7 @@ QPlaceDetailsReply::QPlaceDetailsReply(QObject *parent) } /*! - Destroys the search reply. + Destroys the details reply. */ QPlaceDetailsReply::~QPlaceDetailsReply() { @@ -89,7 +93,7 @@ QPlaceReply::Type QPlaceDetailsReply::type() const } /*! - Returns a place result + Returns the place that was fetched. */ QPlace QPlaceDetailsReply::place() const { @@ -98,7 +102,7 @@ QPlace QPlaceDetailsReply::place() const } /*! - Sets the \a place + Sets the fetched \a place of the reply. */ void QPlaceDetailsReply::setPlace(const QPlace &place) { diff --git a/src/location/places/qplaceeditorial.cpp b/src/location/places/qplaceeditorial.cpp index 081afdcf..a7129c8f 100644 --- a/src/location/places/qplaceeditorial.cpp +++ b/src/location/places/qplaceeditorial.cpp @@ -72,19 +72,22 @@ bool QPlaceEditorialPrivate::compare(const QPlaceContentPrivate *other) const \class QPlaceEditorial \inmodule QtLocation \ingroup QtLocation-places + \ingroup QtLocation-places-data \since QtLocation 5.0 - \brief The QPlaceEditorial class represents a address object. + \brief The QPlaceEditorial class represents a publisher's article describing a place. - Each QPlaceEditorial represents a description object with a number of attributes - such as title, value etc. Each QPlaceEditorial is associated with place. + Each QPlaceEditorial has a title, text and language; in addition to those properties + inherited from QPlaceContent. - Editorial objects are read-only, e.g. user of API might get editorial objects associated to - specific place but can not edit its content. User might also create new editorial. + Note: The Places API only supports editorials as 'retrieve-only' objects. Submitting editorials + to a provider is not a supported use case. + + \sa QPlaceContent */ /*! - Constructs an new place editorial object. + Constructs an new editorial object. */ QPlaceEditorial::QPlaceEditorial() : QPlaceContent(new QPlaceEditorialPrivate) @@ -98,6 +101,10 @@ QPlaceEditorial::~QPlaceEditorial() { } +/*! + \fn QPlaceEditorial::QPlaceEditorial(const QPlaceContent &other) + Constructs a copy of \a other if possible, otherwise constructs a default editorial object. +*/ Q_IMPLEMENT_CONTENT_COPY_CTOR(QPlaceEditorial) Q_IMPLEMENT_CONTENT_D_FUNC(QPlaceEditorial) @@ -124,7 +131,7 @@ void QPlaceEditorial::setText(const QString &text) } /*! - Returns content title. + Returns the title of the editorial. */ QString QPlaceEditorial::title() const { @@ -133,16 +140,17 @@ QString QPlaceEditorial::title() const } /*! - Sets content title. + Sets the \a title of the editorial. */ -void QPlaceEditorial::setTitle(const QString &data) +void QPlaceEditorial::setTitle(const QString &title) { Q_D(QPlaceEditorial); - d->contentTitle = data; + d->contentTitle = title; } /*! - Returns language. + Returns the language of the editorial. Typically this would be a language code + in the 2 letter ISO 639-1 format. */ QString QPlaceEditorial::language() const { @@ -151,10 +159,11 @@ QString QPlaceEditorial::language() const } /*! - Sets language. + Sets the \a language of the editorial. Typically this would be a language code + in the 2 letter ISO 639-1 format. */ -void QPlaceEditorial::setLanguage(const QString &data) +void QPlaceEditorial::setLanguage(const QString &language) { Q_D(QPlaceEditorial); - d->language = data; + d->language = language; } diff --git a/src/location/places/qplaceeditorial.h b/src/location/places/qplaceeditorial.h index 9a808737..d3882778 100644 --- a/src/location/places/qplaceeditorial.h +++ b/src/location/places/qplaceeditorial.h @@ -56,7 +56,11 @@ class Q_LOCATION_EXPORT QPlaceEditorial : public QPlaceContent { public: QPlaceEditorial(); +#ifdef Q_QDOC + QPlaceEditorial::QPlaceEditorial(const QPlaceContent &other) +#else Q_DECLARE_CONTENT_COPY_CTOR(QPlaceEditorial) +#endif virtual ~QPlaceEditorial(); diff --git a/src/location/places/qplaceicon.cpp b/src/location/places/qplaceicon.cpp index f09bfa98..fcd81d06 100644 --- a/src/location/places/qplaceicon.cpp +++ b/src/location/places/qplaceicon.cpp @@ -79,6 +79,72 @@ bool QPlaceIconPrivate::operator == (const QPlaceIconPrivate &other) const && fullUrl == other.fullUrl; } +/*! + \class QPlaceIcon + \inmodule QtLocation + \ingroup QtLocation-places + \ingroup QtLocation-places-data + \since QtLocation 5.0 + + \brief The QPlaceIcon class represents an icon. + + \section2 Usage + The typical usage of an icon is to use the url() function to specify + a preferred size and set of flags. + + \snippet snippets/places/requesthandler.h icon + + Note that the parameters are \e {preferred} only. If a manager backend + does not support one or more of the specified parameters, the url of the icon that most + closely matches those parameters is returned. + + \target Icon internals + \section2 Internals + Icons are tightly coupled to a particular manager and always have a pointer + to that manager. The icon does not have ownership of this pointer. + + The internals of the icon work by specifying either a \e {base} or a + \e {full} url. + + A \e {base} url may be an incomplete url of the form \e {http://example.com/icon}. + When a set of icon parameters is provided to the url() function, the manager + constructs a complete icon url such as \e {http://example.com/icon_32x32_selected.png}. + + A \e {full} url is a complete url which may look something like \e {http://example.com/myicon.png} + When a full url is specified the url() will always return the complete url. + + Only one \e {base} or \e {full} url may be specified for a single icon, setting one implies clearing the other. + Whether full and or base urls are supported depends on the manager backend. + + Any valid URL may be returned by the backend, but it would typically + be either a http://, file://, or data:// URL. +*/ + +/*! + \enum QPlaceIcon::IconFlag + + This enum is used to specify different icon states and types. + + The state flags are: + \value Normal An icon with no state modifications. This flag indicates that the user is not + interacting with the icon, but the functionality represented by the icon is + available. + \value Disabled An icon with a disabled appearance. This flag indicates that the functionality + represented by the icon is not available. + \value Active An icon with an active appearance. This flag indicates that the functionality + represented by the icon is available and the user is interacting with the icon, + for example, touching it. + \value Selected An icon with a selected appearance. This flag indicates that the item represented + by the icon is selected. + + + The type flags are: + \value Map An icon intended for display on a map + \value List An icon intended for display in a list. + + You can use at most one state and one type flag at a time. +*/ + /*! Constructs an icon. */ @@ -112,19 +178,25 @@ QPlaceIcon &QPlaceIcon::operator=(const QPlaceIcon &other) } /*! - Returns true if this icon is equal to \a other. Otherwise returns false. + Returns true if this icon is equal to \a other, otherwise returns false. */ bool QPlaceIcon::operator==(const QPlaceIcon &other) const { return *d == *(other.d); } +/*! + \fn QPlaceIcon::operator!=(const QPlaceIcon &other) const + + Returns true if \a other is not equal to this icon, otherwise returns false. +*/ + /*! Returns an icon url according to the given \a size and \a flags. If a base url has been set by setBaseUrl(), the url to the image that best fits the specified parameters is returned. - If a full url has been set by setUrl(), the full url is returned. + If a full url has been set by setFullUrl(), the full url is returned. If no manager has been assigned to the icon a default constructed QUrl is returned. @@ -142,11 +214,11 @@ QUrl QPlaceIcon::url(const QSize &size, QPlaceIcon::IconFlags flags) const } /*! - Sets a full URL of the resource that represents the image of this + Sets a full \a url of the resource that represents the image of this icon. Because a full URL is being set, specifying different sizes and flags into the url() function will have no effect. - When calling the setUrl() function, the base url is implictly + When calling the this function, the baseUrl() is implictly cleared. */ void QPlaceIcon::setFullUrl(const QUrl &url) @@ -155,16 +227,20 @@ void QPlaceIcon::setFullUrl(const QUrl &url) d->baseUrl.clear(); } +/*! + Returns a the full url that the icon is based off. + \sa baseUrl() +*/ QUrl QPlaceIcon::fullUrl() const { return d->fullUrl; } /*! - Returns a base url that the comlete icon url is based off. - E.g. the base url may be http://example.com/icon - When calling the url() function the base url may be used as a hint - to construct http://example.com/icon_32x32_selected.png + Returns a base url that the complete icon url is based off. + + E.g. the base url may be http://example.com/icon. + When calling the url() function the, base url may be used to construct: http://example.com/icon_32x32_selected.png */ QUrl QPlaceIcon::baseUrl() const { @@ -172,10 +248,9 @@ QUrl QPlaceIcon::baseUrl() const } /*! - Sets a base url that the complete icon url returned by url() is based off. + Sets a base \a url that the complete icon url returned by url() is based off. - When calling setBaseUrl() function, the full url set by - setUrl() is implicitly cleared. + When calling this function, the fullUrl() is implicitly cleared. */ void QPlaceIcon::setBaseUrl(const QUrl &url) { @@ -192,7 +267,8 @@ QPlaceManager *QPlaceIcon::manager() const } /*! - Sets the \a manager that this icon is associated with. + Sets the \a manager that this icon is associated with. The icon does not take + ownership of the pointer. */ void QPlaceIcon::setManager(QPlaceManager *manager) { diff --git a/src/location/places/qplaceidreply.cpp b/src/location/places/qplaceidreply.cpp index a80f4438..67150a98 100644 --- a/src/location/places/qplaceidreply.cpp +++ b/src/location/places/qplaceidreply.cpp @@ -60,10 +60,27 @@ QT_USE_NAMESPACE \class QPlaceIdReply \inmodule QtLocation \ingroup QtLocation-places + \ingroup QtLocation-places-replies \since QtLocation 5.0 \brief The QPlaceIdReply class manages operations which return an id such as saving and removal operations of places and categories. + + The QPlaceIdReply can be considered a multipurpose reply in that it can + be used to save places, save categories, remove places and remove categories. + In each case it returns an id of the place or category that was added/modified/removed. + + See \l {Saving a place cpp}{Saving a place} for an example of how to use an id reply. + \sa QPlaceManager +*/ + +/*! + \enum QPlaceIdReply::OperationType + Defines the type of operation that was used to generate this reply. + \value SavePlace The reply was created for a save place operation + \value RemovePlace The reply was created for a remove place operation. + \value SaveCategory The reply was created for a save category operation + \value RemoveCategory The reply was created for a remove category operation. */ /*! @@ -84,8 +101,7 @@ QPlaceIdReply::~QPlaceIdReply() } /*! - Returns the type of reply. This is an indication of the content - of the reply. + Returns the type of reply. */ QPlaceReply::Type QPlaceIdReply::type() const { @@ -93,7 +109,9 @@ QPlaceReply::Type QPlaceIdReply::type() const } /*! - Returns the operation type of the reply. + Returns the operation type of the reply. i.e whether this + id reply was for a save place operation, + remove category operation etc. */ QPlaceIdReply::OperationType QPlaceIdReply::operationType() const { @@ -102,9 +120,9 @@ QPlaceIdReply::OperationType QPlaceIdReply::operationType() const } /*! - Returns the relevant id for the opeation. Eg for a save place operation, + Returns the relevant id for the operation. Eg for a save place operation, the id is that of the saved place. For a category removal operation, - it is the category id. + it is the id of the category that was removed. */ QString QPlaceIdReply::id() const { diff --git a/src/location/places/qplaceimage.cpp b/src/location/places/qplaceimage.cpp index 91dda7eb..3e109088 100644 --- a/src/location/places/qplaceimage.cpp +++ b/src/location/places/qplaceimage.cpp @@ -71,18 +71,22 @@ bool QPlaceImagePrivate::compare(const QPlaceContentPrivate *other) const \class QPlaceImage \inmodule QtLocation \ingroup QtLocation-places + \ingroup QtLocation-places-data \since QtLocation 5.0 - \brief The QPlaceImage class represents an image. + \brief The QPlaceImage class represents a reference to an image. - Each QPlaceImage represents an image with a number of attributes - such as type, thumbnail, media provider etc. + Each QPlaceImage represents a set of metadata about an image such as it's + url, id and MIME type. These are properties in addition to those provided + by QPlaceContent. - QPlaceImage is an in memory representation of an image. + Note: The Places API only supports images as 'retrieve-only' objects. Submitting + images to a provider is not a supported use case. + \sa QPlaceContent */ /*! - Constructs an new image object. + Constructs an new QPlaceImage. */ QPlaceImage::QPlaceImage() : QPlaceContent(new QPlaceImagePrivate) @@ -96,12 +100,17 @@ QPlaceImage::~QPlaceImage() { } +/*! + \fn QPlaceImage::QPlaceImage(const QPlaceContent &other) + Constructs a copy of \a other if possible, otherwise constructs a default image. +*/ + Q_IMPLEMENT_CONTENT_COPY_CTOR(QPlaceImage) Q_IMPLEMENT_CONTENT_D_FUNC(QPlaceImage) /*! - Returns the image url. + Returns the image's url. */ QUrl QPlaceImage::url() const { @@ -110,7 +119,7 @@ QUrl QPlaceImage::url() const } /*! - Sets image url. + Sets the image's \a url. */ void QPlaceImage::setUrl(const QUrl &url) { @@ -119,7 +128,7 @@ void QPlaceImage::setUrl(const QUrl &url) } /*! - Returns image id. + Returns the image's id. */ QString QPlaceImage::imageId() const { @@ -128,16 +137,16 @@ QString QPlaceImage::imageId() const } /*! - Sets image id. + Sets image's \a id. */ -void QPlaceImage::setImageId(const QString &data) +void QPlaceImage::setImageId(const QString &id) { Q_D(QPlaceImage); - d->id = data; + d->id = id; } /*! - Returns image mime type. + Returns the image's MIME type. */ QString QPlaceImage::mimeType() const { @@ -146,10 +155,10 @@ QString QPlaceImage::mimeType() const } /*! - Sets image mime type. + Sets image's MIME \a type. */ -void QPlaceImage::setMimeType(const QString &data) +void QPlaceImage::setMimeType(const QString &type) { Q_D(QPlaceImage); - d->mimeType = data; + d->mimeType = type; } diff --git a/src/location/places/qplaceimage.h b/src/location/places/qplaceimage.h index f2a41509..9f9091fc 100644 --- a/src/location/places/qplaceimage.h +++ b/src/location/places/qplaceimage.h @@ -60,7 +60,11 @@ class Q_LOCATION_EXPORT QPlaceImage : public QPlaceContent { public: QPlaceImage(); +#ifdef Q_QDOC + QPlaceImage(const QPlaceContent &other); +#else Q_DECLARE_CONTENT_COPY_CTOR(QPlaceImage) +#endif virtual ~QPlaceImage(); diff --git a/src/location/places/qplacemanager.cpp b/src/location/places/qplacemanager.cpp index 1d6d690f..bc3ed271 100644 --- a/src/location/places/qplacemanager.cpp +++ b/src/location/places/qplacemanager.cpp @@ -50,28 +50,105 @@ QT_BEGIN_NAMESPACE \class QPlaceManager \inmodule QtLocation \ingroup QtLocation-places + \ingroup QtLocation-places-manager \since QtLocation 5.0 - \brief The QPlaceManager class is responsible for the discovery and management of places. -*/ + \brief The QPlaceManager class provides the interface which allows clients to access + places stored in a particular backend. + + The following table gives an overview of the functionality provided by the QPlaceManager + \table + \header + \o Functionality + \o Description + \row + \o Searching for places + \o Using set of parameters such as a seach term and search area, relevant places + can be returned to the user. + \row + \o Categories + \o Places can be classified as belonging to different categories. The + manager supports access to these categories. + \row + \o Text predictions + \o Given a partially complete search term, a list of potential complete + search terms can be given. + \row + \o Recommendations + \o Given an existing place, a set of similar recommended places can + be suggested to the user. + \row + \o Rich Content + \o Rich content such as images, reviews etc can be retrieved in a paged + fashion. + \row + \o Place/Category management + \o Places and categories may be saved and removed. It is possible + for notifications to be given when this happens. + \row + \o Localization + \o Different locales may be specified to return place + data in different languages. + \endtable + + \section1 Obtaining a QPlaceManager instance + Creation of a QPlaceManager is facilitated by the QGeoServiceProvider. + See \l {Initializing a manager} for an example on how to create a manager. + + + \section1 Asynchronous interface. + The QPlaceManager class provides an abstraction of the datastore which contains place information. + The functions provided by the QPlaceManager and primarily asynchronous and follow + a request-reply model. Typically a request is given to the manager, consisting + of a various set of parameters and a reply object is created. The reply object + has a signal to notify when the request is done, and once completed, the reply + contains the results of the request, along with any errors that occurred, if any. + + An asynchonous request is generally handled as follows: + \snippet snippets/places/requesthandler.h Simple search + \dots + \dots + \snippet snippets/places/requesthandler.h Simple search handler + + See \l {Common Operations} for a list of examples demonstrating how the QPlaceManger + is used. + + \section1 Category Initialization + Sometime during startup of an application, the initializeCategories() function should + be called to setup the categories. Initializing the categories enables the usage of the + following functions: + + \list + \o QPlaceManager::childCategories() + \o QPlaceManager::category() + \o QPlaceManager::parentCategoryId() + \o QPlaceManager::childrenCategoryIds(); + \endlist + + If the categories need to be refreshed or reloaded, the initializeCategories() function + may be called again. -/*! - \enum QPlaceManager::ManagerFeature - Defines the possible features that the place manager can possible. - \value ImportFeature The manager supports import operations - \value ExportFeature The manager supports export operations - \value CheckInFeature The manaager supports check-in operations - \value PostRatingFeature The manager supports posting ratings for places - \value SuggestionFeature The manager supports the providing of suggestions - \value ReportPlaceFeature The manager supports reporting a place if it is incorrect/inappropriate. - \value AuthenticationFeature The manager supports authentication of a user. - \value CreatePlaceFeature The manager supports the creation of places. - \value UpdatePlaceFeature The manager supports the updating of places. - \value NotifcationsFeature The manager gives notifications for added/modified/remove places and categories. */ /*! - Constructs a new manager with the specified \a pareent and with the + \enum QPlaceManager::ManagerFeature + Defines the possible features that the place manager can have. + \value NoFeatures No features specified/supported + \value SavePlaceFeature The manager can be used to save places + \value RemovePlaceFeature The manager can be used to remove places + \value SaveCategoryFeature The manager can be used to save categories. + \value RemoveCategoryFeature The manager can be used to remove categories. + \value RecommendationsFeature The manager can be used to provide recommendations. + \value TextPredictionsFeature The manager can be used to provide text predictions + \value CorrectionsFeature The manager can be used to provide search term corrections + \value LocaleFeature The manager can be used to provide place data localized + according to locale + \value NotificationsFeature The manager has signal notifications for when + places/categories are added/modified/removed. +*/ + +/*! + Constructs a new manager with the specified \a parent and with the implementation provided by \a engine. This constructor is used internally by QGeoServiceProviderFactory. Regular @@ -109,7 +186,8 @@ QPlaceManager::QPlaceManager(QPlaceManagerEngine *engine, QObject *parent) } /*! - Destroys the manager. + Destroys the manager. This destructor is used internally by QGeoServiceProvider + and should never need to be called in application code. */ QPlaceManager::~QPlaceManager() { @@ -133,7 +211,9 @@ int QPlaceManager::managerVersion() const } /*! - Retrieves a details of place with \a place id. + Retrieves a details of place corresponding to the given \a placeId. + + See \l {Fetching Place Details} for an example of usage. */ QPlaceDetailsReply *QPlaceManager::getPlaceDetails(const QString &placeId) const { @@ -141,8 +221,10 @@ QPlaceDetailsReply *QPlaceManager::getPlaceDetails(const QString &placeId) const } /*! - Retrieves content from a given \a place according to thes parameters specified in + Retrieves content for a given \a place according to the parameters specified in \a request. + + See \l {Fetching Rich Content} for an example of usage. */ QPlaceContentReply *QPlaceManager::getContent(const QPlace &place, const QPlaceContentRequest &request) const { @@ -150,7 +232,9 @@ QPlaceContentReply *QPlaceManager::getContent(const QPlace &place, const QPlaceC } /*! - Searches for places according to a given \a request. + Searches for places according to the parameters specified in \a request. + + See \l {Discovery/Search} for an example of usage. */ QPlaceSearchReply *QPlaceManager::search(const QPlaceSearchRequest &request) const { @@ -158,7 +242,9 @@ QPlaceSearchReply *QPlaceManager::search(const QPlaceSearchRequest &request) con } /*! - Provides recommendation based on a given \a request. + Provides recommendations for places that are similar to \a place, and using the parameters as specified in \a request. + + See \l {Recommendations} for an example of usage. */ QPlaceSearchReply *QPlaceManager::recommendations(const QPlace &place, const QPlaceSearchRequest &request) const { @@ -166,7 +252,11 @@ QPlaceSearchReply *QPlaceManager::recommendations(const QPlace &place, const QPl } /*! - Requests a set of text predictions for a given \a request + Requests a set of text predictions according to the parameters specified in \a request. + The \a request can hold the incomplete search term, along with other data such + as a search area to narrow down relevant results. + + See \l {Text Predictions} for an example of usage. */ QPlaceTextPredictionReply *QPlaceManager::textPredictions(const QPlaceSearchRequest &request) const { @@ -174,7 +264,9 @@ QPlaceTextPredictionReply *QPlaceManager::textPredictions(const QPlaceSearchRequ } /*! - Saves a \a place at the given \a scope. + Saves a specified \a place. + + See \l {Saving a place cpp} for an example of usage. */ QPlaceIdReply *QPlaceManager::savePlace(const QPlace &place) { @@ -183,6 +275,8 @@ QPlaceIdReply *QPlaceManager::savePlace(const QPlace &place) /*! Removes the place corresponding to \a placeId from the manager. + + See \l {Removing a place cpp} for an example of usage. */ QPlaceIdReply *QPlaceManager::removePlace(const QString &placeId) { @@ -190,7 +284,10 @@ QPlaceIdReply *QPlaceManager::removePlace(const QString &placeId) } /*! - Saves a \a category that is a child of \a parent. + Saves a \a category that is a child of the category specified by \a parentId. + An empty \a parentId means \a category is saved as a top level category. + + See \l {Saving a category} for an example of usage. */ QPlaceIdReply *QPlaceManager::saveCategory(const QPlaceCategory &category, const QString &parentId) { @@ -198,7 +295,9 @@ QPlaceIdReply *QPlaceManager::saveCategory(const QPlaceCategory &category, const } /*! - Remove \a category from the manager. + Removes the category corresponding to \a categoryId from the manager. + + See \l {Removing a category} for an example of usage. */ QPlaceIdReply *QPlaceManager::removeCategory(const QString &categoryId) { @@ -206,7 +305,9 @@ QPlaceIdReply *QPlaceManager::removeCategory(const QString &categoryId) } /*! - Initializes the manager categories. + Initializes the categories of the manager. + + See \l {Using Categories} for an example of usage. */ QPlaceReply *QPlaceManager::initializeCategories() { @@ -223,7 +324,7 @@ QString QPlaceManager::parentCategoryId(const QString &categoryId) const /*! Returns the children category ids of the category corresponding to \a categoryId. - If \a categoryId is empty than all top level category ids are returned. + If \a categoryId is empty then all top level category ids are returned. */ QStringList QPlaceManager::childrenCategoryIds(const QString &categoryId) const { @@ -247,11 +348,10 @@ QList QPlaceManager::childCategories(const QString &parentId) co return d->childCategories(parentId); } - /*! Returns the locale of the manager. The locale is used as a hint to determine - what language place details should be returned in. + what language place data should be returned in. */ QLocale QPlaceManager::locale() const { @@ -259,7 +359,7 @@ QLocale QPlaceManager::locale() const } /*! - Sets the locale of the manager. + Sets the \a locale of the manager. */ void QPlaceManager::setLocale(const QLocale &locale) { @@ -275,94 +375,90 @@ QPlaceManager::ManagerFeatures QPlaceManager::supportedFeatures() const } /*! -\fn void QPlaceManager::finished(QPlaceReply* reply) + \fn void QPlaceManager::finished(QPlaceReply* reply) -This signal is emitted when \a reply has finished processing. + This signal is emitted when \a reply has finished processing. -If reply->error() equals QPlaceReply::NoError then the processing -finished successfully. + If reply->error() equals QPlaceReply::NoError then the processing + finished successfully. -This signal and QPlaceReply::finished() will be emitted at the same time. + This signal and QPlaceReply::finished() will be emitted at the same time. -\note Do no delete the \a reply object in the slot connected to this signal. -Use deleteLater() instead. + \note Do no delete the \a reply object in the slot connected to this signal. + Use deleteLater() instead. */ /*! -\fn void QPlaceManager::error(QPlaceReply* reply, QPlaceReply::Error error, const QString &errorString) + \fn void QPlaceManager::error(QPlaceReply* reply, QPlaceReply::Error error, const QString &errorString) -This signal is emitted when an error has been detected in the processing of -\a reply. The QPlaceManager::finished() signal will probably follow. + This signal is emitted when an error has been detected in the processing of + \a reply. The QPlaceManager::finished() signal will probably follow. -The error will be described by the error code \a error. If \a errorString is -not empty it will contain a textual description of the error meant for developers -and not end users. - -This signal and QPlaceReply::error() will be emitted at the same time. - -\note Do no delete the \a reply object in the slot connected to this signal. -Use deleteLater() instead. -*/ - -/*! - \fn void QPlaceManager::authenticationRequired(QAuthenticator *authenticator) + The error will be described by the error code \a error. If \a errorString is + not empty it will contain a textual description of the error meant for developers + and not end users. - This signal is emitted if authentication details are required by the manager - to peform certain operations. If the authentication was successful, the next time - the operations are performed, the same credentials are used and the - authenticationRequired signal is not emitted again. + This signal and QPlaceReply::error() will be emitted at the same time. - If authentication is unsuccessful, the manager will emit the signal again. + \note Do no delete the \a reply object in the slot connected to this signal. + Use deleteLater() instead. */ /*! - \fn void QPlaceManager::placeAdded(const QString&placeId) + \fn void QPlaceManager::placeAdded(const QString &placeId) - This signal is emitted if a place has been added to the manager's datastore. + This signal is emitted if a place has been added to the manager engine's datastore. + The particular added place is specified by \a placeId. - It is generally only emitted by managers that store places locally. + This signal is only emitted by managers that support the QPlaceManager::NotificationsFeature. */ /*! - \fn void QPlaceManager::placeUpdated(const QString&placeId) + \fn void QPlaceManager::placeUpdated(const QString &placeId) This signal is emitted if a place has been modified in the manager's datastore. + The particular modifed place is specified by \a placeId. - It is generally only emitted by managers that store places locally. + This signal is only emitted by managers that support the QPlaceManager::NotificationsFeature. */ /*! - \fn void QPlaceManager::placeRemoved(const QString&placeId) + \fn void QPlaceManager::placeRemoved(const QString &placeId) This signal is emitted if a place has been removed from the manager's datastore. + The particular place that has been removed is specified by \a placeId. - It is generally only emitted by managers that store places locally. + This signal is only emitted by managers that support the QPlaceManager::NotificationsFeature. */ /*! - \fn void QPlaceManager::categoryAdded(const QString&categoryId) + \fn void QPlaceManager::categoryAdded(const QPlaceCategory &category, const QString &parentId) - This signal is emitted if a category has been added to the manager's datastore. + This signal is emitted if a \a category has been added to the manager's datastore. + The parent of the \a category is specified by \a parentId. - It is generally only emitted by managers that store categories locally. + This signal is only emitted by managers that support the QPlaceManager::NotificationsFeature. */ /*! - \fn void QPlaceManager::categoryUpdated(const QString&categoryId) + \fn void QPlaceManager::categoryUpdated(const QPlaceCategory &category, const QString &parentId) - This signal is emitted if a category has been modified in the manager's datastore. + This signal is emitted if a \a category has been modified in the manager's datastore. + The parent of the modified category is specified by \a parentId. - It is generally only emitted by managers that store categories locally. + This signal is only emitted by managers that support the QPlaceManager::NotificationsFeature. */ /*! - \fn void QPlaceManager::categoryRemoved(const QString&categoryId) + \fn void QPlaceManager::categoryRemoved(const QString &categoryId, const QString &parentId) - This signal is emitted if a category has been removed from the manager's datastore. + This signal is emitted when the category correspoinding to \a categoryId has + been removed from the manager's datastore. The parent of the removed category + is specified by \a parentId. - It is generally only emitted by managers that store categories locally. + This signal is only emitted by managers that support the QPlaceManager::NotificationsFeature. */ QT_END_NAMESPACE diff --git a/src/location/places/qplacemanager.h b/src/location/places/qplacemanager.h index 29ef98d4..128f1b85 100644 --- a/src/location/places/qplacemanager.h +++ b/src/location/places/qplacemanager.h @@ -127,9 +127,9 @@ Q_SIGNALS: void placeUpdated(const QString &placeId); void placeRemoved(const QString &placeId); - void categoryAdded(const QPlaceCategory &category, const QString &parentCategoryId); - void categoryUpdated(const QPlaceCategory &category, const QString &parentCategoryId); - void categoryRemoved(const QString &categoryId, const QString &parentCategoryId); + void categoryAdded(const QPlaceCategory &category, const QString &parentId); + void categoryUpdated(const QPlaceCategory &category, const QString &parentId); + void categoryRemoved(const QString &categoryId, const QString &parentId); private: QPlaceManager(QPlaceManagerEngine *engine, QObject *parent = 0); diff --git a/src/location/places/qplacemanagerengine.cpp b/src/location/places/qplacemanagerengine.cpp index f30f72f2..4864857e 100644 --- a/src/location/places/qplacemanagerengine.cpp +++ b/src/location/places/qplacemanagerengine.cpp @@ -48,16 +48,19 @@ QT_USE_NAMESPACE \class QPlaceManagerEngine \inmodule QtLocation \ingroup QtLocation-impl + \ingroup QtLocation-places + \ingroup QtLocation-places-manager \since QtLocation 5.0 - \brief The QPlaceManagerEngine class provides an interface and convenience methods to - implementers of QGeoServiceProvider plugins who want to provide access to place search + \brief The QPlaceManagerEngine class provides an interface for + implementers of QGeoServiceProvider plugins who want to provide access to place functionality. - Subclasses of QPlaceManagerEngine need to provide an implementation of getPlaceDetails(), - getContent(), postRating(), getReviews(), searchForPlaces(), supportedSearchVisibilityScopes(), - recommendations(), textPredictions(), savePlace(), supportedSaveVisibilityScopes(), removePlace(), - initializeCategories() and categories(). + Application developers need not concern themselves with the QPlaceManagerEngine. + Backend implementers however will need to derive from QPlaceManagerEngine and provide + implementations for the abstract virtual functions. + + For more information on writing a backend see the \l {Places Backend} documentation. \sa QPlaceManager */ @@ -82,11 +85,13 @@ QPlaceManagerEngine::~QPlaceManagerEngine() } /*! + \internal Sets the name which this engine implementation uses to distinguish itself from the implementations provided by other plugins to \a managerName. - The combination of managerName() and managerVersion() should be unique - amongst plugin implementations. + This function does not need to be called by engine implementers, + it is implicitly called by QGeoServiceProvider to set the manager + name to be the same as the provider's. */ void QPlaceManagerEngine::setManagerName(const QString &managerName) { @@ -97,8 +102,8 @@ void QPlaceManagerEngine::setManagerName(const QString &managerName) Returns the name which this engine implementation uses to distinguish itself from the implementations provided by other plugins. - The combination of managerName() and managerVersion() should be unique - amongst plugin implementations. + The manager name is automatically set to be the same + as the QGeoServiceProviderFactory::providerName(). */ QString QPlaceManagerEngine::managerName() const { @@ -106,6 +111,7 @@ QString QPlaceManagerEngine::managerName() const } /*! + \internal Sets the version of this engine implementation to \a managerVersion. The combination of managerName() and managerVersion() should be unique @@ -119,8 +125,8 @@ void QPlaceManagerEngine::setManagerVersion(int managerVersion) /*! Returns the version of this engine implementation. - The combination of managerName() and managerVersion() should be unique - amongst plugin implementations. + The manager version is automatically set to be the same + as the QGeoServiceProviderFactory::providerVersion(). */ int QPlaceManagerEngine::managerVersion() const { @@ -135,17 +141,6 @@ QPlaceManager *QPlaceManagerEngine::manager() const return d_ptr->manager; } -/*! - \fn void QPlaceManagerEngine::authenticationRequired(QAuthenticator *authenticator) - - This signal is emitted if authentication details are required by the manager engine - to peform certain operations. If the authentication was successful, the next time - the operations are performed, the same credentials are used and the - authenticationRequired signal is not emitted again. - - If authentication is unsuccessful, the manager engine will emit the signal again. -*/ - QPlaceManagerEnginePrivate::QPlaceManagerEnginePrivate() : managerVersion(-1), manager(0) { @@ -156,53 +151,202 @@ QPlaceManagerEnginePrivate::~QPlaceManagerEnginePrivate() } /*! - \fn void QPlaceManagerEngine::placeAdded(const QString&placeId) + \fn QPlaceDetailsReply *QPlaceManagerEngine::getPlaceDetails(const QString &placeId) - This signal is emitted if a place has been added to the manager engine's datastore. + Retrieves a details of place corresponding to the given \a placeId. +*/ + +/*! \fn QPlaceContentReply *QPlaceManagerEngine::getContent(const QPlace &place, const QPlaceContentRequest &request) + + Retrieves content for a given \a place according to the parameters specified in + \a request. +*/ + +/*! + \fn QPlaceSearchReply *QPlaceManagerEngine::search(const QPlaceSearchRequest &request) + + Searches for places according to the parameters specified in \a request. +*/ + +/*! + \fn QPlaceSearchReply *QPlaceManagerEngine::recommendations(const QPlace &place, const QPlaceSearchRequest &request) + + Provides recommendations for places that similar to \a place, and using the parameters as specified in \a request. +*/ + +/*! + \fn QPlaceTextPredictionReply *QPlaceManagerEngine::textPredictions(const QPlaceSearchRequest &request) + + Requests a set of text predictions according to the parameters specified in \a request. +*/ + +/*! + \fn QPlaceIdReply *QPlaceManagerEngine::savePlace(const QPlace &place) + + Saves a specified \a place to the manager engine's datastore. +*/ + +/*! + \fn QPlaceIdReply *QPlaceManagerEngine::removePlace(const QString &placeId) + + Removes the place corresponding to \a placeId from the manager engine's datastore. +*/ + +/*! + \fn QPlaceIdReply *QPlaceManagerEngine::saveCategory(const QPlaceCategory &category, const QString &parentId) + + Saves a \a category that is a child of the category specified by \a parentId. + An empty \a parentId means \a category is saved as a top level category. +*/ + +/*! + \fn QPlaceIdReply *QPlaceManagerEngine::removeCategory(const QString &categoryId) + + Removes the category corresponding to \a categoryId from the manager engine's datastore. +*/ + +/*! + \fn QPlaceReply *QPlaceManagerEngine::initializeCategories() + + Initializes the categories of the manager engine. +*/ - It is generally only emitted by managers that store places locally. +/*! + \fn QString QPlaceManagerEngine::parentCategoryId(const QString &categoryId) const + + Returns the parent category id of the category corresponding to \a categoryId. +*/ + +/*! + \fn QStringList QPlaceManagerEngine::childrenCategoryIds(const QString &categoryId) const + + Returns the children category ids of the category corresponding to \a categoryId. + If \a categoryId is empty then all top level category ids are returned. +*/ + +/*! + \fn QPlaceCategory QPlaceManagerEngine::category(const QString &categoryId) const + + Returns the category corresponding to the given \a categoryId. +*/ + +/*! + \fn QList QPlaceManagerEngine::childCategories(const QString &parentId) const + + Returns a list of categories that are children of the category corresponding to \a parentId. + If \a parentId is empty, all the top level categories are returned. +*/ + +/*! + \fn QLocale QPlaceManagerEngine ::locale() const + + Returns the locale of the manager engine. The locale is used as a hint to determine + what language place data should be returned in. +*/ + +/*! + \fn void QPlaceManagerEngine::setLocale(const QLocale &locale) + + Sets the \a locale of the manager engine. +*/ + +/*! + \fn QUrl QPlaceManagerEngine::constructIconUrl(const QPlaceIcon &icon, const QSize &size, QPlaceIcon::IconFlags flags) + + Constructs an icon url from a given \a icon, \a size and \a flags. The URL of the icon + image that most closely matches the given parameters is returned. +*/ + +/*! + \fn QPlaceManager::ManagerFeatures QPlaceManagerEngine::supportedFeatures() const + + Returns a set of flags indicating what particular features this manager engine instance supports. +*/ + +/*! + \fn void QPlaceManagerEngine::finished(QPlaceReply* reply) + + This signal is emitted when \a reply has finished processing. + + If reply->error() equals QPlaceReply::NoError then the processing + finished successfully. + + This signal and QPlaceReply::finished() will be emitted at the same time. + + \note Do no delete the \a reply object in the slot connected to this signal. + Use deleteLater() instead. +*/ + +/*! + \fn void QPlaceManagerEngine::error(QPlaceReply * reply, QPlaceReply::Error error, const QString &errorString = QString()); + + This signal is emitted when an error has been detected in the processing of + \a reply. The QPlaceManager::finished() signal will probably follow. + + The error will be described by the error code \a error. If \a errorString is + not empty it will contain a textual description of the error meant for developers + and not end users. + + This signal and QPlaceReply::error() will be emitted at the same time. + + \note Do no delete the \a reply object in the slot connected to this signal. + Use deleteLater() instead. +*/ + +/*! + \fn void QPlaceManagerEngine::placeAdded(const QString &placeId) + + This signal is emitted if a place has been added to the manager engine's datastore. + The particular added place is specified by \a placeId. + This signal is only emitted by manager engines that support the QPlaceManager::NotificationsFeature. */ /*! - \fn void QPlaceManagerEngine::placeUpdated(const QString&placeId) + \fn void QPlaceManagerEngine::placeUpdated(const QString &placeId) This signal is emitted if a place has been modified in the manager engine's datastore. + The particular modifed place is specified by \a placeId. - It is generally only emitted by managers that store places locally. + This signal is only emitted by manager engines that support the QPlaceManager::NotificationsFeature. */ /*! - \fn void QPlaceManagerEngine::placeRemoved(const QString&placeId) + \fn void QPlaceManagerEngine::placeRemoved(const QString &placeId) This signal is emitted if a place has been removed from the manager engine's datastore. + The particular place that has been removed is specified by \a placeId. - It is generally only emitted by managers that store places locally. + This signal is only emitted by manager engines that support the QPlaceManager::NotificationsFeature. */ /*! - \fn void QPlaceManagerEngine::categoryAdded(const QString&categoryId) + \fn void QPlaceManagerEngine::categoryAdded(const QPlaceCategory &category, const QString &parentId) - This signal is emitted if a category has been added to the manager engine's datastore. + This signal is emitted if a \a category has been added to the manager engine's datastore. + The parent of the \a category is specified by \a parentId. - It is generally only emitted by managers that store categories locally. + This signal is only emitted by manager engines that support the QPlaceManager::NotificationsFeature. */ /*! - \fn void QPlaceManagerEngine::categoryUpdated(const QString&categoryId) + \fn void QPlaceManagerEngine::categoryUpdated(const QPlaceCategory &category, const QString &parentId) - This signal is emitted if a category has been modified in the manager engine's datastore. + This signal is emitted if a \a category has been modified in the manager engine's datastore. + The parent of the modified category is specified by \a parentId. - It is generally only emitted by managers that store categories locally. + This signal is only emitted by manager engines that support the QPlaceManager::NotificationsFeature. */ /*! - \fn void QPlaceManagerEngine::categoryRemoved(const QString&categoryId) + \fn void QPlaceManagerEngine::categoryRemoved(const QString &categoryId, const QString &parentId) - This signal is emitted if a category has been removed from the manager engine's datastore. + This signal is emitted when the category correspoinding to \a categoryId has + been removed from the manager engine's datastore. The parent of the removed category + is specified by \a parentId. - It is generally only emitted by managers that store categories locally. + This signal is only emitted by manager engines that support the QPlaceManager::NotificationsFeature. */ #include "moc_qplacemanagerengine.cpp" diff --git a/src/location/places/qplacemanagerengine.h b/src/location/places/qplacemanagerengine.h index 31487bb1..11cd0029 100644 --- a/src/location/places/qplacemanagerengine.h +++ b/src/location/places/qplacemanagerengine.h @@ -94,7 +94,6 @@ public: Q_SIGNALS: void finished(QPlaceReply *reply); void error(QPlaceReply *, QPlaceReply::Error error, const QString &errorString = QString()); - void authenticationRequired(QAuthenticator *authenticator); void placeAdded(const QString &placeId); void placeUpdated(const QString &placeId); diff --git a/src/location/places/qplacerating.cpp b/src/location/places/qplacerating.cpp index ab11fcbb..102722e7 100644 --- a/src/location/places/qplacerating.cpp +++ b/src/location/places/qplacerating.cpp @@ -67,13 +67,10 @@ bool QPlaceRatingPrivate::operator==(const QPlaceRatingPrivate &other) const \class QPlaceRating \inmodule QtLocation \ingroup QtLocation-places + \ingroup QtLocation-places-data \since QtLocation 5.0 - \brief The QPlaceRating class represents a rating object. - - Each QPlaceRating represents a rating object with a count and value. - - QPlaceRating is an in memory representation of a rating object. + \brief The QPlaceRating class contains an aggregated rating for a place. */ /*! @@ -93,24 +90,40 @@ QPlaceRating::QPlaceRating(const QPlaceRating &other) } /*! - Destructor. + Destroys the rating object. */ QPlaceRating::~QPlaceRating() { } -QPlaceRating &QPlaceRating::operator =(const QPlaceRating &other) { +/*! + Assigns \a other to this rating and returns a reference + to this rating. +*/ +QPlaceRating &QPlaceRating::operator=(const QPlaceRating &other) { d = other.d; return *this; } +/*! + Returns true if \a other is equal to this rating, + otherwise returns false. +*/ bool QPlaceRating::operator==(const QPlaceRating &other) const { return (*(d.constData()) == *(other.d.constData())); } /*! - Returns value. + \fn bool QPlaceRating::operator!=(const QPlaceRating &other) const + + Returns true if \a other is not equal to this rating, + otherwise returns false +*/ + +/*! + Returns the value of the rating which is an aggregation + of individual ratings. */ qreal QPlaceRating::value() const { @@ -118,7 +131,7 @@ qreal QPlaceRating::value() const } /*! - Sets the \a value. + Sets the rating's aggregated \a value. */ void QPlaceRating::setValue(qreal value) { @@ -142,7 +155,7 @@ void QPlaceRating::setMaximum(qreal max) } /*! - Returns count. + Returns the total number of individual ratings. */ int QPlaceRating::count() const { @@ -150,7 +163,7 @@ int QPlaceRating::count() const } /*! - Sets the \a count. + Sets the total number of individual ratings to \a count. */ void QPlaceRating::setCount(int count) { diff --git a/src/location/places/qplacereply.cpp b/src/location/places/qplacereply.cpp index 2c56e145..2005cf2e 100644 --- a/src/location/places/qplacereply.cpp +++ b/src/location/places/qplacereply.cpp @@ -48,15 +48,30 @@ QT_USE_NAMESPACE \class QPlaceReply \inmodule QtLocation \ingroup QtLocation-places + \ingroup QtLocation-places-replies \since QtLocation 5.0 - \brief The QPlaceReply class manages an operation started by an instance of QPlaceManager. + \brief The QPlaceReply class manages an operation started by an instance of QPlaceManager and + serves as a base class for more specialized replies. + + The QPlaceReply and each of its specialized subclasses manage the + state and results of their corresponding operations. The QPlaceReply itself is used + for operations that have no results i.e. it only necessary to know if the operation + succeeded or failed. + + The finished() signal can be used to monitor the progress of an operation. + Once an operation is complete, the error() and errorString() methods provide information + on whether the operation completed successfully. If successful, the reply + will contain the results for that operation i.e. each subclass will have appropriate + functions to retrieve the results of an operation. + + \sa QPlaceManager */ /*! \enum QPlaceReply::Error - Describes an error which prevented completion of an operation. + Describes an error which occurred during an operation. \value NoError No error has occurred \value DoesNotExistError @@ -73,6 +88,8 @@ QT_USE_NAMESPACE The operation failed because of insufficient permissions. \value UnsupportedError The operation was not supported by the service provider. + \value BadArgumentError. + A parameter that was provided was invalid. \value CancelError The operation was canceled. \value UnknownError @@ -85,16 +102,18 @@ QT_USE_NAMESPACE Describes the reply's type. \value Reply This is a generic reply. + \value DetailsReply + This is a reply for the retrieval of place details + \value SearchReply + This is a reply for the place search operation. + \value TextPredictionReply - Thi is the reply for a text prediction operation. - \value ReviewReply - This is a reply for the retrieval of place reviews. + This is a reply for a text prediction operation. \value ContentReply - This is a reply for the retrieval of place content. - \value PlaceDetailsReply - This is a reply for the retrieval of place details. - \value PlaceSearchReply - This is a reply for a place search operation. + This is a reply for content associated with a place. + \value IdReply + This is a reply that returns an id of a place/category. + Typically used for place/category save and remove operations. */ /*! @@ -105,13 +124,16 @@ QPlaceReply::QPlaceReply(QObject *parent) { } +/*! + \internal +*/ QPlaceReply::QPlaceReply(QPlaceReplyPrivate *dd, QObject *parent) : QObject(parent),d_ptr(dd) { } /*! - Destructor. + Destroys the reply object. */ QPlaceReply::~QPlaceReply() { @@ -130,7 +152,7 @@ bool QPlaceReply::isFinished() const } /*! - Return type of operation. + Returns the type of the reply. */ QPlaceReply::Type QPlaceReply::type() const { @@ -149,7 +171,7 @@ void QPlaceReply::setFinished(bool finished) /*! Sets the \a error and \a errorString of the reply. - This function does not cause the error(QPlaceReply::Error, const QString &errorString) + This function does not cause the QPlaceReply::error(QPlaceReply::Error, const QString &errorString) signal to be emitted. */ void QPlaceReply::setError(QPlaceReply::Error error, const QString &errorString) @@ -159,7 +181,10 @@ void QPlaceReply::setError(QPlaceReply::Error error, const QString &errorString) } /*! - Returns the error string. + Returns the error string of the reply. The error string is intended to be + used by developers only and is not fit to be displayed to an end user. + + If no error has occurred, the string is empty. */ QString QPlaceReply::errorString() const { @@ -167,7 +192,7 @@ QString QPlaceReply::errorString() const } /*! - Returns error code. + Returns the error code. */ QPlaceReply::Error QPlaceReply::error() const { diff --git a/src/location/places/qplacereply.h b/src/location/places/qplacereply.h index 429ebc14..a764fd57 100644 --- a/src/location/places/qplacereply.h +++ b/src/location/places/qplacereply.h @@ -67,7 +67,6 @@ public: PermissionsError, UnsupportedError, BadArgumentError, - AuthenticationFailedError, CancelError, UnknownError }; diff --git a/src/location/places/qplacereview.cpp b/src/location/places/qplacereview.cpp index 734f112c..92633006 100644 --- a/src/location/places/qplacereview.cpp +++ b/src/location/places/qplacereview.cpp @@ -80,21 +80,21 @@ bool QPlaceReviewPrivate::compare(const QPlaceContentPrivate *other) const \class QPlaceReview \inmodule QtLocation \ingroup QtLocation-places + \ingroup QtLocation-places-data \since QtLocation 5.0 - \brief The QPlaceReview class represents a review object. + \brief The QPlaceReview class represents a review of a place. - Each QPlaceReview represents a review object with a number of attributes - such as rating, review id, connected media etc. Each QPlaceReview is associated - with place. + Each QPlaceReview has a number of properties such as + a title, text, date of submission and rating; in addition to those properties + inherited from QPlaceContent. - Review objects are read-only, e.g. user of API might get list of review objects - associated to specific place but can not edit its content. User might also create new review. + Note: The Places API only supports reviews as 'retrieve-only' objects. Submitting reviews + to a provider is not a supported use case. - QPlaceReview is an in memory representation of a review object. + \sa QPlaceContent, QPlaceEditorial */ - /*! Constructs a new review object. */ @@ -103,11 +103,15 @@ QPlaceReview::QPlaceReview() { } +/*! + \fn QPlaceReview::QPlaceReview(const QPlaceContent &other) + Constructs a copy of \a other, otherwise constructs a default review object. +*/ Q_IMPLEMENT_CONTENT_COPY_CTOR(QPlaceReview) /*! - Destructor. + Destroys the review. */ QPlaceReview::~QPlaceReview() { @@ -116,7 +120,7 @@ QPlaceReview::~QPlaceReview() Q_IMPLEMENT_CONTENT_D_FUNC(QPlaceReview) /*! - Returns the date and time that the review was written. + Returns the date and time that the review was submitted. */ QDateTime QPlaceReview::dateTime() const { @@ -125,12 +129,12 @@ QDateTime QPlaceReview::dateTime() const } /*! - Sets the date and time that the review was written to \a dt. + Sets the date and time that the review was submitted to \a dateTime. */ -void QPlaceReview::setDateTime(const QDateTime &dt) +void QPlaceReview::setDateTime(const QDateTime &dateTime) { Q_D(QPlaceReview); - d->dateTime = dt; + d->dateTime = dateTime; } /*! @@ -154,7 +158,8 @@ void QPlaceReview::setText(const QString &text) } /*! - Returns language. + Returns the language of the review. Typically this would be a language code + in the 2 letter ISO 639-1 format. */ QString QPlaceReview::language() const { @@ -163,16 +168,17 @@ QString QPlaceReview::language() const } /*! - Sets language. + Sets the \a language of the review. Typically this would be a language code + in the 2 letter ISO 639-1 format. */ -void QPlaceReview::setLanguage(const QString &data) +void QPlaceReview::setLanguage(const QString &language) { Q_D(QPlaceReview); - d->language = data; + d->language = language; } /*! - Returns rating. + Returns this review's rating of the place. */ qreal QPlaceReview::rating() const { @@ -181,16 +187,16 @@ qreal QPlaceReview::rating() const } /*! - Sets rating. + Sets the review's \a rating of the place. */ -void QPlaceReview::setRating(qreal data) +void QPlaceReview::setRating(qreal rating) { Q_D(QPlaceReview); - d->rating = data; + d->rating = rating; } /*! - Returns review id. + Returns the review's id. */ QString QPlaceReview::reviewId() const { @@ -199,16 +205,16 @@ QString QPlaceReview::reviewId() const } /*! - Sets review id. + Sets the \a id of the review. */ -void QPlaceReview::setReviewId(const QString &data) +void QPlaceReview::setReviewId(const QString &id) { Q_D(QPlaceReview); - d->reviewId = data; + d->reviewId = id; } /*! - Returns review title. + Returns the title of the review. */ QString QPlaceReview::title() const { @@ -217,12 +223,12 @@ QString QPlaceReview::title() const } /*! - Sets title. + Sets the \a title of the review. */ -void QPlaceReview::setTitle(const QString &data) +void QPlaceReview::setTitle(const QString &title) { Q_D(QPlaceReview); - d->title = data; + d->title = title; } QT_END_NAMESPACE diff --git a/src/location/places/qplacereview.h b/src/location/places/qplacereview.h index 18e61ec9..ad9986e4 100644 --- a/src/location/places/qplacereview.h +++ b/src/location/places/qplacereview.h @@ -57,8 +57,11 @@ class Q_LOCATION_EXPORT QPlaceReview : public QPlaceContent { public: QPlaceReview(); +#ifdef Q_QDOC + QPlaceReview(const QPlaceContent &other); +#else Q_DECLARE_CONTENT_COPY_CTOR(QPlaceReview) - +#endif virtual ~QPlaceReview(); QDateTime dateTime() const; diff --git a/src/location/places/qplacesearchreply.cpp b/src/location/places/qplacesearchreply.cpp index 96d74a1e..2b91c0d1 100644 --- a/src/location/places/qplacesearchreply.cpp +++ b/src/location/places/qplacesearchreply.cpp @@ -60,10 +60,14 @@ QT_USE_NAMESPACE \class QPlaceSearchReply \inmodule QtLocation \ingroup QtLocation-places + \ingroup QtLocation-places-replies \since QtLocation 5.0 - \brief The QPlaceSearchReply class manages a search operation started by an + \brief The QPlaceSearchReply class manages a place search operation started by an instance of QPlaceManager. + + See \l {Discovery/Search} for an example on how to use a search reply. + \sa QPlaceSearchRequest, QPlaceManager */ /*! @@ -117,7 +121,7 @@ QPlaceSearchRequest QPlaceSearchReply::request() const } /*! - Sets the search request used to generate this this reply. + Sets the search \a request used to generate this reply. */ void QPlaceSearchReply::setRequest(const QPlaceSearchRequest &request) { diff --git a/src/location/places/qplacesearchrequest.cpp b/src/location/places/qplacesearchrequest.cpp index 20e34634..6ac5a7b7 100644 --- a/src/location/places/qplacesearchrequest.cpp +++ b/src/location/places/qplacesearchrequest.cpp @@ -158,6 +158,7 @@ void QPlaceSearchRequestPrivate::clear() \class QPlaceSearchRequest \inmodule QtLocation \ingroup QtLocation-places + \ingroup QtLocation-places-requests \since QtLocation 5.0 \brief The QPlaceSearchRequest class represents the set of parameters for a search request. @@ -175,13 +176,15 @@ void QPlaceSearchRequestPrivate::clear() The QPlaceSearchRequest is primarily used with the QPlaceManager to \l {QPlaceManager::search()} {search for places}, however it is also used to provide parameters for \l {QPlaceManager::textPredictions()}{generating text predictions} - and \l {QPlaceManager::recommendations()} {retreiving recommendations}. Note that depending on usage + and \l {QPlaceManager::recommendations()} {retreiving recommendations}. Note that depending on usage, some parameters may not be relevant, e.g. the relevance hint is not important for text predictions. However - in general most of the parameters are useful for each of these operations, eg for a recommendation, a search area + in general, most of the parameters are useful for each of these operations, eg for a recommendation, a search area and categories can be useful in narrowing down recommendation candidates. Also be aware that providers may vary by which parameters they support e.g. some providers may not support - paging while others do, some providers may honor relevance hints while others may completely ignore them. + paging while others do, some providers may honor relevance hints while others may completely ignore them, + see \l {Information about plugins}. + */ /*! @@ -297,9 +300,8 @@ void QPlaceSearchRequest::setCategory(const QPlaceCategory &category) /*! Sets the search request to search from the list of given \a categories. - - It is possible that some backends may not support multiple categories. In this case, - the first category is used and the rest are ignored. + Any places returned during the search will match at least one of the \a + categories. \sa setCategory() */ @@ -320,7 +322,7 @@ QGeoBoundingArea *QPlaceSearchRequest::searchArea() const /*! Sets the search request to search within the given \a area. Ownership of the \a area is - transferred to the request who is responsible for pointer deletion. If a new \a area + transferred to the request, who is now responsible for pointer deletion. If a new \a area is being assigned, the old area is deleted. */ void QPlaceSearchRequest::setSearchArea(QGeoBoundingArea *area) @@ -352,8 +354,8 @@ void QPlaceSearchRequest::setMaximumCorrections(int number) /*! Returns the visibility scope used when searching for places. The default value is - QtLocation::UnspecifiedVisibility meaning that no explicit scope has been assigned. It is up - to the manager implementation to decide what scope it searches by default. + QtLocation::UnspecifiedVisibility meaning that no explicit scope has been assigned. + Places of any scope may be returned during the search. */ QtLocation::VisibilityScope QPlaceSearchRequest::visibilityScope() const { @@ -395,7 +397,7 @@ void QPlaceSearchRequest::setRelevanceHint(QPlaceSearchRequest::RelevanceHint hi Returns the maximum number of search results to retrieve. A negative value for limit means that it is undefined. It is left up to the backend - provider to choose an appropriate number of results to return. + provider to choose an appropriate number of results to return. The default limit is -1. */ int QPlaceSearchRequest::limit() const { @@ -413,7 +415,9 @@ void QPlaceSearchRequest::setLimit(int limit) } /*! - Returns the index of the first item that is to be retrieved. + Returns the offset index of the first item that is to be retrieved. + + The default offset is 0. */ int QPlaceSearchRequest::offset() const { diff --git a/src/location/places/qplacesearchresult.cpp b/src/location/places/qplacesearchresult.cpp index 63fc1f72..e63273ff 100644 --- a/src/location/places/qplacesearchresult.cpp +++ b/src/location/places/qplacesearchresult.cpp @@ -41,11 +41,12 @@ #include "qplacesearchresult.h" #include "qplacesearchresult_p.h" +#include QT_USE_NAMESPACE QPlaceSearchResultPrivate::QPlaceSearchResultPrivate() -: QSharedData(), distance(0), type(QPlaceSearchResult::UnknownSearchResult) + : QSharedData(), distance(qQNaN()), type(QPlaceSearchResult::UnknownSearchResult) { } @@ -74,16 +75,32 @@ bool QPlaceSearchResultPrivate::operator==(const QPlaceSearchResultPrivate &othe \class QPlaceSearchResult \inmodule QtLocation \ingroup QtLocation-places + \ingroup QtLocation-places-data \since QtLocation 5.0 - \brief The QPlaceSearchResult class represents a search result object. + \brief The QPlaceSearchResult class represents a search result. - Each QPlaceSearchResult represents a place with a number of attributes - such as distance, relevance, etc. + There are two types of search result. The first is a + \l {QPlaceSearchResult::PlaceResult} {place result}, which contains + a place that matched a search request, but also metadata about the place + such as the distance from the search center of a search request(if it had one). + + The other type is a \l {QPlaceSearchResult::CorrectionResult}{correction}, which + contains an alternative search term that may better reflect the + user's intended query. + +*/ + +/*! + \enum QPlaceSearchResult::SearchResultType + Defines the type of search result + \value PlaceResult The search result contains a place. + \value CorrectionResult The search result contains a search term correction. + \value UnknownSearchResult The contents of the search result are unknown. */ /*! - Default constructor. Constructs an new search result. + Constructs an new search result. */ QPlaceSearchResult::QPlaceSearchResult() : d(new QPlaceSearchResultPrivate) @@ -99,24 +116,42 @@ QPlaceSearchResult::QPlaceSearchResult(const QPlaceSearchResult &other) } /*! - Destructor. + Destroys the search result. */ QPlaceSearchResult::~QPlaceSearchResult() { } +/*! + Assigns \a other to this search result and returns a reference to this + search result. +*/ QPlaceSearchResult &QPlaceSearchResult::operator =(const QPlaceSearchResult &other) { d = other.d; return *this; } +/*! + Returns true if \a other is equal to this search result, otherwise + returns false. +*/ bool QPlaceSearchResult::operator==(const QPlaceSearchResult &other) const { return (*(d.constData()) == *(other.d.constData())); } /*! - Returns the distance. + \fn bool QPlaceSearchResult::operator!=(const QPlaceSearchResult &other) const + Returns true if \a other not equal to this search result, otherwise + returns false. +*/ + +/*! + Returns the distance of the place to the search center. This field + is only valid when the search result type is QPlaceSearchResult::PlaceResult, + and where the search request contained a search center. Otherwise, + the distance is NaN indicating an undefined distance. The default value + for distance is NaN. */ qreal QPlaceSearchResult::distance() const { @@ -124,7 +159,7 @@ qreal QPlaceSearchResult::distance() const } /*! - Sets the \a distance. + Set the \a distance of the search result's place from a search center. */ void QPlaceSearchResult::setDistance(qreal distance) { @@ -132,7 +167,7 @@ void QPlaceSearchResult::setDistance(qreal distance) } /*! - Returns the place. + Returns the type of the search result. */ QPlaceSearchResult::SearchResultType QPlaceSearchResult::type() const { @@ -140,7 +175,7 @@ QPlaceSearchResult::SearchResultType QPlaceSearchResult::type() const } /*! - Sets the \a place. + Sets the \a type of the search result. */ void QPlaceSearchResult::setType(QPlaceSearchResult::SearchResultType type) { @@ -148,7 +183,8 @@ void QPlaceSearchResult::setType(QPlaceSearchResult::SearchResultType type) } /*! - Returns the place. + Returns the place of the search result. This field is only valid when the search result + type is QPlaceSearchResult::PlaceResult. */ QPlace QPlaceSearchResult::place() const { @@ -156,7 +192,7 @@ QPlace QPlaceSearchResult::place() const } /*! - Sets the \a place. + Sets the \a place that this search result refers to. */ void QPlaceSearchResult::setPlace(const QPlace &place) { @@ -164,7 +200,8 @@ void QPlaceSearchResult::setPlace(const QPlace &place) } /*! - Returns the suggested search term correction. + Returns the correction term that this particular search result represents. + This field is only valid when the search result type is QPlaceSearchResult::CorrectionResult. */ QString QPlaceSearchResult::correction() const { @@ -172,7 +209,7 @@ QString QPlaceSearchResult::correction() const } /*! - Sets the "did you mean" \a string. + Sets the \a correction term of the search result. */ void QPlaceSearchResult::setCorrection(const QString &correction) { diff --git a/src/location/places/qplacesupplier.cpp b/src/location/places/qplacesupplier.cpp index 73596435..cb63085d 100644 --- a/src/location/places/qplacesupplier.cpp +++ b/src/location/places/qplacesupplier.cpp @@ -75,16 +75,21 @@ bool QPlaceSupplierPrivate::operator==(const QPlaceSupplierPrivate &other) const \class QPlaceSupplier \inmodule QtLocation \ingroup QtLocation-places + \ingroup QtLocation-places-data \since QtLocation 5.0 - \brief The QPlaceSupplier class represents a supplier object. + \brief The QPlaceSupplier class represents a supplier of a place or content associated + with a place. - Each QPlaceSupplier represents a supplier object with a number of attributes - such as name, icon etc. Each QPlaceSupplier is associated with place, media, review or description. + Each instance represents a set of data about a supplier, which can include + supplier's name, url and icon. The supplier is typically a business or organization. + + Note: The Places API only supports suppliers as 'retrieve-only' objects. Submitting + suppliers to a provider is not a supported use case. */ /*! - Default constructor. Constructs an new supplier object. + Constructs a new supplier object. */ QPlaceSupplier::QPlaceSupplier() : d(new QPlaceSupplierPrivate) @@ -92,7 +97,7 @@ QPlaceSupplier::QPlaceSupplier() } /*! - Constructs a copy of \a other + Constructs a copy of \a other. */ QPlaceSupplier::QPlaceSupplier(const QPlaceSupplier &other) :d(other.d) @@ -100,24 +105,39 @@ QPlaceSupplier::QPlaceSupplier(const QPlaceSupplier &other) } /*! - Destructor. + Destroys the supplier object. */ QPlaceSupplier::~QPlaceSupplier() { } -QPlaceSupplier &QPlaceSupplier::operator =(const QPlaceSupplier &other) { +/*! + Assigns \a other to this supplier and returns a reference to this + supplier. +*/ +QPlaceSupplier &QPlaceSupplier::operator=(const QPlaceSupplier &other) { d = other.d; return *this; } +/*! + Returns true if this supplier is equal to \a other, + otherwise returns false. +*/ bool QPlaceSupplier::operator==(const QPlaceSupplier &other) const { return (*(d.constData()) == *(other.d.constData())); } /*! - Returns name. + \fn QPlaceSupplier::operator!=(const QPlaceSupplier &other) const + + Returns true if this supplier is not equal to \a other, + otherwise returns false. +*/ + +/*! + Returns the name of the supplier. */ QString QPlaceSupplier::name() const { @@ -125,15 +145,15 @@ QString QPlaceSupplier::name() const } /*! - Sets name. + Sets the \a name of the supplier. */ -void QPlaceSupplier::setName(const QString &data) +void QPlaceSupplier::setName(const QString &name) { - d->name = data; + d->name = name; } /*! - Returns supplier id. + Returns the id of the supplier. */ QString QPlaceSupplier::supplierId() const { @@ -141,15 +161,15 @@ QString QPlaceSupplier::supplierId() const } /*! - Sets supplier id. + Sets the \a id of the supplier. */ -void QPlaceSupplier::setSupplierId(const QString &data) +void QPlaceSupplier::setSupplierId(const QString &id) { - d->supplierId = data; + d->supplierId = id; } /*! - Returns the URL of the supplier. + Returns the url of the supplier. */ QUrl QPlaceSupplier::url() const { @@ -157,7 +177,7 @@ QUrl QPlaceSupplier::url() const } /*! - Sets \a url of the supplier. + Sets the \a url of the supplier. */ void QPlaceSupplier::setUrl(const QUrl &url) { @@ -165,7 +185,7 @@ void QPlaceSupplier::setUrl(const QUrl &url) } /*! - Returns the supplier icon + Returns the icon of the supplier. */ QPlaceIcon QPlaceSupplier::icon() const { @@ -173,7 +193,7 @@ QPlaceIcon QPlaceSupplier::icon() const } /*! - Sets the supplier icon + Sets the \a icon of the supplier. */ void QPlaceSupplier::setIcon(const QPlaceIcon &icon) { diff --git a/src/location/places/qplacetextpredictionreply.cpp b/src/location/places/qplacetextpredictionreply.cpp index 4fc26007..a7a54a96 100644 --- a/src/location/places/qplacetextpredictionreply.cpp +++ b/src/location/places/qplacetextpredictionreply.cpp @@ -59,10 +59,15 @@ QT_USE_NAMESPACE \class QPlaceTextPredictionReply \inmodule QtLocation \ingroup QtLocation-places + \ingroup QtLocation-places-replies \since QtLocation 5.0 \brief The QPlaceTextPredictionReply class manages a text prediction operation started by an instance of QPlaceManager. + + See \l {Text Predictions} for an example on how to use a text prediction reply. + + \sa QPlaceManager */ /*! diff --git a/src/location/places/qplaceuser.cpp b/src/location/places/qplaceuser.cpp index 6e80e87c..cfad197a 100644 --- a/src/location/places/qplaceuser.cpp +++ b/src/location/places/qplaceuser.cpp @@ -67,18 +67,14 @@ bool QPlaceUserPrivate::operator==(const QPlaceUserPrivate &other) const \class QPlaceUser \inmodule QtLocation \ingroup QtLocation-places + \ingroup QtLocation-places-data \since QtLocation 5.0 - \brief The QPlaceUser class represents a user. - - Each QPlaceRating represents a rating object with a count and value. - - QPlaceRating is an in memory representation of a rating object. + \brief The QPlaceUser class represents a individual user. */ - /*! - Constructs a new user. + Constructs a new user object. */ QPlaceUser::QPlaceUser() : d(new QPlaceUserPrivate) @@ -86,7 +82,7 @@ QPlaceUser::QPlaceUser() } /*! - Constructs a copy of \a other + Constructs a copy of \a other. */ QPlaceUser::QPlaceUser(const QPlaceUser &other) :d(other.d) @@ -94,7 +90,7 @@ QPlaceUser::QPlaceUser(const QPlaceUser &other) } /*! - Destructor. + Destroys the user object. */ QPlaceUser::~QPlaceUser() { @@ -109,6 +105,12 @@ QPlaceUser &QPlaceUser::operator=(const QPlaceUser &other) return *this; } +/*! + \fn bool QPlaceUser::operator!=(const QPlaceUser &other) const + + Returns true if \a other is not equal to this user, + otherwise returns false. +*/ /*! Returns true if this user is equal to \a other. @@ -120,7 +122,7 @@ bool QPlaceUser::operator==(const QPlaceUser &other) const } /*! - Returns the user id. + Returns the id of the user. */ QString QPlaceUser::userId() const { @@ -128,15 +130,15 @@ QString QPlaceUser::userId() const } /*! - Sets the \a userId. + Sets the \a id of the user. */ -void QPlaceUser::setUserId(const QString &userId) +void QPlaceUser::setUserId(const QString &id) { - d->userId = userId; + d->userId = id; } /*! - Returns the user's name. + Returns the name of the user. */ QString QPlaceUser::name() const { @@ -144,11 +146,10 @@ QString QPlaceUser::name() const } /*! - Sets the user's \a name. + Sets the \a name of the user. */ void QPlaceUser::setName(const QString &name) { d->name = name; } - diff --git a/src/location/qgeoaddress.cpp b/src/location/qgeoaddress.cpp index 6fd78163..6d0e5e77 100644 --- a/src/location/qgeoaddress.cpp +++ b/src/location/qgeoaddress.cpp @@ -75,6 +75,8 @@ QGeoAddressPrivate::~QGeoAddressPrivate() \class QGeoAddress \inmodule QtLocation \ingroup QtLocation-positioning + \ingroup QtLocation-places-data + \ingroup QtLocation-places \since QtLocation 5.0 \brief The QGeoAddress class represents an address @@ -289,7 +291,7 @@ void QGeoAddress::setPostcode(const QString &postcode) /*! Returns whether this address is empty. An address is considered empty - if \i all of its fields are empty. + if \e all of its fields are empty. */ bool QGeoAddress::isEmpty() const { diff --git a/src/location/qgeoboundingarea.cpp b/src/location/qgeoboundingarea.cpp index 41666734..d5bc9c8f 100644 --- a/src/location/qgeoboundingarea.cpp +++ b/src/location/qgeoboundingarea.cpp @@ -115,7 +115,13 @@ Creates a new QGeoBoundingArea that is a deep copy of this bounding area. \fn bool QGeoBoundingArea::operator==(const QGeoBoundingArea &other) const Returns true if the \a other bounding area is equivalent to this bounding area, - otherwise returns false + otherwise returns false. +*/ + +/*! + \fn bool QGeoBoundingArea::operator!=(const QGeoBoundingArea &other) const + Returns true if \a other is not equivalent to this bounding area, + otherwise returns false. */ QT_END_NAMESPACE diff --git a/src/location/qgeolocation.cpp b/src/location/qgeolocation.cpp index 693f1e41..ca898022 100644 --- a/src/location/qgeolocation.cpp +++ b/src/location/qgeolocation.cpp @@ -73,18 +73,18 @@ bool QGeoLocationPrivate::operator==(const QGeoLocationPrivate &other) const \class QGeoLocation \inmodule QtLocation \ingroup QtLocation-positioning + \ingroup QtLocation-places + \ingroup QtLocation-places-data \since QtLocation 5.0 - \brief The QGeoLocation class represents a location object. + \brief The QGeoLocation class represents basic information about a location. - Each QGeoLocation represents a location object with a number of attributes - such as address, display position etc. - - QGeoLocation is an in memory representation of a location object. + A QGeoLocation consists of a coordinate and corresponding address, along with an optional + bounding box which is the recommended region to be displayed when viewing the location. */ /*! - Default constructor. Constructs an new location object. + Constructs an new location object. */ QGeoLocation::QGeoLocation() : d(new QGeoLocationPrivate) @@ -100,24 +100,31 @@ QGeoLocation::QGeoLocation(const QGeoLocation &other) } /*! - Destructor. + Destroys the location object. */ QGeoLocation::~QGeoLocation() { } +/*! + Assigns \a other to this location and returns a reference to this location. +*/ QGeoLocation &QGeoLocation::operator =(const QGeoLocation &other) { d = other.d; return *this; } +/*! + Returns true if this location is equal to \a other, + otherwise returns false. +*/ bool QGeoLocation::operator==(const QGeoLocation &other) const { return (*(d.constData()) == *(other.d.constData())); } /*! - Returns address. + Returns the address of the location. */ QGeoAddress QGeoLocation::address() const { @@ -125,7 +132,7 @@ QGeoAddress QGeoLocation::address() const } /*! - Sets address. + Sets the \a address of the location. */ void QGeoLocation::setAddress(const QGeoAddress &address) { @@ -133,7 +140,7 @@ void QGeoLocation::setAddress(const QGeoAddress &address) } /*! - Returns the location's coordinate. + Returns the coordinate of the location. */ QGeoCoordinate QGeoLocation::coordinate() const { @@ -141,7 +148,7 @@ QGeoCoordinate QGeoLocation::coordinate() const } /*! - Sets the location's \a coordinate. + Sets the \a coordinate of the location. */ void QGeoLocation::setCoordinate(const QGeoCoordinate &coordinate) { @@ -149,7 +156,8 @@ void QGeoLocation::setCoordinate(const QGeoCoordinate &coordinate) } /*! - Returns view port. + Returns a bounding box which represents the recommended region + to display when viewing this location. */ QGeoBoundingBox QGeoLocation::boundingBox() const { @@ -157,9 +165,9 @@ QGeoBoundingBox QGeoLocation::boundingBox() const } /*! - Sets view port. + Sets the \a boundingBox of the location. */ -void QGeoLocation::setBoundingBox(const QGeoBoundingBox &viewport) +void QGeoLocation::setBoundingBox(const QGeoBoundingBox &boundingBox) { - d->viewport = viewport; + d->viewport = boundingBox; } diff --git a/src/location/qplace.cpp b/src/location/qplace.cpp index a7b35bee..599f4b11 100644 --- a/src/location/qplace.cpp +++ b/src/location/qplace.cpp @@ -54,9 +54,67 @@ QT_BEGIN_NAMESPACE \class QPlace \inmodule QtLocation \ingroup QtLocation-places + \ingroup QtLocation-places-data \since QtLocation 5.0 - \brief The QPlace class represents basic information about a place. + \brief The QPlace class represents a set of data about a place. + + \input place-definition.qdocinc + + \section2 Contact Information + The contact information of a place is based around a common set of + \l {Contact Types}{contact types}. To retrieve all the phone numbers + of a place, one would do: + + \snippet snippets/places/requesthandler.h Phone numbers + + 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. + \list + \o QPlace::primaryPhone() + \o QPlace::primaryEmail() + \o QPlace::primaryWebsite() + \o QPlace::primaryFax() + \endlist + + \section2 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 + \l {Attribute Types}{attribute types}. To retrieve an extended attribute one + would do: + \snippet snippets/places/requesthandler.h Opening hours + + The attribute types are string values by design to allow providers + to introduce new attribute types. + + \section2 Content + The QPlace object is only meant to be a convenient container to hold + rich content such as images, reviews etc. Retrieval of content + should happen via QPlaceManager::getContent(). + + 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. + + \section3 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. + + \section2 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). + + \section2 Saving Caveats + \input place-caveats.qdocinc */ /*! @@ -123,7 +181,7 @@ bool QPlace::operator!= (const QPlace &other) const } /*! - Returns categories. + Returns categories that this place belongs to. */ QList QPlace::categories() const { @@ -132,7 +190,7 @@ QList QPlace::categories() const } /*! - Sets categories. + Sets the \a categories that this place belongs to. */ void QPlace::setCategories(const QList &categories) { @@ -141,7 +199,7 @@ void QPlace::setCategories(const QList &categories) } /*! - Returns location. + Returns the location of the place. */ QGeoLocation QPlace::location() const { @@ -150,7 +208,7 @@ QGeoLocation QPlace::location() const } /*! - Sets location. + Sets the \a location of the place. */ void QPlace::setLocation(const QGeoLocation &location) { @@ -159,7 +217,7 @@ void QPlace::setLocation(const QGeoLocation &location) } /*! - Returns rating. + Returns an aggregated rating of the place. */ QPlaceRating QPlace::rating() const { @@ -168,7 +226,7 @@ QPlaceRating QPlace::rating() const } /*! - Sets rating. + Sets the aggregated \a rating of the place. */ void QPlace::setRating(const QPlaceRating &rating) { @@ -177,7 +235,7 @@ void QPlace::setRating(const QPlaceRating &rating) } /*! - Returns the supplier of this place data. + Returns the supplier of this place. */ QPlaceSupplier QPlace::supplier() const { @@ -186,7 +244,7 @@ QPlaceSupplier QPlace::supplier() const } /*! - Sets the supplier of this place data to \a supplier. + Sets the supplier of this place to \a supplier. */ void QPlace::setSupplier(const QPlaceSupplier &supplier) { @@ -232,7 +290,7 @@ void QPlace::insertContent(QPlaceContent::Type type, const QPlaceContent::Collec /*! Returns the total count of content objects of the given \a type. - This total count indicates how many the manager should have available. + 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. */ @@ -252,7 +310,7 @@ void QPlace::setTotalContentCount(QPlaceContent::Type type, int totalCount) } /*! - Returns name. + Returns the name of the place. */ QString QPlace::name() const { @@ -261,7 +319,7 @@ QString QPlace::name() const } /*! - Sets name. + Sets the \a name of the place. */ void QPlace::setName(const QString &name) { @@ -270,7 +328,9 @@ void QPlace::setName(const QString &name) } /*! - Returns placeId. + Returns the id of the place. The place id is only meaningful to the QPlaceManager that + generated it and is not transferrable between managers. The place id is not guaranteed + to be universally unique, but unique for the manager that generated it. */ QString QPlace::placeId() const { @@ -279,12 +339,12 @@ QString QPlace::placeId() const } /*! - Sets placeId. + Sets the \a id of the place. */ -void QPlace::setPlaceId(const QString &placeId) +void QPlace::setPlaceId(const QString &id) { Q_D(QPlace); - d->placeId = placeId; + d->placeId = id; } /*! @@ -298,7 +358,7 @@ QString QPlace::attribution() const } /*! - Sets the attribution string of the place. + Sets the \a attribution string of the place. */ void QPlace::setAttribution(const QString &attribution) { @@ -316,7 +376,7 @@ QPlaceIcon QPlace::icon() const } /*! - Sets the icon of the place. + Sets the \a icon of the place. */ void QPlace::setIcon(const QPlaceIcon &icon) { @@ -325,7 +385,8 @@ void QPlace::setIcon(const QPlaceIcon &icon) } /*! - Returns the primary phone number for this place. + Returns the primary phone number for this place. This accesses the first contact detail + of the \l {QPlaceContactDetail::Phone}{phone number type}. If no phone details exist, then an empty string is returned. */ QString QPlace::primaryPhone() const { @@ -338,7 +399,8 @@ QString QPlace::primaryPhone() const } /*! - Returns the primary fax number for this place. + Returns the primary fax number for this place. This convenience function accesses the first contact + detail of the \l {QPlaceContactDetail::Fax}{fax type}. If no fax details exist, then an empty string is returned. */ QString QPlace::primaryFax() const { @@ -351,7 +413,9 @@ QString QPlace::primaryFax() const } /*! - Returns the primary email address for this place. + Returns the primary email address for this place. This convenience function accesses the first + contact detail of the \l {QPlaceContactDetail::Email}{email type}. If no email addresses exist, then + an empty string is returned. */ QString QPlace::primaryEmail() const { @@ -364,7 +428,9 @@ QString QPlace::primaryEmail() const } /*! - Returns the primary URL of this place. + Returns the primary website of the place. This convenience function accesses the first + contact detail of the \l {QPlaceContactDetail::Website}{website type}. If no websites exist, + then an empty string is returned. */ QUrl QPlace::primaryWebsite() const { @@ -444,6 +510,8 @@ void QPlace::removeExtendedAttribute(const QString &attributeType) /*! Returns the type of contact details this place has. + + See QPlaceContactDetail for a list of common \l {QPlaceContactDetail::Email}{contact types}. */ QStringList QPlace::contactTypes() const { @@ -452,7 +520,9 @@ QStringList QPlace::contactTypes() const } /*! - Returns a list of contact details of the specified \a contactType + Returns a list of contact details of the specified \a contactType. + + See QPlaceContactDetail for a list of common \l {QPlaceContactDetail::Email}{contact types}. */ QList QPlace::contactDetails(const QString &contactType) const { @@ -465,6 +535,8 @@ QList QPlace::contactDetails(const QString &contactType) co If \a details is empty, then the \a contactType is removed from the place such that it is no longer returned by QPlace::contactTypes(). + + See QPlaceContactDetail for a list of common \l {QPlaceContactDetail::Email}{contact types}. */ void QPlace::setContactDetails(const QString &contactType, QList details) { @@ -477,6 +549,8 @@ void QPlace::setContactDetails(const QString &contactType, QList