home *** CD-ROM | disk | FTP | other *** search
Text File | 1991-08-27 | 43.9 KB | 1,420 lines |
- .\" $XConsortium: CH10,v 1.8 91/08/26 13:38:16 swick Exp $
- .\"
- .\" Copyright 1985, 1986, 1987, 1988, 1991
- .\" Massachusetts Institute of Technology, Cambridge, Massachusetts,
- .\" and 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
- .\" M.I.T. or Digital not be used in in advertising or publicity pertaining
- .\" to distribution of the software without specific, written prior permission.
- .\" M.I.T and 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 \- 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 .
- .IN "action_proc procedure" "" "@DEF@"
- .IN "XtActionProc" "" "@DEF@"
- .FD 0
- typedef void (*XtActionProc)(Widget, XEvent*, String*, Cardinal*);
- .br
- Widget \fIw\fP;
- .br
- XEvent *\fIevent\fP;
- .br
- String *\fIparams\fP;
- .br
- Cardinal *\fInum_params\fP;
- .FN
- .IP \fIw\fP 1i
- Specifies the widget that caused the action to be called.
- .IP \fIevent\fP 1i
- Specifies the event that caused the action to be called.
- If the action is called after a sequence of events,
- then the last event in the sequence is used.
- .IP \fIparams\fP 1i
- Specifies a pointer to the list of strings that were specified
- in the translation table as arguments to the action, 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
- 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.
-
- 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 .
- .IN "XtAppAddActions" "" "@DEF@"
- .FD 0
- void XtAppAddActions(\fIapp_context\fP, \fIactions\fP, \fInum_actions\fP)
- .br
- XtAppContext \fIapp_context\fP;
- .br
- XtActionList \fIactions\fP;
- .br
- Cardinal \fInum_actions\fP;
- .FN
- .IP \fIapp_context\fP 1i
- Specifies the application context.
- .IP \fIactions\fP 1i
- Specifies the action table to register.
- .IP \fInum_actions\fP 1i
- Specifies the number of entries in this action table.
- .LP
- If more than one action is registered with the same name,
- the most recently registered action is used.
- If duplicate actions exist in an action table,
- the first is used.
- The \*(xI register an action table 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 .
- .IN "XtActionHookProc" "" "@DEF@"
- .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
- 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 .
- .IN "XtAppAddActionHook" "" "@DEF@"
- .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
- .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 s
- 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 .
- .IN "XtRemoveActionHook" "" "@DEF@"
- .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
- .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 .
- .IN "XtSetMultiClickTime" "" "@DEF@"
- .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
- .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 .
- .IN "XtGetMultiClickTime" "" "@DEF@"
- .FD 0
- int XtGetMultiClickTime(\fIdisplay\fP)
- .br
- Display *\fIdisplay\fP;
- .FN
- .IP \fIdisplay\fP 1i
- Specifies the display connection.
- .LP
- .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 .
- .IN "XtParseTranslationTable" "" "@DEF@"
- .FD 0
- XtTranslations XtParseTranslationTable(\fItable\fP)
- .br
- String \fItable\fP;
- .FN
- .IP \fItable\fP 1i
- Specifies the translation table to compile.
- .LP
- The
- .PN XtParseTranslationTable
- function compiles the translation table, 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 .
- .IN "XtAugmentTranslations" "" "@DEF@"
- .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
- 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 .
- .IN "XtOverrideTranslations" "" "@DEF@"
- .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
- 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 sharp sign (#) is given as the first character of the table
- followed by one of the keywords ``replace'', ``augment'', or
- ``override'' to indicate
- whether to replace, augment, or override the existing table.
- The replace or merge
- operation is performed during the
- Core
- instance initialization and
- during the
- Core
- set_values invocation.
- Each merge operation produces a new
- translation resource value; if the original tables were shared by
- other widgets, they are unaffected. If no directive is
- specified, ``#replace'' is assumed.
-
- At instance initialization
- the XtNtranslations resource is first fetched. Then, if it was
- not specified or did not contain ``#replace'', the
- resource database is searched for the resource XtNbaseTranslations.
- If XtNbaseTranslations is found it is merged into the widget class
- translation table. Then the widget \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 .
- .IN "XtUninstallTranslations" "" "@DEF@"
- .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
- 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 .
- .IN "display_accelerator procedure" "" "@DEF@"
- .IN "XtStringProc" "" "@DEF@"
- .FD 0
- typedef void (*XtStringProc)(Widget, String);
- .br
- Widget \fIw\fP;
- .br
- String \fIstring\fP;
- .FN
- .IP \fIw\fP 1i
- Specifies the source widget that supplied the accelerators.
- .IP \fIstring\fP 1i
- Specifies the string representation of the accelerators for this widget.
- .LP
- 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 .
- .IN "XtParseAcceleratorTable" "" "@DEF@"
- .FD 0
- XtAccelerators XtParseAcceleratorTable(\fIsource\fP)
- .br
- String \fIsource\fP;
- .FN
- .IP \fIsource\fP 1i
- Specifies the accelerator table to compile.
- .LP
- 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 .
- .IN "XtInstallAccelerators" "" "@DEF@"
- .FD 0
- void XtInstallAccelerators(\fIdestination\fP, \fIsource\fP)
- .br
- Widget \fIdestination\fP;
- .br
- Widget \fIsource\fP;
- .FN
- .IP \fIdestination\fP 1i
- Specifies the widget on which the accelerators are to be installed. \*(cI
- .IP \fIsource\fP 1i
- Specifies the widget from which the accelerators are to come. \*(cI
- .LP
- The
- .PN XtInstallAccelerators
- function installs the \fIaccelerators\fP resource value from
- \fIsource\fP onto \fIdestination\fP
- by merging the 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 .
- .IN "XtInstallAllAccelerators" "" "@DEF@"
- .FD 0
- void XtInstallAllAccelerators(\fIdestination\fP, \fIsource\fP)
- .br
- Widget \fIdestination\fP;
- .br
- Widget \fIsource\fP;
- .FN
- .IP \fIdestination\fP 1i
- Specifies the widget on which the accelerators are to be installed. \*(cI
- .IP \fIsource\fP 1i
- Specifies the root widget of the widget tree
- from which the accelerators are to come. \*(cI
- .LP
- 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 .
- .IN "XtKeyProc" "" "@DEF@"
- .FD 0
- typedef void (*XtKeyProc)(Display*, KeyCode, Modifiers, Modifiers*, \
- KeySym*);
- .br
- Display *\fIdisplay\fP;
- .br
- KeyCode \fIkeycode\fP;
- .br
- Modifiers \fImodifiers\fP;
- .br
- Modifiers *\fImodifiers_return\fP;
- .br
- KeySym *\fIkeysym_return\fP;
- .FN
- .IP \fIdisplay\fP 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.
- .IP \fIkeysym_return\fP 1.1i
- Specifies a location in which to store the resulting KeySym.
- .LP
- This procedure takes a KeyCode and modifiers and produces a KeySym.
- For any given key translator function,
- \fImodifiers_return\fP will be a constant that indicates the subset of all
- modifiers that are examined by the key translator.
- .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 (
- .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 .
- .IN "XtGetKeysymTable" "" "@DEF@"
- .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
- .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 .
- .IN "XtSetKeyTranslator" "" "@DEF@"
- .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
- 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, 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 .
- .IN "XtTranslateKeycode" "" "@DEF@"
- .FD 0
- void XtTranslateKeycode(\fIdisplay\fP, \fIkeycode\fP, \fImodifiers\fP, \
- \fImodifiers_return\fP, \fIkeysym_return\fP)
- .br
- Display *\fIdisplay\fP;
- .br
- KeyCode \fIkeycode\fP;
- .br
- Modifiers \fImodifiers\fP;
- .br
- Modifiers *\fImodifiers_return\fP;
- .br
- KeySym *\fIkeysym_return\fP;
- .FN
- .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
- The
- .PN XtTranslateKeycode
- function passes the specified arguments
- directly to the currently registered KeyCode-to-KeySym translator.
- .sp
- .LP
- To handle capitalization of nonstandard KeySyms, the \*(xI allow
- clients to register case conversion routines.
- Case converter procedure pointers are of type
- .PN XtCaseProc .
- .IN "XtCaseProc" "" "@DEF@"
- .FD 0
- typedef void (*XtCaseProc)(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 lower-case equivalent for
- the KeySym.
- .IP \fIupper_return\fP 1i
- Specifies a location into which to store the upper-case equivalent for
- the KeySym.
- .LP
- If there is no case distinction,
- this procedure should store the KeySym into both return values.
- .sp
- .LP
- To register a case converter, use
- .PN XtRegisterCaseConverter .
- .IN "XtRegisterCaseConverter" "" "@DEF@"
- .FD 0
- void XtRegisterCaseConverter(\fIdisplay\fP, \fIproc\fP, \fIstart\fP, \fIstop\fP)
- .br
- Display *\fIdisplay\fP;
- .br
- XtCaseProc \fIproc\fP;
- .br
- KeySym \fIstart\fP;
- .br
- KeySym \fIstop\fP;
- .FN
- .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
- 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 upper- and lower-case equivalents for a KeySym, use
- .PN XtConvertCase .
- .IN "XtConvertCase" "" "@DEF@"
- .FD 0
- void XtConvertCase(\fIdisplay\fP, \fIkeysym\fP, \fIlower_return\fP, \
- \fIupper_return\fP)
- .br
- Display *\fIdisplay\fP;
- .br
- KeySym \fIkeysym\fP;
- .br
- KeySym *\fIlower_return\fP;
- .br
- KeySym *\fIupper_return\fP;
- .FN
- .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 lower-case equivalent of the KeySym.
- .IP \fIupper_return\fP 1i
- Returns the upper-case equivalent of the KeySym.
- .LP
- The
- .PN XtConvertCase
- function calls the appropriate converter and returns the results.
- A user-supplied
- .PN XtKeyProc
- may need to use this function.
-
- .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 .
- .IN "XtGetActionKeysym" "" "@DEF@"
- .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
- 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 .
- .IN "XtKeysymToKeycodeList" "" "@DEF@"
- .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
- 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 .
- .IN "XtRegisterGrabAction" "" "@DEF@"
- .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
- .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 .
- .IN "XtCallActionProc" "" "@DEF@"
- .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
- .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 envelope the superclass's action. To retrieve
- the list of action procedures registered in the superclass's
- \fIactions\fP field, use
- .PN XtGetActionList .
- .IN "XtGetActionList" "" "@DEF@"
- .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 1i
- Specifies the widget class whose actions are to be returned.
- .IP \fIactions_return\fP 1i
- Returns the action list.
- .IP \fInum_actions_return\fP 1i
- Returns the number of action procedures declared by the class.
- .LP
- .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
-