#include <Wt/WSuggestionPopup>
Public Member Functions | |
WSuggestionPopup (const std::string &matcherJS, const std::string &replacerJS, WContainerWidget *parent=0) | |
Creates a suggestion popup with given matcherJS and replacerJS. | |
WSuggestionPopup (const Options &options, WContainerWidget *parent=0) | |
Creates a suggestion popup with given matcher and replacer options. | |
void | forEdit (WFormWidget *edit) |
Lets this suggestion popup assist in editing the given edit field. | |
void | clearSuggestions () |
Clears the list of suggestions. | |
void | addSuggestion (const WString &suggestionText, const WString &suggestionValue) |
Adds a new suggestion. | |
void | setModel (WAbstractItemModel *model) |
Sets the model to be used for the suggestions. | |
void | setModelColumn (int index) |
Sets the column in the model to be used for the items. | |
WAbstractItemModel * | model () const |
Returns the data model. | |
void | setFilterLength (int count) |
Sets the minimum input length before showing the popup. | |
int | filterLength () const |
Returns the filter length. | |
Signal< WString > & | filterModel () |
Signal that indicates that the model should be filtered. | |
virtual void | setMaximumSize (const WLength &width, const WLength &height) |
Sets a maximum size. | |
Static Public Member Functions | |
static std::string | generateMatcherJS (const Options &options) |
Creates a matcher JavaScript function based on some generic options. | |
static std::string | generateReplacerJS (const Options &options) |
Creates a replacer JavaScript function based on some generic options. | |
Classes | |
struct | Options |
A configuration object to generate a matcher and replacer JavaScript function. More... |
This widget may be associated with one or more WFormWidgets (typically a WLineEdit or a WTextArea).
When the user starts editing one of the associated widgets, this popup will show just below it, offering a list of suggestions that match in some way with the current edit. The mechanism for filtering the total list of suggestions must be specified through a separate 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 member methods clearSuggestions() and addSuggestion() manipulate the model.
The popup may support very large datasets, by using server-side filtering of suggestions based on the input. You can enable this feature using setFilterLength() and then listen to a filter notification using the modelFilter() signal. By using setMaximumSize() you can also limit the maximum height of the popup, in which case scrolling is provided (similar to a combo box).
The class is initialized with an 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 block 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) remove markup from the suggestion // 3) check suggestion if it matches // 4) add markup to suggestion return { match : ..., // does the suggestion match ? (boolean) suggestion : ... // modified suggestion markup }; } }
The replacerJS function block 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 Wt::WSuggestionPopup::Options contactOptions = { "<b>", // highlightBeginTag "</b>", // highlightEndTag ',', // listSeparator (for multiple addresses) " \\n", // whitespace "-., \"@\\n;", // wordSeparators (within an address) ", " // appendReplacedText (prepare next email address) }; Wt::WSuggestionPopup *popup = new Wt::WSuggestionPopup(contactOptions, this); Wt::WTextArea *textEdit = new Wt::WTextArea(this); popup->forEdit(textEdit); // load popup data for (unsigned i = 0; i < contacts.size(); ++i) popup->addSuggestion(contacts[i].formatted(), contacts[i].formatted());
A screenshot of this example:
![]() An example WSuggestionPopup (default) | ![]() An example WSuggestionPopup (polished) |
The suggestion popup is styled by the current CSS theme. The look can be overridden using the Wt-suggest
CSS class and the following selectors:
.Wt-suggest span : A suggestion element .Wt-suggest .sel : A selected suggestion element
Wt::WSuggestionPopup::WSuggestionPopup | ( | const std::string & | matcherJS, | |
const std::string & | replacerJS, | |||
WContainerWidget * | parent = 0 | |||
) |
Creates a suggestion popup with given matcherJS and replacerJS.
See supra for the signature of the matcher and replace JavaScript functions.
Wt::WSuggestionPopup::WSuggestionPopup | ( | const Options & | options, | |
WContainerWidget * | parent = 0 | |||
) |
Creates a suggestion popup with given matcher and replacer options.
void Wt::WSuggestionPopup::forEdit | ( | WFormWidget * | edit | ) |
Lets this suggestion popup assist in editing the given edit field.
A single suggestion popup may assist in several edits by repeated calls of this method.
void Wt::WSuggestionPopup::setModel | ( | WAbstractItemModel * | model | ) |
Sets the model to be used for the suggestions.
The model
may not be 0
, and ownership of the model is not transferred.
The default value is a WStringListModel that is owned by the suggestion popup.
The Wt::DisplayRole is used for the suggestion text. The Wt::UserRole is used for the suggestion value, unless empty, in which case the suggestion text is used as value.
Note that since the default WStringListModel does not support UserRole data, you will want to change it to a more general model (e.g. WStandardItemModel) if you want suggestion values that are different from display values.
void Wt::WSuggestionPopup::setModelColumn | ( | int | index | ) |
Sets the column in the model to be used for the items.
The column index
in the model will be used to retrieve data.
The default value is 0.
WAbstractItemModel* Wt::WSuggestionPopup::model | ( | ) | const [inline] |
void Wt::WSuggestionPopup::setFilterLength | ( | int | count | ) |
Sets the minimum input length before showing the popup.
When the user has typed this much characters, filterModel() is emitted which allows you to filter the model based on the initial input.
The default value is 0, which has the effect of always show the entire model.
int Wt::WSuggestionPopup::filterLength | ( | ) | const [inline] |
Signal that indicates that the model should be filtered.
The argument is the initial input, whose length equals the filterLength().
For example, if you are using a WSortFilterProxyModel, you could react to this signal with:
void MyClass::filterSuggestions(const WString& filter) { proxyModel->setFilterRegExp(filter + ".*"); }
void Wt::WSuggestionPopup::setMaximumSize | ( | const WLength & | width, | |
const WLength & | height | |||
) | [virtual] |
Sets a maximum size.
Specify a minimum size for this widget.
Reimplemented from Wt::WCompositeWidget.