|
|
              
PlaceSearchModelThe PlaceSearchModel element provides access to place search results. More... Inherits QtObject This type was introduced in Qt Location 5.0. Properties
MethodsDetailed DescriptionPlaceSearchModel provides a model of place search results within the searchArea. The searchTerm and categories properties can be set to restrict the search results to places matching those criteria. The PlaceSearchModel returns both sponsored and organic search results. Sponsored search results will have the sponsored role set to true. The model returns data for the following roles:
Search Result TypesThe type role can take on the following values:
Detection of Updated and Removed PlacesThe PlaceSearchModel listens for places that have been updated or removed from its plugin's backend. If it detects that a place has been updated and that place is currently present in the model, then it will call Place::getDetails to refresh the details. If it detects that a place has been removed, then correspondingly the place will be removed from the model if it is currently present. ExampleThe following example shows how to use the PlaceSearchModel to search for Pizza restaurants in close proximity of a given position. A searchTerm and searchArea are provided to the model and execute() is used to perform a lookup query. Note that the model does not incrementally fetch search results, but rather performs a single fetch when execute() is run. The count is set to the number of search results returned during the fetch. import QtQuick 2.0 import QtLocation 5.0 PlaceSearchModel { id: searchModel plugin: myPlugin searchTerm: "Pizza" searchArea: BoundingCircle { center: Coordinate { // Brisbane longitude: 153.02778 latitude: -27.46778 } } Component.onCompleted: update() } ListView { model: searchModel delegate: Text { text: 'Name: ' + place.name } } PagingThe PlaceSearchModel API has some limited support for paging. The offset and limit properties can be used to access paged search results. When the offset and limit properties are set the search results between offset and (offset + limit - 1) will be returned. For example, if the backend has 5 search results in total [a,b,c,d,e], an offset of 0 specifies that the first item returned in the model will be 'a'. An offset of 1 secifies that the first item in the model will be 'b' and so on. The limit specifies the maximum number of items to be returned. For example, assuming an offset of 0 and limit of 3 then a,b,c is returned. If the offset exceeds (or equals) the total number of items, then 0 results are returned in the model. Note that the API currently does not support a means to retrieve the total number of items available from the backed. Also note that support for offset and limit can vary according to the plugin. CorrectionsThe PlaceSearchModel can return correction results if supported by the plugin. Correction results consist of a string which can be used as a search term for another query and are often used in the context of "Did you mean" corrections. The maximumCorrections property can be used to limit the maximum number of search term correction results that may be returned. Setting maximumCorrections to 0 will prevent any search term correction results from being returned. See also PlaceRecommendationModel, CategoryModel, and QPlaceManager. Property DocumentationThis property holds a list of categories to be used when searching. Returned search results will be for places that match at least one of the categories. This property holds the number of results the model has. Note that it does not refer to the total number of search results available in the backend. The total number of search results is not currently supported by the API. This read-only property holds the textual presentation of latest place search model error. If no error has occurred or if the model was cleared an empty string is returned. An empty string may also be returned if an error occurred which has no associated textual representation. This property holds a set of parameters used to specify how search result places are matched to favorites in the favoritesPlugin. By default the parameter map is empty and implies that the favorites plugin matches by alternative identifiers. Generally, an application developer will not need to set this property. In cases where the favorites plugin does not support matching by alternative identifiers, then the backend plugin documentation should be consulted to see precisely what key-value parameters to set. This property holds the Plugin which will be used to search for favorites. Any places from the search which can be cross-referenced or matched in the favoritesPlugin will have their favorite property set to the corresponding Place from the favoritesPlugin. If the favoritesPlugin is not set, the favorite property of the places in the results will always be null. See also Favorites. This property holds the limit of the number of items that will be returned. See also offset. This property holds the maximum number of search term corrections that may be returned. This property holds a relevance hint used in the search query. The hint is given to the provider to help but not dictate the ranking of results. For example, the distance hint may give closer places a higher ranking but it does not necessarily mean the results will be strictly ordered according to distance. A provider may ignore the hint altogether.
This property holds the search area. The search result returned by the model will be within the search area. If this property is set to a BoundingCircle its radius property may be left unset, in which case the Plugin will choose an appropriate radius for the search. Support for specifying a search area can vary according to the plugin backend implementation. For example, some may support a search center only while others may only support bounding boxes. This property holds search term used in query. The search term is a free-form text string. This property holds the status of the model. It can be one of:
This property holds the visibility scope of the places to search. Only places with the specified visibility will be returned in the search results. The visibility scope can be one of:
Method DocumentationCancels an ongoing search query. See also execute() and status. Returns the data for a given role at the specified row index. Resets the model. All search results are cleared, any outstanding requests are aborted and possible errors are cleared. Model status will be set to PlaceSearchModel.Null. Updates the model based on the provided query parameters. The model will be populated with a list of places matching the search parameters specified by the element's properties. Search criteria is specified by setting properties such as the searchTerm, categories, limit and offset. Support for these properties may vary according to plugin. update() then submits the set of criteria to the plugin to process. While the model is updating the status of the model is set to PlaceSearchModel.Loading. If the model is successfully updated the status is set to PlaceSearchModel.Ready, while if it unsuccessfully completes, the status is set to PlaceSearchModel.Error and the model cleared. BoundingCircle {
id: searchLocation
center: Coordinate {
latitude: 10
longitude: 10
}
}
PlaceSearchModel {
id: model
plugin: backendPlugin
searchArea : searchLocation
...
}
MouseArea {
...
onClicked: {
model.searchTerm = "pizza";
model.categories = null; //not searching by any category
searchLocation.center.latitude = -27.5
searchLocation.center.longitude = 153
model.update();
}
}
|
