diff options
Diffstat (limited to 'libXt/specs/CH10')
| -rw-r--r-- | libXt/specs/CH10 | 1521 |
1 files changed, 1521 insertions, 0 deletions
diff --git a/libXt/specs/CH10 b/libXt/specs/CH10 new file mode 100644 index 000000000..b7c0139ca --- /dev/null +++ b/libXt/specs/CH10 @@ -0,0 +1,1521 @@ +.\" $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 |