Callback Editor

Allows you to connect objects in your interface with the application. Callbacks are routines executed in response to user and program actions. The Callback Editor allows the Builder Xcessory to support callback lists (a single action results in the execution of a number of routines).

Click the (...) button to the right of any callback resource on the Resource Editor to pop up the Callback Editor.

Callback Editor

The display area lists the Procedure Name, Parameter Type, and Parameter Value of each callback for the resource for which the Callback Editor has been called.

Selecting, adding, and deleting callbacks

Select, add, and delete work procedures using the following methods:

· Select a callback by clicking on its name in the Callback List. All appropriate fields are updated for the selected callback.

· Add a callback to the list by clicking New and entering the Procedure Name and any necessary parameter data in the appropriate text fields.

· Edit

· Delete a callback by selecting it in the list and clicking the Delete button.


Note: Builder Xcessory prompts you to confirm a new procedure name.

Parameter type values

New procedures are created with a default Parameter Type of Undeclared in the Callback Editor, indicating that parameter values of any type are accepted in the Parameter Value field. Other valid values include:

· Pre-defined types

· User-defined types

· None

None indicates that the callback procedure takes no value as its client data. All other types are listed in the Type Manager. A duplicate list is available by clicking on the arrow to the right of the Parameter Type label in the Callback Editor.

Declaring additional user-defined types

Additional user-defined types can be declared in the Callback Editor by entering the new type name in the Parameter Type field. Builder Xcessory prompts you to confirm a new user-defined type.

The Parameter Type field is grayed out if the callback specified in the Procedure Name field is referenced by a widget or style resource in your interface. The procedure's parameter type cannot be changed, in either the Callback Editor or the Procedure Editor, unless all references to the procedure are removed from the interface.

Matching parameters in the callback editor

When Builder Xcessory encounters a parameter in the Callback Editor, it searches for a match in the following order:

· Identifier

· Constant

If no match is found, Builder Xcessory prompts you to declare the parameter as an identifier.

Parameter values

The Parameter Value field accepts the following values as the client data value to pass to the callback operation:

· Constants

· Identifiers

· Boolean

· Integer

· Floating point

· String values


Note: String values must be double-quoted.

The type of the value must correspond to the type listed in the Parameter Type field.

If the text entered into the Parameter Value field is not a constant, identifier, or actual value, then Builder Xcessory prompts you to declare the value as an identifier of the appropriate type.

An extended editor for the parameter value is accessible by pressing the (...) button to the right of the Parameter Value field.

Predefined Callbacks

Click the arrow button to the right of the Callback Editor's Procedure Name text field to display the following list of predefined callbacks (in the following table, the parameter widget list refers to a string of widget names delimited by commas: widget1, widget2, widget3...):

Predefined Callback

Parameter

Description

BxDestroyCB

Widget list

Calls XtDestroyWidget for each widget in the widget list client data parameter.

BxExitCB

Integer

Calls exit with integer parameter client data passed as the exit code.

BxHelpCB

String

Creates a dialog with a text widget and a dismiss button. The text passed as client_data is displayed in the text widget. The dialog is destroyed when the dismiss button is selected.

BxManageCB

Widget list

Calls XtManageChild for each widget in the widget list client data parameter.

BxMapCB

Widget list

Calls XtMapWidget for each widget in the widget list client data parameter.

Gadgets and other non-widget objects are not legal parameter data.

BxPopdownCB

Widget list

Calls XtPopdown for each shell in the widget list client data parameter.

BxPopupCB

Widget list

Calls XtPopup, with grab set to XtGrabNone, for each shell in the widget list client data parameter.

BxSetInsensitiveCB

Widget list

Calls XtSetSensitive with Boolean parameter set to False for each widget in the widget list client data parameter.

BxSetSensitiveCB

Widget list

Calls XtSetSensitive with Boolean parameter set to True for each widget in the widget list client data parameter.

BxSetValuesCB

String

Passes any string of the following form:

"<widget_name>.<resource>=
<value>

<widget_name>.<resource>=
<value>
.
.
.

<widget_name>.<resource>=<value>"

For example:

"pushButton.background=red

form.foreground=yellow"

Rename widgets with unique names. Widgets assigned default names in one Builder Xcessory session (for example, pushButton, pushButton1,... pushButtonN) are not guaranteed to have the same names when the interface is saved and re-opened in a subsequent Builder Xcessory session.

Wildcard characters are not permitted in the string.

BxSystemCB

String

Passes a string from the client data parameter to the
system system call.

BxUnmanageCB

Widget list

Calls XtUnmanageChild for each widget in the widget list client data parameter.

BxUnmapCB

Widget list

Calls XtUnmapWidget for each widget in the widget list client data parameter.

Gadgets and other non-widget objects are not legal parameter data.

BxVerifyNumericCB

None

Checks for non-numeric text input and disallows text input that contains anything other than digits. For example, this callback does not allow input of signs ("+", "-") or decimal points. Intended as the modifyVerify callback on an XmText or XmTextField widget.

Code Generation

When the callbacks-c.c file is written out, the file includes the fully commented code for the predefined callback.

 

Documentation: