Edit

Specific UI Element Handler Names

Since common UI handlers tend to need to be implemented for specific window classes or fields, there is an easy way to implement these handlers for their specific target.

For the following handlers, you can write a handler that specifies its windowID class and optional additional scope in the handler name:

  • Before:windowID:transtype
  • ItemHit:windowID:itemIdent:transtype
  • ItemHit:windowID:listIdent:transtype:columnName (alternate form for list cells)
  • Validate:windowID:transtype
  • After:windowID:transtype
  • Cancel:windowID:transtype
  • Close:windowID:transtype
  • ValidateField:windowID:fieldindent:transtype
  • EnterField:_windowID:fieldindent:transtype
  • ExitedField:windowID:fieldindent:transtype
  • EnterCell:windowID:listname:columnname:transtype
  • ValidateCell:windowID:listname:columnname:transtype
  • ExitedCell:windowID:listname:columnname:transtype

The transtype specifier only applies to the Transaction entry window and the transaction list window and will not be present for any other kind of window. Your handler will only be called if all of the specifiers match. To have your handler called more generally, simply use fewer specifiers (note that the specifiers are necessarily positional, so you can only reduce specificity by dropping specifiers from the end). If there are multiple handlers for the same message in your script that match, they will all be called, beginning with the most specific. E.g. if you have ValidateField:f_trans:e_user1:DI and also ValidateField:f_trans, they will both be called, in that order (assuming the first one does not return false, in which case the call sequence would stop at that point).

Example:

    // will be called for all transaction entry window fields
    on ValidateField:f_trans
        say("validate trans field")
    return 1
    end
    
    // will only be called for transaction user1 field for a sales invoice
    on ValidateField:f_trans:e_user1:DI
    say("validate sales invoice user1")
    return 1
    end

Note: You SHOULD always return a value (0 or 1) for these validation handlers, however, if you fail to do so, 1 is the default return value.

Important: You should generally never implement a non-specific handler (such as Before or Validate, with no window id) unless you take great care to limit your functionality appropriately. Remember that even the script editor receives these messages.