Name
XtInstallAccelerators — install a widget’s accelerators on another widget.
Synopsis
void XtInstallAccelerators(destination, source)
Widget destination;
Widget source;
Arguments
destination
Specifies the widget in which events specified in the accelerator table will be detected.
sourceSpecifies the widget whose actions will be invoked when events occur in destination.
Description
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.
Every widget includes an XtNaccelerators resource, which is 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.
However, in order for the XtNaccelerators resource to actually be used, the application must call XtInstallAccelerators (or XtInstallAllAccelerators). This call specifies two arguments. The destination widget is the widget whose translation table will be augmented with the accelerator table from the source widget. In other terms, you could think of the source as "source of actions" and the destination as "source of events." That is, events occurring in the destination widget will trigger actions in the source. (From the event’s point of view, the terminology seems backwards! However, the terms source and destination do make sense in terms of what is actually happening to the translation table of the destination widget.)
For example, assume an application whose top-level shell widget was named topLevel, and which contained a Command widget instance named quit. Further assume that the quit widget had the following XtNaccelerators resource defined for it:
∗quit.accelerators: \n\
<KeyPress>q: Quit()
The call:
XtInstallAccelerators (topLevel, quit);
would allow a "q" typed in the application’s top-level window to invoke the quit widget’s Quit action.
If the display_accelerator method in the Core part of the source widget class is non-NULL, XtInstallAccelerators calls it with the source widget and a string representation of the accelerator table. (The string representation of the accelerator table is a canonical translation table representation, not an exact replica of what was registered.) The method is invoked to inform the source widget that its accelerators have been installed on the destination widget so it can display them appropriately.
Core(3) describes the display_accelerator method. Volume Four, X Toolkit Intrinsics Programming Manual, has a complete accelerator programming example.