DOKK / manpages / debian 12 / tklib / widget_listentry.3tk.en
widget_listentry(3tk) widget::listentry widget widget_listentry(3tk) 







widget_listentry - widget::listentry widget








package require Tcl 8.5


package require Tk 8.5


package require widget::listentry ?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::listentry pathname ?options?


widgetCmd destroy


widgetCmd configure


widgetCmd configure option value
  ...


widgetCmd configure option


widgetCmd cget option


{*}cmdprefix get


{*}cmdprefix set values


{*}cmdprefix text errvar


{*}cmdprefix text


{*}cmdprefix cookievar












This package provides a megawidget for the interactive entry of
    ordered and unordered lists. For a simpler and more restricted megawidget
    please see the package widget::listsimple.








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.

  










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.

  










This section explains all the options available to instances of
    widget::listentry. 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.







  

  
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.

  

  

  
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.

  

  

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

  





  

  
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





  

  
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.



  

  
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.









  

  
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.

  

  
This option specifies the status of the widget, normal (= active),
      or disabled. A disabled widget can not be edited.
    
The default is normal.

  

  

  
This option specifies the height of the internal listbox, in lines.
    
The default is 20.

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  
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.

  
























This document, and the package it describes, will undoubtedly
    contain bugs and other problems. Please report such in the category
    widget::listentry 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.








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







  

    0.1.2
    tklib