EtsT_Obj_Dbox_New_Value_Handler
Abstract
Callback: Used to translate user input to attribute values and copy those values to a copy of the object.
Syntax
<object_dbox_new_value_handler_name> (attr_name, value_str, orig_object, copy_object)
| Argument | Type | Description |
|---|---|---|
attr_name |
const char * |
Object name. |
value_str |
const char * |
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 updated
use_default_set_method— indicates that the application should use the standard new value handler routines
invalid_value— indicates that the value entered by the user is invalid
Header
ets_api_obj_dbox.h
Details
An application calls an object dbox new value handler after a user changes an attribute value. A 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, thereby enforcing consistency.
An application does not call an object dbox 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 an object dbox 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 an object dbox 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 flag use_default_set_method set to PRGC_TRUE.
Callbacks of this type are registered as the New Value Handler in an attribute’s Enter ETS Handlers dialog box (see “Active Attributes“ on page 51).