Validating Input to Text Fields

The text field gadget has an optional validation callback member which the user can specify:

!textfield.ValidateCall = <callback string>

When a text input field is actioned (by modifying it and pressing ENTER, or when a button on the form is pressed or the form's OKcall is executed), it is automatically checked to ensure that the typed-in value matches the field's TYPE and its FORMAT constraints. If so, then the user's VALIDATECALL is actioned.

The VALIDATECALL is used to apply any checks you want. If an error is encountered then the callback raises the error and returns.

Note: The validation callback must not attempt to change the value of the text field. It should just detect and raise an error.

When an error is raised, an error alert is displayed and the text field is left with keyboard focus and error highlight. No further form or gadget callbacks are executed and the form is not dismissed from the screen. The User can then modify the field and re-action it.

The VALIDATECALL is a standard callback, and so it can be a single command, a PML function, method or macro, or an open PML method or function. For an open callback, for example:

!textField.validateCall = ‘!this.textvalidate(‘

the corresponding method must be:

define method .1textvalidate( !textin is GADGET, !action is STRING )

where the action string will be 'VALIDATE'.

An Example of Text Validation:

The form !!ValidForm has two text fields of types REAL and STRING.

There are limits on the values that can be typed into each field: the tooltips on each field explain the constraints.

The textvalidate method determines from its !textin parameter which field is being validated, and applies the constraints that have been defined. The Handle block traps any unexpected PML errors generated by the validation code. The first if-block of the validation code checks that the text field is not unset. This also prevents the possibility of unexpected errors in the validation code.

-- $Header: /dev/eventlayer/PMLLIB/validform.pmlfrm 1 17/09/04 13:37 Robin.langridge $

-- PDMS customization User Guide

-- Form ValidForm - Demonstrate text field validation

setup form !!ValidForm dialog

 TITLE |Text Handling|

 HDIST 3

 text .T1 |Real| at wid 8 is REAL tooltip'range 0.0 to 100.0'

 text .T2 |String| wid 12 is STRING tooltip'anything but FRED'

 button .CANCEL at XMIN FORM YMAX FORM CANCEL

 button .OK at XMAX FORM - SIZE YMAX FORM - SIZE OK

exit

define method .ValidForm()

 -- constructor

 !this.t1.validatecall = '!this.textvalidate('

 !this.t2.validatecall = '!this.textvalidate('

 !this.OKcall = '!this.printValues()'

Endmethod

define method .textvalidate( !textin is GADGET, !action is STRING )

 -- validate the given field contents

 -- General form of Validation Callback

 -- !action will contain 'VALIDATE'

 onerror golabel /Errors

 label /Errors

 -- Include handle block for any unexpected PML errors

handle ANY

  -- Example: can get errors from evaluation of the String field

  -- with an 'unset'value

return error 1 'Invalid input'

 endhandle

 -- Validation code -------------------------------------

 -- Check for unset field first (to avoid possible unexpected errors)

 if( !textin.val.unset() ) then

  -- validation callback Failed

  return error 2 'Field is unset'

 else

   !field = !textin.name()

  if(!field eq 'T1') then

   -- TYPED field must check range

   !x = !textin.val

   if(!x lt 0.0 or !x gt 100.0) then

    return error 1 'value must be in range [0.0 to 100.0]'

   endif

  elseif(!field eq 'T2') then

   -- any string but FRED

   if(!textin.val eq 'FRED') then

    return error 4 'value must not be FRED'

   endif

  endif

 endif

endmethod

define method .printValues()

 !r = !this.t1.val

 !s = !this.t2.val

 $p values $!r and $!s

Endmethod