bionic (3) widget_listsimple.3tk.gz
NAME
widget_listsimple - widget::listsimple widget
SYNOPSIS
package require Tcl 8.5
package require Tk 8.5
package require widget::listsimple ?0.1?
package require widget::validator ?0.1?
package require widget::scrolledwindow
package require snit
package require tooltip
package require img::png
package require msgcat
widget::listsimple pathname ?options?
widgetCmd destroy
widgetCmd configure
widgetCmd configure option value ...
widgetCmd configure option
widgetCmd cget option
{*}cmdprefix get
{*}cmdprefix set values
{*}cmdprefix text errvar
_________________________________________________________________
DESCRIPTION
This package provides a megawidget for the interactive entry of unordered lists. For a megawidget
allowing the entry of ordered lists, and more, please see the package widget::listentry.
CLASS API
The widget class supports a single command, for the creation of widgets.
widget::listsimple pathname ?options?
This command creates and configures new instances of the widget.
For details on the available options please see section Widget Options.
The result of the command is the pathname of the new widget.
INSTANCE API
All widget instances supported the following methods.
widgetCmd destroy
This method destroys the widget. Any further access to the widget will generate errors.
The result of the command is the empty string.
widgetCmd configure
This method comes in three variants. This variant here returns a list containing the current
configuration of the widget, i.e. the values for all options.
For details on the available options please see section Widget Options.
widgetCmd configure option value ...
This method comes in three variants. This variant here reconfigures the widget, setting the
specified options to the given values.
Note that it is not possible to change the construction-time only options.
For details on the available options please see section Widget General Options.
The result of the command is the empty string.
widgetCmd configure option
This method comes in three variants. This variant here is an alias for the method cget below and
identical to it.
widgetCmd cget option
This method returns the current value of the specified option.
For details on the available options please see section Widget Options.
WIDGET OPTIONS
This section explains all the options available to instances of widget::listsimple. Please note that a
few of the options can be set only at instance construction time. The majority of the options can however
be set both during construction- and runtime.
WIDGET CONSTRUCTION-TIME ONLY OPTIONS
-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 system 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.
WIDGET GENERAL OPTIONS
-listvariable varname
This option specifies the variable holding the list to be manipulated by the widget. Any changes
to the list outside of the widget are automatically imported into the widget. Similarly, all
changes made to the list by the widget are automatically exported to this variable.
-skin-add string
-skin-remove string
-skin-tip-add string
-skin-tip-remove string
-skin-tip-main string
-skin-tip-entry string
-skin-tip-list string
-skin-tip-empty string
-skin-tip-duplicate string
-skin-tip-add-none string
-skin-tip-remove-none string
-skin-img-add image
-skin-img-remove image
-skin-invalid-color color
These options all modify the appearance of the widget, i.e. its skin.
All options taking a string argument influence the various labels shown, with the -skin-tip-*
options influencing the tooltips shown on hovering the over various parts in particular.
All the strings are run through msgcat first, enabling text localization through message catalogs.
The default values are keys into the message catalogs which are part of the package itself.
The options taking images modify the images shown on the buttons for adding and removing elements
of the list. They default to the PNG images distributed with the package itself.
The single option taking a color value modifies the color used to highlight invalid data entered
into the internal entry field of the widget. This option defaults to yellow.
EXAMPLE
KEYWORDS
data entry lists, data entry set of strings, data entry unordered list, list entry panel, set entry
panel, widget