Provided by: tklib_0.6-3_all bug

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