NAME

       widget_validator - widget::validator behaviour

SYNOPSIS

       package require Tcl  8.5

       package require Tk  8.5

       package require widget::validator  ?0.1?

       widget::validator attach w color cmdprefix

       widget::validator detach w

       widget::validator validate w

________________________________________________________________________________________________________________

DESCRIPTION

       This package provides a unified validation API for ttk's entry and combobox widgets.

       Please  note that the validation behaviour defined in this package will not reject invalid edits. It will
       only highlight the entry containing invalid data and set the proper state flag.

       It is the responsibility of the using package or application to decide how and when  to  actually  reject
       such invalid content.

       widget::validator attach w color cmdprefix
              This method adds a validating behaviour to the widget w.

              Whenever  the  content  of the widget's entry field changes the specified cmdprefix is invoked and
              has to return a boolean value, where true means that content is ok, and false that the content  is
              invalid. For more information on the command prefix see section Validation.  In case of the latter
              the background color of the entry field is changed to color to indicate the invalidity.

              The  system  does  not  support  nesting of validators on a widget, nor the attachment of multiple
              validators. To change validating conditions detach the current validator  first  before  attaching
              the new.

              An error is thrown if the widget has already validating behaviour attached to it.

              The result of the method is the empty string.

              To  achieve  its  aims  the  package  overrides  various  configuration  options of the widget the
              behaviour is attached to. These options are restored to their previous values on detach.

              If other behaviours are attached the  validator  may  be  rendered  temporarily  (partially)  non-
              functional.   Similarly, if the validator is detached while a different behaviour is also attached
              its restoration of configuration settings may render the other non-functional

       widget::validator detach w
              This method removes the validating behaviour from the widget w and restores  it  to  its  original
              state.

              An error is thrown if the widget has no validating behaviour attached to it.

              The result of the method is the empty string.

       widget::validator validate w
              Invoking  this  method  forces  a  validation  of  the  widget w, assuming that it has a validator
              behaviour attached to it.

              The result of the method is the empty string.

VALIDATION

       The command prefix for used for validation has to have the following signature:

       {*}cmdprefix text
              The argument is the text to validate.

              The result of the callback has to be a boolean value where true means that text is ok,  and  false
              that text is invalid.

EXAMPLE

              package require Tk 8.5
              package require widget::validator

              set TE {}
              set TC {}

              ttk::entry    .e -textvariable TE
              ttk::combobox .c -textvariable TC -values {fruit vegetable corn}
              ttk::combobox .n -values {fruit vegetable corn}
              ttk::button   .x -command ::exit -text Exit

              pack .e -expand 1 -fill both -side top
              pack .c -expand 1 -fill both -side top
              pack .n -expand 1 -fill both -side top
              pack .x -expand 1 -fill both -side top

              widget::validator attach .e lightblue {apply {text {
                  expr {$text ne {}}
              }}}

              widget::validator attach .c yellow {apply {text {
                  expr {$text ni {{} hello world}}
              }}}

              widget::validator attach .n pink {apply {text {
                  expr {$text ni {{} blub}}
              }}}

BUGS, IDEAS, FEEDBACK

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

       invalid, state management, ttk::combobox, ttk::entry, validation, widget validation

tklib                                                  0.1                                 widget_validator(3tk)