# Callbacks dialog

The Callbacks dialog allows you to specify a list of callback functions or methods which are to be invoked when a particular user action is performed on a widget. Such callbacks or methods are user-defined: the dialog associates user events within the interface with specific application routines.

Designating a Callback

A callback list is a list of callback functions designated to be triggered by user actions in your application. User actions include mouse button presses, keyboard selections and movements of the pointer. By setting up a callback, you can instruct your interface to call the functions on the callback list whenever a certain user action occurs within a widget.

An "M" or "C" displayed to the right of a callback indicates that a method or callback respectively has been declared. An asterisk (*) indicates that the callback is not supported by Microsoft Windows.

Inherited Callbacks

Widgets which are instances of definitions can inherit callbacks from the corresponding widget in the definition.

Inherited callbacks are shown enclosed in square brackets ([]).

Callback Syntax

In general, the syntax for each function call in the callback list is the same as C syntax. Function brackets () are not required as these are added automatically.

Note - If you add function brackets or parameters to the name of the callback function or method these will be treated as part of the name - they will not be recognised as syntactically separate.

Order of Execution

While the callback list looks like C code, it has no logical flow. This means that you can neither use C's logical operators such as if...else and while, nor can you rely on your callbacks being executed in any particular order. All routines in your list will be executed whenever the specified event occurs but not necessarily in the order you type them. If the execution sequence is important, you can write a single callback function which contains subroutine calls in the order you want.

Client Data

The "Client Data" text box allows you to specify data to be passed in to the callback. It is better practice to use this mechanism when a callback needs to use some data than to use a global variable. Enter the string you wish to appear as the parameter here. You may also add a type cast in the usual C/C++ syntax. You do not, however, need to type the function parameter brackets () as these will be added for you automatically.

Note - You can only add client data to function callbacks, not to method callbacks.

Methods

The "Methods" button is only shown if the selected widget is enclosed in a C++ class. If this is the case, you can select "Methods" to view a list of callback methods already defined for that class. Selecting one of these and pressing "OK" will place the selected item in the "Name of Method" text field.

Edit Code

Pressing this button allows you to edit your stubs file (the generated file containing the specified callbacks) without leaving WorkShop Visual.

Flavor Option Menu

The Flavor Option Menu works in conjunction with the "Edit Code" button. When you edit your stubs file, you must specify which language you are using. WorkShop Visual will try to work this out for you and set the menu accordingly when you invoke the dialog. Sometimes this is not possible if, for example, you are working with two languages in the same design. You should, therefore, always check that the appropriate option is chosen from this menu.

Remove

The "Remove" button removes the currently selected callback. Be careful when using this button as the operation cannot be undone.

Callback Functions

Most callback functions have a similar structure. A typical callback function does some or all of the following:

- Extracts information from widgets, such as the text in a Text widget or the state of a ToggleButton
- Uses this information as parameters for calls to application functions
- Uses the results of these functions to change widget attributes. These attributes include not only values (such as the text in a Text widget) but also sensitivity (responsiveness to user input), visibility and even existence

Callback Function Parameters

A callback function receives three parameters:

- The widget from which the callback was invoked
- The call data
- The client data

The call data is a pointer to a data structure defined by the widget developer. Call data structures are described in the documentation from Motif or the developer of the widget toolkit.

The client data is a pointer that you can use to pass the address of any variable or structure. When you register a callback, you can specify the value for the client data parameter that is passed to the callback function.

In WorkShop Visual, the name of the client data is specified in the callback dialog as a single optional parameter of the callback function. This can be a pointer to a structure, which can be defined and initialized in a suitable prelude. For example, a typical prelude might be:

    /* Pre-manage prelude for main dialog Shell */
    /* Define and initialize client data for the rungrep callback */
    static rcdata_t rcdata = {
    	&hitstring,
    	&errorshell,
    	&errorform,
    	&errortext,
    	&mainshell
    };
    /* End of Shell pre-manage prelude */

The callback is specified as:

    rungrep((XtPointer)&rcdata)

To enter this in the Callbacks dialog, the function name rungrep is typed into the text feld labelled "Name of Function" and the parameter, including the cast, is typed into the "Client data" text field: (XtPointer)&rcdata.

The declaration of the structure rcdata_t would normally be in a header file that would be included in the generated code (via an #include in the module prelude) and in the callback function module. The callback function can then cast the client data to (rcdata_t *) and so access the data.

Note that the structure rcdata is defined to contain pointers to the widget variables, rather than the values of the variables themselves. This lets rcdata be initialized before the widgets are created. You can also define a structure into which the values of the widget variables are copied. However, this cannot be initialized until all the widgets have been created, which can be tricky.

Callbacks in C++

Ideally it would be desirable to add class member functions to widgets as callback functions. Unfortunately this is not possible because callback functions are called by a C library and they cannot provide the instance context (the this pointer) required by a class member function. WorkShop Visual provides an automatic way of calling a class member function from a callback. These are called callback methods.

See also:

- Code Generation
- Code Preludes
- Module Preludes
- Callbacks
- Methods
- About WorkShop Visual