Class WSuggestionPopup


public class WSuggestionPopup
extends WPopupWidget
A widget which popups to assist in editing a textarea or lineedit.

This widget may be associated with one or more WFormWidgets (typically a WLineEdit or a WTextArea).

The popup provides the user with suggestions to enter input. The popup can be used by one or more editors, using forEdit(). The popup will show when the user starts editing the edit field, or when the user opens the suggestions explicitly using a drop down icon or with the down key. The popup positions itself intelligently just below or just on top of the edit field. It offers a list of suggestions that match in some way with the current edit field, and dynamically adjusts this list. The implementation for matching individual suggestions with the current text is provided through a JavaScript function. This function may also highlight part(s) of the suggestions to provide feed-back on how they match.

WSuggestionPopup is an MVC view class, using a simple WStringListModel by default. You can set a custom model using setModel(). The model can provide different text for the suggestion text (ItemDataRole.DisplayRole) and value (getEditRole()). The member methods clearSuggestions() and addSuggestion() manipulate this model.

By default, the popup implements all filtering client-side. To support large datasets, you may enable server-side filtering of suggestions based on the input. The server-side filtering may provide a coarse filtering using a fixed size prefix of the entered text, and complement the client-side filtering. To enable server-side filtering, use setFilterLength() and listen to filter notification using the modelFilter() signal. Whenever a filter event is generated you can adjust the model's content according to the filter (e.g. using a WSortFilterProxyModel). By using WCompositeWidget#setMaximumSize() you can also limit the maximum height of the popup, in which case scrolling is supported (similar to a combo-box).

The class is initialized with an WSuggestionPopup.Options struct which configures how suggestion filtering and result editing is done. Alternatively, you can provide two JavaScript functions, one for filtering the suggestions, and one for editing the value of the textarea when a suggestion is selected.

The matcherJS function must have the following JavaScript signature:


 function (editElement) {
 // fetch the location of cursor and current text in the editElement.

 // return a function that matches a given suggestion with the current value of the editElement.
 return function(suggestion) {

 // 1) if suggestion is null, simply return the current text 'value'
 // 2) check suggestion if it matches
 // 3) add highlighting markup to suggestion if necessary

 return { match : ...,      // does the suggestion match ? (boolean)
 suggestion : ...  // modified suggestion with highlighting
 };
 }
 }

 

The replacerJS function that edits the value has the following JavaScript signature.


 function (editElement, suggestionText, suggestionValue) {
 // editElement is the form element which must be edited.
 // suggestionText is the displayed text for the matched suggestion.
 // suggestionValue is the stored value for the matched suggestion.

 // computed modifiedEditValue and modifiedPos ...

 editElement.value = modifiedEditValue;
 editElement.selectionStart = edit.selectionEnd = modifiedPos;
 }

 

To style the suggestions, you should style the <span> element inside this widget, and the <span>."sel" element to style the current selection.

Usage example:


 // options for email address suggestions
 WSuggestionPopup.Options contactOptions = new WSuggestionPopup.Options();
 contactOptions.highlightBeginTag = "<b>";
 contactOptions.highlightEndTag = "</b>";
 contactOptions.listSeparator = ','; //for multiple addresses)
 contactOptions.whitespace = " \n";
 contactOptions.wordSeparators = "-., \"@\n;"; //within an address
 contactOptions.appendReplacedText = ", "; //prepare next email address

 WSuggestionPopup popup = new WSuggestionPopup(contactOptions, this);

 WTextArea textEdit = new WTextArea(this);
 popup.forEdit(textEdit);

 // load popup data
 for (int i = 0; i < contacts.size(); ++i)
 popup.addSuggestion(contacts.get(i).formatted(), contacts.get(i).formatted());

 

A screenshot of this example:

An example WSuggestionPopup (default)

An example WSuggestionPopup (polished)

When using the DropDownIcon trigger, an additional style class is provided for the edit field: Wt-suggest-dropdown, which renders the icon to the right inside the edit field. This class may be used to customize how the drop down icon is rendered.

Note: This widget requires JavaScript support.