| qplace.cpp |
!
\class QPlace
\inmodule QtLocation
\ingroup QtLocation-places
\ingroup QtLocation-places-data
\since 5.6
\brief The QPlace class represents a set of data about a place.
\input place-definition.qdocinc
\section1 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 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
\li QPlace::primaryPhone()
\li QPlace::primaryEmail()
\li QPlace::primaryWebsite()
\li QPlace::primaryFax()
\endlist
\section1 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 places/requesthandler.h Opening hours
The attribute types are string values by design to allow providers
to introduce new attribute types.
\section1 Content
The QPlace object is only meant to be a convenient container to hold
rich content such as images, reviews and so on. Retrieval of content
should happen via QPlaceManager::getPlaceContent().
The content is stored as a QPlaceContent::Collection which contains
both the index of the content, as well as the content itself. This enables
developers to check whether a particular item has already been retrieved
and if not, then request that content.
\section2 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).
\section1 Saving Caveats
\input place-caveats.qdocinc
|
20145 |
- |
| qplace.h |
|
3673 |
- |
| qplace_p.h |
|
5210 |
- |
| qplaceattribute.cpp |
!
\class QPlaceAttribute
\inmodule QtLocation
\ingroup QtLocation-places
\ingroup QtLocation-places-data
\since 5.6
\brief The QPlaceAttribute class represents generic attribute information about a place.
A QPlaceAttribute instance stores an additional piece of information about a place that is not
otherwise exposed through the QPlace class. A QPlaceAttribute encapsulates a
localized label which describes the attribute and rich text string representing the attribute's value.
Generally, both are intended to be displayed to the end-user as is.
Some plugins may not support attributes at all, others may only support a
certain set, others still may support a dynamically changing set of attributes
over time or even allow attributes to be arbitrarily defined by the client
application. The attributes could also vary on a place by place basis,
for example one place may have opening hours while another does not.
Consult the \l {Plugin References and Parameters}{plugin
references} for details.
\section1 Attribute Types
The QPlaceAttribute class defines some constant strings which characterize standard \e {attribute types}.
\list
\li QPlaceAttribute::OpeningHours
\li QPlaceAttribute::Payment
\li QPlaceAttribute::Provider
\endlist
There is a class of attribute types of the format x_id_<provider> for example x_id_here.
This class of attributes is a set of alternative identifiers of the place, from the specified provider's
perspective.
The above types are used to access and modify attributes in QPlace via:
\list
\li QPlace::extendedAttribute()
\li QPlace::setExtendedAttribute()
\li QPlace::removeExtendedAttribute()
\li QPlace::removeExtendedAttribute()
\endlist
The \e {attribute type} is a string type so that providers are able to introduce
new attributes as necessary. Custom attribute types should always be prefixed
by a qualifier in order to avoid conflicts.
\section3 User Readable and Non-User Readable Attributes
Some attributes may not be intended to be readable by end users, the label field
of such attributes are empty to indicate this fact.
|
9910 |
- |
| qplaceattribute.h |
|
1901 |
- |
| qplaceattribute_p.h |
|
830 |
- |
| qplacecategory.cpp |
!
\class QPlaceCategory
\inmodule QtLocation
\ingroup QtLocation-places
\ingroup QtLocation-places-data
\since 5.6
\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/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.
If the \l QGeoServiceProvider supports it, categories can be created and removed. This
functionality is available in the \l QPlaceManager class.
|
4074 |
- |
| qplacecategory.h |
|
1872 |
- |
| qplacecategory_p.h |
|
995 |
- |
| qplacecontactdetail.cpp |
!
\class QPlaceContactDetail
\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 and so on.
\section1 Contact Types
The QPlaceContactDetail class defines some constant strings which characterize standard \e {contact types}.
\list
\li QPlaceContactDetail::Phone
\li QPlaceContactDetail::Email
\li QPlaceContactDetail::Website
\li QPlaceContactDetail::Fax
\endlist
These types are used to access and modify contact details in QPlace via:
\list
\li QPlace::contactDetails()
\li QPlace::setContactDetails()
\li QPlace::appendContactDetail()
\li 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.
|
6113 |
- |
| qplacecontactdetail.h |
|
2007 |
- |
| qplacecontactdetail_p.h |
|
800 |
- |
| qplacecontent.cpp |
!
\class QPlaceContent
\inmodule QtLocation
\ingroup QtLocation-places
\ingroup QtLocation-places-data
\since 5.6
\brief The QPlaceContent class holds content about places.
A QPlaceContent holds rich content such as images, reviews, or editorials, as well
as attributes about the content such as the user or supplier of the content. Content
objects might hold multiple data, e.g. an item holding a review typically includes
the user that wrote the review. Use type() to inspect the type of content a
QPlaceContent object represents, and dataTags() to see which data is held. Use value()
to get the individual data as a QVariant.
\b {Note:} Some providers may \e {require} that the attribution string be displayed
to the user whenever a piece of content is viewed.
The rich content of a place is typically made available as paginated items.
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.
|
6400 |
- |
| qplacecontent.h |
|
3270 |
- |
| qplacecontent_p.h |
|
1474 |
- |
| qplacecontentreply.cpp |
!
\class QPlaceContentReply
\inmodule QtLocation
\ingroup QtLocation-places
\ingroup QtLocation-places-replies
\since 5.6
\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, QPlaceManager
|
3915 |
- |
| qplacecontentreply.h |
|
1280 |
- |
| qplacecontentrequest.cpp |
!
\class QPlaceContentRequest
\inmodule QtLocation
\ingroup QtLocation-places
\ingroup QtLocation-places-requests
\since 5.6
\brief The QPlaceContentRequest class represents the parameters of a content request.
The QPlaceContentRequest class is used in conjunction with a QPlaceManager to
retrieve rich content like images and reviews in a paginated fashion.
The following code would request a set of 5 images from the 10th index:
\snippet places/requesthandler.h Content request
\dots
\dots
\snippet places/requesthandler.h Content handler
\sa QPlaceContentReply
|
5432 |
- |
| qplacecontentrequest.h |
|
1953 |
- |
| qplacecontentrequest_p.h |
|
962 |
- |
| qplacedetailsreply.cpp |
!
\class QPlaceDetailsReply
\inmodule QtLocation
\ingroup QtLocation-places
\ingroup QtLocation-places-replies
\since 5.6
\brief The QPlaceDetailsReply class manages a place details fetch operation started by an
instance of QPlaceManager.
See \l {QML Places API#Fetching Place Details}{Fetching Place Details} for an example on how to use a details reply.
\sa QPlaceManager
|
1560 |
- |
| qplacedetailsreply.h |
|
805 |
- |
| qplaceicon.cpp |
!
\class QPlaceIcon
\inmodule QtLocation
\ingroup QtLocation-places
\ingroup QtLocation-places-data
\since 5.6
\brief The QPlaceIcon class represents an icon.
The typical usage of an icon is to use the url() function to specify
a preferred icon size.
\snippet places/requesthandler.h icon
The icons are typically backend dependent, if a manager backend does not support a given size, the URL of the icon that most
closely matches those parameters is returned.
The icon class also has a key-value set of parameters. The precise key one
needs to use depends on the \l {Qt Location#Plugin References and Parameters}{plugin}
being used. These parameters influence which icon URL is returned by
the manager and may also be used to specify icon URL locations when
saving icons.
If there is only ever one image for an icon, then QPlaceIcon::SingleUrl can be used as a parameter
key with a QUrl as the associated value. If this key is set, then the url() function will always return the specified URL
and not defer to any manager.
|
6473 |
- |
| qplaceicon.h |
|
1867 |
- |
| qplaceicon_p.h |
|
825 |
- |
| qplaceidreply.cpp |
!
\class QPlaceIdReply
\inmodule QtLocation
\ingroup QtLocation-places
\ingroup QtLocation-places-replies
\since 5.6
\brief The QPlaceIdReply class manages operations which return an identifier 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 identifier of the place or category that was added, modified or removed.
See \l {Saving a place cpp}{Saving a place} for an example of how to use an identifier reply.
\sa QPlaceManager
|
2970 |
- |
| qplaceidreply.h |
|
919 |
- |
| qplacemanager.cpp |
!
\class QPlaceManager
\inmodule QtLocation
\ingroup QtLocation-places
\ingroup QtLocation-places-manager
\since 5.6
\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
\li Functionality
\li Description
\row
\li Searching for places
\li Using set of parameters such as a search term and search area, relevant places
can be returned to the user.
\row
\li Categories
\li Places can be classified as belonging to different categories. The
manager supports access to these categories.
\row
\li Search term suggestions
\li Given a partially complete search term, a list of potential
search terms can be given.
\row
\li Recommendations
\li Given an existing place, a set of similar recommended places can
be suggested to the user.
\row
\li Rich Content
\li Rich content such as images, reviews etc can be retrieved in a paged
fashion.
\row
\li Place or Category management
\li Places and categories may be saved and removed. It is possible
for notifications to be given when this happens.
\row
\li Localization
\li 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 asynchronous request is generally handled as follows:
\snippet places/requesthandler.h Simple search
\dots
\dots
\snippet 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
\li QPlaceManager::childCategories()
\li QPlaceManager::category()
\li QPlaceManager::parentCategoryId()
\li QPlaceManager::childCategoryIds();
\endlist
If the categories need to be refreshed or reloaded, the initializeCategories() function
may be called again.
|
15988 |
- |
| qplacemanager.h |
|
3000 |
- |
| qplacemanagerengine.cpp |
!
\class QPlaceManagerEngine
\inmodule QtLocation
\ingroup QtLocation-impl
\ingroup QtLocation-places
\ingroup QtLocation-places-manager
\since 5.6
\brief The QPlaceManagerEngine class provides an interface for
implementers of QGeoServiceProvider plugins who want to provide access to place
functionality.
\note There are no source or binary compatibility guarantees for the
backend classes. The API is only guaranteed to work with the Qt version it
was developed against. API changes will however only be made in minor
releases. (6.6, 6.7, and so on.)
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
|
13525 |
- |
| qplacemanagerengine.h |
|
3033 |
- |
| qplacemanagerengine_p.h |
|
904 |
- |
| qplacematchreply.cpp |
!
\class QPlaceMatchReply
\inmodule QtLocation
\ingroup QtLocation-places
\ingroup QtLocation-places-replies
\since 5.6
\brief The QPlaceMatchReply class manages a place matching operation started by an
instance of QPlaceManager.
If the operation is successful, the number of places in the reply matches those
in the request. If a particular place in the request is not found, a default
constructed place is used as a place holder in the reply. In this way, there
is always a one is to one relationship between input places in the request,
and output places in the reply.
If the operation is not successful the number of places is always zero.
See \l {Matching places between managers} for an example on how to use
a match reply.
\sa QPlaceMatchRequest, QPlaceManager
|
2414 |
- |
| qplacematchreply.h |
|
896 |
- |
| qplacematchrequest.cpp |
!
\class QPlaceMatchRequest
\inmodule QtLocation
\ingroup QtLocation-places
\ingroup QtLocation-places-requests
\since 5.6
\brief The QPlaceMatchRequest class is used to find places from one manager that match those from another. It represents
a set of request parameters.
Places from another manager that may have corresponding/matching places in the current manager are assigned using setPlaces() or setResults().
A set of further parameters are specified which determines the criteria for matching.
The typical key for matching is the QPlaceMatchRequest::AlternativeId, the value is an alternative identifier attribute type of the format
x_id_<provider name> for example x_id_here. The provider name is name supplied to the QGeoServiceProvider instance.
See \l {Matching places between managers} for an example on how to use a match request.
\sa QPlaceMatchReply, QPlaceManager
|
5007 |
- |
| qplacematchrequest.h |
|
1843 |
- |
| qplaceproposedsearchresult.cpp |
!
\class QPlaceProposedSearchResult
\inmodule QtLocation
\ingroup QtLocation-places
\ingroup QtLocation-places-data
\since QtLocation 5.2
\brief The QPlaceProposedSearchResult class represents a search result containing a proposed search.
\sa QPlaceSearchResult
|
2068 |
- |
| qplaceproposedsearchresult.h |
|
1010 |
- |
| qplaceproposedsearchresult_p.h |
|
995 |
- |
| qplaceratings.cpp |
!
\class QPlaceRatings
\inmodule QtLocation
\ingroup QtLocation-places
\ingroup QtLocation-places-data
\since 5.6
\brief The QPlaceRatings class holds rating information about a place.
Rating information is used to describe how good a place is conceived to be.
Typically this information is visualized as a number of stars.
The average() function returns an aggregated ratings value out of a possible
maximum as given by the maximum() function.
\snippet places/requesthandler.h Ratings
|
4019 |
- |
| qplaceratings.h |
|
1810 |
- |
| qplaceratings_p.h |
|
829 |
- |
| qplacereply.cpp |
!
\class QPlaceReply
\inmodule QtLocation
\ingroup QtLocation-places
\ingroup QtLocation-places-replies
\since 5.6
\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, that is, 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, that is, each subclass will have appropriate
functions to retrieve the results of an operation.
\sa QPlaceManager
|
6413 |
- |
| qplacereply.h |
|
1713 |
- |
| qplacereply_p.h |
|
741 |
- |
| qplaceresult.cpp |
!
\class QPlaceResult
\inmodule QtLocation
\ingroup QtLocation-places
\ingroup QtLocation-places-data
\since 5.6
\brief The QPlaceResult class represents a search result containing a place.
The PlaceResult holds the distance to the place from the center of the search request,
an instance of the place and an indication of whether the result is
sponsored or \l {http://en.wikipedia.org/wiki/Organic_search}{organic}.
The intended usage is that a QPlaceSearchResult can be converted into a QPlaceResult
like so:
\snippet places/requesthandler.h Convert search result
The implementation is handled in such a way that object slicing is not an issue.
\sa QPlaceSearchResult
|
3158 |
- |
| qplaceresult.h |
|
960 |
- |
| qplaceresult_p.h |
|
903 |
- |
| qplacesearchreply.cpp |
!
\class QPlaceSearchReply
\inmodule QtLocation
\ingroup QtLocation-places
\ingroup QtLocation-places-replies
\since 5.6
\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
|
3432 |
- |
| qplacesearchreply.h |
|
1182 |
- |
| qplacesearchrequest.cpp |
!
\class QPlaceSearchRequest
\inmodule QtLocation
\ingroup QtLocation-places
\ingroup QtLocation-places-requests
\since 5.6
\brief The QPlaceSearchRequest class represents the set of parameters for a search request.
A typical search request may look like the following:
\snippet places/requesthandler.h Search request
Note that specifying a search center can be done by setting a circular search area that has
a center but no radius. The default radius is set to -1, which indicates an undefined radius. The provider will
interpret this as being free to choose its own default radius.
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::searchSuggestions()}{generating search term suggestions}.
Note that in this context only some of the parameters may be relevant. For example, the search area
is useful in narrowing down relevant search suggestions, while other parameters such as relevance hint
are not so applicable.
Also be aware that providers may vary by which parameters they support for example some providers may not support
paging while others do, some providers may honor relevance hints while others may completely ignore them,
see the \l {Qt Location#Plugin References and Parameters}{plugin documentation} for more
details.
|
10679 |
- |
| qplacesearchrequest.h |
|
2698 |
- |
| qplacesearchrequest_p.h |
|
1576 |
- |
| qplacesearchresult.cpp |
!
\class QPlaceSearchResult
\inmodule QtLocation
\ingroup QtLocation-places
\ingroup QtLocation-places-data
\since 5.6
\brief The QPlaceSearchResult class is the base class for search results.
A list of search results can be retrieved from the QPlaceSearchReply after it has
successfully completed the request. Common to all search results are the
\l {QPlaceSearchResult::title()} {title} and \l {QPlaceSearchResult::icon()}{icon},
which can be used to present the search result to the user.
The intended usage is that depending on the \l {QPlaceSearchResult::type()} {type},
the search result can be converted to a more detailed subclass like so:
\snippet places/requesthandler.h Convert search result
The implementation is handled in such a way that object slicing is not an issue.
It is not expected that client applications or backend plugins instantiate
a QPlaceSearchResult directly, but rather client applications simply convert
to search result subclasses and backend plugins only instantiate subclasses.
\sa QPlaceResult
|
4674 |
- |
| qplacesearchresult.h |
|
1952 |
- |
| qplacesearchresult_p.h |
|
2725 |
- |
| qplacesearchsuggestionreply.cpp |
!
\class QPlaceSearchSuggestionReply
\inmodule QtLocation
\ingroup QtLocation-places
\ingroup QtLocation-places-replies
\since 5.6
\brief The QPlaceSearchSuggestionReply class manages a search suggestion operation started by an
instance of QPlaceManager.
On successful completion of the operation, the reply will contain a list of search term
suggestions.
See \l {Search Suggestions} for an example on how to use a search suggestion reply.
\sa QPlaceManager
|
1789 |
- |
| qplacesearchsuggestionreply.h |
|
877 |
- |
| qplacesupplier.cpp |
!
\class QPlaceSupplier
\internal
\inmodule QtLocation
\ingroup QtLocation-places
\ingroup QtLocation-places-data
\since 5.6
\brief The QPlaceSupplier class represents a supplier of a place or content associated
with a place.
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.
|
5844 |
- |
| qplacesupplier.h |
|
2108 |
- |
| qplacesupplier_p.h |
|
876 |
- |
| qplaceuser.cpp |
!
\class QPlaceUser
\inmodule QtLocation
\ingroup QtLocation-places
\ingroup QtLocation-places-data
\since 5.6
\brief The QPlaceUser class represents an individual user.
|
3042 |
- |
| qplaceuser.h |
|
1618 |
- |
| qplaceuser_p.h |
|
762 |
- |
| unsupportedreplies_p.h |
|
8334 |
- |