| Home | Reference | Manpage | Examples | Download | License | Contact |
| GRIDPLUS2 - Validations | |
||||||
|
| 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 widget option), is invoked. If -validateauto is set to "0" validations are not performed when the entries loose focus.
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. If -validatepopup is set to "1" The error message appears in a pop-up box (White text on red background) just below the entry field to which it applies.
If the validation fails when losing focus to a modal toplevel window, the entry validation failure is cleared and focus is given to the toplevel.
Three types of validations are supported:-
Note: To invoke validation when the next widget in the keyboard focus order is a button, the button must have the "!+" widget option specified.
| GRIDPLUS Entry Validation Option Format |
The following option formats may be used to specify entry validations:-
| GRIDPLUS Validation Options |
The GRIDPLUS set command mode has the following options which are used to set-up/configure entry field validations:-
| Option | Purpose | Default |
| -century | Sets year at which abbrieviated format dates are assumed to be in the 20th century. | 50 |
| -dateformat | Sets date format (eu European, uk United Kingdom, us United States). | us |
| -errormessage | Sets the global "errormessage" text. | % |
| -pattern | Sets pattern -or- specifies procedure when creating new validation | None |
| -text | Sets validation specific text to be used for percent sustitution in "errormessage". | None |
| -validation | Sets 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.
Note: If the regular expression pattern is prefixed with "trim:" leading and trailing spaces will automatically be removed from the value of the entry being validated.
| Validation Name | Regular Expression Pattern | Validation Text | Comment |
| alpha | {^[a-zA-Z]+$} | Alpha | Alpha only |
| alphanum | {^[a-zA-Z0-9]+$} | Alphanumeric | Alphanumeric |
| int | {trim:^[0-9]+$} | Integer | Integer |
| -int | {trim:^(-)?[0-9]+$} | Integer | Integer allowing negative value |
| num | {trim:^[0-9]+([.][0-9]+)?$} | Numeric | Integer or decimal |
| -num | {trim:^(-)?[0-9]+([.][0-9]+)?$} | Numeric | Integer or decimal allowing negative value |
| decimal | {trim:^[0-9]+[.][0-9]+$} | Decimal | Decimal |
| -decimal | {trim:^(-)?[0-9]+[.][0-9]+$} | Decimal | Decimal allowing negative value |
| money | {trim:^[0-9]+[.][0-9][0-9]$} | Money Format | Two decimal places |
| -money | {trim:^(-)?[0-9]+[.][0-9][0-9]$} | Money Format | Two decimal places allowing negative value |
| notnull | {[^\000]} | Not Null | Not null/blank |
| ! | {[^\000]} | Non Blank | Not null/blank |
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).
Note: Abrieviated formats are not supported for ISO dates.
Example: gridplus set -dateformat uk
Sets the date format to "uk" (dd/mm/yyyy).
| Format Name | Date Format |
| eu | dd.mm.yyyy |
| iso | yyyy-mm-dd |
| uk | dd/mm/yyyy |
| us | mm/dd/yyyy |
Assuming both -dateformat and -century have default values dates can be entered in the following formats:-
| Format | Example | Date Converted To |
| mm/dd/yyyy | 12/03/2004 | 12/03/2004 |
| mmddyyyy | 12032004 | 12/03/2004 |
| mmddyy | 120304 | 12/03/2004 |
| mmddyy | 120364 | 12/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 -width 40 -validatepopup 1 {
{"Field One" .one !int +}
{"Field Two" .two "!date?Valid Date Required"}
{"Field Three" .three !myvalidation}
{"Field Four " .four !@range:1-100}
{"Field Five" .five !range:25-50}
}
gridplus button .test -width 12 -takefocus 0 {
{"Validation" .validate !} {"No Validation" .novalidate}
}
label .errormessage -foreground red
gridplus layout .main -wtitle "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
}
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"}
proc test,novalidate {} {puts "No Validation Pressed"}
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"
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
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
Five entry widgets are created:-
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.
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 set -validation range \
-pattern proc:range \
-text "integer in range %"
gridplus entry .field -width 40 -validatepopup 1 {
{"Field One" .one !int +}
{"Field Two" .two "!date?Valid Date Required"}
{"Field Three" .three !myvalidation}
{"Field Four " .four !@range:1-100}
{"Field Five" .five !range:25-50}
}
Field One Uses built-in "int" (integer) Regular Expression Pattern Match Validation. Field Two Uses built-in "date" Date Validation. The validation error message is set to "Valid Date Required". Field Three Uses user defined Regular Expression Pattern Match Validation Field Four Uses User Validation Procedure ("range") passing "1-100" as the parameter. The field may also be left blank, as specified by "@". Field Five Uses User Validation Procedure ("range") passing "25-50" as the parameter.
gridplus button .test -width 12 -takefocus 0 {
{"Validation" .validate !} {"No Validation" .novalidate}
}
label .errormessage -foreground red
gridplus layout .main -wtitle "Validation Example" {
.field
.test
.errormessage
}
pack .main