Skip To Content ArcGIS for Developers Sign In Dashboard

SuggestListModel QML Type

A list model storing a list of SuggestResult for a LocatorTask. More...

Import Statement: import Esri.ArcGISRuntime 100.6
Since: Esri.ArcGISRuntime 100.0

Properties

Signals

Methods

  • void forEach(callback )
  • SuggestResult get(int index)

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:

RoleTypeDescription
labelstringThe label of the suggestion (ex: 380 New York St. Redlands, CA).

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.


errorChanged()

Emitted when the error property changes, which can indicate that an error occurred.


searchTextChanged()

Emitted when the searchText property of this SuggestListModel changes.


suggestCompleted()

Emitted when the a suggestion task completes, indicating new results are available.


suggestInProgressChanged()

Emitted when the suggestInProgress property of this SuggestListModel changes.


suggestParametersChanged()

Emitted when the suggestParameters property of this SuggestListModel changes.


suggestTimerThresholdChanged()

Emitted when the suggestTimerThreshold property of this SuggestListModel changes.


Method Documentation

void 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.

var 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.



Feedback on this topic?