trigger startModification

Trigger that handles processing when a user starts to modify a field in a form component.

Declaration: trigger startModification
Applies to: Field
Activation: Activated when the user starts to enter or modify data in the field. The exact timing depends on the widget, but is always before the valueChanged or loseFocus trigger.

It is not activated by ProcScript statements that change the value of the field.

Default behavior: None
Behavior upon completion: None affects the structure editor. If $status is:
  • < 0—data just entered is discarded. Focus remains in the field and the startModification trigger is activated again if more data is entered.
  • >=0—data just entered is moved to the field. If this is the first attempted modification to the occurrences (with cautious locking in effect), the lock trigger is activated after the startModification trigger completes.
  • In a unifield only, if $status is 99, the character just entered is discarded; focus remains in the field. This is often used with $prompt to go to another field.

Description

This trigger is often used to ensure that it is currently valid to modify this field.

Caution: The startModification trigger is not intended for I/O operations. Avoid using ProcScript statements here that cause data modification or I/O operations, where these actions involve the current field or the occurrence to which it belongs (such as clear/e). In some circumstances, these can cause Uniface to loop infinitely.

You can use this trigger to implement model validation, such as making sure that an invoice date cannot be entered before an invoice number. For example: 

trigger startModification ; of INV_DATE
if (INV_NUMBER = "")
  message "Supply invoice number first!"
  return -1
endif
end ; startModification

When the startModification trigger is activated, only the pre-modification contents of the field are available. The field is only updated with new data when the trigger successfully completes. In Unifields only, the character code of the character the user entered, which caused this trigger to be activated, is available in $char.

startModification

In the following example, when the user enters a capital D ($char is "D"), ProcScript in the startModification trigger puts the structure editor into Zoom mode and inserts a salutation: 

trigger startModification ; of a unifield
if ($char = 68) ; "D"
   if (GENDER = "M")
     $1 = "Mr."
   else
     $1 = "Ms."
   endif
   macro "^127^096ear %%$1 %%SURNAME, ^CURSOR_RIGHT"
endif
end ; startModification

Return Value 99

Consider a situation where, when a user attempts to enter data beginning with a capital letter into FIELD1, that character should be discarded and input accepted from FIELD2. You might consider using the following ProcScript: 

trigger startModification ; of FIELD1 (unifield)
if ( $char >= 65 & $char <=90 ) ;A-Z
  $prompt = FIELD2
  return 0
endif
end ; startModification

When a capital letter (A-Z) is entered, this trigger returns with $status set to 0. Because $char still contains the character that was entered in FIELD1, the Start Modification trigger of FIELD2 is activated. To prevent this from happening, you can use the return value 99 in the startModification trigger of FIELD1: 

trigger startModification ; of FIELD1
if ( $char >= 65 & $char <=90 ) ;A-Z
   $prompt = FIELD2
   return 99
endif
end ; startModification

Note:  A return value of 99 in this trigger should only be used in the situations like the one described above, that is, to discard the pending input when $prompt is used to move to another field. Do not use a return value of 99 to provide the functionality of return -1, but without making the terminal beep.

Related Topics