Real widget toolkits (upon which IDL widgets are built) are event-driven. C language programs register interest in specific events by providing callback functions that are called when that event occurs. All but the most basic of widgets are capable of generating events.

In order for IDL stub widgets to generate IDL events, you must use CALL_EXTERNAL to invoke code that sets up real widget event callbacks for the events you are interested in. This setup can be done as part of creating the real widgets after the initial call to WIDGET_STUB. These callbacks then call IDL_WidgetIssueStubEvent() to issue the IDL event.

Your C-language widget toolkit callback functions should be patterned after the following template. Note that the arguments and return type will depend on the widget toolkit used, and so cannot be shown here:

stub_widget_call()
{
  char *idl_widget; 
  IDL_WidgetStubLock(TRUE);
     /* Get the IDL user-level identifier for this widget */
     if (idl_widget = IDL_WidgetStubLookup(id)) {
        /* Do whatever work is required */
        ...
        /* Optionally, issue an IDL event */ 
        IDL_WidgetIssueStubEvent(idl_widget, value)
  } 
  IDL_WidgetStubLock(FALSE);
}

Commentary on the Example Shown Above

Note that IDL_WidgetStubLock() is used to protect the critical section where widgets are being manipulated.

Somehow, the callback must be able to find the user-level integer returned by WIDGET_STUB when the stub widget was created in IDL. Usually, this is done in one of two ways:

  • When registering the callback, it is sometimes possible to specify a value that will be passed to the callback without interpretation. For example, the X windows XtAddCallback() function takes an argument named client_data. This value is passed to the callback and can be used to supply the user-level identifier.
  • Some widget toolkits have a set of attributes that they carry along with each widget. Under the X windows Xt toolkit, these attributes are called resources. Xt widgets usually have a resource capable of holding a single integer or memory address. This resource can be used to supply the user level identifier.

IDL_WidgetStubLookup() is used to translate the user level widget identifier into a memory pointer. If this function returns NULL, no further event processing is done since it would be a fatal error to issue an IDL event for a non-existent widget.

The event is issued via IDL_WidgetIssueStubEvent(). This step is not required. Many of the IDL widget types process real widget events via callbacks that do not always result in an IDL widget event being sent.