Sometimes it is desirable for an event received by one widget to activate an action in another. For example, the application may establish a shortcut for activating a button in a menu; the user can activate the menu item even when focus is not in the menu. Motif has two facilities, mnemonics and accelerators, for allowing events in one widget to invoke actions in another.
A mnemonic is a keysym that identifies a key the user can press to activate a menu item when the menu is posted. A button in a MenuBar, PulldownMenu, or PopupMenu can have a mnemonic. When the button is in a PulldownMenu or PopupMenu that is the most recently posted menu, the user activates the button by pressing the key associated with the mnemonic. When the button is in a MenuBar, the MenuBar must have focus for the mnemonic to activate the button. However, the user can activate the button from within the hierarchy that contains the MenuBar, even if the MenuBar does not have focus, by pressing the key while holding the Alt modifier.
An application or user supplies a mnemonic for a button by specifying a value for the Label or LabelGadget resource XmNmnemonic. When the button is displayed, Motif underlines the first character in the label string that exactly matches the mnemonic in the character set specified by XmNmnemonicCharSet. Although the mnemonic must match a character in the label string exactly in order to be underlined, the user can activate the mnemonic by pressing either the shifted or the unshifted key.
An accelerator allows the user to activate a menu item when focus is anywhere in the hierarchy containing the menu, even if the menu is not posted. Accelerators are supported only for PushButtons and ToggleButtons (or their gadget equivalents) in PulldownMenus and PopupMenus.
An application or user supplies an accelerator for a button by specifying a value for the Label or LabelGadget resource XmNaccelerator. The value is a string in the same format as an event description in a translation table, except that only KeyPress events are allowed. Thus, an accelerator can have a modifier like Ctrl or Alt. XmNacceleratorText is a compound string that describes the accelerator event, for example, "Ctrl+A". Motif displays the accelerator text to the side of the button's label string or pixmap.
The following example creates a button with a mnemonic and an accelerator:
n = 0;
XtSetArg(args[n], XmNmnemonic, XStringToKeysym("A"); n++;
XtSetArg(args[n], XmNaccelerator, "Ctrl<Key>A"); n++;
XtSetArg(args[n], XmNacceleratorText,
XmStringCreateLocalized("Ctrl+A"); n++;
button1 = XmCreatePushButton(file_pane, "Answer", args,
n);
Motif's button accelerators and mnemonics are supported only for buttons in certain menus. Xt has a more general facility, also called accelerators, for allowing events in one widget to invoke actions in another.
Xt accelerators are mappings of event descriptions to actions, in the same format as a translation table. An application or user supplies accelerators for a widget as the value of the Core resource XmNaccelerators. The accelerators map events to actions of this widget, called the source widget. The application must then install the accelerators on a destination widget, using XtInstallAccelerators. This routine takes two arguments: the source widget, whose XmNaccelerators resource contains the accelerator table; and the destination widget, where the accelerators are to be installed. When the user produces an event in the destination widget that maps to an accelerator in the table, the event invokes the corresponding action in the source widget.
XtInstallAccelerators merges the accelerators with the destination widget's existing translations (the value of XmNtranslations). Accelerators can be merged in either #augment mode, the default, or #override mode. An accelerator table may begin with an #augment directive or a #override directive. The #replace directive is ignored.
As with translations, accelerators must be in an internal format when they are the value of XmNaccelerators. A string-to-accelerator-table converter parses an accelerator table string from a resource file. An application can use XtParseAcceleratorTable to compile an accelerator table string explicitly.
Accelerators are often defined for a parent source widget and installed on one or more child destination widgets. The SelectionBox and FileSelectionBox widgets install accelerators, the value of XmNtextAccelerators, on their text children. The default accelerators bind osfUp, osfDown, osfBeginLine, osfEndLine, and osfRestore events in the Text widget to SelectionBox or FileSelectionBox actions that select an item in the List and replace the Text widget value with that List item.