XtInstallAc(3x) — HP-UX 9.05

NAME

XtInstallAccelerators − install a widget’s accelerators on another widget.

Synopsis

void XtInstallAccelerators(destination, source)

Widget destination;
Widget source;

Inputs

destination
Specifies the widget in which events specified in the accelerator table will be detected. Must be of class Core or any subclass thereof.

sourceSpecifies the widget whose actions will be invoked when events occur in destination. Must be of class Core or any subclass thereof.

Description

XtInstallAccelerators() merges the accelerator table of source into the translation table of destination. After this call, events in the destination widget will trigger actions in the source widget. If the display_accelerator() method of source is non-NULL, XtInstallAccelerators() calls it with source and a canonical representation of the accelerator table that was installed. This method is a hook that is intended to allow a widget to dynamically modify its appearance (a menu button might display the key sequence that will invoke it, for example) when an accelerator is installed.

Usage

It is often convenient to be able to bind events in one widget to actions in another. In particular, it is often useful to be able to invoke menu actions from the keyboard. The Intrinsics provide a facility, called accelerators, that let you accomplish this. An accelerator table is a translation table that binds events in the destination widget to actions in the source widget. The accelerator table can be installed on one or more destination widgets. When an event sequence in destination would cause an accelerator action to be invoked, and if the source widget is sensitive, the actions are executed as though triggered by the same event sequence in source. The event is passed to the action procedure without modification. The action procedures used within accelerators must assume neither that the source widget is realized, nor that any fields of the event are in reference to the source widget’s window if the widget is realized. defined by the Core widget class. The actual value of this resource can be hardcoded by the application or set in a resource file, just like any other resource. actually be used, however, the application must call XtInstallAccelerators() (or XtInstallAllAccelerators()). This call takes two arguments. The destination widget is the widget whose translation table will be augmented with the accelerator table from the source widget. It can often difficult to remember which of the two widgets in this call is which. If you want to install a keyboard accelerator so that a keystroke in a text widget invokes an action in a menu button, then the menu button is the source, and the text widget is the destination. You must set the the menu button, and then install those accelerators on the text widget.

Example

Assume an application whose top-level shell widget is named topLevel, and which contains a Command widget instance named quit. Further assume that the quit widget has the

*quit.accelerators: 0 <KeyPress>q: notify()

The call:

XtInstallAccelerators (topLevel, quit);

would allow a "q" typed in the application’s top-level window to invoke the quit widget’s notify action. The notify action invokes the callback list of the button, and assuming that a quit callback was registered, causes the application to terminate.

Museum