GRIDPLUS - Validations
Home Reference Manpage Examples Download License Contact

GRIDPLUS Validations

GRIDPLUS provides a simple interface for entry field/widget validation. When a validation is associated with an entry, the validation is performed when the entry looses focus -or- when a button, link -or- menu option (which has been specified with the validate option), is invoked.

If the validation fails, focus is returned to the field which failed the validation. The background color of the entry is set to red and the text color to white. If the window which contains the entry also contains a label widget called "errormessage", the label widget has its text set to the defined error message/text.

Three types of validations are supported:-

Note: There is currently a limitation which prevents a validation taking place if the next widget in the keyboard focus order is a button.

GRIDPLUS Validation Options

The GRIDPLUS set command mode has the following options which are used to set-up/configure entry field validations:-

OptionPurposeDefault
-centurySets year at which abbrieviated format dates are assumed to be in the 20th century.50
-dateformatSets date format (eu European, uk United Kingdom, us United States).us
-errormessageSets the global "errormessage" text.%
-patternSets pattern -or- specifies procedure when creating new validationNone
-textSets validation specific text to be used for percent sustitution in "errormessage".None
-validationSets name of new validation.None

Percent Substitution

Both the -errormessage and -text options can make use of a percent substitution facility.

Where a percent (%) character appears in the string specified by the -errormessage option, it will be replaced by the validation text. The validation text is specified by the -text option for user defined validations.

Where a percent (%) character appears in the string specified by the -text option, it will be replaced by the parameter passed to the User Validation Procedure.

Regular Expression Pattern Match Validations

GRIDPLUS has a small selection of built-in pattern match validations.

Validation NameRegular Expression PatternValidation Text
alpha{^[a-zA-Z]+$}Alpha
alphanum{^[a-zA-Z0-9]+$}Alphanumeric
money{^[0-9]+[.][0-9][0-9]$}Money Format
num{^[0-9]+[.]?[0-9]*$}Numeric
notnull{[^\000]}Not Null
int{^[0-9]+$}Integer

The GRIDPLUS set command mode can be used to create new pattern validations.

Example: gridplus set -validation myval -pattern {^[CR][0-9]{4}$} -text "C or R followed by 4 digits"

Creates a validation called "myval" which checks if the contents of an associated entry has the pattern "{^[CR][0-9]{4}$}". Where the percent (%) substitution is used in errormessage the % character will be replaced with "C or R followed by 4 digits".

Date Validation

The main purpose of the built-in date validation is simply to check if the date in the entry field is a valid date. This validation currently uses the TCL clock command and is, therefore, subject to its limitations.

The date validation also allows for dates to be entered in abbreviated forms depending on the -dateformat and -century options specified. The -century option determintes the year at which dates are assumed to be in the 20th century (Default: 50) when entering dates in an abbrieviated format (See below).

Example: gridplus set -dateformat uk

Sets the date format to "uk" (dd/mm/yyyy).

Format NameDate Format
eudd.mm.yyyy
ukdd/mm/yyyy
usmm/dd/yyyy

Assuming both -dateformat and -century have default values dates can be entered in the following formats:-

FormatExampleDate Converted To
mm/dd/yyyy12/03/200412/03/2004
mmddyyyy1203200412/03/2004
mmddyy12030412/03/2004
mmddyy12036412/03/1964

User Procedure Validations

GRIDPLUS provides a simple method to invoke User Validation Procedures.

The procedure is passed two parameters: The name of the entry field being validated and a user parameter. If no user parameter is specified the user parameter value passed to the procedure is null. To specify the user parameter, a colon delimited parameter is used as a suffix to the name of the validation to be used for a specific GRIDPLUS entry (See the Example).

Note: Parameters must not contain spaces.

To specify that a User Validation Procedure is to be invoked rather than use a regular expression pattern match, the -pattern option is set with name of the procedure prefixed with "proc:".

Example: gridplus set -validation myval -pattern proc:range -text "integer in range %"

Creates a validation called "myval" which checks the contents of an associated using a procedure called "range". Where the percent (%) substitution is used in the string specified by -text the % character will be replaced by the user parameter passed to the validation procedure for the associated entry. Where the percent (%) substitution is used in errormessage the % character will be replaced with "integer in range %".

Validation Example

Window:

If "abc" is entered into "Field One" then either the TAB key -or- the "Validation" button pressed the following is displayed:-

Source Code:

#====================================================================#
# User Validation Procedure: Check if number within specified range. #
#====================================================================#
proc range {entry parameter} {
   global {}

   foreach {lower upper} [split $parameter -] {}

   if {$($entry) >= $lower && $($entry) <= $upper} {return 1}

   return 0
}

#===========================================#
# Procedure invoked by "Validation" button. #
#===========================================#
proc test,validate {} {puts "Validation Pressed"}

#==============================================#
# Proceudre invoked by "No Validation" button. #
#==============================================#
proc test,novalidate {} {puts "No Validation Pressed"}

#=========================================================#
# GRIDPLUS code to set-up validations and display window. #
#=========================================================#

gridplus set -errormessage "Must be %"

gridplus set -validation myvalidation \
             -pattern {^[A-DZ][0-9]{3}[FX]$} \
             -text "A-D or Z followed by three digits with a trailing F or X"

gridplus set -validation range \
             -pattern proc:range \
             -text "integer in range %"


gridplus entry .field -size 40 {
   {"Field One"   .one   !int +}
   {"Field Two"   .two   !date}
   {"Field Three" .three !myvalidation}
   {"Field Four " .four  !range:1-100}
   {"Field Five"  .five  !range:25-50}
}

gridplus button .test -size 12 -takefocus 0 {
   {"Validation" .validate !} {"No Validation" .novalidate}
}

label .errormessage -foreground red

gridplus layout .main -title "Validation Example" {
   .field
   .test
   .errormessage
}

pack .main

Comments:

proc range {entry parameter} {
   global {}

   foreach {lower upper} [split $parameter -] {}

   if {$($entry) >= $lower && $($entry) <= $upper} {return 1}

   return 0
}

Creates a User Validation Procedure call "range".

User Validation Procedures are passed two parameters: The name of the entry field being validated and a user parameter. If no parameter is specified the parameter value passed to the procedure is null.

This procedure requires that a parameter is passed which has the following format:-

lower-upper

Where lower is the lowest and upper is the highest integer to be accepted. For example: 25-100 will check if the value of the entry is an integer in the range 25 to 100.

proc test,validate   {} {puts "Validation Pressed"}

Creates a procedure called "test,validate" which is invoked when the "Validation" button is pressed.

proc test,novalidate   {} {puts "No Validation Pressed"}

Creates a procedure called "test,novalidate" which is invoked when the "No Validation" button is pressed.

gridplus set -errormessage "Must be %"

Sets GRIDPLUS global error message to "Must be %". The % character will be replaced by the validation specific text (See Percent Substitution).

gridplus set -validation myvalidation \
             -pattern {^[A-DZ][0-9]{3}[FX]$} \
             -text "A-D or Z followed by three digits with a trailing F or X"

Creates a new Regular Expression Pattern Match Validation called "myvalidation". Entry fields associated with this validation will be checked against the regular expression pattern "{^[A-DZ][0-9]{3}[FX]$}".

If the validation fails the ".errormessage" label will be set to:-

Must be A-D or Z followed by three digits with a trailing F or X

gridplus set -validation range \
             -pattern proc:range \
             -text "integer in range %"

Creates a User Validation Procedure called "range". Entry fields associated with this validation will be checked using a procedure called "range" as specified by the "-pattern proc:range" option. The % character will be replaced by the parameter passed to the User Validation Procedure. (See Percent Substitution).

Assuming the "range" procedure is passed the parameter "1-100", if the validation fails the ".errormessage" label will be set to:-

Must be integer in range 1-100

gridplus entry .field -size 40 {
   {"Field One"   .one   !int +}
   {"Field Two"   .two   !date}
   {"Field Three" .three !myvalidation}
   {"Field Four " .four  !range:1-100}
   {"Field Five"  .five  !range:25-50}
}

Creates a grid of GRIDPLUS entry widgets named ".field". The default for entry size is set to "40" characters.

Five entry widgets are created:-

Field OneUses built-in "int" (integer) Regular Expression Pattern Match Validation.
Field TwoUses built-in "date" Date Validation.
Field ThreeUses user defined Regular Expression Pattern Match Validation
Field FourUses User Validation Procedure ("range") passing "1-100" as the parameter.
Field FiveUses User Validation Procedure ("range") passing "25-50" as the parameter.

gridplus button .test -size 12 -takefocus 0 {
   {"Validation" .validate !} {"No Validation" .novalidate}
}

Creates a grid of GRIDPLUS button widgets named ".test. The default width for the buttons is set to "12" characters and are set to not take keyboard focus.

Two buttons are created: The button with the text "Validation" uses the "!" option. This causes the entry validations for the window containing the buttons to be performed when the button is pressed. By default, entry validations are not performed when a button/link/menu options are invoked.

label .errormessage -foreground red

Creates a label widget called ".errormessage" with the text color set to "red.

If, when an entry validation fails, the window containing the entry has a label widget called "errormessage", the text of the label will be set according to the values defined for "-errormessage", the validation text and the parameter (if used). This also works for toplevel windows, where the "errormessage" may be called something like ".mytoplevel.errormessage".

gridplus layout .main -title "Validation Example" {
   .field
   .test
   .errormessage
}

pack .main

Creates a GRIDPLUS layout called ".main" to arrange the widgets in the window, and uses "pack" to display the layout.

Copyright © 2004 Adrian Davis.