Scroll to navigation

widget_listsimple(3tk) widget::listsimple widget widget_listsimple(3tk) 





NAME


widget_listsimple - widget::listsimple widget






SYNOPSIS


package require Tcl 8.5


package require Tk 8.5


package require widget::listsimple ?0.1.2?


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.



  

  
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.



  

  
This method destroys the widget. Any further access to the widget will
      generate errors.
    
The result of the command is the empty string.

  

  

  
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.

  

  

  
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.

  

  

  
This method comes in three variants. This variant here is an alias for the
      method cget below and identical to it.

  

  
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



  

  
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.

  







  

  
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



  

  
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.

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  
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












BUGS, IDEAS, FEEDBACK


This document, and the package it describes, will undoubtedly
    contain bugs and other problems. Please report such in the category
    widget::listsimple of the Tklib Trackers
    [http://core.tcl.tk/tklib/reportlist]. Please also report any ideas for
    enhancements you may have for either package and/or documentation.






KEYWORDS


data entry lists, data entry set of strings, data entry unordered
    list, list entry panel, set entry panel, widget







  

    0.1.2
    tklib