- -ordered boolean
This options tells the new widget instance whether the list it manages
is ordered or not. If it is ordered the widget will show buttons with
which the selected entries can be moved around, editing the order.
The default is false, indicating an unordered list.
- -allow-duplicates boolean
This options tells the new widget instance whether we are allowed to
add a string to the list multiple times, or not.
The default is false, indicating that duplicates are not
allowed.
- -values cmdprefix
This option specifies a callback for the management of a predefined
list of strings a user may enter.
If specified the widget will use a combobox instead of a plain
entry field and fill its list during widget construction using the data
delivered by this callback.
The callback will be further invoked whenever a new value is entered
into the main list, to save the extended list of predefined values.
The signature of this callback is
- {*}cmdprefix get
In this form the callback is expected to return a list of strings.
The strings are loaded into the list of the internal combobox for
quick access by the user.
It will be invoked once, during widget construction, to load the
list of predefined strings a user may enter.
- {*}cmdprefix set values
In this form the callback is given a list of new strings and
expected to save them somewhere for future use.
The return value of the callback is ignored.
This form is invoked whenever the user entered a new string
into the main list. The order of strings in values represents
the order used to show them in the combobox's list.
- -validate cmdprefix
This option specifies a callback which is invoked after every change of
the contents of the internal entry field. The signature of this callback is
- {*}cmdprefix text errvar
where text is the string to validate, and errvar the name of
a variable the callback can store an error message into when it detects
invalid data.
The widget expects that the callback returns a boolean value, where
true indicates that text is valid.
The default validation, when no callback was specified, will treat the
empty string as invalid, and everything else as valid.
Please note that the widget will prevent the entry of
duplicate values into the main list, regardless of the validity of the
input otherwise. This is in keeping with that this widget is meant for
the entry of unordered lists, essentially a set of strings.
- -transform cmdprefix
This option specifies a callback which is invoked whenever a newly
entered element is moved from the entry field to the main list, or the
entry field is validated, as part of a check for duplicates, if such are
not allowed. The callback is given the text in the entry field and has
to return the text which is actually added to, or checked against the list.
The use case for this callback is essentially
input normalization. The most simple case of such would be, for
example the use of
string tolower
to impose a standard letter
case on the data. More complex example can be thought of, like rewriting
of multiple syntaxes of input to a canonical form.
The signature of this callback is
- {*}cmdprefix text
where text is the string to transform.
The widget expects that the callback returns the transformed string.
The default is to not transform the entered strings.
- -browse cmdprefix
If this option is specified the widget will display a "Search" button
and invoke the callback provided by the option whenever the user clicks
on that button.
The signature of the callback is
- {*}cmdprefix cookievar
where the cookie variable provides access to context information the
callback may wish to preserve between invokations. The initial value
stored in the variable is the empty string. After that it is whatever
the callback wishes to store.
The widget expects that the callback returns a list of strings,
which are then added to the list, modulo validity and duplicate checks.
By default there is no browse callback and no button shown.