New Value Handler Functions
Abstract
Use this handler to translate user input to attribute values and copy those values to a copy of the object.
Syntax
<new value handler name> (attr_name, value_str, orig_object, copy_object)
| Argument | Type | Description |
|---|---|---|
attr_name |
const char * |
Pointer to a string containing the object name |
value_str |
const char * |
Pointer to a string containing the new value |
orig_object |
EtsT_Obj_Handle |
Handle for the original attribute object |
copy_object |
EtsT_Obj_Handle |
Handle for a copy of the original attribute object |
Return Type
EtsT_Obj_Dbox_New_Value_Options
A structure containing the following Boolean values:
dbox_refresh— indicates that the attribute value has changed, and that the attribute display must be updateduse_default_set_method— indicates that the application should use the standard new value handler routinesinvalid_value— indicates that the value entered by the user is invalid
Details
An application calls a new value handler after a user changes an attribute value. The new value handler is responsible for translating user input to attribute values and assigning them to copy_object. This is especially useful for menus with settings in string format (such as “1,000”) that must be translated to valid attribute settings. You can also use this handler to change other attribute values affected by the proposed change, and thereby enforce consistency.
An application does not call a new value handler if the click handler defined a dialog box and returned with EtsC_Obj_Dbox_Click_Show_Dbox set to PRGC_TRUE. (In that case, the ETS dialog box code should perform any input-processing routines.)
You can use a new value handler to perform custom validations—for example, to perform dynamic validations based on a model’s state. When writing custom validation routines, set the invalid_value flag to PRGC_TRUE or PRGC_FALSE to indicate whether the new setting is invalid.
You should make all changes to copy_object, not orig_object, so a user can cancel any changes if desired. You should also set the dbox_refresh flag to PRGC_TRUE; this indicates that the attribute display must be updated.
You can use a new value handler to replace the standard new value handler routines in an object’s attribute dialog box. These routines are normally responsible for validating user input and translating that input to valid attribute settings. To use the standard handlers, simply return with the use_default_set_method flag set to PRGC_TRUE.