SuggestListModel QML Type
A list model storing a list of SuggestResult for a LocatorTask. More...
| Import Statement: | import Esri.ArcGISRuntime |
| Since: | Esri.ArcGISRuntime 100.0 |
Properties
- count : int
- error : Error
- searchText : string
- suggestInProgress : bool
- suggestParameters : SuggestParameters
- suggestTimerThreshold : int
Signals
- countChanged()
- errorChanged()
- searchTextChanged()
- suggestCompleted()
- suggestInProgressChanged()
- suggestParametersChanged()
- suggestTimerThresholdChanged()
Methods
Detailed Description
Suggestions are used to create an auto-complete experience, where as a user types an address, potential matches are returned and displayed to the user. The potential matches that are returned are the SuggestResults. Suggestions can be made for street addresses, points of interest by name, points of interest by type (such as "restaurant"), administrative place names (such as "Seattle"), or postal codes.
The SuggestListModel is meant to simplify the workflow of obtaining suggestions from the LocatorTask, and populating the resulting information into a view. The task for fetching new suggestions will be executed whenever SuggestListModel::searchText is set. You can use property binding to bind a QML element's text property to SuggestListModel::searchText. For example, you could declare a TextField, and whenever that element's text value changes, it automatically gets the updated suggestions. You can also use property binding to bind a view's (e.g. ListView) model property to this SuggestListModel. This will result in the view UI component to update automatically whenever the model's data changes. Alternatively, if you do not want to populate the results in a view component, you can access the SuggestResults with the forEach or get methods.
The model returns data for the following roles:
| Role | Type | Description |
|---|---|---|
| label | string | The label of the suggestion (ex: 380 New York St. Redlands, CA). |
| isCollection | bool | A flag indicating if the suggestion is a collection. |
Note: There is no limit to how many concurrent tasks can be started. For example, if the suggestTimerThreshold is set very low, then potentially many requests can be run concurrently. With that, there is no guarantee that results will be processed in the order they were started. Use suggestTimerThreshold to fine tune how frequently new requests for suggestions will be made.
Note: Assigning an empty string to SuggestListModel::searchText will not start a task and will instead clear the model's data. This is needed so that if a user begins typing, and then deletes what they just typed, the previous results will not be displayed. The only exception to this rule is if SuggestParameters have been assigned using categories, in which case an empty string is acceptable (a user may want to search for all coffee shops, but not provide additional search text).
See also LocatorTask, SuggestParameters, and SuggestResult.
Property Documentation
count : int |
Returns the number of SuggestResults in this model (read-only).
error : Error |
Returns the error object (read-only).
searchText : string |
The search text used to generate suggestions.
Suggestions are automatically requested whenever this property is set. You can either explicitly set this property to generate suggestions, or use property binding to automatically retrieve suggestions whenever another object's property changes. A common example is to create a TextField, and to bind the TextField's text property to this property. This will result in suggestions being requested whenever the TextField's text property changes.
suggestInProgress : bool |
Whether a suggestion task is currently in progress.
This is useful for hooking up a busy indicator to notify the user that a search is in progress.
suggestParameters : SuggestParameters |
The suggest parameters used to generate suggestions.
SuggestParameters allow for more fine-grained control over the suggestion task. For example, you may want to set a search extent or to only search for restaurants. If this suggest parameters are set, all suggestions will implicitely use the provided parameters. To clear the currently applied parameters, set this property to null.
suggestTimerThreshold : int |
The timer threshold used by the SuggestListModel.
The SuggestListModel is designed to be bound to a text field, where tasks can be kicked off every time the user types a character. This is achieved through binding the text field to SuggestListModel::searchText. However, you may want to throttle this down to minimize the amount of concurrent requests being made. The suggest timer threshold can be used to set the time that should elapse between requests, based on the provided threshold in milliseconds. If there is no task in progress, a new task is always started. Whenever a new task is started, the timer is restarted, and no new task will start until the task completes or the timer has finished. When the task completes or the timer has finished, it will determine if the user typed any text while it was running and run a new task with the latest text.
For example, consider the following scenario where the threshold is set to 3000 ms, and the user is typing the string "Redlands":
- A user types "R" which starts a new task to get suggestions for "R".
- The timer begins its 3000 ms countdown.
- While the timer is running, but before results are returned, the user continues to type "edlands" and then waits.
- Results are returned and the UI is updated for "R" (this can happen while the timer is running, before it has elapsed).
- When the timer has elapsed, the SuggestListModel determines that another suggest is needed so a new one is kicked off with "Redlands", which was the last searchText entered.
- Results are returned for "Redlands".
The default value is 500 ms.
Signal Documentation
countChanged() |
Emitted when the count property of this SuggestListModel changes.
Note: The corresponding handler is onCountChanged.
errorChanged() |
Emitted when the error property changes, which can indicate that an error occurred.
Note: The corresponding handler is onErrorChanged.
searchTextChanged() |
Emitted when the searchText property of this SuggestListModel changes.
Note: The corresponding handler is onSearchTextChanged.
suggestCompleted() |
Emitted when the a suggestion task completes, indicating new results are available.
Note: The corresponding handler is onSuggestCompleted.
suggestInProgressChanged() |
Emitted when the suggestInProgress property of this SuggestListModel changes.
Note: The corresponding handler is onSuggestInProgressChanged.
suggestParametersChanged() |
Emitted when the suggestParameters property of this SuggestListModel changes.
Note: The corresponding handler is onSuggestParametersChanged.
suggestTimerThresholdChanged() |
Emitted when the suggestTimerThreshold property of this SuggestListModel changes.
Note: The corresponding handler is onSuggestTimerThresholdChanged.
Method Documentation
error forEach(callback) |
Receives a callback function to execute for each suggest result in the model.
The callback function can take 0 to 3 optional arguments, in order:
- element Current suggest result.
- index Current index in array.
- array Reference to SuggestListModel.
Returns undefined if no error occurred, and an error message otherwise.
const error = suggestListModel.forEach(function(element, index, array) { ... }); if (error) { console.error(error.message); }
SuggestResult get(int index) |
Gets the SuggestResult at a given index in the model.