The <callback> Option
The "callback" keyword is used to define a function that is automatically called each time input is added to a field. You can use this function to check the field's input and take appropriate action if necessary.
The arguments to the "callback" function are interpreted differently when the template is used to define a GUI form (i.e. the header of the template contains the "gui_form" keyword). Note that both callback definitions have the same argument types -- they are just interpreted differently for command templates versus GUI form templates.
The callback function has the following arguments:
|
/* callback function for command templates */ int callback_function ( char *template name, /* I: name of command template that invoked this callback */ int field_id, /* I: id of template field for which this callback was invoked */ int idx_data /* I: index of command's VDATA object */ ) |
|
/* callback function for GUI forms */ int callback_function ( char *template_name, /* I: name of GUI form that invoked this callback */ int field_id, /* I: id of GUI widget (e.g. scrolling list) for which this callback was invoked */ int item_id /* I: id of widget item that was clicked (e.g. scrolling list item number) */ ) |
See the information in Widget Classes and Options for the item numbers associated with each GUI widget class.
Return 1 from the callback function if you want the Input Manager to stay at the active field. Otherwise, return 0 and the Input Manager will process the field as usual.
For example, if the input associated with the field isn't what you're looking for, you could force the Input Manager to re-execute the field.
Use "InGuiSend(char *string)" to send null-terminated command strings to the Input Manager from your callback function. For instance,
"InGuiSend("@2")" tells the Input Manager to go to field number two
of the active template. In this particular case, "field number" is not the same as the "field id" included in the template definition. "Field number" refers to the field's sequence number within the template definition, numbered from zero.
