A list model storing a list of SuggestResult for a LocatorTask. More...
| Header: | #include <SuggestListModel.h> |
| Since: | Esri::ArcGISRuntime 100.0 |
| Inherits: | QAbstractListModel |
Public Types
| enum | SuggestRoles { SuggestLabelRole, SuggestIsCollectionRole } |
Public Functions
| virtual | ~SuggestListModel() override |
| void | clearSuggestParameters() |
| QString | searchText() const |
| void | setSearchText(const QString &searchText) |
| void | setSuggestParameters(const Esri::ArcGISRuntime::SuggestParameters ¶meters) |
| void | setSuggestTimerThreshold(int thresholdInMs) |
| bool | suggestInProgress() const |
| Esri::ArcGISRuntime::SuggestParameters | suggestParameters() const |
| QList<Esri::ArcGISRuntime::SuggestResult> | suggestResults() const |
| int | suggestTimerThreshold() const |
Reimplemented Public Functions
| virtual QVariant | data(const QModelIndex &index, int role = Qt::DisplayRole) const override |
Signals
| void | errorOccurred(const Esri::ArcGISRuntime::Error &error) |
| void | searchTextChanged() |
| void | suggestCompleted() |
| void | suggestInProgressChanged() |
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::setSearchText is called. If you are using QML for your UI, you can use property binding to bind a QML element's text property to SuggestListModel::setSearchText. 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 directly as a QList, using SuggestListModel::suggestResults.
The model returns data for the following roles:
| Role | Type | Description | SuggestRoles |
|---|---|---|---|
| label | QString | The label of the suggestion (ex: 380 New York St. Redlands, CA). | SuggestLabelRole |
| isCollection | bool | A flag indicating if the suggestion is a collection. | SuggestIsCollectionRole |
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::setSearchText 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.
Member Type Documentation
enum SuggestListModel::SuggestRoles
This enum specifies the custom roles which can be used with SuggestListModel::data.
| Constant | Value | Description |
|---|---|---|
Esri::ArcGISRuntime::SuggestListModel::SuggestLabelRole | Qt::UserRole + 1 | The label of the suggestion. |
Esri::ArcGISRuntime::SuggestListModel::SuggestIsCollectionRole | Qt::UserRole + 2 | A flag indicating if the suggestion is a collection. |
Member Function Documentation
[override virtual] SuggestListModel::~SuggestListModel ()
Destructor.
void SuggestListModel::clearSuggestParameters ()
Clears the suggest parameters so that subsequent suggestion requests do not use the currently set parameters.
Use this when you have set suggest parameters, but no longer want to use these parameters. For example, you might want to provide a way for a user to apply categories to their search. In this case, they will need to use SuggestParameters. If the category filters are no longer wanted, you need to call clearSuggestParameters to unset the parameters.
See also setSuggestParameters and SuggestParameters.
[override virtual] QVariant SuggestListModel::data(const QModelIndex &index, int role = Qt::DisplayRole) const
Reimplements: QAbstractItemModel::data(const QModelIndex &index, int role) const.
Returns the data stored under the given role for the suggestion referred to by the index.
- index. The index in the model for which to return data.
- role. The role for which to return data.
[signal] void SuggestListModel::errorOccurred (const Esri::ArcGISRuntime::Error &error)
Signal emitted when an error occurs.
- error - The Error object.
QString SuggestListModel::searchText () const
Returns the search text used to generate suggestions.
See also setSearchText().
[signal] void SuggestListModel::searchTextChanged ()
Signal emitted after the searchText changes for this object.
void SuggestListModel::setSearchText (const QString &searchText )
Sets the searchText used to generate suggestions.
Suggestions are automatically requested whenever this function is called. You can either explicitly call this function 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 function. This will result in suggestions being requested whenever the TextField's text property changes.
See also searchText().
void SuggestListModel::setSuggestParameters (const Esri::ArcGISRuntime::SuggestParameters ¶meters)
Sets 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 use these parameters until clearSuggestParameters is called.
See also suggestParameters().
void SuggestListModel::setSuggestTimerThreshold (int thresholdInMs )
Sets the timer thresholdInMs 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 setSearchText. 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.
See also suggestTimerThreshold().
[signal] void SuggestListModel::suggestCompleted ()
Signal emitted after a suggestion completes.
For example, you could call setSearchText, and once this signal emits, you could access the suggestResults.
bool SuggestListModel::suggestInProgress () const
Returns 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.
[signal] void SuggestListModel::suggestInProgressChanged ()
Signal emitted after suggestInProgress changes for this object.
Esri::ArcGISRuntime::SuggestParameters SuggestListModel::suggestParameters () const
Returns the suggest parameters used to generate suggestions.
See also setSuggestParameters().
QList<Esri::ArcGISRuntime::SuggestResult > SuggestListModel::suggestResults () const
Returns a list of SuggestResults.
Use this to directly obtain the list of SuggestResult, as opposed to hooking up the list model to a view. Obtain these results when the suggestCompleted signal emits.
int SuggestListModel::suggestTimerThreshold () const
Returns the timer threshold used by the SuggestListModel in milliseconds.
The default value is 500 ms.
See also setSuggestTimerThreshold().