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