#include <Wt/WSuggestionPopup>
Public Member Functions | |
WSuggestionPopup (const std::string &matcherJS, const std::string &replacerJS, WContainerWidget *parent=0) | |
Construct a WSuggestionPopup with given matcherJS and replacerJS. | |
void | forEdit (WFormWidget *edit) |
Let this suggestion popup assist in editing the given edit field. | |
void | clearSuggestions () |
Clear the list of suggestions. | |
void | addSuggestion (const WString &suggestionText, const WString &suggestionValue) |
Add a new suggestion. | |
void | setModel (WAbstractItemModel *model) |
Set the model to be used for the suggestions. | |
void | setModelColumn (int index) |
Set the column in the model to be used for the items. | |
WAbstractItemModel * | model () const |
Return the data model. | |
Static Public Member Functions | |
static std::string | generateMatcherJS (const Options &options) |
Create a matcher JavaScript function based on some generic options. | |
static std::string | generateReplacerJS (const Options &options) |
Create 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 class is initialized with two JavaScript functions, one for filtering the suggestions, and one for editing the value of the textarea when a suggestion is selected. Two static methods, generateMatcherJS() and generateReplacerJS() may be used to generate these functions based on a set of options (in the Options struct). If the flexibility provided in this way is not sufficient, and writing JavaScript does not give you an instant heart-attack, you may provide your own implementations.
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) remove markup from the suggestion // 2) check suggestion if it matches // 3) 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(Wt::WSuggestionPopup::generateMatcherJS(contactOptions), Wt::WSuggestionPopup::generateReplacerJS(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()); // set style popup->setStyleClass("suggest");
Example CSS:
.suggest {
background-color: #e0ecff;
color: #1010cc;
border: 1px solid #666666;
cursor: default;
font-size: smaller;
padding: 2px;
}
.suggest span {
padding-left: 0.5em;
padding-right: 0.5em;
}
.suggest .sel {
background-color: #C3D9FF;
}
A screenshot of this example:
Example of WSuggestionPopup
void Wt::WSuggestionPopup::forEdit | ( | WFormWidget * | edit | ) |
Let 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 | ) |
Set 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 | ) |
Set 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] |