The Place type represents a location that is a position of interest. 更多...
| import 语句： | import QtLocation 6.5 |
| Since: | QtLocation 5.5 |
The Place type represents a physical location with additional metadata describing that location. Contrasted with 定位 , 地址 ，和 coordinate type which are used to describe where a location is. The basic properties of a Place are its name and location .
Place objects are typically obtained from a search model and will generally only have their basic properties set. The detailsFetched property can be used to test if further property values need to be fetched from the Plugin . This can be done by invoking the getDetails () method. Progress of the fetching operation can be monitored with the status property, which will be set to Place.Fetching when the details are being fetched.
The Place type has many properties holding information about the location. Details on how to contact the place are available from the contactDetails property. Convenience properties for obtaining the primary phone , fax , email and website are also available.
Each place is assigned zero or more categories . Categories are typically used when searching for a particular kind of place, such as a restaurant or hotel. Some places have a ratings object, which gives an indication of the quality of the place.
Place metadata is provided by a supplier who may require that an attribution message be displayed to the user when the place details are viewed.
Places have an associated icon which can be used to represent a place on a map or to decorate a delegate in a view.
Places may have additional rich content associated with them. The currently supported rich content include editorial descriptions, reviews and images. These are exposed as a set of models for retrieving the content. Editorial descriptions of the place are available from the editorialModel property. Reviews of the place are available from the reviewModel property. A gallery of pictures of the place can be accessed using the imageModel 特性。
Places may have additional attributes which are not covered in the formal API. The extendedAttributes property provides access to these. The type of extended attributes available is specific to each Plugin .
A Place is almost always tied to a plugin 。 plugin property must be set before it is possible to call save (), remove () 或 getDetails ()。 reviewModel , imageModel and editorialModel are only valid then the plugin property is set.
若 Plugin supports it, the Place type can be used to save a place. First create a new Place and set its properties:
Place { id: myPlace plugin: myPlugin name: "Brisbane Technology Park" location: Location { address: Address { street: "53 Brandl Street" city: "Eight Mile Plains" postalCode: "4113" country: "Australia" } coordinate { latitude: -27.579646 longitude: 153.100308 } } visibility: Place.PrivateVisibility }
Then invoke the save () method:
myPlace.save();
The status property will change to Place.Saving and then to Place.Ready if the save was successful or to Place.Error if an error occurs.
若 placeId property is set, the backend will update an existing place otherwise it will create a new place. On success the placeId property will be updated with the identifier of the newly saved place.
The Places API is currently designed for only saving core details. Saving rich content like images and reviews or details like supplier and rating is not a supported use case. Typically a manager will generally ignore these fields upon save and may produce a warning message if they are populated.
The Places API only supports saving of the following core details :
It is possible that providers may only support a subset of these. See the plugin documentation 了解更多细节。
Saving of properties such as the rating, extended attributes, images, reviews, editorials and supplier is explicitly not supported by the Places API.
When saving places between plugins, there are a few things to be aware of. Some fields of a place such as the id, categories and icons are plugin specific entities. For example the categories in one manager may not be recognised in another. Therefore trying to save a place directly from one plugin to another is not possible.
It is generally recommended that saving across plugins be handled as saving favorites as explained in the Favorites section. However there is another approach which is to create a new place, set its (destination) plugin and then use the copyFrom () method to copy the details of the original place. Using copyFrom () only copies data that is supported by the destination plugin, plugin specific data such as the place identifier is not copied over. Once the copy is done, the place is in a suitable state to be saved.
The following snippet provides an example of saving a place to a different plugin using the copyFrom 方法：
var place = Qt.createQmlObject('import QtLocation 5.3; Place { }', parent); place.plugin = destinationPlugin; place.copyFrom(originalPlace); place.save();
To remove a place, ensure that a Place object with a valid placeId property exists and call its remove () 方法。 status property will change to Place.Removing and then to Place.Ready if the save was successful or to Place.Error if an error occurs.
The Places API supports the concept of favorites. Favorites are generally implemented by using two plugins, the first plugin is typically a read-only source of places (origin plugin) and a second read/write plugin (destination plugin) is used to store places from the origin as favorites.
Each Place has a favorite property which is intended to contain the corresponding place from the destination plugin (the place itself is sourced from the origin plugin). Because both the original place and favorite instances are available, the developer can choose which properties to show to the user. For example the favorite may have a modified name which should be displayed rather than the original name.
Text { text: place.favorite ? place.favorite.name : place.name }
The following demonstrates how to save a new favorite instance. A call is made to create/initialize the favorite instance and then the instance is saved.
place.initializeFavorite(destinationPlugin); //if necessary customizations to the favorite can be made here. //... place.favorite.save();
The following demonstrates favorite removal:
place.favorite.remove(); ... //check successful removal of the favorite by monitoring its status. //once that is done we can assign null to the favorite place.favorite = null;
The PlaceSearchModel has a favoritesPlugin property. If the property is set, any places found during a search are checked against the favoritesPlugin to see if there is a corresponding favorite place. If so, the favorite property of the Place is set, otherwise the favorite property is remains null.
另请参阅 PlaceSearchModel .
|
attribution : string |
This property holds a rich text attribution string for the place. Some providers may require that the attribution be shown to the user whenever a place is displayed. The contents of this property should be shown to the user if it is not empty.
This property holds the list of categories this place is a member of. The categories that can be assigned to a place are specific to each plugin .
|
[read-only] contactDetails : ContactDetails |
This property holds the contact information for this place, for example a phone number or a website URL. This property is a map of contactDetail 对象。
|
[read-only] detailsFetched : bool |
This property indicates whether the details of the place have been fetched. If this property is false, the place details have not yet been fetched. Fetching can be done by invoking the getDetails () 方法。
另请参阅 getDetails ().
|
[read-only] editorialModel : EditorialModel |
This property holds a model which can be used to retrieve editorial descriptions of the place.
|
[read-only] extendedAttributes : ExtendedAttributes |
This property holds the extended attributes of a place. Extended attributes are additional information about a place not covered by the place's properties.
|
favorite : Place |
This property holds the favorite instance of a place.
|
icon : 图标 |
This property holds a graphical icon which can be used to represent the place.
|
[read-only] imageModel : ImageModel |
This property holds a model which can be used to retrieve images of the place.
|
location : QtPositioning::Location |
This property holds the location of the place which can be used to retrieve the coordinate, address and the bounding box.
|
name : string |
This property holds the name of the place which can be used to represent the place.
|
placeId : string |
This property holds the unique identifier of the place. The place identifier is only meaningful to the Plugin that generated it and is not transferable between 插件 . The place id is not guaranteed to be universally unique, but unique within the Plugin that generated it.
If only the place identifier is known, all other place data can fetched from the Plugin .
place.plugin = myPlugin;
place.placeId = "known-place-id";
place.getDetails();
|
plugin : Plugin |
此特性保持 Plugin that provided this place which can be used to retrieve more information about the service.
|
[read-only] primaryEmail : string |
This property holds the primary email address of the place. If no "email" contact detail is defined for this place this property will be an empty string. It is equivalent to
var primaryEmail;
if (place.contactDetails["email"].length > 0)
primaryEmail = place.contactDetails["email"][0].value;
|
[read-only] primaryFax : string |
This property holds the primary fax number of the place. If no "fax" contact detail is defined for this place this property will be an empty string. It is equivalent to
var primaryFax;
if (place.contactDetails["fax"].length > 0)
primaryFax = place.contactDetails["fax"][0].value;
|
[read-only] primaryPhone : string |
This property holds the primary phone number of the place. If no "phone" contact detail is defined for this place, this property will be an empty string. It is equivalent to:
var primaryPhone;
if (place.contactDetails["phone"].length > 0)
primaryPhone = place.contactDetails["phone"][0].value;
|
[read-only] primaryWebsite : string |
This property holds the primary website url of the place. If no "website" contact detail is defined for this place this property will be an empty string. It is equivalent to
var primaryWebsite;
if (place.contactDetails["website"].length > 0)
primaryWebsite = place.contactDetails["website"][0].value;
|
ratings : Ratings |
This property holds ratings of the place. The ratings provide an indication of the quality of a place.
|
[read-only] reviewModel : ReviewModel |
This property holds a model which can be used to retrieve reviews about the place.
|
[read-only] status : enumeration |
This property holds the status of the place. It can be one of:
| Place.Ready | No error occurred during the last operation, further operations may be performed on the place. |
| Place.Saving | The place is currently being saved, no other operation may be performed until complete. |
| Place.Fetching | The place details are currently being fetched, no other operations may be performed until complete. |
| Place.Removing | The place is currently being removed, no other operations can be performed until complete. |
| Place.Error | An error occurred during the last operation, further operations can still be performed on the place. |
The status of a place can be checked by connecting the status property to a handler function, and then have the handler function process the change in status.
place.statusChanged.connect(statusChangedHandler); ... function statusChangedHandler() { if (statusChangedHandler.prevStatus === Place.Saving) { switch (place.status) { case Place.Ready: console.log('Save successful'); break; case Place.Error: console.log('Save failed'); break; default: break; } } statusChangedHandler.prevStatus = place.status; }
|
supplier : Supplier |
This property holds the supplier of the place data. The supplier is typically a business or organization that collected the data about the place.
|
visibility : enumeration |
This property holds the visibility of the place. It can be one of:
| Place.UnspecifiedVisibility | The visibility of the place is unspecified, the default visibility of the Plugin 会被使用。 |
| Place.DeviceVisibility | The place is limited to the current device. The place will not be transferred off of the device. |
| Place.PrivateVisibility | The place is private to the current user. The place may be transferred to an online service but is only ever visible to the current user. |
| Place.PublicVisibility | The place is public. |
Note that visibility does not affect how the place is displayed in the user-interface of an application on the device. Instead, it defines the sharing semantics of the place.
|
void copyFrom ( Place original ) |
Copies data from an original place into this place. Only data that is supported by this place's plugin is copied over and plugin specific data such as place identifier is not copied over.
|
string errorString () |
Returns a string description of the error of the last operation. If the last operation completed successfully then the string is empty.
|
void getDetails () |
This method starts fetching place details.
The status property will change to Place.Fetching while the fetch is in progress. On success the object's properties will be updated, status will be set to Place.Ready and detailsFetched will be set to true. On error status will be set to Place.Error. The errorString () method can be used to get the details of the error.
|
void initializeFavorite ( Plugin destinationPlugin ) |
Creates a favorite instance for the place which is to be saved into the destination plugin
destinationPlugin
. This method does nothing if the favorite property is not
null
.
|
void remove () |
This method performs a remove operation on the place.
The status property will change to Place.Removing while the save operation is in progress. On success status will be set to Place.Ready. On error status will be set to Place.Error. The errorString () method can be used to get the details of the error.
|
void save () |
This method performs a save operation on the place.
The status property will change to Place.Saving while the save operation is in progress. On success the status will be set to Place.Ready. On error status will be set to Place.Error. The errorString () method can be used to get the details of the error.
若 placeId property was previously empty, it will be assigned a valid value automatically during a successful save operation.
注意，
PlaceSearchModel
将调用
Place::getDetails
on any place that it detects an update on. A consequence of this is that whenever a Place from a
PlaceSearchModel
is successfully saved, it will be followed by a fetch of place details, leading to a sequence of state changes of
Saving
,
Ready
,
Fetching
,
Ready
.