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 XtAp‐
  pAddActions() 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 trans‐
  lation 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.  Callbacks 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 table,
  and document any arguments each action  expects,  and	 also  the  event
  types that the action can be safely called on.  Also, if an action pro‐
  cedure 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()

Vote for polarhome