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