\&
.sp 1
.ce 3
\s+1\fBChapter 10\fP\s-1

\s+1\fBTranslation Management\s-1 
.sp 2
.nr H1 10
.nr H2 0
.nr H3 0
.nr H4 0
.nr H5 0
.LP
.XS
Chapter 10 \- Translation Management 
.XE
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.
.LP
The translation manager provides an interface to specify and manage the
mapping of X Event sequences into widget-supplied functionality,
for example, calling procedure \fIAbc\fP when the \fIy\fP key 
is pressed.
.LP
The translation manager uses two kinds of tables to perform translations:
.IP \(bu 5
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.
.IP \(bu 5
A translation table, which is in the widget class structure,
specifies the mapping of event sequence to procedure name strings.
.LP
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 resource name is XtNtranslations.
.NH 2
Action Tables
.XS
\fB\*(SN Action Tables\fP
.XE
.LP
All widget class records contain an action table.
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.
The translation action_proc procedure pointer is of type
.PN XtActionProc :
.IN "action_proc procedure" "" "@DEF@"
.IN "XtActionProc" "" "@DEF@"
.FD 0
typedef void (*XtActionProc)(Widget, XEvent *, String *, Cardinal *);
.br
      Widget \fIw\fP;
.br
      XEvent *\fIevent\fP;
.br
      String *\fIparams\fP;
.br
      Cardinal *\fInum_params\fP;
.FN
.IP \fIw\fP 1i
Specifies the widget that caused the action to be called.
.IP \fIevent\fP 1i
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.
.IP \fIparams\fP 1i
Specifies a pointer to the list of strings that were specified
in the translation table as arguments to the action.
.IP \fInum_params\fP 1i
Specifies the number of arguments specified in the translation table.
.IN "XtActionsRec"
.IN "XtActionList"
.LP
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct _XtActionsRec {
	String action_name;
	XtActionProc action_proc;
} XtActionsRec, *XtActionList;
.De
The action_name field is the name that you use in translation tables to access
the procedure.
The action_proc field is a pointer to a procedure that implements
the functionality.
.LP
For example, the Command widget has procedures to take the following actions:
.IP \(bu 5
Set the command button to indicate it is activated
.IP \(bu 5
Unset the button back to its normal mode
.IP \(bu 5
Highlight the button borders
.IP \(bu 5
Unhighlight the button borders
.IP \(bu 5
Notify any callbacks that the button has been activated
.LP
The action table for the Command widget class makes these functions
available to translation tables written for Command or any subclass.
The string entry is the name used in translation tables.
The procedure entry (often spelled identically to the string)
is the name of the C procedure that implements that function:
.LP
.IN "Action Table"
.Ds 0
.TA .5i 1.5i
.ta .5i 1.5i
XtActionsRec actionTable[] = {
	{"Set",	Set},
	{"Unset",	Unset},
	{"Highlight",	Highlight},
	{"Unhighlight",	Unhighlight}
	{"Notify",	Notify},
};
.De
.NH 3
Action Table Registration
.XS
\*(SN Action Table Registration
.XE
.LP
To declare an action table and register it with the translation manager, use
.PN XtAppAddActions .
.IN "XtAppAddActions" "" "@DEF@"
.FD 0
void XtAppAddActions(\fIapp_context\fP, \fIactions\fP, \fInum_actions\fP)
.br
      XtAppContext \fIapp_context\fP;
.br
      XtActionList \fIactions\fP;
.br
      Cardinal \fInum_actions\fP;
.FN
.IP \fIapp_context\fP 1i
Specifies the application context.
.IP \fIactions\fP 1i
Specifies the action table to register.
.IP \fInum_args\fP 1i
Specifies the number of entries in this action table.
.LP
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 \*(xI register an action table for
.PN MenuPopup
and
.PN MenuPopdown
as part of \*(tk initialization.
.NH 3
Action Names to Procedure Translations
.XS
\*(SN Action Names to Procedure Translations
.XE
.LP
The translation manager uses a simple algorithm to convert 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:
.IP \(bu 5
The widget's class action table for the name
.IP \(bu 5
The widget's superclass action table and on up the superclass chain
.IP \(bu 5
The action tables registered with
.PN XtAddActions 
(from the most recently added table to the oldest table)
.LP
As soon as it finds a name,
the translation manager stops the search.
If it cannot find a name,
the translation manager generates an error.
.NH 2
Translation Tables
.XS
\*(SN Translation Tables
.XE
.LP
All widget instance records contain a translation table,
which is a resource with no default value.
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.
.LP
As an example, the default behavior of Command is:
.IP \(bu 5
Highlight on enter window
.IP \(bu 5
Unhighlight on exit window
.IP \(bu 5
Invert on left button down
.IP \(bu 5
Call callbacks and reinvert on left button up
.LP
The following illustrates the Command's default translation table:
.LP
.IN "Translation Table"
.Ds 0
.TA .5i 1.5i
.ta .5i 1.5i
static String defaultTranslations =
	"<EnterWindow>:	Highlight()\\n\\
	<LeaveWindow>:	Unhighlight()\\n\\
	<Btn1Down>:	Set()\\n\\
	<Btn1Up>:	Notify() Unset()";
.De
.LP
The tm_table field of the
.PN CoreClass
record should be filled in at static 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
.PN XtInheritTranslations
into tm_table.
After the class initialization procedures have been called,
the \*(xI compile this translation table into an efficient internal form.
Then, at widget creation time,
this default translation table is used for any widgets
that have not had their core translations field set by the
resource manager or the initialize procedures.
.LP
The resource conversion mechanism automatically compiles
string translation tables that are resources.
If a client uses translation tables that are not resources,
it must compile them itself using
.PN XtParseTranslationTable .
.LP
The \*(xI 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.
.NH 3
Event Sequences
.XS
\*(SN Event Sequences
.XE
.LP
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: 
.IP \(bu 5
The X event type 
.IP \(bu 5
A prefix consisting of the X modifier bits
.IP \(bu 5
An event specific suffix
.LP
Various abbreviations are supported to make translation tables easier
to read.
.NH 3
Action Sequences
.XS
\*(SN Action Sequences
.XE
.LP
Action sequences specify what program or widget actions to take in response to
incoming X events. An action sequence of action procedure call specifications.
Each action procedure call consists of the name of an action procedure and a
parenthesized list of string parameters to pass to that procedure.
.NH 2
Translation Table Management
.XS
\fB\*(SN Translation Table Management\fP
.XE
.LP
Sometimes an application needs to destructively or nondestructively add
its own translations to a widget's translation.
For example, a window manager provides functions to move a window.
It usually may move the window when any pointer button is pressed down
in a title bar,
but it allows the user to specify other translations for the middle
or right button down in the title bar,
and it ignores any user translations for left button down.
.LP
To accomplish this,
the window manager first should 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).
The other translation table contains the translations that the
window manager wants regardless of what the user has specified.
.LP
Three \*(xI functions support this merging:
.TS
lw(2i) lw(3.75i).
T{
.PN XtParseTranslationTable
T}	T{
Compiles a translation table.
T}
.sp
T{
.PN XtAugmentTranslations
T}	T{
Nondestructively merges a compiled translation table into a widget's
compiled translation table.
T}
.sp
T{
.PN XtOverrideTranslations
T}	T{
Destructively merges a compiled translation table into a widget's
compiled translation table.
T}
.TE
.sp
.LP
To compile a translation table, use
.PN XtParseTranslationTable .
.IN "XtParseTranslationTable" "" "@DEF@"
.FD 0
XtTranslations XtParseTranslationTable(\fItable\fP)
.br
      String \fItable\fP;
.FN
.IP \fItable\fP 1i
Specifies the translation table to compile.
.LP
The
.PN XtParseTranslationTable
function compiles the translation table into the opaque internal representation
of type
.PN XtTranslations .
Note that if an empty translation table is required for any purpose,
one can be obtained by calling
.PN XtParseTranslationTable
and passing an empty string.
.sp
.LP
To merge new translations into an existing translation table, use
.PN XtAugmentTranslations .
.IN "XtAugmentTranslations" "" "@DEF@"
.FD 0
void XtAugmentTranslations(\fIw\fP, \fItranslations\fP)
.br
      Widget \fIw\fP;
.br
      XtTranslations \fItranslations\fP;
.FN
.ds Wi into which the new translations are to be merged
.IP \fIw\fP 1i
Specifies the widget \*(Wi.
.IP \fItranslations\fP 1i
Specifies the compiled translation table to merge in (must not be NULL).
.LP
The
.PN XtAugmentTranslations
function nondestructively merges the new translations into the existing widget
translations.
If the new translations contain an event or event sequence that
already exists in the widget's translations,
the new translation is ignored.
.sp
.LP
To overwrite existing translations with new translations, use
.PN XtOverrideTranslations .
.IN "XtOverrideTranslations" "" "@DEF@"
.FD 0
void XtOverrideTranslations(\fIw\fP, \fItranslations\fP)
.br
      Widget \fIw\fP;
.br
      XtTranslations \fItranslations\fP;
.FN
.ds Wi into which the new translations are to be merged
.IP \fIw\fP 1i
Specifies the widget \*(Wi.
.IP \fItranslations\fP 1i
Specifies the compiled translation table to merge in (must not be NULL).
.LP
The
.PN XtOverrideTranslations
function destructively merges the new translations into the existing widget
translations.
If the new translations contain an event or event sequence that
already exists in the widget's translations,
the new translation is merged in and override the widget's translation.
.LP
To replace a widget's translations completely, use
.PN XtSetValues
on the XtNtranslations resource and specifiy a compiled translation table
as the value.
.sp
.LP
To make it possible for users to easily modify translation tables in their
resource files, 
the string-to-translation-table resource type converter
allows specifying whether the table should replace, augment, or override any
existing translation table in the widget. 
As an option,
you can specify a number sign (#) as the first character of the table 
followed by ``replace'' (default), ``augment'', or ``override'' to indicate
whether to replace, augment, or override any existing table.
.sp
.LP
To completely remove existing translations, use
.PN XtUninstallTranslations .
.IN "XtUninstallTranslations" "" "@DEF@"
.FD 0
void XtUninstallTranslations(\fIw\fP)
.br
      Widget \fIw\fP;
.FN
.ds Wi from which the translations are to be removed
.IP \fIw\fP 1i
Specifies the widget \*(Wi.
.LP
The
.PN XtUninstallTranslations
function causes the entire translation table for widget to be removed.
.NH 2
Using Accelerators
.XS
\fB\*(SN Using Accelerators\fP
.XE
.LP
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 \*(xI provide a facility, called accelerators, that let you 
accomplish this.
.IN "Accelerator" "" "@DEF@"
An accelerator is a translation table that is bound with its
actions in the context of a particular widget.
The accelerator table can then be installed on some destination widget.
When an action in the destination widget would cause an accelerator action 
to be taken, rather than causing an action in the context of the destination, 
the actions are executed as though triggered by an action in the accelerator 
widget.
.LP
Each widget instance contains that widget's exported accelerator table.
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
.PN XtStringProc :
.IN "display_accelerator procedure" "" "@DEF@"
.IN "XtStringProc" "" "@DEF@"
.FD 0
typedef void (*XtStringProc)(Widget, String);
.br
      Widget \fIw\fP;
.br
      String \fIstring\fP;
.FN
.IP \fIw\fP 1i
Specifies the widget that the accelerators are installed on.
.IP \fIstring\fP 1i
Specifies the string representation of the accelerators for this widget.
.LP
Accelerators can be specified in defaults files, 
and the string representation is the same as for a translation table.
However,
the interpretation of the #augment and #override directives apply 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.
.sp
.LP
To parse an accelerator table, use
.PN XtParseAcceleratorTable .
.IN "XtParseAcceleratorTable" "" "@DEF@"
.FD 0
XtAccelerators XtParseAcceleratorTable(\fIsource\fP)
.br
      String \fIsource\fP;
.FN
.ds So to compile
.IP \fIsource\fP 1i
Specifies the accelerator table \*(So.
.LP
The
.PN XtParseAcceleratorTable
function compiles the accelerator table into the opaque internal representation.
.sp
.LP
To install accelerators from a widget on another widget, use
.PN XtInstallAccelerators .
.IN "XtInstallAccelerators" "" "@DEF@"
.FD 0
void XtInstallAccelerators(\fIdestination\fP, \fIsource\fP)
.br
      Widget \fIdestination\fP;
.br
      Widget \fIsource\fP;
.FN
.IP \fIdestination\fP 1i
Specifies the widget on which the accelerators are to be installed.
.ds Sr widget
.IP \fIsource\fP 1i
Specifies the \*(Sr from which the accelerators are to come.
.LP
The
.PN XtInstallAccelerators
function installs the accelerators from source onto destination
by augmenting the destination translations with the source accelerators.
If the source display_accelerator method is non-NULL, 
.PN 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.
.sp
.LP
As a convenience for installing all accelerators from a widget and all its
descendants onto one destination, use
.PN XtInstallAllAccelerators .
.IN "XtInstallAllAccelerators" "" "@DEF@"
.FD 0
void XtInstallAllAccelerators(\fIdestination\fP, \fIsource\fP)
.br
      Widget \fIdestination\fP;
.br
      Widget \fIsource\fP;
.FN
.IP \fIdestination\fP 1i
Specifies the widget on which the accelerators are to be installed.
.ds Sr root widget of the widget tree
.IP \fIsource\fP 1i
Specifies the \*(Sr from which the accelerators are to come.
.LP
The
.PN XtInstallAllAccelerators
function recursively descends the widget tree rooted at source 
and installs the accelerators of each widget encountered onto destination.
A common use is to call
.PN XtInstallAllAccelerators
and pass the application main window as the source.
.NH 2
KeyCode-to-KeySym Conversions
.XS
\*(SN KeyCode-to-KeySym Conversions
.XE
.LP
The translation manager provides support for automatically translating key
codes in incoming key events into KeySyms.
KeyCode-to-KeySym-translator procedure pointers are of type
.PN XtKeyProc :
.IN "XtKeyProc" "" "@DEF@"
.FD 0
typedef void (*XtKeyProc)(Display *, KeyCode, Modifiers, Modifiers *, \
KeySym *);
.br
    Display *\fIdisplay\fP;
.br
    KeyCode \fIkeycode\fP;
.br
    Modifiers \fImodifiers\fP;
.br
    Modifiers *\fImodifiers_return\fP;
.br
    KeySym *\fIkeysym_return\fP;
.FN
.IP \fIdisplay\fP 1i
Specifies the display that the KeyCode is from.
.IP \fIkeycode\fP 1i
Specifies the KeyCode to translate.
.IP \fImodifiers\fP 1i
Specifies the modifiers to the KeyCode.
.IP \fImodifiers_return\fP 1i
Returns a mask that indicates the subset of all
modifiers that are examined by the key translator.
.IP \fIkeysym_return\fP 1i
Returns the resulting KeySym.
.LP
This procedure takes a KeyCode and modifiers and produces a KeySym.
For any given key translator function,
modifiers_return will be a constant that indicates the subset of all
modifiers that are examined by the key translator.
.sp
.LP
To register a key translator, use
.PN XtSetKeyTranslator .
.IN "XtSetKeyTranslator" "" "@DEF@"
.FD 0
void XtSetKeyTranslator(\fIdisplay\fP, \fIproc\fP)
.br
    Display *\fIdisplay\fP;
.br
    XtKeyProc \fIproc\fP;
.FN
.ds Di \ from which to translate the events
.IP \fIdisplay\fP 1i
Specifies the display\*(Di.
.ds Pr \ to perform key translations
.IP \fIproc\fP 1i
Specifies the procedure that is\*(Pr.
.LP
The
.PN XtSetKeyTranslator
function sets the specified procedure as the current key translator.
The default translator is 
.PN XtTranslateKey ,
an
.PN XtKeyProc
that uses Shift and Lock modifiers with the interpretations defined
by the core protocol.
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.
.sp
.LP
To invoke the currently registered KeyCode-to-KeySym translator,
use
.PN XtTranslateKeycode .
.IN "XtTranslateKeycode" "" "@DEF@"
.FD 0
void XtTranslateKeycode(\fIdisplay\fP, \fIkeycode\fP, \fImodifiers\fP, \
\fImodifiers_return\fP, \fIkeysym_return\fP)
.br
    Display *\fIdisplay\fP;
.br
    KeyCode \fIkeycode\fP;
.br
    Modifiers \fImodifiers\fP;
.br
    Modifiers *\fImodifiers_return\fP;
.br
    KeySym *\fIkeysym_return\fP;
.FN
.ds Di \ that the KeyCode is from
.IP \fIdisplay\fP 1i
Specifies the display\*(Di.
.IP \fIkeycode\fP 1i
Specifies the KeyCode to translate.
.IP \fImodifiers\fP 1i
Specifies the modifiers to the KeyCode.
.IP \fImodifiers_return\fP 1i
Returns a mask that indicates the modifiers actually used 
to generate the KeySym.
.IP \fIkeysym_return\fP 1i
Returns the resulting KeySym.
.LP
The
.PN XtTranslateKeycode
function passes the specified arguments 
directly to the currently registered KeyCode to KeySym translator.
.sp
.LP
To handle capitalization of nonstandard KeySyms, the \*(xI allow
clients to register case conversion routines.
Case converter procedure pointers are of type
.PN XtCaseProc :
.IN "XtCaseProc" "" "@DEF@"
.FD 0
typedef void (*XtCaseProc)(KeySym *, KeySym *, KeySym *);
.br
    KeySym *\fIkeysym\fP;
.br
    KeySym *\fIlower_return\fP;
.br
    KeySym *\fIupper_return\fP;
.FN
.IP \fIkeysym\fP 1i
Specifies the KeySym to convert.
.IP \fIlower_return\fP 1i
Specifies the lowercase equivalent for the KeySym.
.IP \fIupper_return\fP 1i
Specifies the uppercase equivalent for the KeySym.
.LP
If there is no case distinction, 
this procedure should store the KeySym into both return values.
.sp
.LP
To register a case converter, use
.PN XtRegisterCaseConverter .
.IN "XtRegisterCaseConverter" "" "@DEF@"
.FD 0
void XtRegisterCaseConverter(\fIdisplay\fP, \fIproc\fP, \fIstart\fP, \fIstop\fP)
.br
    Display *\fIdisplay\fP;
.br
    XtCaseProc \fIproc\fP;
.br
    KeySym \fIstart\fP;
.br
    KeySym \fIstop\fP;
.FN
.ds Di \ from which the key events are to come
.IP \fIdisplay\fP 1i
Specifies the display\*(Di.
.IP \fIproc\fP 1i
Specifies the 
.PN XtCaseProc 
that is to do the conversions.
.IP \fIstart\fP 1i
Specifies the first KeySym for which this converter is valid.
.IP \fIstop\fP 1i
Specifies the last KeySym for which this converter is valid.
.LP
The
.PN 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 \*(xI  refreshes the keyboard state if necessary.
The default converter understands case conversion for all
KeySyms defined in the core protocol.
.sp
.LP
To determine upper and lowercase equivalents for a KeySym, use
.PN XtConvertCase .
.IN "XtConvertCase" "" "@DEF@"
.FD 0
void XtConvertCase(\fIdisplay\fP, \fIkeysym\fP, \fIlower_return\fP, \
\fIupper_return\fP)
.br
    Display *\fIdisplay\fP;
.br
    KeySym \fIkeysym\fP;
.br
    KeySym *\fIlower_return\fP;
.br
    KeySym *\fIupper_return\fP;
.FN
.ds Di \ that the KeySym came from
.IP \fIdisplay\fP 1i
Specifies the display\*(Di.
.IP \fIkeysym\fP 1i
Specifies the KeySym to convert.
.IP \fIlower_return\fP 1i
Returns the lowercase equivalent of the KeySym.
.IP \fIupper_return\fP 1i
Returns the uppercase equivalent of the KeySym.
.LP
The
.PN XtConvertCase
function calls the appropriate converter and returns the results.
A user-supplied
.PN XtKeyProc 
may need to use this function.
.bp
