Query: xtcallbackd
OS: hpux
Section: 3
Format: Original Unix Latex Style Formatted with HTML and a Horizontal Scroll Bar
XtCallbackProc() XtCallbackProc()
Name
XtCallbackProc - interface definition for callback procedure.
Synopsis
typedef void (*XtCallbackProc)(Widget, XtPointer, XtPointer);
Widget w;
XtPointer client_data;
XtPointer call_data;
Inputs
w Specifies the widget for which the callback is registered.
client_data
Specifies the data that was registered with this callback.
call_data Specifies data passed by the widget; its type is defined by the particular callback list of the particular widget class.
Description
XtCallbackProc is the type of all procedures registered on callback lists with XtAddCallback() or XtAddCallbacks(). A callback procedure
is called when a widget calls XtCallCallbacks() or XtCallCallbackList() to invoke all the procedures that have been registered on one of
its callback lists. Most callback lists are invoked from an action procedure in response to an event or series of events, as when an Xaw
Command widget is clicked on, or when an Xaw Scrollbar widget is scrolled.
An XtCallbackProc takes three arguments:
o The first argument is the widget that triggered the callback: the widget for which the callback procedure was registered. You would use
the value of this argument in your callback function if you registered the same function as a callback for two different widgets, and if
you wanted to distinguish in the callback which widget called it, or you would use it if the purpose of the callback were to perform
some operation on the widget itself.
o The second argument, client_data, is whatever value was passed as the last argument of XtAddCallback(). client_data provides a way for
the client registering the callback also to register data that the callback procedure will need. This may be data of any type, cast to
an XtPointer when registered, and cast back to the desired type within the callback procedure. Generally, callback procedures should be
passed whatever data they are to operate on as their client_data; if this is not done, the callback procedure will have to rely on
global variables.
o The third argument, call_data, is data supplied by the widget. The argument is of type XtPointer, but the actual type of the data
depends on the particular widget class, and the callback list of that widget. Some widgets pass no data in this argument, others pass a
single scalar type, and others pass a pointer to a structure of some type. The Xaw Command widget doesn't provide any call_data, but
the Xaw Scroll widget, for example, passes back the current position of the scrollbar. The documentation for the widget will specify
the contents of this argument if it is used. The call_data argument may not contain all the relevant information that a callback proce-
dure might need. Callback procedures can also use XtGetValues() or other functions to obtain more information about the state of the
widget.
See the "Background" section below for more information about registering callback procedures and about callback lists.
Usage
Almost every application will define and register a number of callback procedures. Once you have created the widgets that make up your
application's interface and called XtAppMainLoop(), it is the callback procedures that you have registered that do all the processing for
your application.
Action procedures and event handlers are other ways of having a procedure invoked when certain events occur, but are both lower level and
far less commonly used than callback procedures. See XtAppAddActions() and XtAddEventHandler().
You can also register procedures to be called when the application is idle, when a timeout expires, or when there is input available from a
source other than the X server. This is done with XtAppAddWorkProc(), XtAppAddTimeOut(), and XtAppAddInput(). The procedures registered
are similar in concept to callback procedures, but are not of type XtCallbackProc.
Note that not all callbacks are called in response to user events. The XtNdestroyCallback list of all widgets and objects is invoked when
an object is destoyed, for example, and the XtNpopupCallback list of Shell widgets is called just before the shell widget is popped up,
whether or not a user event directly triggered the popup.
If any of the arguments are unused in your callback procedure, use the /* ARGSUSED */ comment to avoid warnings from lint. For ANSI-C type
checking, you should declare your callbacks with all three arguments even if some are unused. Note that you can use procedures that are
not of type XtCallbackProc (such as XtUnmanageChild(), for example) if you cast those procedures to type XtCallbackProc when you register
them.
Example
The following callback procedure is from the editres client:
/* ARGSUSED */
void
PannerCallback(w, closure, report_ptr)
Widget w;
XtPointer closure, report_ptr;
{
Arg args[2];
XawPannerReport *report = (XawPannerReport *) report_ptr;
if (global_tree_info == NULL)
return;
XtSetArg (args[0], XtNx, -report->slider_x);
XtSetArg (args[1], XtNy, -report->slider_y);
XtSetValues(global_tree_info->tree_widget, args, TWO);
}
It is registered by editres on the XtNreportCallback list of the widget panner, and is registered with another widget, porthole as
client_data.
XtAddCallback(panner, XtNreportCallback, PannerCallback, (XtPointer) porthole);
Background
Whenever a client wants to pass a callback list as an argument in an XtCreateWidget(), XtSetValues(), or XtGetValues() call, it should
specify the address of a NULL-terminated array of type XtCallbackList.
When a callback procedure, or list of callback procedures, is passed as a resource argument, Xt constructs an internal data structure for
the callback list. Subsequently, callback lists cannot be queried. Because Xt doesn't support a string-to-callback resource converter,
callbacks cannot be specified in resource files. The internal form can only be accessed by the Intrinsics functions XtAddCallback(), XtAdd-
Callbacks(), XtRemoveCallback(), XtRemoveCallbacks(), XtCallCallbacks(), XtCallCallbackList(), and XtHasCallbacks(). Furthermore, since
callback lists are handled specially by the Intrinsics, widget procedures should not allocate memory for callback lists passed as
resources. Unlike other resources, a widget's initialize() method should not attempt to make copies of resources of type XtRCallback.
For the Intrinsics to find and correctly handle callback lists, they must be declared with a resource type of XtRCallback. The internal
representation of a callback list is implementation-dependent; widgets may make no assumptions about the value stored in this resource if
it is non-NULL. Except to compare the value to NULL (which is equivalent to XtCallbackHasNone returned by XtHasCallbacks()), access to
callback list resources must be made through other Intrinsics procedures.
Structures
The XtCallbackRec structure and the XtCallbackList types are defined as follows:
typedef struct _XtCallbackRec {
XtCallbackProc callback;
XtPointer closure;
} XtCallbackRec, *XtCallbackList;
See Also
XtAddCallback(1), XtAddCallbacks(1), XtCallCallbacks(1), XtHasCallbacks(1), XtRemoveCallback(1), XtRemoveCallbacks(1).
Xt - Callbacks XtCallbackProc()