diff options
46 files changed, 1672 insertions, 420 deletions
diff --git a/doc/src/place-caveats.qdocinc b/doc/src/place-caveats.qdocinc new file mode 100644 index 00000000..751467bd --- /dev/null +++ b/doc/src/place-caveats.qdocinc @@ -0,0 +1,20 @@ + The Places API is currently designed for only saving \a {core} details. Saving rich content like + images and reviews or details like supplier and rating is not a supported use case. Typically a manager + will generally ignore these fields upon save and may produce a warning message if they are populated. + + The Places API only supports saving of the following \e {core details}: + \list + \o name + \o place id + \o location + \o contact details + \o icon + \o categories + \o visibility scope + \endlist + + It is possible that providers may only support a subset of these. + See the \l {Information about plugins} {provider plugins} for more details. + + Saving of properties such as the rating, extended attributes, + images, reviews, editorials and supplier is explicitly not supported by the Places API. diff --git a/doc/src/place-definition.qdocinc b/doc/src/place-definition.qdocinc new file mode 100644 index 00000000..7cb8c93e --- /dev/null +++ b/doc/src/place-definition.qdocinc @@ -0,0 +1,22 @@ +A place is a point of interest, it could be a favorite restaurant, a park or someone's home. +A QPlace object represents a place by acting as a container for various information about that place. + +This information can be divided into 2 broad classifications + +\list +\o Details +\o Rich content +\endlist + +The place details consists of properties of the place, such as the name, location, contact information etc. +When a place is returned during a search, these details are filled in. Sometimes in order to save bandwidth, +there are further details about the place that can be retrieved on an individual place by place basis, +if the user is interested. The QPlace::detailsFetched() function can be queried to see if all available details +have been fetched, and if not, QPlaceManager::getPlaceDetails() can be used to retrieve them. Precisely which +details are populated during a search and which need to be fetched individually may vary from +provider to provider. (See \l {Information about plugins}). + +The rich content of a place consists items such as images, reviews and editorials. Potentially +there may be many rich content items, so they are treated separately from the place details. +They can be retrieved in a paged fashion via QPlaceManager::getContent(). If necessary, +the content may be assigned to a place so it can act as a convenient container. diff --git a/doc/src/places.qdoc b/doc/src/places.qdoc index 7dac9ec4..1acdbd8a 100644 --- a/doc/src/places.qdoc +++ b/doc/src/places.qdoc @@ -31,41 +31,16 @@ \title Places \previouspage {qtlocation-cpp.html}{QtLocation} - \brief Places enables places of interest to be identified and retrieved by - position and metadata. - \section1 Overview - The Places API allows users to discover places, view rich content about the places - as reviews and images. It can also be used to facilitated management - of places such as saving and removing. + The Places API allows users to discover places/points of interest + and view details about them such as address and contact information; + some places may even have rich content such as images and reviews. + The Places API also facilitates management of places and + categories, allowing users to save and remove them. \section1 Place Definition - A place is a point of interest whether it be a favorite restaurant, a park or someone's home. - A QPlace object describes a place by acting as a container for various information. The information can - be divided into 3 classifications - - \list - \o Core data - \o Detailed data - \o Rich content - \endlist - - The \e {Core} data consists of the bare essential information regarding a place. What comes under core - may vary from provider to provider but typically it would consist of the place name, location, contact information, - categories and icon. When searching for places with an online provider, it is typical that of the candidate places - returned only the core data is populated to save bandwidth. If a user is interested in a particular place, then - the details of that data are retrieved. - - The \e {Detailed} data consists of the remaining place data fields like the supplier and attributes, but with - the exception of rich content as described below. For offline providers the details are usually all available, - so when a search operation is conducted, the places contain detailed information. To check whether a place does - contain detailed information the QPlace::detailsFetched() function can be queried. The QPlaceManager::getPlaceDetails() - function can be used to fetch the details if necessary. - - The \e {Rich Content} consists of media type information such as images and reviews. These are typically paginated - and thus are retrieved independently from the place using the QPlaceManager. \e {Rich Content} can then be assigned - to a place instance as necessary so it can act as a container for the content. + \input place-definition.qdocinc \section1 Common Operations @@ -133,15 +108,26 @@ The usage of the QPlaceContent::Collection and the conversion between content and its subtypes means that code for handling the mechanics of paging reviews, images and editorials can be easily shared. - \section2 Text Prediction + \section2 Text Predictions The retrieval of text predictions is very similar to performing a place search. A QPlaceSearchRequest is used just like a place search, the only difference being that the search term is set to a - semi-completed string. + partially completed string. \snippet snippets/places/requesthandler.h Prediction request And when the request is done, we can use the reply to show the predictions. \snippet snippets/places/requesthandler.h Prediction handler + \section2 Recommendations + Recommendations are suggestions for places that are similar to a specified place. + The retrieval of recommendations is very similar to retrieving text predictions or + performing a place search. + + \snippet snippets/places/requesthandler.h Recommendation + \dots + \dots + \snippet snippets/places/requesthandler.h Recommendation handler + + \target Saving a place cpp \section2 Saving a place The saving of a new place is performed as follows, we create a QPlace instance and populate it with information such as a name, address and coordinate. Once @@ -162,10 +148,19 @@ from a web service will typically not emit these signals while managers accessing places locally stored generally will. \section3 Caveats - The Places API is currently designed for only saving \a {core} data. Saving a place with \e {rich content} - or \a {detailed} data is not a supported use case. Typically a manager will generally ignore these fields upon save and may - produce a warning message if they are populated. - + \input place-caveats.qdocinc + + \section3 Saving between managers + When saving places between managers, there are a few things to be aware of. + Some fields of a place such as the id, categories and icons are manager specific entities + e.g. the categories in one manager may not be recognised in another. + Therefore trying to save a place directly from one manager 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 visibility scope may also need to be modified. + \snippet snippets/places/requesthandler.h Save to different manager + + \target Removing a place cpp \section2 Removing a place The removal of a place is performed as follows: \snippet snippets/places/requesthandler.h Remove place @@ -225,11 +220,19 @@ manager does so is provider specific. Managers accessing places from a web service will typically not emit these signals, while managers accessing places stored locally generally will. - \section1 Places Examples + \section1 Classes in Places + \section2 Data classes + \annotatedlist QtLocation-places-data - \section1 Classes in Places + \section2 Request classes + \annotatedlist QtLocation-places-requests + + \target Places Reply Classes + \section2 Reply classes + \annotatedlist QtLocation-places-replies - \annotatedlist QtLocation-places + \section2 Manager classes + \annotatedlist QtLocation-places-manager */ diff --git a/doc/src/plugins/jsondb.qdoc b/doc/src/plugins/jsondb.qdoc index c7484d04..72fc0abb 100644 --- a/doc/src/plugins/jsondb.qdoc +++ b/doc/src/plugins/jsondb.qdoc @@ -28,13 +28,105 @@ /*! \page location-plugin-jsondb.html \title QtLocation JsonDb plugin +\previouspage {QtLocation Module} + \ingroup QtLocation-plugins \brief Local store for private places. \section1 Overview -Included with QtLocation is a JsonDb store of private places. +Included with QtLocation is a plugin which stores places in a Json database (aka JsonDb) The JsonDb GeoServices plugin can be loaded by using the plugin key "nokia_places_jsondb". + + +\section1 Places +The Nokia JsonDb provider accesses places stored locally on device. +It provides read/write access to the place repository. The specific +capabiliies are outlined below: + +\section2 Capabilities +\table + \row + \o Storage + \o local + \row + \o Read/Write + \o read/write + \row + \o Icon url type(see \l {Icon internals} {QPlaceIcon}) + \o full url + \row + \o Text Prediction + \o no + \row + \o Recommendations + \o no + \row + \o Category structure + \o Hierarchical + \row + \o (Rich) Content images + \o no + \row + \o (Rich) Content reviews + \o no + \row + \o (Rich) Content editorials + \o no + \row + \o All details fetched during search + \o yes + \row + \o Paging offset index + \o yes + \row + \o Paging limit + \o yes + \row + \o Distance relevance hint + \o yes + \row + \o Lexical name relevance hint + \o yes + \row + \o Search term corrections + \o no + \row + \o Extended Attributes + \o no + \row + \o Notifications for added/removed places/categories + \o yes + \row + \o visibility scopes + \o device +\endtable + +\section2 Plugin specific behaviours +\section3 Search +The following list shows what core place data is returned during a place search: +\list +\o name +\o location +\o contact information +\o icon +\o categories +\endlist + +The JsonDb plugin does not support any other details so all +available details are fetched during a search. The JsonDb plugin +does not support saving of any other details. + +\section3 Icons +The icon urls for the JsonDb plugin take the form of a file path. +There can only be one icon image per icon, hence only the +\l {Icon internals} {full url} is supported. No icon variations are +supported. + +\section3 Visibility scope +The JsonDb plugin only supports places of the QtLocation::PrivateVisibility scope. +Specifying the QtLocation::UnspecifiedVisibility when saving a place will default +to the QtLocation::PrivateVisibility scope. */ diff --git a/doc/src/plugins/nokia.qdoc b/doc/src/plugins/nokia.qdoc index 8b08d6fb..099d76c0 100644 --- a/doc/src/plugins/nokia.qdoc +++ b/doc/src/plugins/nokia.qdoc @@ -28,6 +28,7 @@ /*! \page location-plugin-nokia.html \title QtLocation Nokia plugin +\previouspage {QtLocation Module} \ingroup QtLocation-plugins \brief Uses the relevant Nokia services provided by Nokia. @@ -105,4 +106,92 @@ The following table lists optional parameters that can be passed to the Nokia pl \o Client token for the service used for authentication by search manager. \endtable +\section1 Places +The Nokia provider remotely accesses places from a REST based server. It only +provides read-only access the place repository. The specific capabilities +and behaviours are outlined below: + +\section2 Capabilities +\table + \row + \o Storage + \o remote + \row + \o Read/Write + \o read-only + \row + \o Icon url type(see \l {Icon internals} {QPlaceIcon}) + \o not supported + \row + \o Text Prediction + \o yes + \row + \o Recommendations + \o yes + \row + \o Category structure + \o Hierarchical + \row + \o (Rich) Content images + \o yes + \row + \o (Rich) Content reviews + \o yes + \row + \o (Rich) Content editorials + \o yes + \row + \o All details fetched during search + \o no + \row + \o Paging offset index + \o no + \row + \o Paging limit + \o yes + \row + \o Distance relevance hint + \o no + \row + \o Lexical name relevance hint + \o no + \row + \o Search term corrections + \o no + \row + \o Extended Attributes + \o no + \row + \o Notifications for added/removed places/categories + \o no + \row + \o visibility scopes + \o public +\endtable + +\section2 Plugin specific behaviours +\section3 Search +The following list shows what core place data is returned during a place search: +\list +\o name +\o location +\o contact information +\o attribution +\o categories +\o rating +\o visibility +\endlist + +The following list shows further details that may be retrieved +via QPlaceManager::getDetails() +\list +\o supplier +\o extended attributes +\endlist + +\section3 Text prediction +Only a search term and search center is supported for text prediction + +\section3 Recommendation +Only a given place is supported as a parameter for a recommendation. No other parameters are used. */ diff --git a/doc/src/plugins/places-backend.qdoc b/doc/src/plugins/places-backend.qdoc new file mode 100644 index 00000000..7402f5ee --- /dev/null +++ b/doc/src/plugins/places-backend.qdoc @@ -0,0 +1,141 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page location-places-backend.html +\title Places Backend +\previouspage {QtLocation Module} + +\brief The Places backend is responsible for managing a places datastore whether + it is located remotely or locally + +\section1 Overview + +The QPlaceManager interface, provided to clients to allow access to place information, +depends directly on an implementation of QPlaceManagerEngine. The engine provides +the backend function implementations which are called by the manager. + +A places backend implementer needs to derive from QPlaceManagerEngine +and provide implementations for the abstract virtual functions. Most of these +functions are asynchronous and so implementers will also need to derive +the appropriate \l {Places Reply Classes}{reply classes}. The reply objects are reponsible for managing +an asynchronous request; they are used to notify when a request is complete +and hold the results of that request. + +\section2 Implementing/Inheriting reply objects +A reply object would be inherited as follows: +\snippet snippets/places/requesthandler.h Implement reply pt1 +\dots +\snippet snippets/places/requesthandler.h Implement reply pt2 + +The protected functions of QPlaceSearchReply::setResults() and QPlaceSearchReply::setRequest() +are made publically accessible so the plugin can assign results and requests. Because +these functions are not publically exported, accessibility is not so much of an issue. +An alternative would have been to declare a friend class in SearchReply. + +Typically the engine instance would be made the \c parent of the reply. If the developer +fails to discard the replies when finished, the engine can clean those upon destruction. +Commonly, the reply also has a pointer reference back to the engine, which may be used +to emit the QPlaceManager::finished() and QPlaceManager::error() signals. This is +just one of many ways the reply could be implemented. + +Usually the QPlaceReply::finished() signal of the reply is somehow tied to a notification mechanism of the +implementation e.g. for a network based engine, the reply's finished signal may be +emitted from a slot which is in turn is invoked by a QNetworkReply::finished() signal. +Sometimes however, we may want to emit the QPlaceReply::finished() signal without +depending upon an underlying asynchronous notification mechanism. This +is a common case when a portion of functionality is not supported. For example, +a backend may not support text predictions, so we need a way to trigger the finished +signal, but there's no underlying asynchronous mechanism to do so. In this case, +the typical approach is to use QMetaObject::invokeMethod() with a Qt::QueuedConnection, +so that the QPlaceReply::finished(), QPlaceReply::error(), QPlaceManagerEngine::finished() +and QPlaceManagerEngine::error() signals are emitted at the next event loop. + +\snippet snippets/places/requesthandler.h Trigger done +(\note the above code is not necessary if there already is an underlying +asynchronous notification mechanism) + +\section2 Icon Urls + +Icon URLs are provided through the QPlaceManagerEngine::constructIconUrl() function. +Two important concepts regarding icons that needs to be discused +is that of the \e baseUrl and \e fullUrl. +A \e {baseUrl} is an incomplete URL similar to the following: +\code +http://www.example.com/icons/icon_ +or +file://home/user/icons/icon_ +or +http://www.example.com/icons/icon +or +file://home/user/icons/icon +\endcode + +A \e {fullUrl} is a complete URL like: +\code +http://www.example.com/icons/icon.png +or +file://home/user/icons/icon.png +\endcode + +The purpose of the \e {baseUrl} is to accommodate different variations +of the same icon. e.g. A server may provide icons with dimensions of +16x16 but also 48x48 to allow for clients which have different form factors. +Some providers may have a set of icons suited for maps, as well as another +set more suited for lists. These kinds of engines populate the \e {baseUrl} of a place's +QPlaceIcon, + +The \e {baseUrl} is used in conjunction with the +requested size and usage flag parameters of +QPlaceManagerEngine::constructIconUrl() to give the closest matching +url of the icon. e.g. +\code +//base +http://www.example.com/icons/icon_ +//constructed icons +http://www.example.com/icons/icon_48_selected.png +http://www.example.com/icons/icon_16_map.png +http://www.example.com/icons/icon_16_selected_map.png +\endcode + +If a datastore does not support icon variations, then the \e {fullUrl} +of the QPlaceIcon should be populated. The \e baseUrl and \e {fullUrl} +are mutually exclusive, if one is set the other is implicitly cleared. +If the \e {fullUrl} of an icon is used, then the manager engine should +always returns the contents of the \e {fullUrl} as is, regardless of +the variation parameters specified. + +\note It is possible for icon URLs to be \l {http://dataurl.net}{data URLs} where the icon image +itself is embedded into the URL. + +\section2 Categories +The categories of a manager engine are relatively static entities; for engines accessing +remote place datastores it may be desirable to cache the category structure rather than +querying a server every time QPlaceManagerEngine::initializeCategories() is called. +Depending on how dynamic the categories are, always downloading the freshest +set of categories may be more appropriate. +*/ diff --git a/doc/src/qtlocation-cpp.qdoc b/doc/src/qtlocation-cpp.qdoc index f8966e45..f070c08f 100644 --- a/doc/src/qtlocation-cpp.qdoc +++ b/doc/src/qtlocation-cpp.qdoc @@ -29,6 +29,7 @@ \page qtlocation-cpp.html \title QtLocation C++ API \brief Information about the QtLocation C++ API +\previouspage {QtLocation Module} The Location API provides a library for location positioning, mapping and navigation. @@ -41,11 +42,11 @@ Positioning information can be sourced from GPS satellites or a stream of data u NMEA formatted text. Once a position is acquired we can monitor the updated position to see if it moves into or out of a given region. With the Maps API we can associate the position with a map in various formats supplied by a backend. -Then the Places API could be used to populated locations on the Map or even -the current position as a place of interest complete with icons, contact details -and other information. +Then the Places API could be used to populate places on the Map or even +specify the current position as a place of interest and associate it with +an icon, contact details and other information. -The following table provides links to more detailed information on section of the +The following table provides links to more detailed information on sections of the QtLocation C++ API. \table @@ -57,7 +58,7 @@ QtLocation C++ API. \o Displaying maps and finding routes. \row \o \l {Places} - \o Searching for places. + \o Searching for and managing points of interest. \endtable @@ -80,10 +81,8 @@ QtLocation C++ API. -\section1 Location Places of Interest +\section1 Places classes \annotatedlist QtLocation-places - - */ diff --git a/doc/src/qtlocation.qdoc b/doc/src/qtlocation.qdoc index cddad533..b77b7cd7 100644 --- a/doc/src/qtlocation.qdoc +++ b/doc/src/qtlocation.qdoc @@ -51,19 +51,21 @@ Applications can access QtLocation using QML or C++. \o Examples demonstrating use of the QtLocation APIs \endtable -\section1 Plugins +\section1 Information about plugins The QtLocation API uses plugins to enable location services to be implemented by multiple service -providers. The following is a list of GeoServices plugins included with QtLocation. +providers. \annotatedlist QtLocation-plugins -\section1 Information for Backend Implementors +\section1 Information for Backend Implementers \table \row \o \l {QtLocation GeoServices}{GeoServices} \o Information about the QtLocation GeoServices plugins + \row + \o \l {Places Backend} {Places} + \o Information for \l {Places Backend} Implementors \endtable */ - diff --git a/doc/src/snippets/declarative/places.qml b/doc/src/snippets/declarative/places.qml index 55afbe75..a3d8451c 100644 --- a/doc/src/snippets/declarative/places.qml +++ b/doc/src/snippets/declarative/places.qml @@ -224,6 +224,17 @@ Item { //! [Place savePlace] } + function saveToNewPlugin() { + //! [Place save to different plugin] + myPlace.plugin = diffPlugin; + place.placeId = ""; + place.categories = null; + place.icon = null; + place.visibility = QtLocation.UnspecifiedVisibility; //let the manager choose an appropriate default visibility + place.save(); + //! [Place save to different plugin] + } + function getPlaceForId() { //! [Place placeId] place.plugin = myPlugin; diff --git a/doc/src/snippets/places/requesthandler.h b/doc/src/snippets/places/requesthandler.h index eb784d11..9808266b 100644 --- a/doc/src/snippets/places/requesthandler.h +++ b/doc/src/snippets/places/requesthandler.h @@ -46,6 +46,7 @@ #include <QPlaceManager> #include <QPlaceSearchReply> #include <QPlaceImage> +#include <QtCore/QMetaObject> class RequestHandler : public QObject { @@ -58,6 +59,22 @@ public: //! [Initialize Manager] } + void simpleSearch() + { + //! [Simple search] + //1) Make an appropriate request + QPlaceSearchRequest searchRequest; + searchRequest.setSearchTerm("ice cream"); + searchRequest.setSearchArea(new QGeoBoundingCircle(QGeoCoordinate(12.34, 56.78))); + + //2) Use the manager to initiate a request and retreive a reply object + QPlaceSearchReply * searchReply = manager->search(searchRequest); + + //3) Connect the reply object to a slot which is invoked upon operation completion + connect(searchReply, SIGNAL(finished()), this, SLOT(processSearchReply())); + //! [Simple search] + } + void search() { //! [Search for places cpp] @@ -103,7 +120,6 @@ public: //! [Corrections handling pt2] } - void details() { QPlace place; @@ -141,6 +157,17 @@ public: //! [Prediction request] } + void recommendation() + { + //! [Recommendation] + QPlaceSearchRequest request; + request.setSearchArea(new QGeoBoundingCircle(QGeoCoordinate(12.34, 56.78))); + + /* QPlaceSearchReply * */ recommendationReply = manager->recommendations(place, request); + connect(recommendationReply, SIGNAL(finished()), this, SLOT(handleRecommendationReply())); + //! [Recommendation] + } + void savePlace() { //! [Save place pt1] @@ -245,9 +272,67 @@ public: //! [Content request] } + void contentConversion() + { + //! [Content conversion] + QPlaceImage image; + image.setUrl(QUrl("www.example.com")); + + QPlaceContent content = image; + + QPlaceImage image2; + image2 = content; + qDebug() << image2.url(); //image2.url() == "www.example.com" + //! [Content conversion] + } + + void icon() { + QPlace place; + //! [icon] + QUrl iconSourceUrl = place.icon().url(QSize(32,32), QPlaceIcon::Selected | QPlaceIcon::List); + + //A default icon may also be requested like so + iconSourceUrl = place.icon().url(); + //! [icon] + } + + void saveBetweenManagers() { + QPlaceSearchResult result; + QPlaceIdReply *saveReply; + //! [ Save to different manager] + //result retrieved from a different manager + QPlace place = result.place(); + + //clear manager specific fields and + //save to new manager + place.setPlaceId(QString()); + place.setCategories(QList<QPlaceCategory>()); + place.setIcon(QPlaceIcon()); + place.setVisibility(QtLocation::UnspecifiedVisibility); //let the manager choose an appropriate default visibility + saveReply = manager->savePlace(place); + //! [ Save to different manager] + } + + public slots: + // ![Simple search handler] + //4) Have the slot appropriately process the results of the operation + void processSearchReply() { + if (searchReply->error() == QPlaceReply::NoError) { + foreach (const QPlaceSearchResult &result, searchReply->results()) { + if (result.type() == QPlaceSearchResult::PlaceResult) + qDebug() << "Name:" << result.place().name(); + } + } + + //5) Discard the rely object when done. + searchReply->deleteLater(); + searchReply = 0; + } + // ![Simple search handler] + //! [Search for places handler cpp] - void handleSearchReply(){ + void handleSearchReply() { if (searchReply->error() == QPlaceReply::NoError) { foreach (const QPlaceSearchResult &result, searchReply->results()) { if (result.type() == QPlaceSearchResult::PlaceResult) { @@ -316,6 +401,21 @@ public slots: //! [Prediction handler] + //! [Recommendation handler] + void handleRecommendationReply() { + if (recommendationReply->error() == QPlaceReply::NoError) { + foreach (const QPlaceSearchResult &result, searchReply->results()) { + if (result.type() == QPlaceSearchResult::PlaceResult) + qDebug() << result.place().name(); + } + } + recommendationReply->deleteLater(); //discard reply + recommendationReply = 0; + } + + + //! [Recommendation handler] + //! [Save place handler] void handleSavePlaceReply() { if (savePlaceReply->error() == QPlaceReply::NoError) @@ -394,7 +494,25 @@ public slots: } //! [Content handler] + void phoneNumbers() { + //! [Phone numbers] + if (place.contactTypes().contains(QPlaceContactDetail::Phone)) { + foreach (const QPlaceContactDetail &number, place.contactDetails(QPlaceContactDetail::Phone)) + qDebug() << number.label() << ":" << number.value(); + } + //! [Phone numbers] + } + + + void openingHours() { + //! [Opening hours] + if (place.extendedAttributeTypes().contains(QPlaceAttribute::OpeningHours)) + qDebug() << place.extendedAttribute(QPlaceAttribute::OpeningHours).text(); + //! [Opening hours] + } + QPlaceSearchReply *searchReply; +QPlaceSearchReply *recommendationReply; QPlaceManager *manager; QPlaceDetailsReply *detailsReply; QPlaceContentReply *contentReply; @@ -406,3 +524,59 @@ QPlaceIdReply *removeCategoryReply; QPlaceReply *initCatReply; QPlace place; }; + +class ManagerEngine : public QObject +{ +}; + +//! [Implement reply pt1] +class SearchReply : public QPlaceSearchReply +{ +public: + explicit SearchReply(ManagerEngine *engine) + : QPlaceSearchReply(engine), m_engine(engine){} + + ~SearchReply(); + void setResults(const QList<QPlaceSearchResult> &results); + void setRequest(const QPlaceSearchRequest &request); +//! [Implement reply pt1] + +//! [Implement reply pt2] + void triggerDone(QPlaceReply::Error error = QPlaceReply::NoError, + const QString &errorString = QString()); + + ManagerEngine *m_engine; +}; +//! [Implement reply pt2] + +class TextPredictionReply : public QPlaceTextPredictionReply +{ +public: + void triggerDone(QPlaceReply::Error error = QPlaceReply::NoError, + const QString &errorString = QString()); + + ManagerEngine *m_engine; + +}; + +//! [Trigger done] +void TextPredictionReply::triggerDone(QPlaceReply::Error error, + const QString &errorString) +{ + if (error != QPlaceReply::NoError) { + this->setError(error,errorString); + QMetaObject::invokeMethod(m_engine, "error", Qt::QueuedConnection, + Q_ARG(QPlaceReply *,this), + Q_ARG(QPlaceReply::Error, error), + Q_ARG(QString, errorString)); + QMetaObject::invokeMethod(this, "error", Qt::QueuedConnection, + Q_ARG(QPlaceReply::Error, error), + Q_ARG(QString, errorString)); + } + + this->setFinished(true); + QMetaObject::invokeMethod(m_engine, "finished", Qt::QueuedConnection, + Q_ARG(QPlaceReply *,this)); + QMetaObject::invokeMethod(this, "finished", Qt::QueuedConnection); +} +//! [Trigger done] 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<int, QPlaceContent>. 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 @@ -80,6 +80,72 @@ bool QPlaceIconPrivate::operator == (const QPlaceIconPrivate &other) const } /*! + \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. */ QPlaceIcon::QPlaceIcon() @@ -112,7 +178,7 @@ 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 { @@ -120,11 +186,17 @@ bool QPlaceIcon::operator==(const QPlaceIcon &other) const } /*! + \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<QPlaceCategory> 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<QPlaceCategory> 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 <QtCore/qnumeric.h> 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<QPlaceCategory> QPlace::categories() const { @@ -132,7 +190,7 @@ QList<QPlaceCategory> QPlace::categories() const } /*! - Sets categories. + Sets the \a categories that this place belongs to. */ void QPlace::setCategories(const QList<QPlaceCategory> &categories) { @@ -141,7 +199,7 @@ void QPlace::setCategories(const QList<QPlaceCategory> &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<QPlaceContactDetail> QPlace::contactDetails(const QString &contactType) const { @@ -465,6 +535,8 @@ QList<QPlaceContactDetail> 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<QPlaceContactDetail> details) { @@ -477,6 +549,8 @@ void QPlace::setContactDetails(const QString &contactType, QList<QPlaceContactDe /*! Appends a contact \a detail of a specified \a contactType. + + See QPlaceContactDetail for a list of common \l {QPlaceContactDetail::Email}{contact types}. */ void QPlace::appendContactDetail(const QString &contactType, const QPlaceContactDetail &detail) { @@ -508,6 +582,10 @@ void QPlace::setVisibility(QtLocation::Visibility visibility) /*! Returns the visibility of the place. + + The default visibility of a new place is set to QtLocatin::Unspecified visibility. + If a place is saved with unspecified visibility the backend chooses an appropriate + default visibilty to use when saving. */ QtLocation::Visibility QPlace::visibility() const { diff --git a/src/location/qtlocation.cpp b/src/location/qtlocation.cpp index 3e039c74..d8091eeb 100644 --- a/src/location/qtlocation.cpp +++ b/src/location/qtlocation.cpp @@ -59,8 +59,7 @@ namespace QtLocation { Defines the visibility of a QPlace or QPlaceCategory. - \value UnspecifiedVisibility Only used when search for places and categories. Indicates - that results with any visibility should be returned. + \value UnspecifiedVisibility No explicit visibility has been defined. \value DeviceVisibility Places and categories with DeviceVisibility are only stored on the local device. \value PrivateVisibility Places and categories with PrivateVisibility are only visible @@ -68,6 +67,16 @@ namespace QtLocation { on a remote service or both. \value PublicVisibility Places and categories with PublicVisibility are visible to everyone. + + A particular manager may support one or more visibility scopes. For example a manager from one provider may only provide places + that are public to everyone, whilst another may provide both public and private places. + + \note The meaning of unspecified visibility depends on the context it is used. + + When \e saving a place or category, the + default visibility is unspecified meaning that the manager chooses an appropriate visibility scope for the item. + + When \e searching for places, unspecified means that places of any scope is returned. */ } diff --git a/tests/auto/qplacesearchresult/tst_qplacesearchresult.cpp b/tests/auto/qplacesearchresult/tst_qplacesearchresult.cpp index 5cedb44e..5e2900e3 100644 --- a/tests/auto/qplacesearchresult/tst_qplacesearchresult.cpp +++ b/tests/auto/qplacesearchresult/tst_qplacesearchresult.cpp @@ -58,7 +58,7 @@ void tst_QPlaceSearchResult::test() QPlaceSearchResult result; QCOMPARE(result.type(), QPlaceSearchResult::UnknownSearchResult); - QCOMPARE(result.distance(), 0.0); + QVERIFY(qIsNaN(result.distance())); QCOMPARE(result.place(), QPlace()); QVERIFY(result.correction().isEmpty()); |