hpux man page for xtactionproc

XtActionProc()															    XtActionProc()

Name
  XtActionProc - interface definition for action procedure.

Synopsis
  typedef void (*XtActionProc)(Widget, XEvent *, String *, Cardinal *);
	 Widget w;
	 XEvent *event;
	 String *params;
	 Cardinal *num_params;

Inputs
  w	    Specifies the widget in which the event occurred that caused the action to be called.

  event     Specifies the event that caused the action to be called.  If the action is called after a sequence of events, then the last event
	    in the sequence is used.

  params    Specifies an array of strings that were specified in the translation table as comma-separated arguments to the action.

  num_params
	    Specifies the number of strings in params.

Description
  An XtActionProc is an action procedure.  Action procedures are given names in an XtActionList and that array	of  name/procedure  pairs  is
  then	registered with the Translation Manager either through a call to XtAppAddActions() or by statically initializing the actions field of
  the Core widget record.  The translation table of a widget binds event sequences into a sequence of action procedures, and the  Translation
  Manager automatically invokes the action procedures when the specified event sequences occur.

  The  params  argument  is  an  array	of strings that the action may use.  These strings are the comma-separated arguments specified in the
  translation table.  An action procedure may use or ignore them, and may invoke a resource converter to convert strings to convert  each  of
  the strings to some other desired type.

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

Usage
  As an application programmer, you can often customize the behavior of a widget either by adding callback functions  to  one  of  the	lists
  defined by the widget, or by writing and registering custom action procedures and invoking them from the widget's translation table.	Call-
  backs are the simpler approach and are usually sufficient.  Action procedures are usually used when you need to  directly  bind  particular
  user	events	to  particular actions-for example, when the widget does not provide a callback that is invoked in response to the event type
  that you are interested in.  If you wanted to pop up a menu when the mouse entered a widget, or draw	a  box	when  the  user  clicked  and
  dragged  the	mouse,	for  example,  you  would  probably  use  action  procedures.	Note that action procedures are not registered with a
  client_data argument as callbacks are, and so application-level action procedures may have to depend on global data.	 Widget-level  action
  procedures can usually get all the data they need from their widget argument.

  Note that it is usually a widget's action procedures that invoke the functions registered on that widget's callback lists.

  Many	action	routines are intentionally written not to depend on the detailed information inside any particular type of event, so that the
  user may use the translation table to invoke the action in response to different types of events.  For example, it is useful for an  action
  routine  normally  triggered	by a pointer click to work when called in response to a key instead.  Such an action should not depend on the
  event structure fields unique to button events.  If your action does depend on the details of a particular event type, you  must  cast  the
  event argument to a pointer to an event structure of the appropriate type.

  When	you  write a widget or an application, you should document each of the action procedures that users may invoke from a translation ta-
  ble, and document any arguments each action expects, and also the event types that the action can be safely called on.  Also, if an  action
  procedure invokes the procedures on a callback list without checking that the widget is realized, the callback documentation must note that
  the widget may not yet be realized.

  In many action procedures, the last two arguments are unused.  When you don't use the last two arguments, be sure to place the lint comment
  /*ARGSUSED*/	just  before  the  action  procedure  definition.   To conform to ANSI-C standards, all four arguments of an action should be
  declared, even if the trailing arguments are not used.

  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
  The following two action procedures are from the Xaw Command widget:

     static void
     Highlight(w,event,params,num_params)
     Widget w;
     XEvent *event;
     String *params;
     Cardinal *num_params;
     {
       CommandWidget cbw = (CommandWidget)w;

       if ( *num_params == (Cardinal) 0)
	 cbw->command.highlighted = HighlightWhenUnset;
       else {
	 if ( *num_params != (Cardinal) 1)
	   XtWarning("Too many parameters passed to highlight action table.");
	 switch (params[0][0]) {
	 case 'A':
	 case 'a':
	   cbw->command.highlighted = HighlightAlways;
	   break;
	 default:
	   cbw->command.highlighted = HighlightWhenUnset;
	   break;
	 }
       }

       if (XtIsRealized(w))
	 PaintCommandWidget(w, HighlightRegion(cbw), TRUE);
     }

     /* ARGSUSED */
     static void
     Notify(w,event,params,num_params)
     Widget w;
     XEvent *event;
     String *params;	     /* unused */
     Cardinal *num_params;   /* unused */
     {
       CommandWidget cbw = (CommandWidget)w;

       /* check to be sure state is still Set so that user can cancel
	  the action (e.g., by moving outside the window, in the default
	  bindings.
       */
       if (cbw->command.set)
	 XtCallCallbackList(w, cbw->command.callbacks, NULL);
     }

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
  XtAppAddActions(1).

Xt - Translations and Actions													    XtActionProc()