Chapter 10

Translation Management

Except under unusual circumstances, widgets do not hardwire the mapping of user events into widget behavior by using the event manager. Instead, they provide a default mapping of events into behavior that you can override.

The translation manager provides an interface to specify and manage the mapping of X event sequences into widget-supplied functionality, for example, calling procedure Abc when the y key is pressed.

The translation manager uses two kinds of tables to perform translations:

• The action tables, which are in the widget class structure, specify the mapping of externally available procedure name strings to the corresponding procedure implemented by the widget class.

• A translation table, which is in the widget class structure, specifies the mapping of event sequences to procedure name strings.

You can override the translation table in the class structure for a specific widget instance by supplying a different translation table for the widget instance. The resources XtNtranslations and XtNbaseTranslations are used to modify the class default translation table; see Section 10.3.

All widget class records contain an action table, an array of XtActionsRec entries. In addition, an application can register its own action tables with the translation manager so that the translation tables it provides to widget instances can access application functionality directly. The translation action procedure pointer is of type XtActionProc.

typedef void (*XtActionProc)(Widget, XEvent*, String*, Cardinal*);

Widget w;
XEvent *event;
String *params;
Cardinal *num_params;

typedef struct _XtActionsRec {
        String string;
        XtActionProc proc;
} XtActionsRec, *XtActionList;

The string field is the name used in translation tables to access the procedure. The proc field is a pointer to a procedure that implements the functionality.

When the action list is specified as the CoreClassPart actions field the string pointed to by string must be permanently allocated prior to or during the execution of the class initialization procedure and must not be subsequently deallocated.

Action procedures should not assume that the widget in which they are invoked is realized; an accelerator specification can cause an action procedure to be called for a widget that does not yet have a window. Widget writers should also note which of a widget's callback lists are invoked from action procedures and warn clients not to assume the widget is realized in those callbacks.

For example, a Pushbutton widget has procedures to take the following actions:

• Set the button to indicate it is activated.

• Unset the button back to its normal mode.

• Highlight the button borders.

• Unhighlight the button borders.

• Notify any callbacks that the button has been activated.

The action table for the Pushbutton widget class makes these functions available to translation tables written for Pushbutton or any subclass. The string entry is the name used in translation tables. The procedure entry (usually spelled identically to the string) is the name of the C procedure that implements that function:

            XtActionsRec actionTable[ ] = {
                    {"Set",         Set},
                    {"Unset",       Unset},
                    {"Highlight",   Highlight},
                    {"Unhighlight", Unhighlight}
                    {"Notify",      Notify},
            };

The Intrinsics reserve all action names and parameters starting with the characters "Xt" for future standard enhancements. Users, applications, and widgets should not declare action names or pass parameters starting with these characters except to invoke specified built-in Intrinsics functions.

10.1.1. Action Table Registration

The actions and num_actions fields of CoreClassPart specify the actions implemented by a widget class. These are automatically registered with the Intrinsics when the class is initialized and must be allocated in writable storage prior to Core class_part initialization, and never deallocated.
To save memory and optimize access, the Intrinsics may overwrite the storage in order to compile the list into an internal representation.

To declare an action table within an application and register it with the translation manager, use XtAppAddActions.

void XtAppAddActions(app_context, actions, num_actions)

XtAppContext app_context;
XtActionList actions;
Cardinal num_actions;

If more than one action is registered with the same name, the most recently registered action is used. If duplicate actions exist in an action table, the first is used. The Intrinsics register an action table containing XtMenuPopup and XtMenuPopdown as part of XtCreateApplicationContext.

10.1.2. Action Names to Procedure Translations

The translation manager uses a simple algorithm to resolve the name of a procedure specified in a translation table into the actual procedure specified in an action table. When the widget is realized, the translation manager performs a search for the name in the following tables, in order:

• The widget's class and all superclass action tables, in subclass-to-superclass order.

• The parent's class and all superclass action tables, in subclass-to-superclass order, then on up the ancestor tree.

• The action tables registered with XtAppAddActions and XtAddActions from the most recently added table to the oldest table.

As soon as it finds a name, the translation manager stops the search. If it cannot find a name, the translation manager generates a warning message.

10.1.3. Action Hook Registration

An application can specify a procedure that will be called just before every action routine is dispatched by the translation manager. To do so, the application supplies a procedure pointer of type XtActionHookProc.

typedef void (*XtActionHookProc)(Widget, XtPointer, String, XEvent*, String*, Cardinal*);

Widget w;
XtPointer client_data;
String action_name;
Xevent* event;
String* params;
Cardinal* num_params;

Action hooks should not modify any of the data pointed to by the arguments other than the client_data argument.

To add an action hook, use XtAppAddActionHook.

XtActionHookId XtAppAddActionHook(app, proc, client_data)

XtAppContext app;
XtActionHookProc proc;
XtPointer client_data;

XtAppAddActionHook adds the specified procedure to the front of a list maintained in the application context. In the future, when an action routine is about to be invoked for any widget in this application context, either through the translation manager or via XtCallActionProc, the action hook procedures will be called in reverse order of registration just prior to invoking the action routine.

Action hook procedures are removed automatically and the XtActionHookId s destroyed when the application context in which they were added is destroyed.

To remove an action hook procedure without destroying the application context, use XtRemoveActionHook.

void XtRemoveActionHook(id)

XtActionHookId id;

XtRemoveActionHook removes the specified action hook procedure from the list in which it was registered.

All widget instance records contain a translation table, which is a resource with a default value specified elsewhere in the class record. A translation table specifies what action procedures are invoked for an event or a sequence of events. A translation table is a string containing a list of translations from an event sequence into one or more action procedure calls. The translations are separated from one another by newline characters (ASCII LF). The complete syntax of translation tables is specified in Appendix B.

As an example, the default behavior of Pushbutton is

• Highlight on enter window.

• Unhighlight on exit window.

• Invert on left button down.

• Call callbacks and reinvert on left button up.

The following illustrates Pushbutton's default translation table:

               static String defaultTranslations =
                       "<EnterWindow>:Highlight( )\n\
                       <LeaveWindow>:Unhighlight( )\n\
                       <BtnlDown>: Set( )\n\
                       <BtnlUp>: Notify( ) Unset( )";

The tm_table field of the CoreClassPart should be filled in at class initialization time with the string containing the class's default translations. If a class wants to inherit its superclass's translations, it can store the special value XtInheritTranslations into tm_table. In Core's class part initialization procedure, the Intrinsics compile this translation table into an efficient internal form. Then, at widget creation time, this default translation table is combined with the XtNtranslations and XtNbaseTranslations resources; see Section 10.3.

The resource conversion mechanism automatically compiles string translation tables that are specified in the resource database. If a client uses translation tables that are not retrieved via a resource conversion, it must compile them itself using XtParseTranslationTable.

The Intrinsics use the compiled form of the translation table to register the necessary events with the event manager. Widgets need do nothing other than specify the action and translation tables for events to be processed by the translation manager.

10.2.1. Event Sequences

An event sequence is a comma-separated list of X event descriptions that describes a specific sequence of X events to map to a set of program actions. Each X event description consists of three parts: The X event type, a prefix consisting of the X modifier bits, and an event-specific suffix.

Various abbreviations are supported to make translation tables easier to read. The events must match incoming events in left-to-right order to trigger the action sequence.

10.2.2. Action Sequences

Action sequences specify what program or widget actions to take in response to incoming X events. An action sequence consists of space-separated action procedure call specifications. Each action procedure call consists of the name of an action procedure and a parenthesized list of zero or more comma-separated string parameters to pass to that procedure. The actions are invoked in left-to-right order as specified in the action sequence.

10.2.3. Multi-click Time

Translation table entries may specify actions that are taken when two or more identical events occur consecutively within a short time interval, called the multi-click time. The multi-click time value may be specified as an application resource with name "multiClickTime" and class "MultiClickTime" and may also be modified dynamically by the application. The multi-click time is unique for each Display value and is retrieved from the resource database by XtDisplayInitialize. If no value is specified, the initial value is 200 milliseconds.

To set the multi-click time dynamically, use XtSetMultiClickTime.

void XtSetMultiClickTime(display, time)

Display *display;
int time;

XtSetMultiClickTime sets the time interval used by the translation manager to determine when multiple events are interpreted as a repeated event. When a repeat count is specified in a translation entry, the interval between the timestamps in each pair of repeated events (e.g., between two ButtonPress events) must be less than the multi-click time in order for the translation actions to be taken.

To read the multi-click time, use XtGetMultiClickTime.

int XtGetMultiClickTime(display)

Display *display;

XtGetMultiClickTime returns the time in milliseconds that the translation manager uses to determine if multiple events are to be interpreted as a repeated event for purposes of matching a translation entry containing a repeat count.

Sometimes an application needs to merge its own translations with a widget's translations. For example, a window manager provides functions to move a window. The window manager wishes to bind this operation to a specific pointer button in the title bar without the possibility of user override and bind it to other buttons that may be overridden by the user.

To accomplish this, the window manager should first create the title bar and then should merge the two translation tables into the title bar's translations. One translation table contains the translations that the window manager wants only if the user has not specified a translation for a particular event or event sequence (i.e., those that may be overridden). The other translation table contains the translations that the window manager wants regardless of what the user has specified.

Three Intrinsics functions support this merging:

XtParseTranslationTable	Compiles a translation table.
XtAugmentTranslations	Merges a compiled translation table into a widget's compiled translation table, ignoring any new translations that conflict with existing translations.
XtOverrideTranslations	Merges a compiled translation table into a widget's compiled translation table, replacing any existing translations that conflict with new translations.

To compile a translation table, use XtParseTranslationTable.

XtTranslations XtParseTranslationTable(table)

String table;

The XtParseTranslationTable function compiles the translation table, provided in the format given in Appendix B, into an opaque internal representation of type XtTranslations. Note that if an empty translation table is required for any purpose, one can be obtained by calling XtParseTranslationTable and passing an empty string.

To merge additional translations into an existing translation table, use XtAugmentTranslations.

void XtAugmentTranslations(w, translations)

Widget w;
XtTranslations translations;

The XtAugmentTranslations function merges the new translations into the existing widget translations, ignoring any #replace, #augment, or #override directive that may have been specified in the translation string. The translation table specified by translations is not altered by this process. XtAugmentTranslations logically appends the string representation of the new translations to the string representation of the widget's current translations and reparses the result with no warning messages about duplicate left-hand sides, then stores the result back into the widget instance; i.e., if the new translations contain an event or event sequence that already exists in the widget's translations, the new translation is ignored.

To overwrite existing translations with new translations, use XtOverrideTranslations.

void XtOverrideTranslations(w, translations)

Widget w;
XtTranslations translations;

The XtOverrideTranslations function merges the new translations into the existing widget translations, ignoring any #replace, #augment, or #override directive that may have been specified in the translation string. The translation table specified by translations is not altered by this process. XtOverrideTranslations logically appends the string representation of the widget's current translations to the string representation of the new translations and reparses the result with no warning messages about duplicate left-hand sides, then stores the result back into the widget instance; i.e., if the new translations contain an event or event sequence that already exists in the widget's translations, the new translation overrides the widget's translation.

To replace a widget's translations completely, use XtSetValues on the XtNtranslations resource and specify a compiled translation table as the value.

To make it possible for users to easily modify translation tables in their resource files, the string-to-translation-table resource type converter allows the string to specify whether the table should replace, augment, or override any existing translation table in the widget. To specify this, a sharp sign (#) is given as the first character of the table followed by one of the keywords "replace", "augment", or "override" to indicate whether to replace, augment, or override the existing table. The replace or merge operation is performed during the Core instance initialization. Each merge operation produces a new translation resource value; if the original tables were shared by other widgets, they are unaffected. If no directive is specified, "#replace" is assumed.

At instance initialization the XtNtranslations resource is first fetched. Then, if it was not specified or did not contain "#replace", the resource database is searched for the resource XtNbaseTranslations. If XtNbaseTranslations is found it is merged into the widget class translation table.

Then the widget translations field is merged into the result, or into the class translation table if XtNbaseTranslations was not found. This final table is then stored into the widget translations field. If the XtNtranslations resource specified "#replace" no merge is done. If neither XtNbaseTranslations or XtNtranslations are specified, the class translation table is copied into the widget instance.

To completely remove existing translations, use XtUninstallTranslations.

void XtUninstallTranslations(w)

Widget w;

The XtUninstallTranslations function causes the entire translation table for the widget to be removed.

It is often desirable 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 lets you accomplish this. An accelerator table is a translation table that is bound with its actions in the context of a particular widget, the source widget. The accelerator table can then be installed on one or more destination widgets. When an event sequence in the destination widget would cause an accelerator action to be taken, and if the source widget is sensitive, the actions are executed as though triggered by the same event sequence in the accelerator source widget. The event is passed to the action procedure without modification. The action procedures used within accelerators must not assume 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.

Each widget instance contains that widget's exported accelerator table as a resource. Each class of widget exports a method that takes a displayable string representation of the accelerators so that widgets can display their current accelerators. The representation is the accelerator table in canonical translation table form (see Appendix B). The display_accelerator procedure pointer is of type XtStringProc.

typedef void (*XtStringProc)(Widget, String);

Widget w;
String string;

Accelerators can be specified in resource files, and the string representation is the same as for a translation table. However, the interpretation of the #augment and #override directives applies to what will happen when the accelerator is installed; that is, whether or not the accelerator translations will override the translations in the destination widget. The default is #augment, which means that the accelerator translations have lower priority than the destination translations. The #replace directive is ignored for accelerator tables.

To parse an accelerator table, use XtParseAcceleratorTable.

XtAccelerators XtParseAcceleratorTable(source)

String source;

The XtParseAcceleratorTable function compiles the accelerator table into an opaque internal representation. The client should set the XtNaccelerators resource of each widget that is to be activated by these translations to the returned value.

To install accelerators from a widget on another widget, use XtInstallAccelerators.

void XtInstallAccelerators(destination, source)

Widget destination;
Widget source;

The XtInstallAccelerators function installs the accelerators resource value from source onto destination by merging the source accelerators into the destination translations. If the source display_accelerator field is non-NULL, XtInstallAccelerators calls it with the source widget and a string representation of the accelerator table, which indicates that its accelerators have been installed and that it should display them appropriately. The string representation of the accelerator table is its canonical translation table representation.

As a convenience for installing all accelerators from a widget and all its descendants onto one destination, use XtInstallAllAccelerators.

void XtInstallAllAccelerators(destination, source)

Widget destination;
Widget source;

The XtInstallAllAccelerators function recursively descends the widget tree rooted at source and installs the accelerators resource value of each widget encountered onto destination. A common use is to call XtInstallAllAccelerators and pass the application main window as the source.

The translation manager provides support for automatically translating KeyCodes in incoming key events into KeySyms. KeyCode-to-KeySym translator procedure pointers are of type XtKeyProc.

typedef void (*XtKeyProc)(Display*, KeyCode, Modifiers, Modifiers*, KeySym*);

Display *display;
KeyCode keycode;
Modifiers modifiers;
Modifiers *modifiers_return;
KeySym *keysym_return;

This procedure takes a KeyCode and modifiers and produces a KeySym. For any given key translator function and keyboard encoding, modifiers_return will be a constant per KeyCode that indicates the subset of all modifiers that are examined by the key translator for that KeyCode.

The KeyCode-to-KeySym translator procedure must be implemented such that multiple calls with the same display, keycode, and modifiers return the same result until either a new case converter ( XtCaseProc) is installed or a MappingNotify event is received.

The Intrinsics maintain tables internally to map KeyCodes to KeySyms for each open display. Translator procedures and other clients may share a single copy of this table to perform the same mapping.

To return a pointer to the KeySym-to-KeyCode mapping table for a particular display, use XtGetKeysymTable.

KeySym *XtGetKeysymTable(display, min_keycode_return, keysyms_per_keycode_return)

Display *display;
KeyCode *min_keycode_return;
int *keysyms_per_keycode_return;

XtGetKeysymTable returns a pointer to the Intrinsics' copy of the server's KeyCode-to-KeySym table. This table must not be modified. There are keysyms_per_keycode return KeySyms associated with each KeyCode, located in the table with indices starting at index

(test_keycode - min_keycode_return) * keysyms_per_keycode_return

for KeyCode test_keycode. Any entries that have no KeySyms associated with them contain the value NoSymbol. Clients should not cache the KeySym table but should call XtGetKeysymTable each time the value is needed, as the table may change prior to dispatching each event.

For more information on this table, see Section 12.7 in Xlib - C Language X Interface.

To register a key translator, use XtSetKeyTranslator.

void XtSetKeyTranslator(display, proc)

Display *display;
XtKeyProc proc;

The XtSetKeyTranslator function sets the specified procedure as the current key translator. The default translator is XtTranslateKey, an XtKeyProc that uses the Shift, Lock, numlock, and group modifiers with the interpretations defined in X Window System Protocol, Section 5 (provided in printed version only). It is provided so that new translators can call it to get default KeyCode-to-KeySym translations and so that the default translator can be reinstalled.

To invoke the currently registered KeyCode-to-KeySym translator, use XtTranslateKeycode.

void XtTranslateKeycode(display, keycode, modifiers, modifiers_return, keysym_return)

Display *display;
KeyCode keycode;
Modifiers modifiers;
Modifiers *modifiers_return;
KeySym *keysym_return;

The XtTranslateKeycode function passes the specified arguments directly to the currently registered KeyCode-to-KeySym translator.

To handle capitalization of nonstandard KeySyms, the Intrinsics allow clients to register case conversion routines. Case converter procedure pointers are of type XtCaseProc.

typedef void (*XtCaseProc)(Display*, KeySym, KeySym*, KeySym*);

Display *display;
KeySym keysym;
KeySym *lower_return;
KeySym *upper_return;

If there is no case distinction, this procedure should store the KeySym into both return values.

To register a case converter, use XtRegisterCaseConverter.

void XtRegisterCaseConverter(display, proc, start, stop)

Display *display;
XtCaseProc proc;
KeySym start;
KeySym stop;

The XtRegisterCaseConverter registers the specified case converter. The start and stop arguments provide the inclusive range of KeySyms for which this converter is to be called. The new converter overrides any previous converters for KeySyms in that range. No interface exists to remove converters; you need to register an identity converter. When a new converter is registered, the Intrinsics refresh the keyboard state if necessary. The default converter understands case conversion for all Latin KeySyms defined in X Window System Protocol, Appendix A (provided in printed version only).

To determine upper- and lower-case equivalents for a KeySym, use XtConvertCase.

void XtConvertCase(display, keysym, lower_return, upper_return)

Display *display;
KeySym keysym;
KeySym *lower_return;
KeySym *upper_return;

The XtConvertCase function calls the appropriate converter and returns the results. A user-supplied XtKeyProc may need to use this function.

When an action procedure is invoked on a KeyPress or KeyRelease event, it often has a need to retrieve the KeySym and modifiers corresponding to the event that caused it to be invoked. In order to avoid repeating the processing that was just performed by the Intrinsics to match the translation entry, the KeySym and modifiers are stored for the duration of the action procedure and are made available to the client.

To retrieve the KeySym and modifiers that matched the final event specification in the translation table entry, use XtGetActionKeysym.

KeySym XtGetActionKeysym(event, modifiers_return)

XEvent *event;
Modifiers *modifiers_return;

If XtGetActionKeysym is called after an action procedure has been invoked by the Intrinsics and before that action procedure returns, and if the event pointer has the same value as the event pointer passed to that action routine, and if the event is a KeyPress or KeyRelease event, then XtGetActionKeysym returns the KeySym that matched the final event specification in the translation table and, if modifiers_return is non-NULL, the modifier state actually used to generate this KeySym; otherwise, if the event is a KeyPress or KeyRelease event, then XtGetActionKeysym calls XtTranslateKeycode and returns the results; else it returns NoSymbol and does not examine modifiers_return.

Note that if an action procedure invoked by the Intrinsics invokes a subsequent action procedure (and so on) via XtCallActionProc, the nested action procedure may also call XtGetActionKeysym to retrieve the Intrinsics' KeySym and modifiers.

To return the list of KeyCodes that map to a particular KeySym in the keyboard mapping table maintained by the Intrinsics, use XtKeysymToKeycodeList.

void XtKeysymToKeycodeList(display, keysym, keycodes_return, keycount_return)

Display *display;
KeySym keysym;
KeyCode **keycodes_return;
Cardinal *keycount_return;

The XtKeysymToKeycodeList procedure returns all the KeyCodes that have keysym in their entry for the keyboard mapping table associated with display. For each entry in the table, the first four KeySyms (groups 1 and 2) are interpreted as specified by X Window System Protocol, Section 5 (provided in printed version only). If no KeyCodes map to the specified KeySym, keycount_return is zero and *keycodes_return is NULL.

The caller should free the storage pointed to by keycodes_return using XtFree when it is no longer useful. If the caller needs to examine the KeyCode-to-KeySym table for a particular KeyCode, it should call XtGetKeysymTable.

To register button and key grabs for a widget's window according to the event bindings in the widget's translation table, use XtRegisterGrabAction.

void XtRegisterGrabAction(action_proc, owner_events, event_mask, pointer_mode, keyboard_mode)

XtActionProc action_proc;
Boolean owner_events;
unsigned int event_mask;
int pointer_mode,keyboard_mode;

owner_events
event mask
pointer_mode
keyboard_mode

Specify arguments to XtGrabButton or XtGrabKey.

XtRegisterGrabAction adds the specified action_proc to a list known to the translation manager. When a widget is realized, or when the translations of a realized widget or the accelerators installed on a realized widget are modified, its translation table and any installed accelerators are scanned for action procedures on this list. If any are invoked on ButtonPress or KeyPress events as the only or final event in a sequence, the Intrinsics will call XtGrabButton or XtGrabKey for the widget with every button or KeyCode which maps to the event detail field, passing the specified owner_events, event_mask, pointer_mode, and keyboard_mode. For ButtonPress events, the modifiers specified in the grab are determined directly from the translation specification and confine_to and cursor are specified as None. For KeyPress events, if the translation table entry specifies colon (:) in the modifier list, the modifiers are determined by calling the key translator procedure registered for the display and calling XtGrabKey for every combination of standard modifiers which map the KeyCode to the specified event detail KeySym, and ORing any modifiers specified in the translation table entry, and event_mask is ignored. If the translation table entry does not specify colon in the modifier list, the modifiers specified in the grab are those specified in the translation table entry only. For both ButtonPress and KeyPress events, don't-care modifiers are ignored unless the translation entry explicitly specifies "Any" in the modifiers field.

If the specified action_proc is already registered for the calling process, the new values will replace the previously specified values for any widgets that become realized following the call, but existing grabs are not altered on currently-realized widgets.

When translations or installed accelerators are modified for a realized widget, any previous key or button grabs registered as a result of the old bindings are released if they do not appear in the new bindings and are not explicitly grabbed by the client with XtGrabKey or XtGrabButton.

Normally action procedures are invoked by the Intrinsics when an event or event sequence arrives for a widget. To invoke an action procedure directly, without generating (or synthesizing) events, use XtCallActionProc.

void XtCallActionProc(widget, action, event, params, num_params)

Widget widget;
String action;
XEvent *event;
String *params;
Cardinal num_params;

XtCallActionProc searches for the named action routine in the same manner and order as translation tables are bound, as described in Section 10.1.2, except that application action tables are searched, if necessary, as of the time of the call to XtCallActionProc. If found, the action routine is invoked with the specified widget, event pointer, and parameters. It is the responsibility of the caller to ensure that the contents of the event, params, and num_params arguments are appropriate for the specified action routine and, if necessary, that the specified widget is realized or sensitive. If the named action routine cannot be found, XtCallActionProc generates a warning message and returns.

Occasionally a subclass will require the pointers to one or more of its superclass's action procedures. This would be needed, for example, in order to envelope the superclass's action. To retrieve the list of action procedures registered in the superclass's actions field, use XtGetActionList.

void XtGetActionList(widget_class, actions_return, num_actions_return)

WidgetClass widget_class;
XtActionList *actions_return;
Cardinal *num_actions_return;

XtGetActionList returns the action table defined by the specified widget class. This table does not include actions defined by the superclasses. If widget class is not initialized, or is not coreWidgetClass or a subclass thereof, or if the class does not define any actions, *actions_return will be NULL and *num_actions_return will be zero. If *actions_return is nonNULL the client is responsible for freeing the table using XtFree when it is no longer needed.