hpux man page for xtappaddacb

XtAppAddActions()														 XtAppAddActions()

Name
  XtAppAddActions - register an action table with the Translation Manager.

Synopsis
  void XtAppAddActions(app_context, actions, num_actions)
	 XtAppContext app_context;
	 XtActionList actions;
	 Cardinal num_actions;

Inputs
  app_context
	    Specifies the application context.

  actions   Specifies the action table to register.

  num_args  Specifies the number of entries in this action table.

Description
  XtAppAddActions() registers actions, an array of num_actions	XtActionsRec structures with the Translation Manager for the application con-
  text app_context.  Each element of the array contains an action name and an action procedure pointer.   When	a  named  action  is  invoked
  through a translation table, the procedure to be called is looked up in the action tables that have been registered.

  If  more  than  one action is registered with the same name, the most recently registered action is used.  If duplicate actions exist in an
  action table, the first is used.  XtAppAddActions() registers actions globally to an application context.  This is in contrast  to  actions
  placed in the Core widget class part actions field which are defined locally to a widget class only.

  See XtActionProc(2) for an explanation of how to write an action procedure.

Usage
  Note	that  there  is  no  way to unregister actions.  Registering an new definition for an action name will simply make the old definition
  inaccessible.

  Action procedures should not assume that the widget in which they are invoked is realized; an accelerator can cause an action to be  called
  for a widget that does not yet have a window.

  You  should  never need to call XtAppAddActions() when writing a widget.  Widget's actions are registered locally to the widget through the
  Core class part actions field.

Background
  The translation manager provides an interface to specify and manage the mapping of X event sequences into  procedure	calls,	for  example,
  calling procedure Yes() when the `Y' key is pressed.

  The translation manager uses two kinds of tables to perform translations:

  o  Action tables, which specify the mapping of externally available procedure name strings to the corresponding procedure.

  o  A translation table, which specifies the mapping of event sequences to procedure name strings.

  The  translation manager uses a simple algorithm to resolve the name of a procedure specified in a translation table into the actual proce-
  dure specified in an action table.  When the widget is realized, the translation manager performs a search for the name  in  the  following
  tables, in order:

  o  The widget's class and all superclass action tables, in subclass-to-superclass order.

  o  The parent's class and all superclass action tables, in subclass-to-superclass order, then on up the ancestor tree.

  o  The action tables registered with XtAppAddActions() and XtAddActions() from the most recently added table to the oldest table.

  As  soon as it finds a name, the translation manager stops the search.  If it cannot find a name, the translation manager generates a warn-
  ing message.

  The Intrinsics reserve all action names and parameters starting with the characters "Xt" for future standard enhancements.  Users, applica-
  tions,  and  widgets	should not declare action names or pass parameters starting with these characters except to invoke specified built-in
  Intrinsics functions.

Example
  An action table is generally declared as a statically initialized array.  By convention, the name of an action and the C function name  are
  identical except that the function name begins with an uppercase letter:

     static XtActionsRec global_actions[] = {
	  {"confirm", Confirm},
	  {"quit", Quit},
     };

  This action table could be registered with the following command:

     XtAppAddActions(app, global_actions, XtNumber(global_action));

Structures
  The XtActionsRec structure and the XtActionList type are defined as follows:

     typedef struct _XtActionsRec{
	 String      string;
	 XtActionProc proc;
     } XtActionsRec;

     typedef struct _XtActionsRec *XtActionList;

See Also
  XtActionProc(2).

Xt - Translations and Actions													 XtAppAddActions()