%ICHANGE_METHOD
Perform input field change processing
WTSupported in traditional Synergy on Windows
|
WNSupported in Synergy .NET on Windows
|
USupported on UNIX
|
VSupported on OpenVMS
|
function ICHANGE_METHOD,^val a_data_entered ,a a_data_stored ,a a_pending_status ,n a_inpinfo ,a a_inprec ,a a_methoddata1 ,any . . a_methoddata20 ,any
Return value
%ICHANGE_METHOD must return one of the values listed under a_pending_status below. (n)
Arguments
a_data_entered
A buffer containing the field data as entered by the user. (a)
a_data_stored
A buffer for the final storage of the data. (a)
a_pending_status
The result of Toolkit’s field validations; one of the following (defined in tools.def): (n)
Input is valid, proceed.
Value not in range.
Invalid numeric digit.
Not an allowed entry.
Non-zero or non-blank value required.
Invalid date.
Negative value not allowed.
Too many digits.
Invalid time.
Negative value only allowed.
Invalid entry, but error message already emitted.
a_inpinfo
The structure of input information. (a)
a_inprec
(optional) The data_area argument (or the data_location argument for I_INPFLD on Windows) passed to the calling input routine. This is not passed if the calling routine is L_INPFLD. And, on UNIX and OpenVMS, this is not passed if the calling routine is I_INPFLD. (a)
a_methoddata1 through a_methoddata20
(optional) Up to 20 additional data arguments. (any)
Discussion
%ICHANGE_METHOD is a function you write and name when you want your program to perform extra actions after a specific input field is validated. By default, a field is not validated until focus is lost. Immediate validation can be specified for check boxes, radio buttons, and combo boxes by using the D_VALSTCHG option in E_STATE. %ICHANGE_METHOD must be declared as a ^VAL function.
This function is called by I_INPUT, I_INPFLD, L_INPUT, and L_INPFLD when a change method is specified for the field being processed. You can specify a change method for the field by using the CHANGE_METHOD qualifier in a .FIELD script command or the D_FLD_CHANGE option in I_FLDMOD or IB_FIELD.
%ICHANGE_METHOD is called only after the new field contents have been subjected to all the specified Toolkit validation tests. %ICHANGE_METHOD has the “last chance” opportunity to override or add to the Toolkit’s functionality.
When %ICHANGE_METHOD is called, a_data_stored contains the storage form of the new data as validated by the Toolkit. If you wish to override the storage form of valid input, you may store the desired information in this argument prior to returning from the method. The following table shows the expected contents of a_data_entered based on field type.
Field type |
Contents of a_data_entered |
---|---|
Editable (including enumerated allow list) |
Data as entered |
Selection list/window (including enumerated and radio buttons) |
Text of selected entry |
Check box |
Blank (for non-checked) or the contents of g_chk_char (for checked). See g_chk_char for more information. |
Note that the length of the text passed in a_data_entered is defined by the input length for the field. It is not limited by either the display length or the view length.
If a_pending_status is one of the D_xxxERR values when %ICHANGE_METHOD is called, the contents of a_data_stored are undefined.
A_pending_status contains the result of Toolkit’s validations. %ICHANGE_METHOD can simply return this value or return a different value (as the return value of the function) if you want to override Toolkit’s validation of the field.
If %CHANGE_METHOD returns D_OK, the entry is accepted. Any other return value will revert the entry and storage to its original contents and force re-entry. (You do not need to revert the data in a_data_entered.) If %ICHANGE_METHOD returns any of the values D_RNGERR through D_NEGOERR, the appropriate error message is also displayed. D_EMITTEDERR should be returned when %ICHANGE_METHOD displays its own error message. (This implies that, on Windows, a change of focus within the change method is acceptable and is actually expected when returning D_EMITTEDERR.)
The include file inpinf.def defines a_inpinfo. See IARRIVE_METHOD for more information, but note that you must include inpinf.def as the fourth argument within your change method.
A_inprec is the same record passed to the data_area argument for I_INPUT and L_INPUT and, on Windows, the data_location argument for I_INPFLD. (On UNIX and OpenVMS, this argument is not passed if I_INPFLD is the calling routine.) Note that the area of the record occupied by the current field does not yet contain the data being validated.
A_methoddata1 through a_methoddata20 are up to 20 additional optional arguments that can be passed to I_INPUT, I_INPFLD, or L_INPUT. They are passed, in turn, directly to %ICHANGE_METHOD. This enables you to communicate additional information to %ICHANGE_METHOD.
See also
- Overloading UI Toolkit routines for more information on creating this function
- Appendix D: Methods for important information about method limitations
Examples
In this example, if the user enters a non-zero value in the field, all fields in the set named “rest” are cleared and disabled. Otherwise, these fields are enabled.
function check_full , ^val a_data_entered ,n a_data_stored ,n a_pending_status ,n .include 'WND:inpinf.def' a_record ,a .include 'WND:tools.def' proc if (g_select) freturn D_OK ;Menu entry signaled, don't do anything special. if (a_data_entered) then ;The value entered is non-zero. begin xcall i_init(inp_wndid, 'rest', a_record) ;Clear fields in set xcall i_disable(D_SET, inp_wndid, 'rest') ; 'rest' and disable them. end else ;A non-zero value xcall i_enable(D_SET, inp_wndid, 'rest') ;Enable the fields in 'rest'. freturn D_OK ;Accept the input for this field end