hpux man page for xtaddcallba

XtAddCallback() 														   XtAddCallback()

Name
  XtAddCallback - add a callback procedure to a named callback list.

Synopsis
  void XtAddCallback(object, callback_name, callback, client_data)
	 Widget object;
	 String callback_name;
	 XtCallbackProc callback;
	 XtPointer client_data;

Inputs
  object    Specifies the object which owns the callback list; may be of class Object or any subclass thereof.

  callback_name
	    Specifies the resource name of the callback list to which the procedure is to be added.

  callback  Specifies the procedure to be added.

  client_data
	    Specifies data to be passed to callback when it is invoked, or NULL.

Description
  XtAddCallback()  adds  the  procedure callback and the data client_data to the callback list named by callback_name in the widget or object
  object.  If the procedure already appears on the list, with the same or with different data, it will be added to the list again,  and  when
  the callback list is invoked, the procedure will be called as many times as it has been added.

  The  callback  procedure  must  be  of type XtCallbackProc.  This procedure type expects three arguments and does not return anything.  The
  arguments are the widget or object that caused the callback to be invoked, the untyped data (client_data) that was registered with the pro-
  cedure,  and	another untyped argument, call_data which generally points to a structure which contains data particular to the callback list
  and object class.  See XtCallbackProc(2).

Usage
  The order that callback procedures are invoked in is, unfortunately, not specified by the Xt Intrinsics.  If you  have  several  operations
  that	must  be  executed  in	a particular order, you should not register them as separate callbacks.  Instead you should register a single
  callback that invokes each of the operations sequentially.

  If you want to register several callback procedures at the same time, you can use XtAddCallbacks().  Callbacks can also be set on  a	call-
  back	list  by  specifying a XtCallbackList as a resource when the widget is created.  A callback list should not be set with XtSetValues()
  once a widget is created, however, because this replaces the entire list of procedures rather than simply  adding  new  procedures  to  the
  list.  The Intrinsics do not define a String-to-XtCallbackList converter, but if you write one and use it in your application, then you can
  also specify callbacks from a resource file.	Finally, note that callback lists in a widget are compiled  into  an  internal	form  by  the
  Intrinsics, so attempting to examine a callback list with XtGetValues() will not work.

Background
  Generally  speaking,	a widget expecting to interact with an application will declare one or more callback lists as resources; the applica-
  tion adds functions to these callback lists, which will be invoked whenever the predefined callback conditions  are  met.   Callback	lists
  have resource names, so that the application can add and remove functions to a callback list by name.

  Callbacks  are  not  necessarily  invoked  in response to any event; a widget can call the specified routines at any arbitrary point in its
  code, whenever it wants to provide a "hook" for application interaction.  For example, all widgets provide an  XtNdestroyCallback  resource
  to allow applications to interpose a routine to be executed when the widget is destroyed.

  Widgets can define additional callback lists as they see fit.  For example, the Athena Command widget defines the XtNcallback callback list
  to notify clients when the widget has been activated (by the user clicking on it with the pointer).  (This is actually  a  poor  choice  of
  names.  It should have been given a more specific name, such as XtNnotifyCallback.)

  Callbacks  differ  from  actions  in the way that the registered function is invoked.  For callbacks, the trigger is an abstract occurrence
  defined by the widget, which may or may not be event-related.  The routines on a widget's callback lists are invoked by  the	widget	code,
  using a call to XtCallCallbacks().  Actions, on the other hand, are invoked directly by Xt, as the result of an event combination specified
  by the translations mechanism.

See Also
  XtAddCallbacks(1), XtCallCallbacks(1), XtRemoveAllCallbacks(1), XtRemoveCallback(1), XtRemoveCallbacks(1),
  XtCallbackProc(2).

Xt - Callbacks															   XtAddCallback()