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.

Callbacks which apply to generated Java code are listed with the letter `J' after them in the list. Only callback methods are supported in Java.

An "M2.1" marker indicates that the callback type is new in Motif 2.1.

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 X-Designer.

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. X-Designer 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.

Update

Update Settings allows you to update any of the attributes of an existing callback, select the callback and make the modifications and select update settings for the new attributes to take.

Clear Settings

This option returns the dialog to its default state. It unselects any selected callbacks and removes all information pertaining to it.

Callback Functions

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

Callback Function Parameters

A callback function receives three parameters: 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 X-Designer, 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. X-Designer provides an automatic way of calling a class member function from a callback. These are called callback methods.

Smart Code Options with Callbacks

For information about Smart Code and its uses follow the Smart Code links below. When you select the Smart Code toggle you may choose one of three "levels" of smart code:

  1. Get/Set.

    This provides you with a suite of "getter" and "setter" functions for a group of widgets.

  2. Thin Client.

    This provides not only the getters and setters, it also triggers X-Designer to generate a separate client application containing the user interface and a server application containing the Smart Code callback(s). In addition, the code to handle the communication protocol between the two is generated.

  3. Internet.

    This option is very similar to the "Thin Client" option above except that no server application is generated. Use this option for generating applications which will connect to an existing server or which will fetch Web pages.

A Smart Code callback requires a Group. This Group is passed to the callback when it is triggered, thus providing a handle onto the user interface and the data contained within it - the contents of text fields, for example. To specify a Group do one of the following:
  1. Type the name of a Group into the "Group" text field.
  2. Press the "Group" button to display the Group Editor, select a Group and press "Apply".
The "Style" option menu lets you choose the type of Smart Code you require and, therefore, the structure of the application you are creating. The code generated for each style is different.

See also: