#include <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. | |
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 is only available when JavaScript is enabled.
This widget may be associated with one or more WFormWidget (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.
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 // and store pre-processed. // return a function that matches a 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 and suggestionValue are the displayed text // and stored value for the matched suggestion. 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 = { "<B>", // highlightBeginTag "</B>", // highlightEndTag ',', // listSeparator (for multiple addresses) " \\n", // whitespace "-., \"@\\n;", // wordSeparators (within an address) ", " // appendReplacedText (prepare next email address) }; WSuggestionPopup *popup = new WSuggestionPopup(WSuggestionPopup::generateMatcherJS(contactOptions), WSuggestionPopup::generateReplacerJS(contactOptions), parent); WTextArea *textEdit = new WTextArea(parent); 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.