1522 lines
46 KiB
Plaintext
1522 lines
46 KiB
Plaintext
.\" $Xorg: CH10,v 1.3 2000/08/17 19:42:46 cpqbld Exp $
|
|
.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
|
|
.\" X Consortium
|
|
.\"
|
|
.\" Permission is hereby granted, free of charge, to any person obtaining
|
|
.\" a copy of this software and associated documentation files (the
|
|
.\" "Software"), to deal in the Software without restriction, including
|
|
.\" without limitation the rights to use, copy, modify, merge, publish,
|
|
.\" distribute, sublicense, and/or sell copies of the Software, and to
|
|
.\" permit persons to whom the Software is furnished to do so, subject to
|
|
.\" the following conditions:
|
|
.\"
|
|
.\" The above copyright notice and this permission notice shall be included
|
|
.\" in all copies or substantial portions of the Software.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
|
|
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
|
|
.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
|
|
.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
|
|
.\" OTHER DEALINGS IN THE SOFTWARE.
|
|
.\"
|
|
.\" Except as contained in this notice, the name of the X Consortium shall
|
|
.\" not be used in advertising or otherwise to promote the sale, use or
|
|
.\" other dealings in this Software without prior written authorization
|
|
.\" from the X Consortium.
|
|
.\"
|
|
.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
|
|
.\" Digital Equipment Corporation, Maynard, Massachusetts.
|
|
.\"
|
|
.\" Permission to use, copy, modify and distribute this documentation for any
|
|
.\" purpose and without fee is hereby granted, provided that the above copyright
|
|
.\" notice appears in all copies and that both that copyright notice and this
|
|
.\" permission notice appear in supporting documentation, and that the name of
|
|
.\" Digital not be used in in advertising or publicity pertaining
|
|
.\" to distribution of the software without specific, written prior permission.
|
|
.\" Digital makes no representations about the suitability of the
|
|
.\" software described herein for any purpose.
|
|
.\" It is provided ``as is'' without express or implied warranty.
|
|
.\"
|
|
\&
|
|
.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 \(em 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 sequences 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 resources
|
|
XtNtranslations and XtNbaseTranslations are used to modify the class
|
|
default translation table; see Section 10.3.
|
|
|
|
.NH 2
|
|
Action Tables
|
|
.XS
|
|
\fB\*(SN Action Tables\fP
|
|
.XE
|
|
.LP
|
|
All widget class records contain an action table,
|
|
an array of
|
|
.PN 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
|
|
.PN XtActionProc .
|
|
.LP
|
|
.IN "action_proc procedure" "" "@DEF@"
|
|
.IN "XtActionProc" "" "@DEF@"
|
|
.sM
|
|
.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, or NULL.
|
|
.IP \fInum_params\fP 1i
|
|
Specifies the number of entries in \fIparams\fP.
|
|
.IN "XtActionsRec"
|
|
.IN "XtActionList"
|
|
.LP
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
typedef struct _XtActionsRec {
|
|
String string;
|
|
XtActionProc proc;
|
|
} XtActionsRec, *XtActionList;
|
|
.De
|
|
.LP
|
|
.eM
|
|
The \fIstring\fP field is the name used in translation tables to access
|
|
the procedure.
|
|
The \fIproc\fP field is a pointer to a procedure that implements
|
|
the functionality.
|
|
.LP
|
|
When the action list is specified as the
|
|
.PN CoreClassPart
|
|
\fIactions\fP field, the string pointed to by \fIstring\fP must be
|
|
permanently allocated prior to or during the execution of the class
|
|
initialization procedure and must not be subsequently deallocated.
|
|
.LP
|
|
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.
|
|
.LP
|
|
For example, a Pushbutton widget has procedures to take the following actions:
|
|
.IP \(bu 5
|
|
Set the 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 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:
|
|
.LP
|
|
.IN "Action Table"
|
|
.Ds
|
|
.TA .5i 1.5i
|
|
.ta .5i 1.5i
|
|
XtActionsRec actionTable[] = {
|
|
{"Set", Set},
|
|
{"Unset", Unset},
|
|
{"Highlight", Highlight},
|
|
{"Unhighlight", Unhighlight}
|
|
{"Notify", Notify},
|
|
};
|
|
.De
|
|
.LP
|
|
The \*(xI 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 \*(xI functions.
|
|
|
|
.NH 3
|
|
Action Table Registration
|
|
.XS
|
|
\fB\*(SN Action Table Registration\fP
|
|
.XE
|
|
.LP
|
|
.IN "actions"
|
|
The \fIactions\fP and \fInum_actions\fP fields of
|
|
.PN CoreClassPart
|
|
specify the actions implemented by a widget class. These are
|
|
automatically registered with the \*(xI 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 \*(xI may overwrite the storage in order to compile the
|
|
list into an internal representation.
|
|
.sp
|
|
.LP
|
|
To declare an action table within an application
|
|
and register it with the translation manager, use
|
|
.PN XtAppAddActions .
|
|
.LP
|
|
.IN "XtAppAddActions" "" "@DEF@"
|
|
.sM
|
|
.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_actions\fP 1i
|
|
Specifies the number of entries in this action table.
|
|
.LP
|
|
.eM
|
|
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 containing
|
|
.PN XtMenuPopup
|
|
and
|
|
.PN XtMenuPopdown
|
|
as part of
|
|
.PN XtCreateApplicationContext .
|
|
|
|
.NH 3
|
|
Action Names to Procedure Translations
|
|
.XS
|
|
\fB\*(SN Action Names to Procedure Translations\fP
|
|
.XE
|
|
.LP
|
|
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:
|
|
.IP \(bu 5
|
|
The widget's class and all superclass action tables, in subclass-to-superclass
|
|
order.
|
|
.IP \(bu 5
|
|
The parent's class and all superclass action tables, in subclass-to-superclass
|
|
order, then on up the ancestor tree.
|
|
.IP \(bu 5
|
|
The action tables registered with
|
|
.PN XtAppAddActions
|
|
and
|
|
.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 a warning message.
|
|
|
|
.NH 3
|
|
Action Hook Registration
|
|
.XS
|
|
\fB\*(SN Action Hook Registration\fP
|
|
.XE
|
|
.LP
|
|
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
|
|
.PN XtActionHookProc .
|
|
.LP
|
|
.IN "XtActionHookProc" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
typedef void (*XtActionHookProc)(Widget, XtPointer, String, XEvent*, \
|
|
String*, Cardinal*);
|
|
.br
|
|
Widget \fIw\fP;
|
|
.br
|
|
XtPointer \fIclient_data\fP;
|
|
.br
|
|
String \fIaction_name\fP;
|
|
.br
|
|
XEvent* \fIevent\fP;
|
|
.br
|
|
String* \fIparams\fP;
|
|
.br
|
|
Cardinal* \fInum_params\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget whose action is about to be dispatched.
|
|
.IP \fIclient_data\fP 1i
|
|
Specifies the application-specific closure that was passed to
|
|
.PN XtAppAddActionHook.
|
|
.IP \fIaction_name\fP 1i
|
|
Specifies the name of the action to be dispatched.
|
|
.IP \fIevent\fP 1i
|
|
Specifies the event argument that will be passed to the action routine.
|
|
.IP \fIparams\fP 1i
|
|
Specifies the action parameters that will be passed to the action routine.
|
|
.IP \fInum_params\fP 1i
|
|
Specifies the number of entries in \fIparams\fP.
|
|
.LP
|
|
.eM
|
|
Action hooks should not modify any of the data pointed to by the
|
|
arguments other than the \fIclient_data\fP argument.
|
|
.sp
|
|
.LP
|
|
To add an action hook, use
|
|
.PN XtAppAddActionHook .
|
|
.LP
|
|
.IN "XtAppAddActionHook" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XtActionHookId XtAppAddActionHook(\fIapp\fP, \fIproc\fP, \fIclient_data\fP)
|
|
.br
|
|
XtAppContext \fIapp\fP;
|
|
.br
|
|
XtActionHookProc \fIproc\fP;
|
|
.br
|
|
XtPointer \fIclient_data\fP;
|
|
.FN
|
|
.IP \fIapp\fP 1i
|
|
Specifies the application context.
|
|
.IP \fIproc\fP 1i
|
|
Specifies the action hook procedure.
|
|
.IP \fIclient_data\fP 1i
|
|
Specifies application-specific data to be passed to the action hook.
|
|
.LP
|
|
.eM
|
|
.PN 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
|
|
.PN XtCallActionProc ,
|
|
the action hook procedures will be called in reverse
|
|
order of registration just prior to invoking the action routine.
|
|
.LP
|
|
Action hook procedures are removed automatically and the
|
|
.PN XtActionHookId is
|
|
destroyed when the application context in which
|
|
they were added is destroyed.
|
|
.sp
|
|
.LP
|
|
To remove an action hook procedure without destroying the application
|
|
context, use
|
|
.PN XtRemoveActionHook .
|
|
.LP
|
|
.IN "XtRemoveActionHook" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtRemoveActionHook(\fIid\fP)
|
|
.br
|
|
XtActionHookId \fIid\fP;
|
|
.FN
|
|
.IP \fIid\fP 1i
|
|
Specifies the action hook id returned by
|
|
.PN XtAppAddActionHook .
|
|
.LP
|
|
.eM
|
|
.PN XtRemoveActionHook
|
|
removes the specified action hook procedure from
|
|
the list in which it was registered.
|
|
|
|
.NH 2
|
|
Translation Tables
|
|
.XS
|
|
\fB\*(SN Translation Tables\fP
|
|
.XE
|
|
.LP
|
|
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.
|
|
.LP
|
|
As an example, the default behavior of Pushbutton 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 Pushbutton's default translation table:
|
|
.LP
|
|
.IN "Translation tables"
|
|
.Ds
|
|
.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 \fItm_table\fP field of the
|
|
.PN 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
|
|
.PN XtInheritTranslations
|
|
into \fItm_table\fP.
|
|
In Core's class part initialization procedure,
|
|
the \*(xI 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.
|
|
.LP
|
|
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
|
|
.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
|
|
\fB\*(SN Event Sequences\fP
|
|
.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:
|
|
The X event type, a prefix consisting of the X modifier bits, and
|
|
an event-specific suffix.
|
|
.LP
|
|
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.
|
|
|
|
.NH 3
|
|
Action Sequences
|
|
.XS
|
|
\fB\*(SN Action Sequences\fP
|
|
.XE
|
|
.LP
|
|
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.
|
|
|
|
.NH 3
|
|
Multi-Click Time
|
|
.XS
|
|
\fB\*(SN Multi-Click Time\fP
|
|
.XE
|
|
.LP
|
|
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
|
|
.IN "multiClickTime" "" "@DEF@"
|
|
.IN "Resources" "multiClickTime"
|
|
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
|
|
.PN XtDisplayInitialize .
|
|
If no value is specified, the initial value is 200 milliseconds.
|
|
.sp
|
|
.LP
|
|
To set the multi-click time dynamically, use
|
|
.PN XtSetMultiClickTime .
|
|
.LP
|
|
.IN "XtSetMultiClickTime" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtSetMultiClickTime(\fIdisplay\fP, \fItime\fP)
|
|
.br
|
|
Display *\fIdisplay\fP;
|
|
.br
|
|
int \fItime\fP;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the display connection.
|
|
.IP \fItime\fP 1i
|
|
Specifies the multi-click time in milliseconds.
|
|
.LP
|
|
.eM
|
|
.PN 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
|
|
.PN ButtonPress
|
|
events) must be less than the
|
|
multi-click time in order for the translation actions to be taken.
|
|
.sp
|
|
.LP
|
|
To read the multi-click time, use
|
|
.PN XtGetMultiClickTime .
|
|
.LP
|
|
.IN "XtGetMultiClickTime" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
int XtGetMultiClickTime(\fIdisplay\fP)
|
|
.br
|
|
Display *\fIdisplay\fP;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the display connection.
|
|
.LP
|
|
.eM
|
|
.PN 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.
|
|
|
|
.NH 2
|
|
Translation Table Management
|
|
.XS
|
|
\fB\*(SN Translation Table Management\fP
|
|
.XE
|
|
.LP
|
|
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.
|
|
.LP
|
|
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.
|
|
.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{
|
|
Merges a compiled translation table into a widget's
|
|
compiled translation table, ignoring any new translations that
|
|
conflict with existing translations.
|
|
T}
|
|
.sp
|
|
T{
|
|
.PN XtOverrideTranslations
|
|
T} T{
|
|
Merges a compiled translation table into a widget's
|
|
compiled translation table, replacing any existing translations that
|
|
conflict with new translations.
|
|
T}
|
|
.TE
|
|
.sp
|
|
.LP
|
|
To compile a translation table, use
|
|
.PN XtParseTranslationTable .
|
|
.LP
|
|
.IN "XtParseTranslationTable" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XtTranslations XtParseTranslationTable(\fItable\fP)
|
|
.br
|
|
String \fItable\fP;
|
|
.FN
|
|
.IP \fItable\fP 1i
|
|
Specifies the translation table to compile.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtParseTranslationTable
|
|
function compiles the translation table, provided in the format given
|
|
in Appendix B, into an 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 additional translations into an existing translation table, use
|
|
.PN XtAugmentTranslations .
|
|
.LP
|
|
.IN "XtAugmentTranslations" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtAugmentTranslations(\fIw\fP, \fItranslations\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.br
|
|
XtTranslations \fItranslations\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget into which the new translations are to be merged. \*(cI
|
|
.IP \fItranslations\fP 1i
|
|
Specifies the compiled translation table to merge in.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtAugmentTranslations
|
|
function merges the new translations into the existing widget
|
|
translations, ignoring any
|
|
.PN #replace ,
|
|
.PN #augment ,
|
|
or
|
|
.PN #override
|
|
directive that may have been specified
|
|
in the translation string. The translation table specified by
|
|
\fItranslations\fP is not altered by this process.
|
|
.PN 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.
|
|
.sp
|
|
.LP
|
|
To overwrite existing translations with new translations, use
|
|
.PN XtOverrideTranslations .
|
|
.LP
|
|
.IN "XtOverrideTranslations" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtOverrideTranslations(\fIw\fP, \fItranslations\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.br
|
|
XtTranslations \fItranslations\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget into which the new translations are to be merged. \*(cI
|
|
.IP \fItranslations\fP 1i
|
|
Specifies the compiled translation table to merge in.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtOverrideTranslations
|
|
function merges the new translations into the existing widget
|
|
translations, ignoring any
|
|
.PN #replace ,
|
|
.PN #augment ,
|
|
or
|
|
.PN #override
|
|
directive that may have been
|
|
specified in the translation string. The translation table
|
|
specified by \fItranslations\fP is not altered by this process.
|
|
.PN 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.
|
|
.LP
|
|
To replace a widget's translations completely, use
|
|
.PN XtSetValues
|
|
on the XtNtranslations resource and specify 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 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 ``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.
|
|
.LP
|
|
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 \fItranslations\fP 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 \fItranslations\fP 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.
|
|
.sp
|
|
.LP
|
|
To completely remove existing translations, use
|
|
.PN XtUninstallTranslations .
|
|
.LP
|
|
.IN "XtUninstallTranslations" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtUninstallTranslations(\fIw\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget from which the translations are to be removed. \*(cI
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtUninstallTranslations
|
|
function causes the entire translation table for the widget to be removed.
|
|
|
|
.NH 2
|
|
Using Accelerators
|
|
.XS
|
|
\fB\*(SN Using Accelerators\fP
|
|
.XE
|
|
.LP
|
|
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 \*(xI provide a facility, called accelerators, that lets you
|
|
accomplish this.
|
|
.IN "Accelerator" "" "@DEF@"
|
|
An accelerator table is a translation table that is bound with its
|
|
actions in the context of a particular widget, the \fIsource\fP widget.
|
|
The accelerator table can then be installed on one or more \fIdestination\fP 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.
|
|
.LP
|
|
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
|
|
.PN XtStringProc .
|
|
.LP
|
|
.IN "display_accelerator procedure" "" "@DEF@"
|
|
.IN "XtStringProc" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
typedef void (*XtStringProc)(Widget, String);
|
|
.br
|
|
Widget \fIw\fP;
|
|
.br
|
|
String \fIstring\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the source widget that supplied the accelerators.
|
|
.IP \fIstring\fP 1i
|
|
Specifies the string representation of the accelerators for this widget.
|
|
.LP
|
|
.eM
|
|
Accelerators can be specified in resource files,
|
|
and the string representation is the same as for a translation table.
|
|
However,
|
|
the interpretation of the
|
|
.PN #augment
|
|
and
|
|
.PN #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
|
|
.PN #augment ,
|
|
which means that the accelerator translations have lower priority
|
|
than the destination translations.
|
|
The
|
|
.PN #replace
|
|
directive is ignored for accelerator tables.
|
|
.sp
|
|
.LP
|
|
To parse an accelerator table, use
|
|
.PN XtParseAcceleratorTable .
|
|
.LP
|
|
.IN "XtParseAcceleratorTable" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XtAccelerators XtParseAcceleratorTable(\fIsource\fP)
|
|
.br
|
|
String \fIsource\fP;
|
|
.FN
|
|
.IP \fIsource\fP 1i
|
|
Specifies the accelerator table to compile.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN 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.
|
|
.sp
|
|
.LP
|
|
To install accelerators from a widget on another widget, use
|
|
.PN XtInstallAccelerators .
|
|
.LP
|
|
.IN "XtInstallAccelerators" "" "@DEF@"
|
|
.sM
|
|
.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. \*(cI
|
|
.IP \fIsource\fP 1i
|
|
Specifies the widget from which the accelerators are to come. \*(cI
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtInstallAccelerators
|
|
function installs the \fIaccelerators\fP resource value from
|
|
\fIsource\fP onto \fIdestination\fP
|
|
by merging the source accelerators into the destination translations.
|
|
If the source \fIdisplay_accelerator\fP field 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 .
|
|
.LP
|
|
.IN "XtInstallAllAccelerators" "" "@DEF@"
|
|
.sM
|
|
.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. \*(cI
|
|
.IP \fIsource\fP 1i
|
|
Specifies the root widget of the widget tree
|
|
from which the accelerators are to come. \*(cI
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtInstallAllAccelerators
|
|
function recursively descends the widget tree rooted at \fIsource\fP
|
|
and installs the accelerators resource value
|
|
of each widget encountered onto \fIdestination\fP.
|
|
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
|
|
KeyCodes in incoming key events into KeySyms.
|
|
KeyCode-to-KeySym translator procedure pointers are of type
|
|
.PN XtKeyProc .
|
|
.LP
|
|
.IN "XtKeyProc" "" "@DEF@"
|
|
.sM
|
|
.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 1.1i
|
|
Specifies the display that the KeyCode is from.
|
|
.IP \fIkeycode\fP 1.1i
|
|
Specifies the KeyCode to translate.
|
|
.IP \fImodifiers\fP 1.1i
|
|
Specifies the modifiers to the KeyCode.
|
|
.IP \fImodifiers_return\fP 1.1i
|
|
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.
|
|
.IP \fIkeysym_return\fP 1.1i
|
|
Specifies a location in which to store the resulting KeySym.
|
|
.LP
|
|
.eM
|
|
This procedure takes a KeyCode and modifiers and produces a KeySym.
|
|
For any given key translator function and keyboard encoding,
|
|
\fImodifiers_return\fP will be a constant per KeyCode that indicates
|
|
the subset of all modifiers that are examined by the key translator
|
|
for that KeyCode.
|
|
.LP
|
|
The KeyCode-to-KeySym translator procedure
|
|
must be implemented such that multiple calls with the same
|
|
\fIdisplay\fP, \fIkeycode\fP, and \fImodifiers\fP return the same
|
|
result until either a new case converter, an
|
|
.PN XtCaseProc ,
|
|
is installed or a
|
|
.PN MappingNotify
|
|
event is received.
|
|
|
|
.sp
|
|
.LP
|
|
The \*(xI 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.
|
|
.LP
|
|
To return a pointer to the KeySym-to-KeyCode mapping table for a
|
|
particular display, use
|
|
.PN XtGetKeysymTable .
|
|
.LP
|
|
.IN "XtGetKeysymTable" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
KeySym *XtGetKeysymTable(\fIdisplay\fP, \fImin_keycode_return\fP, \
|
|
\fIkeysyms_per_keycode_return\fP)
|
|
.br
|
|
Display *\fIdisplay\fP;
|
|
.br
|
|
KeyCode *\fImin_keycode_return\fP;
|
|
.br
|
|
int *\fIkeysyms_per_keycode_return\fP;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the display whose table is required.
|
|
.IP \fImin_keycode_return\fP 1i
|
|
Returns the minimum KeyCode valid for the display.
|
|
.IP \fIkeysyms_per_keycode_return\fP 1i
|
|
Returns the number of KeySyms stored for each KeyCode.
|
|
.LP
|
|
.eM
|
|
.PN XtGetKeysymTable
|
|
returns a pointer to the \*(xI' copy of the
|
|
server's KeyCode-to-KeySym table. This table must not be modified.
|
|
There are \fIkeysyms_per_keycode_return\fP KeySyms associated with each
|
|
KeyCode, located in the table with indices starting at index
|
|
.IP
|
|
(test_keycode - min_keycode_return) * keysyms_per_keycode_return
|
|
.LP
|
|
for KeyCode \fItest_keycode\fP. Any entries that have no KeySyms associated
|
|
with them contain the value
|
|
.PN NoSymbol .
|
|
Clients should not cache the KeySym table but should call
|
|
.PN XtGetKeysymTable
|
|
each time the value is
|
|
needed, as the table may change prior to dispatching each event.
|
|
.LP
|
|
For more information on this table, see Section 12.7 in \fI\*(xL\fP.
|
|
.sp
|
|
.LP
|
|
To register a key translator, use
|
|
.PN XtSetKeyTranslator .
|
|
.LP
|
|
.IN "XtSetKeyTranslator" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtSetKeyTranslator(\fIdisplay\fP, \fIproc\fP)
|
|
.br
|
|
Display *\fIdisplay\fP;
|
|
.br
|
|
XtKeyProc \fIproc\fP;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the display from which to translate the events.
|
|
.IP \fIproc\fP 1i
|
|
Specifies the procedure to perform key translations.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtSetKeyTranslator
|
|
function sets the specified procedure as the current key translator.
|
|
The default translator is
|
|
.PN XtTranslateKey ,
|
|
an
|
|
.PN XtKeyProc
|
|
that uses the Shift, Lock, numlock, and group modifiers
|
|
with the interpretations defined in \fI\*(xP\fP, 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.
|
|
.sp
|
|
.LP
|
|
To invoke the currently registered KeyCode-to-KeySym translator,
|
|
use
|
|
.PN XtTranslateKeycode .
|
|
.LP
|
|
.IN "XtTranslateKeycode" "" "@DEF@"
|
|
.sM
|
|
.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
|
|
.IP \fIdisplay\fP 1.1i
|
|
Specifies the display that the KeyCode is from.
|
|
.IP \fIkeycode\fP 1.1i
|
|
Specifies the KeyCode to translate.
|
|
.IP \fImodifiers\fP 1.1i
|
|
Specifies the modifiers to the KeyCode.
|
|
.IP \fImodifiers_return\fP 1.1i
|
|
Returns a mask that indicates the modifiers actually used
|
|
to generate the KeySym.
|
|
.IP \fIkeysym_return\fP 1.1i
|
|
Returns the resulting KeySym.
|
|
.LP
|
|
.eM
|
|
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 .
|
|
.LP
|
|
.IN "XtCaseProc" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
typedef void (*XtCaseProc)(Display*, KeySym, KeySym*, KeySym*);
|
|
.br
|
|
Display *\fIdisplay\fP;
|
|
.br
|
|
KeySym \fIkeysym\fP;
|
|
.br
|
|
KeySym *\fIlower_return\fP;
|
|
.br
|
|
KeySym *\fIupper_return\fP;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the display connection for which the conversion is required.
|
|
.IP \fIkeysym\fP 1i
|
|
Specifies the KeySym to convert.
|
|
.IP \fIlower_return\fP 1i
|
|
Specifies a location into which to store the lowercase equivalent for
|
|
the KeySym.
|
|
.IP \fIupper_return\fP 1i
|
|
Specifies a location into which to store the uppercase equivalent for
|
|
the KeySym.
|
|
.LP
|
|
.eM
|
|
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 .
|
|
.LP
|
|
.IN "XtRegisterCaseConverter" "" "@DEF@"
|
|
.sM
|
|
.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
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the display from which the key events are to come.
|
|
.IP \fIproc\fP 1i
|
|
Specifies the
|
|
.PN XtCaseProc
|
|
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
|
|
.eM
|
|
The
|
|
.PN XtRegisterCaseConverter
|
|
registers the specified case converter.
|
|
The \fIstart\fP and \fIstop\fP 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 refresh the keyboard state if necessary.
|
|
The default converter understands case conversion for all
|
|
Latin KeySyms defined in \fI\*(xP\fP, Appendix A.
|
|
.sp
|
|
.LP
|
|
To determine uppercase and lowercase equivalents for a KeySym, use
|
|
.PN XtConvertCase .
|
|
.LP
|
|
.IN "XtConvertCase" "" "@DEF@"
|
|
.sM
|
|
.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
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the display that the KeySym came from.
|
|
.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
|
|
.eM
|
|
The
|
|
.PN XtConvertCase
|
|
function calls the appropriate converter and returns the results.
|
|
A user-supplied
|
|
.PN XtKeyProc
|
|
may need to use this function.
|
|
|
|
.NH 2
|
|
Obtaining a KeySym in an Action Procedure
|
|
.XS
|
|
\fB\*(SN Obtaining a KeySym in an Action Procedure\fP
|
|
.XE
|
|
.LP
|
|
When an action procedure is invoked on a
|
|
.PN KeyPress
|
|
or
|
|
.PN 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
|
|
\*(xI 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.
|
|
.LP
|
|
To retrieve the KeySym and modifiers that matched the final event
|
|
specification in the translation table entry, use
|
|
.PN XtGetActionKeysym .
|
|
.LP
|
|
.IN "XtGetActionKeysym" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
KeySym XtGetActionKeysym(\fIevent\fP, \fImodifiers_return\fP)
|
|
.br
|
|
XEvent *\fIevent\fP;
|
|
.br
|
|
Modifiers *\fImodifiers_return\fP;
|
|
.FN
|
|
.IP \fIevent\fP 1.25i
|
|
Specifies the event pointer passed to the action procedure by the \*(xI.
|
|
.IP \fImodifiers_return\fP 1.25i
|
|
Returns the modifiers that caused the match, if non-NULL.
|
|
.LP
|
|
.eM
|
|
If
|
|
.PN XtGetActionKeysym
|
|
is called after an action procedure has been
|
|
invoked by the \*(xI 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
|
|
.PN KeyPress
|
|
or
|
|
.PN KeyRelease
|
|
event, then
|
|
.PN XtGetActionKeysym
|
|
returns the KeySym that matched the final
|
|
event specification in the translation table and, if \fImodifiers_return\fP
|
|
is non-NULL, the modifier state actually used to generate this KeySym;
|
|
otherwise, if the event is a
|
|
.PN KeyPress
|
|
or
|
|
.PN KeyRelease
|
|
event, then
|
|
.PN XtGetActionKeysym
|
|
calls
|
|
.PN XtTranslateKeycode
|
|
and returns the results;
|
|
else it returns
|
|
.PN NoSymbol
|
|
and does not examine \fImodifiers_return\fP.
|
|
.LP
|
|
Note that if an action procedure invoked by the \*(xI
|
|
invokes a subsequent action procedure (and so on) via
|
|
.PN XtCallActionProc ,
|
|
the nested action procedure may also call
|
|
.PN XtGetActionKeysym
|
|
to retrieve the \*(xI' KeySym and modifiers.
|
|
|
|
.NH 2
|
|
KeySym-to-KeyCode Conversions
|
|
.XS
|
|
\*(SN KeySym-to-KeyCode Conversions
|
|
.XE
|
|
.LP
|
|
To return the list of KeyCodes that map to a particular KeySym in
|
|
the keyboard mapping table maintained by the \*(xI, use
|
|
.PN XtKeysymToKeycodeList .
|
|
.LP
|
|
.IN "XtKeysymToKeycodeList" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtKeysymToKeycodeList(\fIdisplay\fP, \fIkeysym\fP, \fIkeycodes_return\fP, \
|
|
\fIkeycount_return\fP)
|
|
.br
|
|
Display *\fIdisplay\fP;
|
|
.br
|
|
KeySym \fIkeysym\fP;
|
|
.br
|
|
KeyCode **\fIkeycodes_return\fP;
|
|
.br
|
|
Cardinal *\fIkeycount_return\fP;
|
|
.FN
|
|
.IP \fIdisplay\fP 1.25i
|
|
Specifies the display whose table is required.
|
|
.IP \fIkeysym\fP 1.25i
|
|
Specifies the KeySym for which to search.
|
|
.IP \fIkeycodes_return\fP 1.25i
|
|
Returns a list of KeyCodes that have \fIkeysym\fP
|
|
associated with them, or NULL if \fIkeycount_return\fP is 0.
|
|
.IP \fIkeycount_return\fP 1.25i
|
|
Returns the number of KeyCodes in the keycode list.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtKeysymToKeycodeList
|
|
procedure returns all the KeyCodes that have \fIkeysym\fP
|
|
in their entry for the keyboard mapping table associated with \fIdisplay\fP.
|
|
For each entry in the
|
|
table, the first four KeySyms (groups 1 and 2) are interpreted as
|
|
specified by \fI\*(xP\fP, Section 5. If no KeyCodes map to the
|
|
specified KeySym, \fIkeycount_return\fP is zero and *\fIkeycodes_return\fP is NULL.
|
|
.LP
|
|
The caller should free the storage pointed to by \fIkeycodes_return\fP using
|
|
.PN 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
|
|
.PN XtGetKeysymTable .
|
|
|
|
.NH 2
|
|
Registering Button and Key Grabs for Actions
|
|
.XS
|
|
\fB\*(SN Registering Button and Key Grabs for Actions\fP
|
|
.XE
|
|
.LP
|
|
To register button and key grabs for a widget's window according to the
|
|
event bindings in the widget's translation table, use
|
|
.PN XtRegisterGrabAction .
|
|
.LP
|
|
.IN "XtRegisterGrabAction" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtRegisterGrabAction(\fIaction_proc\fP, \fIowner_events\fP, \
|
|
\fIevent_mask\fP, \fIpointer_mode\fP, \fIkeyboard_mode\fP)
|
|
.br
|
|
XtActionProc \fIaction_proc\fP;
|
|
.br
|
|
Boolean \fIowner_events\fP;
|
|
.br
|
|
unsigned int \fIevent_mask\fP;
|
|
.br
|
|
int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
|
|
.FN
|
|
.IP \fIaction_proc\fP 1i
|
|
Specifies the action procedure to search for in translation tables.
|
|
.sp
|
|
.IP \fIowner_events\fP
|
|
.br
|
|
.ns
|
|
.IP \fIevent_mask\fP
|
|
.br
|
|
.ns
|
|
.IP \fIpointer_mode\fP
|
|
.br
|
|
.ns
|
|
.IP \fIkeyboard_mode\fP 1i
|
|
Specify arguments to
|
|
.PN XtGrabButton
|
|
or
|
|
.PN XtGrabKey .
|
|
.LP
|
|
.eM
|
|
.PN XtRegisterGrabAction
|
|
adds the specified \fIaction_proc\fP 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
|
|
.PN ButtonPress
|
|
or
|
|
.PN KeyPress
|
|
events as the only or final event
|
|
in a sequence, the \*(xI will call
|
|
.PN XtGrabButton
|
|
or
|
|
.PN XtGrabKey
|
|
for the widget with every button or KeyCode which maps to the
|
|
event detail field, passing the specified \fIowner_events\fP, \fIevent_mask\fP,
|
|
\fIpointer_mode\fP, and \fIkeyboard_mode\fP. For
|
|
.PN ButtonPress
|
|
events, the modifiers
|
|
specified in the grab are determined directly from the translation
|
|
specification and \fIconfine_to\fP and \fIcursor\fP are specified as
|
|
.PN None .
|
|
For
|
|
.PN 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
|
|
.PN 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 \fIevent_mask\fP 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
|
|
.PN ButtonPress
|
|
and
|
|
.PN KeyPress
|
|
events, don't-care modifiers are ignored unless the translation entry
|
|
explicitly specifies ``Any'' in the \fImodifiers\fP field.
|
|
.LP
|
|
If the specified \fIaction_proc\fP 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.
|
|
.LP
|
|
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
|
|
.PN XtGrabKey
|
|
or
|
|
.PN XtGrabButton .
|
|
|
|
.NH 2
|
|
Invoking Actions Directly
|
|
.XS
|
|
\fB\*(SN Invoking Actions Directly\fP
|
|
.XE
|
|
.LP
|
|
Normally action procedures are invoked by the \*(xI when an
|
|
event or event sequence arrives for a widget. To
|
|
invoke an action procedure directly, without generating
|
|
(or synthesizing) events, use
|
|
.PN XtCallActionProc .
|
|
.LP
|
|
.IN "XtCallActionProc" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtCallActionProc(\fIwidget\fP, \fIaction\fP, \fIevent\fP, \fIparams\fP, \
|
|
\fInum_params\fP)
|
|
.br
|
|
Widget \fIwidget\fP;
|
|
.br
|
|
String \fIaction\fP;
|
|
.br
|
|
XEvent *\fIevent\fP;
|
|
.br
|
|
String *\fIparams\fP;
|
|
.br
|
|
Cardinal \fInum_params\fP;
|
|
.FN
|
|
.IP \fIwidget\fP 1i
|
|
Specifies the widget in which the action is to be invoked. \*(cI
|
|
.IP \fIaction\fP 1i
|
|
Specifies the name of the action routine.
|
|
.IP \fIevent\fP 1i
|
|
Specifies the contents of the \fIevent\fP passed to the action routine.
|
|
.IP \fIparams\fP 1i
|
|
Specifies the contents of the \fIparams\fP passed to the action routine.
|
|
.IP \fInum_params\fP 1i
|
|
Specifies the number of entries in \fIparams\fP.
|
|
.LP
|
|
.eM
|
|
.PN 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
|
|
.PN 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 \fIevent\fP, \fIparams\fP, and \fInum_params\fP 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,
|
|
.PN XtCallActionProc
|
|
generates a warning message and returns.
|
|
|
|
.NH 2
|
|
Obtaining a Widget's Action List
|
|
.XS
|
|
\*(SN Obtaining a Widget's Action List
|
|
.XE
|
|
.LP
|
|
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
|
|
\fIactions\fP field, use
|
|
.PN XtGetActionList .
|
|
.LP
|
|
.IN "XtGetActionList" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtGetActionList(\fIwidget_class\fP, \fIactions_return\fP, \
|
|
\fInum_actions_return\fP)
|
|
.br
|
|
WidgetClass \fIwidget_class\fP;
|
|
.br
|
|
XtActionList *\fIactions_return\fP;
|
|
.br
|
|
Cardinal *\fInum_actions_return\fP;
|
|
.FN
|
|
.IP \fIwidget_class\fP 1.5i
|
|
Specifies the widget class whose actions are to be returned.
|
|
.IP \fIactions_return\fP 1.5i
|
|
Returns the action list.
|
|
.IP \fInum_actions_return\fP 1.5i
|
|
Returns the number of action procedures declared by the class.
|
|
.LP
|
|
.eM
|
|
.PN XtGetActionList
|
|
returns the action table defined by the specified
|
|
widget class. This table does not include actions defined by the
|
|
superclasses. If \fIwidget_class\fP is not initialized, or is not
|
|
.PN coreWidgetClass
|
|
or a subclass thereof, or if the class does not define any actions,
|
|
*\fIactions_return\fP will be NULL and *\fInum_actions_return\fP
|
|
will be zero.
|
|
If *\fIactions_return\fP is non-NULL the client is responsible for freeing
|
|
the table using
|
|
.PN XtFree
|
|
when it is no longer needed.
|
|
.bp
|