hpux man page for xtaddcallbb

XtAddCallbacks()														  XtAddCallbacks()

Name
  XtAddCallbacks - add an array of callback procedures to a named callback list.

Synopsis
  void XtAddCallbacks(object, callback_name, callbacks)
	 Widget object;
	 String callback_name;
	 XtCallbackList callbacks;

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 procedures are to be added.

  callbacks Specifies a NULL-terminated array of callback procedures and corresponding client data.

Description
  XtAddCallbacks()  adds  the  procedure/data  pairs  specified in callbacks to the callback list named callback_name in the widget or object
  object.  Each element of callbacks is a structure of type XtCallbackRec and contains a pointer to a callback procedure and the data  to  be
  registered  with and passed to that procedure.  Because XtAddCallbacks() does not have an argument that specifies the length of this array,
  the last element of the array must contain NULL in both of its fields.

  A procedure may appear multiple times in the callbacks array, and may be added to a callback list more than once, with  different  or  even
  with the same data.  When the callback list is invoked, each procedure will be called as many times as it appears on the list.

  Each	procedure  to be added to the callback list 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 that was registered  with
  the procedure, 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 only a single callback procedure, XtAddCallback() is easier to use.  You may find this function easier even if  you
  are registering several functions, because it does not require you to declare and initialize an array of XtCallbackRec.

  Callbacks  can  also	be  set  on a callback 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  com-
  piled 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.

Example
  When calling XtAddCallbacks(), you will generally use a statically initialized array like the following:

     XtCallbackRec button_callback_list[] = {
	 {dispatch_function, (XtPointer) 1},
	 {dispatch_function, (XtPointer) 2},
	 {do_something_else, NULL},
	 {(XtCallbackProc) NULL, (XtPointer) NULL},
     };

Structures
     typedef struct _XtCallbackRec {
	 XtCallbackProc  callback;
	 XtPointer	closure;
     } XtCallbackRec, *XtCallbackList;

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

Xt - Callbacks															  XtAddCallbacks()