Adding Callbacks

Builder Xcessory allows you to add callbacks of your own design to the list of predefined callbacks in the Callback Editor. The procedure for adding predefined callbacks is similar to that of adding resource editors.

On most systems, Builder Xcessory dynamically loads the shared library containing the callbacks. If there is a function in that library called AddUserFunctions, it is called. In that function, you can make calls to other functions to register the callbacks with Builder Xcessory on all systems.

To construct this library, build a shared library and include an object file with the function AddUserFunctions defined in it.

When Builder Xcessory starts, it looks in both locations (the definitions in the second override the definitions in the first):

{BX}/xcessory/lib/functions
{HOME}/.builderXcessory/lib/functions/

Systems running SunOS 4

On systems running SunOS 4, you must modify your interface file (addWidgets.c in our example), and add to the AddUserFunctions defined in the file. Then, relink Builder Xcessory with addWidgets.c and with a new file containing the callbacks, as described in Chapter 2--Adding Widgets.

Adding a Callback to Predefined Function List

To add a callback function to the predefined function list, you must register the function by calling one of the following functions:

void RegisterUserCallback(char *name
XtCallbackProc fct,
char *unused)

void RegisterUserTypedCallback(char *name,
XtCallbackProc fct,
char *parameter_type)

name The name of the function. You must provide a value for this parameter.

fct A pointer to the callback function. If you do not provide a value for this parameter, Builder Xcessory cannot use the function in Play Mode.

unused No longer used by Builder Xcessory.

In previous versions of Builder Xcessory, the third argument to RegisterUserCallback was the name of a file containing the code to insert in the user's callbacks file when generating code for the named function. The file containing the codemust now have the same name as the function. If this file cannot be found during code generation, Builder Xcessory produces only a stub function.

parameter_type The name of the type for the client data parameter to the callback. If you specify a type name, Builder Xcessory allows the user to specify the function's parameter, as long as its type is the same as the type named by parameter_type.

Example

The following sections illustrate an example of adding the callback function InterceptWMDelete to the list of predefined callbacks in Builder Xcessory. InterceptWMDelete is written to be placed on a shell widget in its popupCallback.

InterceptWMDelete

InterceptWMDelete registers another function (Intercepted) with the X Translation Manager that is called when a shell receives the WM_DELETE_WINDOW protocol message.

The actual code for this function can be found in the {BX}/examples directory in the file intwmdel.c.

Adding the function to Builder Xcessory

To add this function to builder xcessory, you would include the following call to RegisterUserCallback in AddUserFunctions:

void AddUserFunctions()
{
RegisterUserCallback("InterceptWMDelete",
InterceptWMDelete,
NULL);
}

Because InterceptWMDelete does not expect any client data, you might want to ensure that the user cannot enter a client_data parameter inside Builder Xcessory.

Ensuring that the user cannot enter client data

To ensure that the user cannot enter client_data parameters you must use RegisterUserTypedCallback and indicate a parameter_type of "None", as follows:

void AddUserFunctions()
{
RegisterUserTypedCallback("InterceptWMDelete",
InterceptWMDelete,
"None");
}

This example registers the function InterceptWMDelete. When generating code, Builder Xcessory looks for a file with the same name as this function, InterceptWMDelete. If this file exists, Builder Xcessory inserts the code from this file in the Callbacks file as long as the function InterceptWMDelete is referred to and not already in the Callbacks file.

Builder Xcessory search order

Builder Xcessory searches for InterceptWMDelete in the gen directories. The order in which it searches is:

  • {HOME}/.builderXcessory/gen/{LANG}
  • {BX}/xcessory/gen/{LANG}
  • {BX}/xcessory/gen/common

where {LANG} is the language for which code is being generated. This search order allows you to better customize the generated code for the chosen language.

Documentation: