Wt::WSuggestionPopup Class Reference
[Model/view system]

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

#include <Wt/WSuggestionPopup>

Inheritance diagram for Wt::WSuggestionPopup:

Inheritance graph
[legend]

List of all members.

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.
WAbstractItemModelmodel () 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...


Detailed Description

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

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:
WSuggestionPopup-default-1.png

An example WSuggestionPopup (default)

WSuggestionPopup-polished-1.png

An example WSuggestionPopup (polished)

CSS

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

Note:
This widget requires JavaScript support.

Constructor & Destructor Documentation

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.

See also:
generateMatcherJS(), generateReplacerJS()


Member Function Documentation

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.

See also:
setModelColumn(int)

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.

See also:
setModel()

WAbstractItemModel* Wt::WSuggestionPopup::model (  )  const [inline]

Returns the data model.

See also:
setModel()

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.

See also:
filterModel()

int Wt::WSuggestionPopup::filterLength (  )  const [inline]

Returns the filter length.

See also:
setFilterLength()

Signal< WString >& Wt::WSuggestionPopup::filterModel (  )  [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.

See also:
resize(), maximumWidth(), maximumHeight()

Reimplemented from Wt::WCompositeWidget.


Generated on Thu May 20 18:14:49 2010 for Wt by doxygen 1.5.6