Wt::WSuggestionPopup Class Reference

A widget which popups to assist in editing a textarea or lineedit. More...

#include <Wt/WSuggestionPopup>

Inheritance diagram for Wt::WSuggestionPopup:

[legend]

List of all members.

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

---

Detailed Description

A widget which popups to assist in editing a textarea or lineedit.

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

---

Member Function Documentation

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.