xref: /xsrc/external/mit/libXt/dist/specs/CH10.xml

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">

<chapter id='Translation_Management'>
<title>Translation Management</title>
<para>
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.
</para>

<para>
The translation manager provides an interface to specify and manage the
mapping of X event sequences into widget-supplied functionality,
for example, calling procedure <emphasis remap='I'>Abc</emphasis> when the <emphasis remap='I'>y</emphasis> key
is pressed.
</para>

<para>
The translation manager uses two kinds of tables to perform translations:
</para>
<itemizedlist spacing='compact'>
  <listitem>
    <para>
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.
    </para>
  </listitem>
  <listitem>
    <para>
A translation table, which is in the widget class structure,
specifies the mapping of event sequences to procedure name strings.
    </para>
  </listitem>
</itemizedlist>
<para>
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 <xref linkend='Translation_Table_Management' />.
</para>
<sect1 id="Action_Tables">
<title>Action Tables</title>
<para>
All widget class records contain an action table,
an array of
<function>XtActionsRec</function>
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
<xref linkend='XtActionProc' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtActionProc'>
<funcprototype>
<funcdef>typedef void <function>(*XtActionProc)</function></funcdef>
   <paramdef>Widget <parameter>w</parameter></paramdef>
   <paramdef>XEvent *<parameter>event</parameter></paramdef>
   <paramdef>String *<parameter>params</parameter></paramdef>
   <paramdef>Cardinal *<parameter>num_params</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget that caused the action to be called.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>event</emphasis>
    </term>
    <listitem>
      <para>
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.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>params</emphasis>
    </term>
    <listitem>
      <para>
Specifies a pointer to the list of strings that were specified
in the translation table as arguments to the action, or NULL.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>num_params</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of entries in <emphasis remap='I'>params</emphasis>.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<programlisting>
typedef struct _XtActionsRec {
        String          string;
        XtActionProc    proc;
} XtActionsRec, *XtActionList;
</programlisting>
<para>
The <emphasis remap='I'>string</emphasis> field is the name used in translation tables to access
the procedure.
The <emphasis remap='I'>proc</emphasis> field is a pointer to a procedure that implements
the functionality.
</para>

<para>
When the action list is specified as the
<function>CoreClassPart</function>
<emphasis remap='I'>actions</emphasis> field, the string pointed to by <emphasis remap='I'>string</emphasis> must be
permanently allocated prior to or during the execution of the class
initialization procedure and must not be subsequently deallocated.
</para>

<para>
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.
</para>

<para>
For example, a Pushbutton widget has procedures to take the following actions:
</para>
<itemizedlist spacing='compact'>
  <listitem>
    <para>
Set the button to indicate it is activated.
    </para>
  </listitem>
  <listitem>
    <para>
Unset the button back to its normal mode.
    </para>
  </listitem>
  <listitem>
    <para>
Highlight the button borders.
    </para>
  </listitem>
  <listitem>
    <para>
Unhighlight the button borders.
    </para>
  </listitem>
  <listitem>
    <para>
Notify any callbacks that the button has been activated.
    </para>
  </listitem>
</itemizedlist>
<para>
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:
</para>
<programlisting>
XtActionsRec actionTable[] = {
        {"Set",         Set},
        {"Unset",       Unset},
        {"Highlight",   Highlight},
        {"Unhighlight", Unhighlight}
        {"Notify",      Notify},
};
</programlisting>
<para>
The Intrinsics reserve all action names and parameters starting with
the characters &ldquo;Xt&rdquo; 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.
</para>
<sect2 id="Action_Table_Registration">
<title>Action Table Registration</title>
<para>
The <emphasis remap='I'>actions</emphasis> and <emphasis remap='I'>num_actions</emphasis> fields of
<function>CoreClassPart</function>
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.
</para>

<para>
To declare an action table within an application
and register it with the translation manager, use
<xref linkend='XtAppAddActions' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtAppAddActions'>
<funcprototype>
<funcdef>void <function>XtAppAddActions</function></funcdef>
   <paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
   <paramdef>XtActionList <parameter>actions</parameter></paramdef>
   <paramdef>Cardinal <parameter>num_actions</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>app_context</emphasis>
    </term>
    <listitem>
      <para>
Specifies the application context.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>actions</emphasis>
    </term>
    <listitem>
      <para>
Specifies the action table to register.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>num_actions</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of entries in this action table.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
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
<xref linkend='XtMenuPopup' xrefstyle='select: title'/>
and
<xref linkend='XtMenuPopdown' xrefstyle='select: title'/>
as part of
<xref linkend='XtCreateApplicationContext' xrefstyle='select: title'/>.
</para>
</sect2>

<sect2 id="Action_Names_to_Procedure_Translations">
<title>Action Names to Procedure Translations</title>
<para>
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:
</para>
<itemizedlist spacing='compact'>
  <listitem>
    <para>
The widget's class and all superclass action tables, in subclass-to-superclass
order.
    </para>
  </listitem>
  <listitem>
    <para>
The parent's class and all superclass action tables, in subclass-to-superclass
order, then on up the ancestor tree.
    </para>
  </listitem>
  <listitem>
    <para>
The action tables registered with
<xref linkend='XtAppAddActions' xrefstyle='select: title'/>
and
<xref linkend='XtAddActions' xrefstyle='select: title'/>
from the most recently added table to the oldest table.
    </para>
  </listitem>
</itemizedlist>
<para>
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.
</para>
</sect2>

<sect2 id="Action_Hook_Registration">
<title>Action Hook Registration</title>
<para>
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
<xref linkend='XtActionHookProc' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtActionHookProc'>
<funcprototype>
<funcdef>typedef void <function>(*XtActionHookProc)</function></funcdef>
   <paramdef>Widget <parameter>w</parameter></paramdef>
   <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
   <paramdef>String <parameter>action_name</parameter></paramdef>
   <paramdef>XEvent* <parameter>event</parameter></paramdef>
   <paramdef>String* <parameter>params</parameter></paramdef>
   <paramdef>Cardinal* <parameter>num_params</parameter></paramdef>
</funcprototype>
</funcsynopsis>



<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget whose action is about to be dispatched.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>client_data</emphasis>
    </term>
    <listitem>
      <para>
Specifies the application-specific closure that was passed to
<function>XtAppAddActionHook.</function>
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>action_name</emphasis>
    </term>
    <listitem>
      <para>
Specifies the name of the action to be dispatched.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>event</emphasis>
    </term>
    <listitem>
      <para>
Specifies the event argument that will be passed to the action routine.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>params</emphasis>
    </term>
    <listitem>
      <para>
Specifies the action parameters that will be passed to the action routine.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>num_params</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of entries in <emphasis remap='I'>params</emphasis>.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
Action hooks should not modify any of the data pointed to by the
arguments other than the <emphasis remap='I'>client_data</emphasis> argument.
</para>

<para>
To add an action hook, use
<xref linkend='XtAppAddActionHook' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtAppAddActionHook'>
<funcprototype>
<funcdef>XtActionHookId <function>XtAppAddActionHook</function></funcdef>
   <paramdef>XtAppContext <parameter>app</parameter></paramdef>
   <paramdef>XtActionHookProc <parameter>proc</parameter></paramdef>
   <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>app</emphasis>
    </term>
    <listitem>
      <para>
Specifies the application context.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>proc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the action hook procedure.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>client_data</emphasis>
    </term>
    <listitem>
      <para>
Specifies application-specific data to be passed to the action hook.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<xref linkend='XtAppAddActionHook' xrefstyle='select: title'/>
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
<xref linkend='XtCallActionProc' xrefstyle='select: title'/>,
the action hook procedures will be called in reverse
order of registration just prior to invoking the action routine.
</para>

<para>
Action hook procedures are removed automatically and the
<function>XtActionHookId is</function>
destroyed when the application context in which
they were added is destroyed.
</para>

<para>
To remove an action hook procedure without destroying the application
context, use
<xref linkend='XtRemoveActionHook' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtRemoveActionHook'>
<funcprototype>
<funcdef>void <function>XtRemoveActionHook</function></funcdef>
   <paramdef>XtActionHookId <parameter>id</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>id</emphasis>
    </term>
    <listitem>
      <para>
Specifies the action hook id returned by
<xref linkend='XtAppAddActionHook' xrefstyle='select: title'/>.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<xref linkend='XtRemoveActionHook' xrefstyle='select: title'/>
removes the specified action hook procedure from
the list in which it was registered.
</para>
</sect2>
</sect1>

<sect1 id="Translation_Tables">
<title>Translation Tables</title>
<para>
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.
</para>

<para>
As an example, the default behavior of Pushbutton is
</para>
<itemizedlist spacing='compact'>
  <listitem>
    <para>
Highlight on enter window.
    </para>
  </listitem>
  <listitem>
    <para>
Unhighlight on exit window.
    </para>
  </listitem>
  <listitem>
    <para>
Invert on left button down.
    </para>
  </listitem>
  <listitem>
    <para>
Call callbacks and reinvert on left button up.
    </para>
  </listitem>
</itemizedlist>
<para>
The following illustrates Pushbutton's default translation table:
</para>
<programlisting>
static String defaultTranslations =
        "&lt;EnterWindow&gt;:   Highlight()\n\
        &lt;LeaveWindow&gt;:    Unhighlight()\n\
        &lt;Btn1Down&gt;:       Set()\n\
        &lt;Btn1Up&gt;: Notify() Unset()";
</programlisting>
<para>
The <emphasis remap='I'>tm_table</emphasis> field of the
<function>CoreClassPart</function>
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
<function>XtInheritTranslations</function>
into <emphasis remap='I'>tm_table</emphasis>.
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
<xref linkend='Translation_Table_Management' />.
</para>

<para>
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
<xref linkend='XtParseTranslationTable' xrefstyle='select: title'/>.
</para>

<para>
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.
</para>
<sect2 id="Event_Sequences">
<title>Event Sequences</title>
<para>
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.
</para>

<para>
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.
</para>
</sect2>

<sect2 id="Action_Sequences">
<title>Action Sequences</title>
<para>
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.
</para>
</sect2>

<sect2 id="Multi_Click_Time">
<title>Multi-Click Time</title>
<para>
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 &ldquo;multiClickTime&rdquo; and
class &ldquo;MultiClickTime&rdquo; 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
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>.
If no value is specified, the initial value is 200 milliseconds.
</para>

<para>
To set the multi-click time dynamically, use
<xref linkend='XtSetMultiClickTime' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtSetMultiClickTime'>
<funcprototype>
<funcdef>void <function>XtSetMultiClickTime</function></funcdef>
   <paramdef>Display *<parameter>display</parameter></paramdef>
   <paramdef>int <parameter>time</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the display connection.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>time</emphasis>
    </term>
    <listitem>
      <para>
Specifies the multi-click time in milliseconds.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<xref linkend='XtSetMultiClickTime' xrefstyle='select: title'/>
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
<function>ButtonPress</function>
events) must be less than the
multi-click time in order for the translation actions to be taken.
</para>

<para>
To read the multi-click time, use
<xref linkend='XtGetMultiClickTime' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtGetMultiClickTime'>
<funcprototype>
<funcdef>int <function>XtGetMultiClickTime</function></funcdef>
   <paramdef>Display *<parameter>display</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the display connection.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<xref linkend='XtGetMultiClickTime' xrefstyle='select: title'/>
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.
</para>
</sect2>
</sect1>

<sect1 id="Translation_Table_Management">
<title>Translation Table Management</title>
<para>
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.
</para>

<para>
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.
</para>

<para>
Three Intrinsics functions support this merging:
</para>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>XtParseTranslationTable</emphasis>
    </term>
    <listitem>
      <para>Compiles a translation table.</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>XtAugmentTranslations</emphasis>
    </term>
    <listitem>
      <para>Merges a compiled translation table into a widget's
      compiled translation table, ignoring any new translations that
      conflict with existing translations.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>XtOverrideTranslations</emphasis>
    </term>
    <listitem>
      <para>Merges a compiled translation table into a widget's
      compiled translation table, replacing any existing translations that
      conflict with new translations.
      </para>
    </listitem>
  </varlistentry>
</variablelist>

<para>
To compile a translation table, use
<xref linkend='XtParseTranslationTable' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtParseTranslationTable'>
<funcprototype>
<funcdef>XtTranslations <function>XtParseTranslationTable</function></funcdef>
   <paramdef>const char * <parameter>table</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>table</emphasis>
    </term>
    <listitem>
      <para>
Specifies the translation table to compile.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtParseTranslationTable' xrefstyle='select: title'/>
function compiles the translation table, provided in the format given
in Appendix B, into an opaque internal representation
of type
<function>XtTranslations</function>.
Note that if an empty translation table is required for any purpose,
one can be obtained by calling
<xref linkend='XtParseTranslationTable' xrefstyle='select: title'/>
and passing an empty string.
</para>

<para>
To merge additional translations into an existing translation table, use
<xref linkend='XtAugmentTranslations' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtAugmentTranslations'>
<funcprototype>
<funcdef>void <function>XtAugmentTranslations</function></funcdef>
   <paramdef>Widget <parameter>w</parameter></paramdef>
   <paramdef>XtTranslations <parameter>translations</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget into which the new translations are to be merged.  Must be of class Core or any subclass thereof.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>translations</emphasis>
    </term>
    <listitem>
      <para>
Specifies the compiled translation table to merge in.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtAugmentTranslations' xrefstyle='select: title'/>
function merges the new translations into the existing widget
translations, ignoring any
<function>#replace</function>,
<function>#augment</function>,
or
<function>#override</function>
directive that may have been specified
in the translation string.  The translation table specified by
<emphasis remap='I'>translations</emphasis> is not altered by this process.
<xref linkend='XtAugmentTranslations' xrefstyle='select: title'/>
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.
</para>

<para>
To overwrite existing translations with new translations, use
<xref linkend='XtOverrideTranslations' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtOverrideTranslations'>
<funcprototype>
<funcdef>void <function>XtOverrideTranslations</function></funcdef>
   <paramdef>Widget <parameter>w</parameter></paramdef>
   <paramdef>XtTranslations <parameter>translations</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget into which the new translations are to be merged. Must be of class Core or any subclass thereof.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>translations</emphasis>
    </term>
    <listitem>
      <para>
Specifies the compiled translation table to merge in.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtOverrideTranslations' xrefstyle='select: title'/>
function merges the new translations into the existing widget
translations, ignoring any
<function>#replace</function>,
<function>#augment</function>,
or
<function>#override</function>
directive that may have been
specified in the translation string.  The translation table
specified by <emphasis remap='I'>translations</emphasis> is not altered by this process.
<xref linkend='XtOverrideTranslations' xrefstyle='select: title'/>
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.
</para>

<para>
To replace a widget's translations completely, use
<xref linkend='XtSetValues' xrefstyle='select: title'/>
on the XtNtranslations resource and specify a compiled translation table
as the value.
</para>

<para>
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 pound sign (#) is given as the first character of the table
followed by one of the keywords &ldquo;replace&rdquo;, &ldquo;augment&rdquo;, or
&ldquo;override&rdquo; 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, &ldquo;#replace&rdquo; is assumed.
</para>

<para>
At instance initialization
the XtNtranslations resource is first fetched.  Then, if it was
not specified or did not contain &ldquo;#replace&rdquo;, 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 <emphasis remap='I'>translations</emphasis> 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 <emphasis remap='I'>translations</emphasis> field.  If the XtNtranslations
resource specified &ldquo;#replace&rdquo;, no merge is done.
If neither XtNbaseTranslations or XtNtranslations are specified,
the class translation table is copied into the widget instance.
</para>

<para>
To completely remove existing translations, use
<xref linkend='XtUninstallTranslations' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtUninstallTranslations'>
<funcprototype>
<funcdef>void <function>XtUninstallTranslations</function></funcdef>
   <paramdef>Widget <parameter>w</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget from which the translations are to be removed.   Must be of class Core or any subclass thereof.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtUninstallTranslations' xrefstyle='select: title'/>
function causes the entire translation table for the widget to be removed.
</para>
</sect1>

<sect1 id="Using_Accelerators">
<title>Using Accelerators</title>
<para>
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 <emphasis remap='I'>source</emphasis> widget.
The accelerator table can then be installed on one or more <emphasis remap='I'>destination</emphasis> 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.
</para>

<para>
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
<xref linkend='XtStringProc' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtStringProc'>
<funcprototype>
<funcdef>typedef void <function>(*XtStringProc)</function></funcdef>
   <paramdef>Widget <parameter>w</parameter></paramdef>
   <paramdef>String <parameter>string</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the source widget that supplied the accelerators.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>string</emphasis>
    </term>
    <listitem>
      <para>
Specifies the string representation of the accelerators for this widget.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
Accelerators can be specified in resource files,
and the string representation is the same as for a translation table.
However,
the interpretation of the
<function>#augment</function>
and
<function>#override</function>
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
<function>#augment</function>,
which means that the accelerator translations have lower priority
than the destination translations.
The
<function>#replace</function>
directive is ignored for accelerator tables.
</para>

<para>
To parse an accelerator table, use
<xref linkend='XtParseAcceleratorTable' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtParseAcceleratorTable'>
<funcprototype>
<funcdef>XtAccelerators <function>XtParseAcceleratorTable</function></funcdef>
   <paramdef>const char * <parameter>source</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>source</emphasis>
    </term>
    <listitem>
      <para>
Specifies the accelerator table to compile.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtParseAcceleratorTable' xrefstyle='select: title'/>
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.
</para>

<para>
To install accelerators from a widget on another widget, use
<xref linkend='XtInstallAccelerators' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtInstallAccelerators'>
<funcprototype>
<funcdef>void <function>XtInstallAccelerators</function></funcdef>
   <paramdef>Widget <parameter>destination</parameter></paramdef>
   <paramdef>Widget <parameter>source</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>destination</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget on which the accelerators are to be installed.  Must be of class Core or any subclass thereof.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>source</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget from which the accelerators are to come.  Must be of class Core or any subclass thereof.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtInstallAccelerators' xrefstyle='select: title'/>
function installs the <emphasis remap='I'>accelerators</emphasis> resource value from
<emphasis remap='I'>source</emphasis> onto <emphasis remap='I'>destination</emphasis>
by merging the source accelerators into the destination translations.
If the source <emphasis remap='I'>display_accelerator</emphasis> field is non-NULL,
<xref linkend='XtInstallAccelerators' xrefstyle='select: title'/>
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.
</para>

<para>
As a convenience for installing all accelerators from a widget and all its
descendants onto one destination, use
<xref linkend='XtInstallAllAccelerators' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtInstallAllAccelerators'>
<funcprototype>
<funcdef>void <function>XtInstallAllAccelerators</function></funcdef>
   <paramdef>Widget <parameter>destination</parameter></paramdef>
   <paramdef>Widget <parameter>source</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>destination</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget on which the accelerators are to be installed.  Must be of class Core or any subclass thereof.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>source</emphasis>
    </term>
    <listitem>
      <para>
Specifies the root widget of the widget tree
from which the accelerators are to come.  Must be of class Core or any subclass thereof.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtInstallAllAccelerators' xrefstyle='select: title'/>
function recursively descends the widget tree rooted at <emphasis remap='I'>source</emphasis>
and installs the accelerators resource value
of each widget encountered onto <emphasis remap='I'>destination</emphasis>.
A common use is to call
<xref linkend='XtInstallAllAccelerators' xrefstyle='select: title'/>
and pass the application main window as the source.
</para>
</sect1>

<sect1 id="KeyCode_to_KeySym_Conversions">
<title>KeyCode-to-KeySym Conversions</title>
<para>
The translation manager provides support for automatically translating
KeyCodes in incoming key events into KeySyms.
KeyCode-to-KeySym translator procedure pointers are of type
<xref linkend='XtKeyProc' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtKeyProc'>
<funcprototype>
<funcdef>typedef void <function>(*XtKeyProc)</function></funcdef>
   <paramdef>Display *<parameter>display</parameter></paramdef>
   <paramdef>KeyCode <parameter>keycode</parameter></paramdef>
   <paramdef>Modifiers <parameter>modifiers</parameter></paramdef>
   <paramdef>Modifiers *<parameter>modifiers_return</parameter></paramdef>
   <paramdef>KeySym *<parameter>keysym_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the display that the KeyCode is from.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>keycode</emphasis>
    </term>
    <listitem>
      <para>
Specifies the KeyCode to translate.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>modifiers</emphasis>
    </term>
    <listitem>
      <para>
Specifies the modifiers to the KeyCode.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>modifiers_return</emphasis>
    </term>
    <listitem>
      <para>
Specifies a location in which to store
a mask that indicates the subset of all
modifiers that are examined by the key translator for the specified keycode.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>keysym_return</emphasis>
    </term>
    <listitem>
      <para>
Specifies a location in which to store the resulting KeySym.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
This procedure takes a KeyCode and modifiers and produces a KeySym.
For any given key translator function and keyboard encoding,
<emphasis remap='I'>modifiers_return</emphasis> will be a constant per KeyCode that indicates
the subset of all modifiers that are examined by the key translator
for that KeyCode.
</para>

<para>
The KeyCode-to-KeySym translator procedure
must be implemented such that multiple calls with the same
<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>keycode</emphasis>, and <emphasis remap='I'>modifiers</emphasis> return the same
result until either a new case converter, an
<xref linkend='XtCaseProc' xrefstyle='select: title'/>,
is installed or a
<function>MappingNotify</function>
event is received.
</para>

<para>
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.
</para>

<para>
To return a pointer to the KeySym-to-KeyCode mapping table for a
particular display, use
<xref linkend='XtGetKeysymTable' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtGetKeysymTable'>
<funcprototype>
<funcdef>KeySym *<function>XtGetKeysymTable</function></funcdef>
   <paramdef>Display *<parameter>display</parameter></paramdef>
   <paramdef>KeyCode *<parameter>min_keycode_return</parameter></paramdef>
   <paramdef>int *<parameter>keysyms_per_keycode_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the display whose table is required.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>min_keycode_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the minimum KeyCode valid for the display.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>keysyms_per_keycode_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the number of KeySyms stored for each KeyCode.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<xref linkend='XtGetKeysymTable' xrefstyle='select: title'/>
returns a pointer to the Intrinsics' copy of the
server's KeyCode-to-KeySym table.  This table must not be modified.
There are <emphasis remap='I'>keysyms_per_keycode_return</emphasis> KeySyms associated with each
KeyCode, located in the table with indices starting at index
</para>
<programlisting>
    (test_keycode - min_keycode_return) * keysyms_per_keycode_return
</programlisting>
<para>
for KeyCode <emphasis remap='I'>test_keycode</emphasis>.  Any entries that have no KeySyms associated
with them contain the value
<function>NoSymbol</function>.
Clients should not cache the KeySym table but should call
<xref linkend='XtGetKeysymTable' xrefstyle='select: title'/>
each time the value is
needed, as the table may change prior to dispatching each event.
</para>

<para>
For more information on this table, see
<olink targetdoc='libX11' targetptr='Manipulating_the_Keyboard_Encoding'>Section 12.7</olink> in
<olink targetdoc='libX11' targetptr='libX11'>Xlib &mdash; C Language X Interface</olink>.
</para>

<para>
To register a key translator, use
<xref linkend='XtSetKeyTranslator' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtSetKeyTranslator'>
<funcprototype>
<funcdef>void <function>XtSetKeyTranslator</function></funcdef>
   <paramdef>Display *<parameter>display</parameter></paramdef>
   <paramdef>XtKeyProc <parameter>proc</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the display from which to translate the events.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>proc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the procedure to perform key translations.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtSetKeyTranslator' xrefstyle='select: title'/>
function sets the specified procedure as the current key translator.
The default translator is
<function>XtTranslateKey</function>,
an
<xref linkend='XtKeyProc' xrefstyle='select: title'/>
that uses the Shift, Lock, numlock, and group modifiers
with the interpretations defined in <emphasis remap='I'>X Window System Protocol</emphasis>, Section 5.
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.
</para>

<para>
To invoke the currently registered KeyCode-to-KeySym translator,
use
<xref linkend='XtTranslateKeycode' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtTranslateKeycode'>
<funcprototype>
<funcdef>void <function>XtTranslateKeycode</function></funcdef>
   <paramdef>Display *<parameter>display</parameter></paramdef>
   <paramdef>KeyCode <parameter>keycode</parameter></paramdef>
   <paramdef>Modifiers <parameter>modifiers</parameter></paramdef>
   <paramdef>Modifiers *<parameter>modifiers_return</parameter></paramdef>
   <paramdef>KeySym *<parameter>keysym_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the display that the KeyCode is from.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>keycode</emphasis>
    </term>
    <listitem>
      <para>
Specifies the KeyCode to translate.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>modifiers</emphasis>
    </term>
    <listitem>
      <para>
Specifies the modifiers to the KeyCode.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>modifiers_return</emphasis>
    </term>
    <listitem>
      <para>
Returns a mask that indicates the modifiers actually used
to generate the KeySym.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>keysym_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the resulting KeySym.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtTranslateKeycode' xrefstyle='select: title'/>
function passes the specified arguments
directly to the currently registered KeyCode-to-KeySym translator.
</para>

<para>
To handle capitalization of nonstandard KeySyms, the Intrinsics allow
clients to register case conversion routines.
Case converter procedure pointers are of type
<xref linkend='XtCaseProc' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtCaseProc'>
<funcprototype>
<funcdef>typedef void <function>(*XtCaseProc)</function></funcdef>
   <paramdef>Display *<parameter>display</parameter></paramdef>
   <paramdef>KeySym <parameter>keysym</parameter></paramdef>
   <paramdef>KeySym *<parameter>lower_return</parameter></paramdef>
   <paramdef>KeySym *<parameter>upper_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the display connection for which the conversion is required.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>keysym</emphasis>
    </term>
    <listitem>
      <para>
Specifies the KeySym to convert.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>lower_return</emphasis>
    </term>
    <listitem>
      <para>
Specifies a location into which to store the lowercase equivalent for
the KeySym.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>upper_return</emphasis>
    </term>
    <listitem>
      <para>
Specifies a location into which to store the uppercase equivalent for
the KeySym.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

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

<para>
To register a case converter, use
<xref linkend='XtRegisterCaseConverter' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtRegisterCaseConverter'>
<funcprototype>
<funcdef>void <function>XtRegisterCaseConverter</function></funcdef>
   <paramdef>Display *<parameter>display</parameter></paramdef>
   <paramdef>XtCaseProc <parameter>proc</parameter></paramdef>
   <paramdef>KeySym <parameter>start</parameter></paramdef>
   <paramdef>KeySym <parameter>stop</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the display from which the key events are to come.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>proc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the
<xref linkend='XtCaseProc' xrefstyle='select: title'/>
to do the conversions.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>start</emphasis>
    </term>
    <listitem>
      <para>
Specifies the first KeySym for which this converter is valid.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>stop</emphasis>
    </term>
    <listitem>
      <para>
Specifies the last KeySym for which this converter is valid.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtRegisterCaseConverter' xrefstyle='select: title'/>
registers the specified case converter.
The <emphasis remap='I'>start</emphasis> and <emphasis remap='I'>stop</emphasis> 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 <emphasis remap='I'>X Window System Protocol</emphasis>, Appendix A.
</para>

<para>
To determine uppercase and lowercase equivalents for a KeySym, use
<xref linkend='XtConvertCase' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtConvertCase'>
<funcprototype>
<funcdef>void <function>XtConvertCase</function></funcdef>
   <paramdef>Display *<parameter>display</parameter></paramdef>
   <paramdef>KeySym <parameter>keysym</parameter></paramdef>
   <paramdef>KeySym *<parameter>lower_return</parameter></paramdef>
   <paramdef>KeySym *<parameter>upper_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the display that the KeySym came from.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>keysym</emphasis>
    </term>
    <listitem>
      <para>
Specifies the KeySym to convert.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>lower_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the lowercase equivalent of the KeySym.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>upper_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the uppercase equivalent of the KeySym.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtConvertCase' xrefstyle='select: title'/>
function calls the appropriate converter and returns the results.
A user-supplied
<xref linkend='XtKeyProc' xrefstyle='select: title'/>
may need to use this function.
</para>
</sect1>

<sect1 id="Obtaining_a_KeySym_in_an_Action_Procedure">
<title>Obtaining a KeySym in an Action Procedure</title>
<para>
When an action procedure is invoked on a
<function>KeyPress</function>
or
<function>KeyRelease</function>
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.
</para>

<para>
To retrieve the KeySym and modifiers that matched the final event
specification in the translation table entry, use
<xref linkend='XtGetActionKeysym' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtGetActionKeysym'>
<funcprototype>
<funcdef>KeySym <function>XtGetActionKeysym</function></funcdef>
   <paramdef>XEvent *<parameter>event</parameter></paramdef>
   <paramdef>Modifiers *<parameter>modifiers_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>event</emphasis>
    </term>
    <listitem>
      <para>
Specifies the event pointer passed to the action procedure by the Intrinsics.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>modifiers_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the modifiers that caused the match, if non-NULL.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
If
<xref linkend='XtGetActionKeysym' xrefstyle='select: title'/>
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
<function>KeyPress</function>
or
<function>KeyRelease</function>
event, then
<xref linkend='XtGetActionKeysym' xrefstyle='select: title'/>
returns the KeySym that matched the final
event specification in the translation table and, if <emphasis remap='I'>modifiers_return</emphasis>
is non-NULL, the modifier state actually used to generate this KeySym;
otherwise, if the event is a
<function>KeyPress</function>
or
<function>KeyRelease</function>
event, then
<xref linkend='XtGetActionKeysym' xrefstyle='select: title'/>
calls
<xref linkend='XtTranslateKeycode' xrefstyle='select: title'/>
and returns the results;
else it returns
<function>NoSymbol</function>
and does not examine <emphasis remap='I'>modifiers_return</emphasis>.
</para>

<para>
Note that if an action procedure invoked by the Intrinsics
invokes a subsequent action procedure (and so on) via
<xref linkend='XtCallActionProc' xrefstyle='select: title'/>,
the nested action procedure may also call
<xref linkend='XtGetActionKeysym' xrefstyle='select: title'/>
to retrieve the Intrinsics' KeySym and modifiers.
</para>
</sect1>

<sect1 id="KeySym_to_KeyCode_Conversions">
<title>KeySym-to-KeyCode Conversions</title>
<para>
To return the list of KeyCodes that map to a particular KeySym in
the keyboard mapping table maintained by the Intrinsics, use
<xref linkend='XtKeysymToKeycodeList' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtKeysymToKeycodeList'>
<funcprototype>
<funcdef>void <function>XtKeysymToKeycodeList</function></funcdef>
   <paramdef>Display *<parameter>display</parameter></paramdef>
   <paramdef>KeySym <parameter>keysym</parameter></paramdef>
   <paramdef>KeyCode **<parameter>keycodes_return</parameter></paramdef>
   <paramdef>Cardinal *<parameter>keycount_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>display</emphasis>
    </term>
    <listitem>
      <para>
Specifies the display whose table is required.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>keysym</emphasis>
    </term>
    <listitem>
      <para>
Specifies the KeySym for which to search.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>keycodes_return</emphasis>
    </term>
    <listitem>
      <para>
Returns a list of KeyCodes that have <emphasis remap='I'>keysym</emphasis>
associated with them, or NULL if <emphasis remap='I'>keycount_return</emphasis> is 0.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>keycount_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the number of KeyCodes in the keycode list.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtKeysymToKeycodeList' xrefstyle='select: title'/>
procedure returns all the KeyCodes that have <emphasis remap='I'>keysym</emphasis>
in their entry for the keyboard mapping table associated with <emphasis remap='I'>display</emphasis>.
For each entry in the
table, the first four KeySyms (groups 1 and 2) are interpreted as
specified by <emphasis remap='I'>X Window System Protocol</emphasis>, Section 5.  If no KeyCodes map to the
specified KeySym, <emphasis remap='I'>keycount_return</emphasis> is zero and *<emphasis remap='I'>keycodes_return</emphasis> is NULL.
</para>

<para>
The caller should free the storage pointed to by <emphasis remap='I'>keycodes_return</emphasis> using
<xref linkend='XtFree' xrefstyle='select: title'/>
when it is no longer useful.  If the caller needs to examine
the KeyCode-to-KeySym table for a particular KeyCode, it should call
<xref linkend='XtGetKeysymTable' xrefstyle='select: title'/>.
</para>
</sect1>

<sect1 id="Registering_Button_and_Key_Grabs_for_Actions">
<title>Registering Button and Key Grabs for Actions</title>
<para>
To register button and key grabs for a widget's window according to the
event bindings in the widget's translation table, use
<xref linkend='XtRegisterGrabAction' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtRegisterGrabAction'>
<funcprototype>
<funcdef>void <function>XtRegisterGrabAction</function></funcdef>
   <paramdef>XtActionProc <parameter>action_proc</parameter></paramdef>
   <paramdef>Boolean <parameter>owner_events</parameter></paramdef>
   <paramdef>unsigned int <parameter>event_mask</parameter></paramdef>
   <paramdef>int <parameter>pointer_mode</parameter></paramdef>
   <paramdef>int <parameter>keyboard_mode</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>action_proc</emphasis>
    </term>
    <listitem>
      <para>
Specifies the action procedure to search for in translation tables.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>owner_events</emphasis>
    </term>
    <listitem>
      <para></para>

    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>event_mask</emphasis>
    </term>
    <listitem>
      <para></para>

    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>pointer_mode</emphasis>
    </term>
    <listitem>
      <para></para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>keyboard_mode</emphasis>
    </term>
    <listitem>
      <para>
Specify arguments to
<xref linkend='XtGrabButton' xrefstyle='select: title'/>
or
<xref linkend='XtGrabKey' xrefstyle='select: title'/>.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<xref linkend='XtRegisterGrabAction' xrefstyle='select: title'/>
adds the specified <emphasis remap='I'>action_proc</emphasis> 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
<function>ButtonPress</function>
or
<function>KeyPress</function>
events as the only or final event
in a sequence, the Intrinsics will call
<xref linkend='XtGrabButton' xrefstyle='select: title'/>
or
<xref linkend='XtGrabKey' xrefstyle='select: title'/>
for the widget with every button or KeyCode which maps to the
event detail field, passing the specified <emphasis remap='I'>owner_events</emphasis>, <emphasis remap='I'>event_mask</emphasis>,
<emphasis remap='I'>pointer_mode</emphasis>, and <emphasis remap='I'>keyboard_mode</emphasis>.  For
<function>ButtonPress</function>
events, the modifiers
specified in the grab are determined directly from the translation
specification and <emphasis remap='I'>confine_to</emphasis> and <emphasis remap='I'>cursor</emphasis> are specified as
<function>None</function>.
For
<function>KeyPress</function>
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
<xref linkend='XtGrabKey' xrefstyle='select: title'/>
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 <emphasis remap='I'>event_mask</emphasis> 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
<function>ButtonPress</function>
and
<function>KeyPress</function>
events, don't-care modifiers are ignored unless the translation entry
explicitly specifies &ldquo;Any&rdquo; in the <emphasis remap='I'>modifiers</emphasis> field.
</para>

<para>
If the specified <emphasis remap='I'>action_proc</emphasis> 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.
</para>

<para>
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
<xref linkend='XtGrabKey' xrefstyle='select: title'/>
or
<xref linkend='XtGrabButton' xrefstyle='select: title'/>.
</para>
</sect1>

<sect1 id="Invoking_Actions_Directly">
<title>Invoking Actions Directly</title>
<para>
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
<xref linkend='XtCallActionProc' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtCallActionProc'>
<funcprototype>
<funcdef>void <function>XtCallActionProc</function></funcdef>
   <paramdef>Widget <parameter>widget</parameter></paramdef>
   <paramdef>const char * <parameter>action</parameter></paramdef>
   <paramdef>XEvent * <parameter>event</parameter></paramdef>
   <paramdef>String * <parameter>params</parameter></paramdef>
   <paramdef>Cardinal <parameter>num_params</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>widget</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget in which the action is to be invoked.  Must be of class Core or any subclass thereof.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>action</emphasis>
    </term>
    <listitem>
      <para>
Specifies the name of the action routine.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>event</emphasis>
    </term>
    <listitem>
      <para>
Specifies the contents of the <emphasis remap='I'>event</emphasis> passed to the action routine.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>params</emphasis>
    </term>
    <listitem>
      <para>
Specifies the contents of the <emphasis remap='I'>params</emphasis> passed to the action routine.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>num_params</emphasis>
    </term>
    <listitem>
      <para>
Specifies the number of entries in <emphasis remap='I'>params</emphasis>.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<xref linkend='XtCallActionProc' xrefstyle='select: title'/>
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
<xref linkend='XtCallActionProc' xrefstyle='select: title'/>.
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 <emphasis remap='I'>event</emphasis>, <emphasis remap='I'>params</emphasis>, and <emphasis remap='I'>num_params</emphasis> 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,
<xref linkend='XtCallActionProc' xrefstyle='select: title'/>
generates a warning message and returns.
</para>
</sect1>

<sect1 id="Obtaining_a_Widget_s_Action_List">
<title>Obtaining a Widget's Action List</title>
<para>
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 envelop the superclass's action.  To retrieve
the list of action procedures registered in the superclass's
<emphasis remap='I'>actions</emphasis> field, use
<xref linkend='XtGetActionList' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtGetActionList'>
<funcprototype>
<funcdef>void <function>XtGetActionList</function></funcdef>
   <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
   <paramdef>XtActionList *<parameter>actions_return</parameter></paramdef>
   <paramdef>Cardinal *<parameter>num_actions_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>widget_class</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget class whose actions are to be returned.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>actions_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the action list.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>num_actions_return</emphasis>
    </term>
    <listitem>
      <para>
Returns the number of action procedures declared by the class.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
<xref linkend='XtGetActionList' xrefstyle='select: title'/>
returns the action table defined by the specified
widget class.  This table does not include actions defined by the
superclasses.  If <emphasis remap='I'>widget_class</emphasis> is not initialized, or is not
<function>coreWidgetClass</function>
or a subclass thereof, or if the class does not define any actions,
*<emphasis remap='I'>actions_return</emphasis> will be NULL and *<emphasis remap='I'>num_actions_return</emphasis>
will be zero.
If *<emphasis remap='I'>actions_return</emphasis> is non-NULL the client is responsible for freeing
the table using
<xref linkend='XtFree' xrefstyle='select: title'/>
when it is no longer needed.
</para>
</sect1>
</chapter>