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 proce‐
dure in response to an event or series of events, as when an Xaw Com‐
mand widget is clicked on, or when an Xaw Scrollbar widget is scrolled.
An XtCallbackProc takes three arguments:
· 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 reg‐
istered 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 per‐
form some operation on the widget itself.
· 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.
· 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 call‐
back procedure might need. Callback procedures can also use XtGet‐
Values() or other functions to obtain more information about the
state of the widget.
See the "Background" section below for more information about register‐
ing 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 appli‐
cation's interface and called XtAppMainLoop(), it is the callback pro‐
cedures that you have registered that do all the processing for your
application.
Action procedures and event handlers are other ways of having a proce‐
dure 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 XtCall‐
backProc.
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 spec‐
ify 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(), XtCallCall‐
backs(), 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 AlsoXtAddCallback(1), XtAddCallbacks(1), XtCallCallbacks(1), XtHasCall‐
backs(1), XtRemoveCallback(1), XtRemoveCallbacks(1).
Xt - Callbacks XtCallbackProc()
