diff options
author | Matt Dew <marcoz@osource.org> | 2011-10-22 00:12:48 -0600 |
---|---|---|
committer | Matt Dew <marcoz@osource.org> | 2011-10-22 00:12:48 -0600 |
commit | 6a0f9423ccbe13a56e579638ef18f6027a78f327 (patch) | |
tree | 54d5804df3afd04e07aea381377a998a213c8b58 | |
parent | 90e4f5055bd72624597717ee58cd3e5396ab1042 (diff) |
Updated CH10.xml
-rw-r--r-- | specs/CH10.xml | 1305 |
1 files changed, 454 insertions, 851 deletions
diff --git a/specs/CH10.xml b/specs/CH10.xml index a858b10..0e1c71c 100644 --- a/specs/CH10.xml +++ b/specs/CH10.xml @@ -1,76 +1,21 @@ -<!-- .\" $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<function>Chapter 10</function>\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 --> -<para> -<!-- .LP --> -<!-- .XS --> -<!-- Chapter 10 \(em Translation Management --> -<!-- .XE --> +<chapter id='Translation_Management'> +<title>Translation Management</title> +<para> Except under unusual circumstances, widgets do not hardwire the mapping of user events into widget behavior by using the event manager. Instead, they provide a default mapping of events into behavior that you can override. </para> + <para> -<!-- .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 <emphasis remap='I'>Abc</emphasis> when the <emphasis remap='I'>y</emphasis> key is pressed. </para> + <para> -<!-- .LP --> The translation manager uses two kinds of tables to perform translations: </para> <itemizedlist> @@ -89,21 +34,15 @@ specifies the mapping of event sequences to procedure name strings. </listitem> </itemizedlist> <para> -<!-- .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. - </para> -<sect2 id="Action_Tables"> +<sect1 id="Action_Tables"> <title>Action Tables</title> -<!-- .XS --> -<!-- <function>(SN Action Tables</function> --> -<!-- .XE --> <para> -<!-- .LP --> All widget class records contain an action table, an array of <function>XtActionsRec</function> @@ -113,25 +52,19 @@ 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 -<function>XtActionProc .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "action_proc procedure" "" "@DEF@" --> -<!-- .IN "XtActionProc" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -typedef void (*XtActionProc)(Widget, XEvent*, String*, Cardinal*); -<!-- .br --> - Widget <emphasis remap='I'>w</emphasis>; -<!-- .br --> - XEvent *<emphasis remap='I'>event</emphasis>; -<!-- .br --> - String *<emphasis remap='I'>params</emphasis>; -<!-- .br --> - Cardinal *<emphasis remap='I'>num_params</emphasis>; -<!-- .FN --> +<function>XtActionProc</function>. +</para> + +<funcsynopsis id='XtActionProc'> +<funcprototype> +<funcdef>void <function>*XtActionProc</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>XEvent *<parameter>event</parameter></paramdef> + <paramdef>String *<parameter>params</parameter></paramdef> + <paramdef>Cardinal *<parameter>num_params</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -173,41 +106,32 @@ in the translation table as arguments to the action, or NULL. <listitem> <para> Specifies the number of entries in <emphasis remap='I'>params</emphasis>. -<!-- .IN "XtActionsRec" --> -<!-- .IN "XtActionList" --> </para> </listitem> </varlistentry> </variablelist> -<para> -<!-- .LP --> <literallayout class="monospaced"> -<!-- .TA .5i 3i --> -<!-- .ta .5i 3i --> typedef struct _XtActionsRec { String string; XtActionProc proc; } XtActionsRec, *XtActionList; </literallayout> -</para> <para> -<!-- .LP --> -<!-- .eM --> The <emphasis remap='I'>string</emphasis> field is the name used in translation tables to access the procedure. The <emphasis remap='I'>proc</emphasis> field is a pointer to a procedure that implements the functionality. </para> + <para> -<!-- .LP --> When the action list is specified as the <function>CoreClassPart</function> <emphasis remap='I'>actions</emphasis> field, the string pointed to by <emphasis remap='I'>string</emphasis> must be permanently allocated prior to or during the execution of the class initialization procedure and must not be subsequently deallocated. </para> + <para> -<!-- .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 @@ -215,8 +139,8 @@ have a window. Widget writers should also note which of a widget's callback lists are invoked from action procedures and warn clients not to assume the widget is realized in those callbacks. </para> + <para> -<!-- .LP --> For example, a Pushbutton widget has procedures to take the following actions: </para> <itemizedlist> @@ -247,19 +171,13 @@ Notify any callbacks that the button has been activated. </listitem> </itemizedlist> <para> -<!-- .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: </para> -<para> -<!-- .LP --> -<!-- .IN "Action Table" --> <literallayout class="monospaced"> -<!-- .TA .5i 1.5i --> -<!-- .ta .5i 1.5i --> XtActionsRec actionTable[] = { {"Set", Set}, {"Unset", Unset}, @@ -268,54 +186,41 @@ XtActionsRec actionTable[] = { {"Notify", Notify}, }; </literallayout> -</para> <para> -<!-- .LP --> -The (xI reserve all action names and parameters starting with +The Intrinsics 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. - +built-in Intrinsics functions. </para> -<sect3 id="Action_Table_Registration"> +<sect2 id="Action_Table_Registration"> <title>Action Table Registration</title> -<!-- .XS --> -<!-- <function>(SN Action Table Registration</function> --> -<!-- .XE --> <para> -<!-- .LP --> -<!-- .IN "actions" --> The <emphasis remap='I'>actions</emphasis> and <emphasis remap='I'>num_actions</emphasis> fields of <function>CoreClassPart</function> specify the actions implemented by a widget class. These are -automatically registered with the (xI when the class is initialized +automatically registered with the Intrinsics when the class is initialized and must be allocated in writable storage prior to Core class_part initialization, and never deallocated. To save memory and optimize -access, the (xI may overwrite the storage in order to compile the +access, the Intrinsics may overwrite the storage in order to compile the list into an internal representation. -<!-- .sp --> </para> + <para> -<!-- .LP --> To declare an action table within an application and register it with the translation manager, use -<function>XtAppAddActions .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtAppAddActions" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -void XtAppAddActions(<emphasis remap='I'>app_context</emphasis>, <emphasis remap='I'>actions</emphasis>, <emphasis remap='I'>num_actions</emphasis>) -<!-- .br --> - XtAppContext <emphasis remap='I'>app_context</emphasis>; -<!-- .br --> - XtActionList <emphasis remap='I'>actions</emphasis>; -<!-- .br --> - Cardinal <emphasis remap='I'>num_actions</emphasis>; -<!-- .FN --> +<function>XtAppAddActions</function>. +</para> + +<funcsynopsis id='XtAppAddActions'> +<funcprototype> +<funcdef>void <function>XtAppAddActions</function></funcdef> + <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> + <paramdef>XtActionList <parameter>actions</parameter></paramdef> + <paramdef>Cardinal <parameter>num_actions</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -349,28 +254,22 @@ Specifies the number of entries in this action table. </varlistentry> </variablelist> <para> -<!-- .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 +The Intrinsics register an action table containing <function>XtMenuPopup</function> and <function>XtMenuPopdown</function> as part of -<function>XtCreateApplicationContext .</function> - +<function>XtCreateApplicationContext</function>. </para> -</sect3> -<sect3 id="Action_Names_to_Procedure_Translations"> +</sect2> + +<sect2 id="Action_Names_to_Procedure_Translations"> <title>Action Names to Procedure Translations</title> -<!-- .XS --> -<!-- <function>(SN Action Names to Procedure Translations</function> --> -<!-- .XE --> <para> -<!-- .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 @@ -403,47 +302,36 @@ from the most recently added table to the oldest table. </listitem> </itemizedlist> <para> -<!-- .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. - </para> -</sect3> -<sect3 id="Action_Hook_Registration"> +</sect2> + +<sect2 id="Action_Hook_Registration"> <title>Action Hook Registration</title> -<!-- .XS --> -<!-- <function>(SN Action Hook Registration</function> --> -<!-- .XE --> <para> -<!-- .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 -<function>XtActionHookProc .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtActionHookProc" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -typedef void (*XtActionHookProc)(Widget, XtPointer, String, XEvent*, \ -String*, Cardinal*); -<!-- .br --> - Widget <emphasis remap='I'>w</emphasis>; -<!-- .br --> - XtPointer <emphasis remap='I'>client_data</emphasis>; -<!-- .br --> - String <emphasis remap='I'>action_name</emphasis>; -<!-- .br --> - XEvent* <emphasis remap='I'>event</emphasis>; -<!-- .br --> - String* <emphasis remap='I'>params</emphasis>; -<!-- .br --> - Cardinal* <emphasis remap='I'>num_params</emphasis>; -<!-- .FN --> +<function>XtActionHookProc</function>. +</para> + +<funcsynopsis id='XtActionHookProc'> +<funcprototype> +<funcdef>void <function>*XtActionHookProc</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>XtPointer <parameter>client_data</parameter></paramdef> + <paramdef>String <parameter>action_name</parameter></paramdef> + <paramdef>XEvent* <parameter>event</parameter></paramdef> + <paramdef>String* <parameter>params</parameter></paramdef> + <paramdef>Cardinal* <parameter>num_params</parameter></paramdef> +</funcprototype> +</funcsynopsis> + + + <variablelist> <varlistentry> <term> @@ -508,31 +396,24 @@ Specifies the number of entries in <emphasis remap='I'>params</emphasis>. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> Action hooks should not modify any of the data pointed to by the arguments other than the <emphasis remap='I'>client_data</emphasis> argument. -<!-- .sp --> </para> + <para> -<!-- .LP --> To add an action hook, use -<function>XtAppAddActionHook .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtAppAddActionHook" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -XtActionHookId XtAppAddActionHook(<emphasis remap='I'>app</emphasis>, <emphasis remap='I'>proc</emphasis>, <emphasis remap='I'>client_data</emphasis>) -<!-- .br --> - XtAppContext <emphasis remap='I'>app</emphasis>; -<!-- .br --> - XtActionHookProc <emphasis remap='I'>proc</emphasis>; -<!-- .br --> - XtPointer <emphasis remap='I'>client_data</emphasis>; -<!-- .FN --> +<function>XtAppAddActionHook</function>. +</para> + +<funcsynopsis id='XtAppAddActionHook'> +<funcprototype> +<funcdef>XtActionHookId <function>XtAppAddActionHook</function></funcdef> + <paramdef>XtAppContext <parameter>app</parameter></paramdef> + <paramdef>XtActionHookProc <parameter>proc</parameter></paramdef> + <paramdef>XtPointer <parameter>client_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -566,41 +447,36 @@ Specifies application-specific data to be passed to the action hook. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> <function>XtAppAddActionHook</function> 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 -<function>XtCallActionProc ,</function> +<function>XtCallActionProc</function>, the action hook procedures will be called in reverse order of registration just prior to invoking the action routine. </para> + <para> -<!-- .LP --> Action hook procedures are removed automatically and the <function>XtActionHookId is</function> destroyed when the application context in which they were added is destroyed. -<!-- .sp --> </para> + <para> -<!-- .LP --> To remove an action hook procedure without destroying the application context, use -<function>XtRemoveActionHook .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtRemoveActionHook" "" "@DEF@" --> -<!-- .sM --> +<function>XtRemoveActionHook</function>. </para> -<!-- .FD 0 --> -void XtRemoveActionHook(<emphasis remap='I'>id</emphasis>) -<!-- .br --> - XtActionHookId <emphasis remap='I'>id</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtRemoveActionHook'> +<funcprototype> +<funcdef>void <function>XtRemoveActionHook</function></funcdef> + <paramdef>XtActionHookId <parameter>id</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -609,28 +485,22 @@ void XtRemoveActionHook(<emphasis remap='I'>id</emphasis>) <listitem> <para> Specifies the action hook id returned by -<function>XtAppAddActionHook .</function> +<function>XtAppAddActionHook</function>. </para> </listitem> </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> <function>XtRemoveActionHook</function> removes the specified action hook procedure from the list in which it was registered. - </para> -</sect3> </sect2> -<sect2 id="Translation_Tables"> +</sect1> + +<sect1 id="Translation_Tables"> <title>Translation Tables</title> -<!-- .XS --> -<!-- <function>(SN Translation Tables</function> --> -<!-- .XE --> <para> -<!-- .LP --> All widget instance records contain a translation table, which is a resource with a default value specified elsewhere in the class record. @@ -643,8 +513,8 @@ The translations are separated from one another by newline characters (ASCII LF). The complete syntax of translation tables is specified in Appendix B. </para> + <para> -<!-- .LP --> As an example, the default behavior of Pushbutton is </para> <itemizedlist> @@ -670,24 +540,16 @@ Call callbacks and reinvert on left button up. </listitem> </itemizedlist> <para> -<!-- .LP --> The following illustrates Pushbutton's default translation table: </para> -<para> -<!-- .LP --> -<!-- .IN "Translation tables" --> <literallayout class="monospaced"> -<!-- .TA .5i 1.5i --> -<!-- .ta .5i 1.5i --> static String defaultTranslations = "<EnterWindow>: Highlight()\\n\\ <LeaveWindow>: Unhighlight()\\n\\ <Btn1Down>: Set()\\n\\ <Btn1Up>: Notify() Unset()"; </literallayout> -</para> <para> -<!-- .LP --> The <emphasis remap='I'>tm_table</emphasis> field of the <function>CoreClassPart</function> should be filled in at class initialization time with @@ -697,36 +559,31 @@ it can store the special value <function>XtInheritTranslations</function> into <emphasis remap='I'>tm_table</emphasis>. In Core's class part initialization procedure, -the (xI compile this translation table into an efficient internal form. +the Intrinsics compile this translation table into an efficient internal form. Then, at widget creation time, this default translation table is combined with the XtNtranslations and XtNbaseTranslations resources; see Section 10.3. </para> + <para> -<!-- .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 -<function>XtParseTranslationTable .</function> +<function>XtParseTranslationTable</function>. </para> + <para> -<!-- .LP --> -The (xI use the compiled form of the translation table to register the +The Intrinsics use the compiled form of the translation table to register the necessary events with the event manager. Widgets need do nothing other than specify the action and translation tables for events to be processed by the translation manager. - </para> -<sect3 id="Event_Sequences"> +<sect2 id="Event_Sequences"> <title>Event Sequences</title> -<!-- .XS --> -<!-- <function>(SN Event Sequences</function> --> -<!-- .XE --> <para> -<!-- .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. @@ -734,21 +591,17 @@ Each X event description consists of three parts: The X event type, a prefix consisting of the X modifier bits, and an event-specific suffix. </para> + <para> -<!-- .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. - </para> -</sect3> -<sect3 id="Action_Sequences"> +</sect2> + +<sect2 id="Action_Sequences"> <title>Action Sequences</title> -<!-- .XS --> -<!-- <function>(SN Action Sequences</function> --> -<!-- .XE --> <para> -<!-- .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. @@ -757,46 +610,36 @@ parenthesized list of zero or more comma-separated string parameters to pass to that procedure. The actions are invoked in left-to-right order as specified in the action sequence. - </para> -</sect3> -<sect3 id="Multi_Click_Time"> +</sect2> + +<sect2 id="Multi_Click_Time"> <title>Multi-Click Time</title> -<!-- .XS --> -<!-- <function>(SN Multi-Click Time</function> --> -<!-- .XE --> <para> -<!-- .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 -<function>XtDisplayInitialize .</function> +<function>XtDisplayInitialize</function>. If no value is specified, the initial value is 200 milliseconds. -<!-- .sp --> </para> + <para> -<!-- .LP --> To set the multi-click time dynamically, use -<function>XtSetMultiClickTime .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtSetMultiClickTime" "" "@DEF@" --> -<!-- .sM --> +<function>XtSetMultiClickTime</function>. </para> -<!-- .FD 0 --> -void XtSetMultiClickTime(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>time</emphasis>) -<!-- .br --> - Display *<emphasis remap='I'>display</emphasis>; -<!-- .br --> - int <emphasis remap='I'>time</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtSetMultiClickTime'> +<funcprototype> +<funcdef>void <function>XtSetMultiClickTime</function></funcdef> + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>int <parameter>time</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -820,8 +663,6 @@ Specifies the multi-click time in milliseconds. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> <function>XtSetMultiClickTime</function> sets the time interval used by the translation manager to determine when multiple events are interpreted as a @@ -831,23 +672,20 @@ events (e.g., between two <function>ButtonPress</function> events) must be less than the multi-click time in order for the translation actions to be taken. -<!-- .sp --> </para> + <para> -<!-- .LP --> To read the multi-click time, use -<function>XtGetMultiClickTime .</function> +<function>XtGetMultiClickTime</function>. </para> -<para> -<!-- .LP --> -<!-- .IN "XtGetMultiClickTime" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -int XtGetMultiClickTime(<emphasis remap='I'>display</emphasis>) -<!-- .br --> - Display *<emphasis remap='I'>display</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtGetMultiClickTime'> +<funcprototype> +<funcdef>int <function>XtGetMultiClickTime</function></funcdef> + <paramdef>Display *<parameter>display</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -861,24 +699,18 @@ Specifies the display connection. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> <function>XtGetMultiClickTime</function> returns the time in milliseconds that the translation manager uses to determine if multiple events are to be interpreted as a repeated event for purposes of matching a translation entry containing a repeat count. - </para> -</sect3> </sect2> -<sect2 id="Translation_Table_Management"> +</sect1> + +<sect1 id="Translation_Table_Management"> <title>Translation Table Management</title> -<!-- .XS --> -<!-- <function>(SN Translation Table Management</function> --> -<!-- .XE --> <para> -<!-- .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. @@ -886,8 +718,8 @@ The window manager wishes to bind this operation to a specific pointer button in the title bar without the possibility of user override and bind it to other buttons that may be overridden by the user. </para> + <para> -<!-- .LP --> To accomplish this, the window manager should first create the title bar and then should merge the two translation tables into @@ -898,9 +730,9 @@ or event sequence (i.e., those that may be overridden). The other translation table contains the translations that the window manager wants regardless of what the user has specified. </para> + <para> -<!-- .LP --> -Three (xI functions support this merging: +Three Intrinsics functions support this merging: <informaltable> <tgroup cols='2' align='center'> <colspec colname='c1'/> @@ -972,23 +804,20 @@ Three (xI functions support this merging: </tbody> </tgroup> </informaltable> -<!-- .sp --> </para> + <para> -<!-- .LP --> To compile a translation table, use -<function>XtParseTranslationTable .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtParseTranslationTable" "" "@DEF@" --> -<!-- .sM --> +<function>XtParseTranslationTable</function>. </para> -<!-- .FD 0 --> -XtTranslations XtParseTranslationTable(<emphasis remap='I'>table</emphasis>) -<!-- .br --> - String <emphasis remap='I'>table</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtParseTranslationTable'> +<funcprototype> +<funcdef>XtTranslations <function>XtParseTranslationTable</function></funcdef> + <paramdef>String <parameter>table</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -1002,37 +831,31 @@ Specifies the translation table to compile. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtParseTranslationTable</function> function compiles the translation table, provided in the format given in Appendix B, into an opaque internal representation of type -<function>XtTranslations .</function> +<function>XtTranslations</function>. Note that if an empty translation table is required for any purpose, one can be obtained by calling <function>XtParseTranslationTable</function> and passing an empty string. -<!-- .sp --> </para> + <para> -<!-- .LP --> To merge additional translations into an existing translation table, use -<function>XtAugmentTranslations .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtAugmentTranslations" "" "@DEF@" --> -<!-- .sM --> +<function>XtAugmentTranslations</function>. </para> -<!-- .FD 0 --> -void XtAugmentTranslations(<emphasis remap='I'>w</emphasis>, <emphasis remap='I'>translations</emphasis>) -<!-- .br --> - Widget <emphasis remap='I'>w</emphasis>; -<!-- .br --> - XtTranslations <emphasis remap='I'>translations</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtAugmentTranslations'> +<funcprototype> +<funcdef>void <function>XtAugmentTranslations</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>XtTranslations <parameter>translations</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -1040,7 +863,7 @@ void XtAugmentTranslations(<emphasis remap='I'>w</emphasis>, <emphasis remap='I' </term> <listitem> <para> -Specifies the widget into which the new translations are to be merged. (cI +Specifies the widget into which the new translations are to be merged. Must be of class Core or any subclass thereof. </para> </listitem> </varlistentry> @@ -1056,14 +879,12 @@ Specifies the compiled translation table to merge in. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtAugmentTranslations</function> function merges the new translations into the existing widget translations, ignoring any -<function>#replace ,</function> -<function>#augment ,</function> +<function>#replace</function>, +<function>#augment</function>, or <function>#override</function> directive that may have been specified @@ -1077,25 +898,21 @@ 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 --> </para> + <para> -<!-- .LP --> To overwrite existing translations with new translations, use -<function>XtOverrideTranslations .</function> +<function>XtOverrideTranslations</function>. </para> -<para> -<!-- .LP --> -<!-- .IN "XtOverrideTranslations" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -void XtOverrideTranslations(<emphasis remap='I'>w</emphasis>, <emphasis remap='I'>translations</emphasis>) -<!-- .br --> - Widget <emphasis remap='I'>w</emphasis>; -<!-- .br --> - XtTranslations <emphasis remap='I'>translations</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtOverrideTranslations'> +<funcprototype> +<funcdef>void <function>XtOverrideTranslations</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>XtTranslations <parameter>translations</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -1103,7 +920,7 @@ void XtOverrideTranslations(<emphasis remap='I'>w</emphasis>, <emphasis remap='I </term> <listitem> <para> -Specifies the widget into which the new translations are to be merged. (cI +Specifies the widget into which the new translations are to be merged. Must be of class Core or any subclass thereof. </para> </listitem> </varlistentry> @@ -1119,14 +936,12 @@ Specifies the compiled translation table to merge in. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtOverrideTranslations</function> function merges the new translations into the existing widget translations, ignoring any -<function>#replace ,</function> -<function>#augment ,</function> +<function>#replace</function>, +<function>#augment</function>, or <function>#override</function> directive that may have been @@ -1141,16 +956,15 @@ if the new translations contain an event or event sequence that already exists in the widget's translations, the new translation overrides the widget's translation. </para> + <para> -<!-- .LP --> To replace a widget's translations completely, use <function>XtSetValues</function> on the XtNtranslations resource and specify a compiled translation table as the value. -<!-- .sp --> </para> + <para> -<!-- .LP --> To make it possible for users to easily modify translation tables in their resource files, the string-to-translation-table resource type converter @@ -1171,8 +985,8 @@ translation resource value; if the original tables were shared by other widgets, they are unaffected. If no directive is specified, ``#replace'' is assumed. </para> + <para> -<!-- .LP --> At instance initialization the XtNtranslations resource is first fetched. Then, if it was not specified or did not contain ``#replace'', the @@ -1185,23 +999,20 @@ stored into the widget <emphasis remap='I'>translations</emphasis> field. If th 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 --> </para> + <para> -<!-- .LP --> To completely remove existing translations, use -<function>XtUninstallTranslations .</function> +<function>XtUninstallTranslations</function>. </para> -<para> -<!-- .LP --> -<!-- .IN "XtUninstallTranslations" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -void XtUninstallTranslations(<emphasis remap='I'>w</emphasis>) -<!-- .br --> - Widget <emphasis remap='I'>w</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtUninstallTranslations'> +<funcprototype> +<funcdef>void <function>XtUninstallTranslations</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -1209,34 +1020,27 @@ void XtUninstallTranslations(<emphasis remap='I'>w</emphasis>) </term> <listitem> <para> -Specifies the widget from which the translations are to be removed. (cI +Specifies the widget from which the translations are to be removed. Must be of class Core or any subclass thereof. </para> </listitem> </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtUninstallTranslations</function> function causes the entire translation table for the widget to be removed. - </para> -</sect2> -<sect2 id="Using_Accelerators"> +</sect1> + +<sect1 id="Using_Accelerators"> <title>Using Accelerators</title> -<!-- .XS --> -<!-- <function>(SN Using Accelerators</function> --> -<!-- .XE --> <para> -<!-- .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 +The Intrinsics 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 <emphasis remap='I'>source</emphasis> widget. The accelerator table can then be installed on one or more <emphasis remap='I'>destination</emphasis> widgets. @@ -1250,8 +1054,8 @@ procedures used within accelerators must not assume that the source widget is realized nor that any fields of the event are in reference to the source widget's window if the widget is realized. </para> + <para> -<!-- .LP --> Each widget instance contains that widget's exported accelerator table as a resource. Each class of widget exports a method that takes a @@ -1260,21 +1064,18 @@ 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 -<function>XtStringProc .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "display_accelerator procedure" "" "@DEF@" --> -<!-- .IN "XtStringProc" "" "@DEF@" --> -<!-- .sM --> +<function>XtStringProc</function>. </para> -<!-- .FD 0 --> -typedef void (*XtStringProc)(Widget, String); -<!-- .br --> - Widget <emphasis remap='I'>w</emphasis>; -<!-- .br --> - String <emphasis remap='I'>string</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtStringProc'> +<funcprototype> +<funcdef>void <function>*XtStringProc</function></funcdef> + + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>String <parameter>string</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -1298,8 +1099,6 @@ Specifies the string representation of the accelerators for this widget. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> Accelerators can be specified in resource files, and the string representation is the same as for a translation table. However, @@ -1312,29 +1111,26 @@ what will happen when the accelerator is installed; that is, whether or not the accelerator translations will override the translations in the destination widget. The default is -<function>#augment ,</function> +<function>#augment</function>, which means that the accelerator translations have lower priority than the destination translations. The <function>#replace</function> directive is ignored for accelerator tables. -<!-- .sp --> </para> + <para> -<!-- .LP --> To parse an accelerator table, use -<function>XtParseAcceleratorTable .</function> +<function>XtParseAcceleratorTable</function>. </para> -<para> -<!-- .LP --> -<!-- .IN "XtParseAcceleratorTable" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -XtAccelerators XtParseAcceleratorTable(<emphasis remap='I'>source</emphasis>) -<!-- .br --> - String <emphasis remap='I'>source</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtParseAcceleratorTable'> +<funcprototype> +<funcdef>XtAccelerators <function>XtParseAcceleratorTable</function></funcdef> + <paramdef>String <parameter>source</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -1348,8 +1144,6 @@ Specifies the accelerator table to compile. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtParseAcceleratorTable</function> function compiles the accelerator table into an opaque internal representation. @@ -1357,25 +1151,21 @@ The client should set the XtNaccelerators resource of each widget that is to be activated by these translations to the returned value. -<!-- .sp --> </para> + <para> -<!-- .LP --> To install accelerators from a widget on another widget, use -<function>XtInstallAccelerators .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtInstallAccelerators" "" "@DEF@" --> -<!-- .sM --> +<function>XtInstallAccelerators</function>. </para> -<!-- .FD 0 --> -void XtInstallAccelerators(<emphasis remap='I'>destination</emphasis>, <emphasis remap='I'>source</emphasis>) -<!-- .br --> - Widget <emphasis remap='I'>destination</emphasis>; -<!-- .br --> - Widget <emphasis remap='I'>source</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtInstallAccelerators'> +<funcprototype> +<funcdef>void <function>XtInstallAccelerators</function></funcdef> + <paramdef>Widget <parameter>destination</parameter></paramdef> + <paramdef>Widget <parameter>source</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -1383,7 +1173,7 @@ void XtInstallAccelerators(<emphasis remap='I'>destination</emphasis>, <emphasis </term> <listitem> <para> -Specifies the widget on which the accelerators are to be installed. (cI +Specifies the widget on which the accelerators are to be installed. Must be of class Core or any subclass thereof. </para> </listitem> </varlistentry> @@ -1393,14 +1183,12 @@ Specifies the widget on which the accelerators are to be installed. (cI </term> <listitem> <para> -Specifies the widget from which the accelerators are to come. (cI +Specifies the widget from which the accelerators are to come. Must be of class Core or any subclass thereof. </para> </listitem> </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtInstallAccelerators</function> function installs the <emphasis remap='I'>accelerators</emphasis> resource value from @@ -1414,26 +1202,22 @@ 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 --> </para> + <para> -<!-- .LP --> As a convenience for installing all accelerators from a widget and all its descendants onto one destination, use -<function>XtInstallAllAccelerators .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtInstallAllAccelerators" "" "@DEF@" --> -<!-- .sM --> +<function>XtInstallAllAccelerators</function>. </para> -<!-- .FD 0 --> -void XtInstallAllAccelerators(<emphasis remap='I'>destination</emphasis>, <emphasis remap='I'>source</emphasis>) -<!-- .br --> - Widget <emphasis remap='I'>destination</emphasis>; -<!-- .br --> - Widget <emphasis remap='I'>source</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtInstallAllAccelerators'> +<funcprototype> +<funcdef>void <function>XtInstallAllAccelerators</function></funcdef> + <paramdef>Widget <parameter>destination</parameter></paramdef> + <paramdef>Widget <parameter>source</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -1441,7 +1225,7 @@ void XtInstallAllAccelerators(<emphasis remap='I'>destination</emphasis>, <empha </term> <listitem> <para> -Specifies the widget on which the accelerators are to be installed. (cI +Specifies the widget on which the accelerators are to be installed. Must be of class Core or any subclass thereof. </para> </listitem> </varlistentry> @@ -1452,14 +1236,12 @@ Specifies the widget on which the accelerators are to be installed. (cI <listitem> <para> Specifies the root widget of the widget tree -from which the accelerators are to come. (cI +from which the accelerators are to come. Must be of class Core or any subclass thereof. </para> </listitem> </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtInstallAllAccelerators</function> function recursively descends the widget tree rooted at <emphasis remap='I'>source</emphasis> @@ -1468,40 +1250,29 @@ of each widget encountered onto <emphasis remap='I'>destination</emphasis>. A common use is to call <function>XtInstallAllAccelerators</function> and pass the application main window as the source. - </para> -</sect2> -<sect2 id="KeyCode_to_KeySym_Conversions"> +</sect1> + +<sect1 id="KeyCode_to_KeySym_Conversions"> <title>KeyCode-to-KeySym Conversions</title> -<!-- .XS --> -<!-- (SN KeyCode-to-KeySym Conversions --> -<!-- .XE --> <para> -<!-- .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 -<function>XtKeyProc .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtKeyProc" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -typedef void (*XtKeyProc)(Display*, KeyCode, Modifiers, Modifiers*, \ -KeySym*); -<!-- .br --> - Display *<emphasis remap='I'>display</emphasis>; -<!-- .br --> - KeyCode <emphasis remap='I'>keycode</emphasis>; -<!-- .br --> - Modifiers <emphasis remap='I'>modifiers</emphasis>; -<!-- .br --> - Modifiers *<emphasis remap='I'>modifiers_return</emphasis>; -<!-- .br --> - KeySym *<emphasis remap='I'>keysym_return</emphasis>; -<!-- .FN --> +<function>XtKeyProc</function>. +</para> + +<funcsynopsis id='XtKeyProc'> +<funcprototype> +<funcdef>void <function>*XtKeyProc</function></funcdef> + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>KeyCode <parameter>keycode</parameter></paramdef> + <paramdef>Modifiers <parameter>modifiers</parameter></paramdef> + <paramdef>Modifiers *<parameter>modifiers_return</parameter></paramdef> + <paramdef>KeySym *<parameter>keysym_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -1557,54 +1328,45 @@ Specifies a location in which to store the resulting KeySym. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> This procedure takes a KeyCode and modifiers and produces a KeySym. For any given key translator function and keyboard encoding, <emphasis remap='I'>modifiers_return</emphasis> will be a constant per KeyCode that indicates the subset of all modifiers that are examined by the key translator for that KeyCode. </para> + <para> -<!-- .LP --> The KeyCode-to-KeySym translator procedure must be implemented such that multiple calls with the same <emphasis remap='I'>display</emphasis>, <emphasis remap='I'>keycode</emphasis>, and <emphasis remap='I'>modifiers</emphasis> return the same result until either a new case converter, an -<function>XtCaseProc ,</function> +<function>XtCaseProc</function>, is installed or a <function>MappingNotify</function> event is received. - -<!-- .sp --> </para> + <para> -<!-- .LP --> -The (xI maintain tables internally to map KeyCodes to KeySyms +The Intrinsics maintain tables internally to map KeyCodes to KeySyms for each open display. Translator procedures and other clients may share a single copy of this table to perform the same mapping. </para> + <para> -<!-- .LP --> To return a pointer to the KeySym-to-KeyCode mapping table for a particular display, use -<function>XtGetKeysymTable .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtGetKeysymTable" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -KeySym *XtGetKeysymTable(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>min_keycode_return</emphasis>, \ -<emphasis remap='I'>keysyms_per_keycode_return</emphasis>) -<!-- .br --> - Display *<emphasis remap='I'>display</emphasis>; -<!-- .br --> - KeyCode *<emphasis remap='I'>min_keycode_return</emphasis>; -<!-- .br --> - int *<emphasis remap='I'>keysyms_per_keycode_return</emphasis>; -<!-- .FN --> +<function>XtGetKeysymTable</function>. +</para> + +<funcsynopsis id='XtGetKeysymTable'> +<funcprototype> +<funcdef>KeySym * <function>XtGetKeysymTable</function></funcdef> + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>KeyCode *<parameter>min_keycode_return</parameter></paramdef> + <paramdef>int *<parameter>keysyms_per_keycode_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -1638,10 +1400,8 @@ Returns the number of KeySyms stored for each KeyCode. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> <function>XtGetKeysymTable</function> -returns a pointer to the (xI' copy of the +returns a pointer to the Intrinsics' copy of the server's KeyCode-to-KeySym table. This table must not be modified. There are <emphasis remap='I'>keysyms_per_keycode_return</emphasis> KeySyms associated with each KeyCode, located in the table with indices starting at index @@ -1654,37 +1414,32 @@ KeyCode, located in the table with indices starting at index </listitem> </itemizedlist> <para> -<!-- .LP --> for KeyCode <emphasis remap='I'>test_keycode</emphasis>. Any entries that have no KeySyms associated with them contain the value -<function>NoSymbol .</function> +<function>NoSymbol</function>. Clients should not cache the KeySym table but should call <function>XtGetKeysymTable</function> each time the value is needed, as the table may change prior to dispatching each event. </para> + <para> -<!-- .LP --> -For more information on this table, see Section 12.7 in <emphasis remap='I'>(xL</emphasis>. -<!-- .sp --> +For more information on this table, see Section 12.7 in <emphasis remap='I'>Xlib — C Language X Interface.</emphasis>. </para> + <para> -<!-- .LP --> To register a key translator, use -<function>XtSetKeyTranslator .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtSetKeyTranslator" "" "@DEF@" --> -<!-- .sM --> +<function>XtSetKeyTranslator</function>. </para> -<!-- .FD 0 --> -void XtSetKeyTranslator(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>proc</emphasis>) -<!-- .br --> - Display *<emphasis remap='I'>display</emphasis>; -<!-- .br --> - XtKeyProc <emphasis remap='I'>proc</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtSetKeyTranslator'> +<funcprototype> +<funcdef>void <function>XtSetKeyTranslator</function></funcdef> + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>XtKeyProc <parameter>proc</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -1708,13 +1463,11 @@ Specifies the procedure to perform key translations. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtSetKeyTranslator</function> function sets the specified procedure as the current key translator. The default translator is -<function>XtTranslateKey ,</function> +<function>XtTranslateKey</function>, an <function>XtKeyProc</function> that uses the Shift, Lock, numlock, and group modifiers @@ -1722,33 +1475,25 @@ with the interpretations defined in <emphasis remap='I'>(xP</emphasis>, Section 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 --> </para> + <para> -<!-- .LP --> To invoke the currently registered KeyCode-to-KeySym translator, use -<function>XtTranslateKeycode .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtTranslateKeycode" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -void XtTranslateKeycode(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>keycode</emphasis>, <emphasis remap='I'>modifiers</emphasis>, \ -<emphasis remap='I'>modifiers_return</emphasis>, <emphasis remap='I'>keysym_return</emphasis>) -<!-- .br --> - Display *<emphasis remap='I'>display</emphasis>; -<!-- .br --> - KeyCode <emphasis remap='I'>keycode</emphasis>; -<!-- .br --> - Modifiers <emphasis remap='I'>modifiers</emphasis>; -<!-- .br --> - Modifiers *<emphasis remap='I'>modifiers_return</emphasis>; -<!-- .br --> - KeySym *<emphasis remap='I'>keysym_return</emphasis>; -<!-- .FN --> +<function>XtTranslateKeycode</function>. +</para> + +<funcsynopsis id='XtTranslateKeycode'> +<funcprototype> +<funcdef>void <function>XtTranslateKeycode</function></funcdef> + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>KeyCode <parameter>keycode</parameter></paramdef> + <paramdef>Modifiers <parameter>modifiers</parameter></paramdef> + <paramdef>Modifiers *<parameter>modifiers_return</parameter></paramdef> + <paramdef>KeySym *<parameter>keysym_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -1803,37 +1548,29 @@ Returns the resulting KeySym. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtTranslateKeycode</function> function passes the specified arguments directly to the currently registered KeyCode-to-KeySym translator. -<!-- .sp --> </para> + <para> -<!-- .LP --> -To handle capitalization of nonstandard KeySyms, the (xI allow +To handle capitalization of nonstandard KeySyms, the Intrinsics allow clients to register case conversion routines. Case converter procedure pointers are of type -<function>XtCaseProc .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtCaseProc" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -typedef void (*XtCaseProc)(Display*, KeySym, KeySym*, KeySym*); -<!-- .br --> - Display *<emphasis remap='I'>display</emphasis>; -<!-- .br --> - KeySym <emphasis remap='I'>keysym</emphasis>; -<!-- .br --> - KeySym *<emphasis remap='I'>lower_return</emphasis>; -<!-- .br --> - KeySym *<emphasis remap='I'>upper_return</emphasis>; -<!-- .FN --> +<function>XtCaseProc</function>. +</para> + +<funcsynopsis id='XtCaseProc'> +<funcprototype> +<funcdef>void <function>*XtCaseProc</function></funcdef> + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>KeySym <parameter>keysym</parameter></paramdef> + <paramdef>KeySym *<parameter>lower_return</parameter></paramdef> + <paramdef>KeySym *<parameter>upper_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -1879,33 +1616,25 @@ the KeySym. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> If there is no case distinction, this procedure should store the KeySym into both return values. -<!-- .sp --> </para> + <para> -<!-- .LP --> To register a case converter, use -<function>XtRegisterCaseConverter .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtRegisterCaseConverter" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -void XtRegisterCaseConverter(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>proc</emphasis>, <emphasis remap='I'>start</emphasis>, <emphasis remap='I'>stop</emphasis>) -<!-- .br --> - Display *<emphasis remap='I'>display</emphasis>; -<!-- .br --> - XtCaseProc <emphasis remap='I'>proc</emphasis>; -<!-- .br --> - KeySym <emphasis remap='I'>start</emphasis>; -<!-- .br --> - KeySym <emphasis remap='I'>stop</emphasis>; -<!-- .FN --> +<function>XtRegisterCaseConverter</function>. +</para> + +<funcsynopsis id='XtRegisterCaseConverter'> +<funcprototype> +<funcdef>void <function>XtRegisterCaseConverter</function></funcdef> + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>XtCaseProc <parameter>proc</parameter></paramdef> + <paramdef>KeySym <parameter>start</parameter></paramdef> + <paramdef>KeySym <parameter>stop</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -1951,8 +1680,6 @@ Specifies the last KeySym for which this converter is valid. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtRegisterCaseConverter</function> registers the specified case converter. @@ -1962,33 +1689,26 @@ 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 Intrinsics refresh the keyboard state if necessary. The default converter understands case conversion for all Latin KeySyms defined in <emphasis remap='I'>(xP</emphasis>, Appendix A. -<!-- .sp --> </para> + <para> -<!-- .LP --> To determine uppercase and lowercase equivalents for a KeySym, use -<function>XtConvertCase .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtConvertCase" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -void XtConvertCase(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>keysym</emphasis>, <emphasis remap='I'>lower_return</emphasis>, \ -<emphasis remap='I'>upper_return</emphasis>) -<!-- .br --> - Display *<emphasis remap='I'>display</emphasis>; -<!-- .br --> - KeySym <emphasis remap='I'>keysym</emphasis>; -<!-- .br --> - KeySym *<emphasis remap='I'>lower_return</emphasis>; -<!-- .br --> - KeySym *<emphasis remap='I'>upper_return</emphasis>; -<!-- .FN --> +<function>XtConvertCase</function>. +</para> + +<funcsynopsis id='XtConvertCase'> +<funcprototype> +<funcdef>void <function>XtConvertCase</function></funcdef> + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>KeySym <parameter>keysym</parameter></paramdef> + <paramdef>KeySym *<parameter>lower_return</parameter></paramdef> + <paramdef>KeySym *<parameter>upper_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -2032,24 +1752,18 @@ Returns the uppercase equivalent of the KeySym. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtConvertCase</function> function calls the appropriate converter and returns the results. A user-supplied <function>XtKeyProc</function> may need to use this function. - </para> -</sect2> -<sect2 id="Obtaining_a_KeySym_in_an_Action_Procedure"> +</sect1> + +<sect1 id="Obtaining_a_KeySym_in_an_Action_Procedure"> <title>Obtaining a KeySym in an Action Procedure</title> -<!-- .XS --> -<!-- <function>(SN Obtaining a KeySym in an Action Procedure</function> --> -<!-- .XE --> <para> -<!-- .LP --> When an action procedure is invoked on a <function>KeyPress</function> or @@ -2057,28 +1771,25 @@ or 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 +Intrinsics to match the translation entry, the KeySym and modifiers are stored for the duration of the action procedure and are made available to the client. </para> + <para> -<!-- .LP --> To retrieve the KeySym and modifiers that matched the final event specification in the translation table entry, use -<function>XtGetActionKeysym .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtGetActionKeysym" "" "@DEF@" --> -<!-- .sM --> +<function>XtGetActionKeysym</function>. </para> -<!-- .FD 0 --> -KeySym XtGetActionKeysym(<emphasis remap='I'>event</emphasis>, <emphasis remap='I'>modifiers_return</emphasis>) -<!-- .br --> - XEvent *<emphasis remap='I'>event</emphasis>; -<!-- .br --> - Modifiers *<emphasis remap='I'>modifiers_return</emphasis>; -<!-- .FN --> + +<funcsynopsis id='XtGetActionKeysym'> +<funcprototype> +<funcdef>KeySym <function>XtGetActionKeysym</function></funcdef> + <paramdef>XEvent *<parameter>event</parameter></paramdef> + <paramdef>Modifiers *<parameter>modifiers_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -2086,7 +1797,7 @@ KeySym XtGetActionKeysym(<emphasis remap='I'>event</emphasis>, <emphasis remap=' </term> <listitem> <para> -Specifies the event pointer passed to the action procedure by the (xI. +Specifies the event pointer passed to the action procedure by the Intrinsics. </para> </listitem> </varlistentry> @@ -2102,12 +1813,10 @@ Returns the modifiers that caused the match, if non-NULL. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> If <function>XtGetActionKeysym</function> is called after an action procedure has been -invoked by the (xI and before that action procedure returns, and +invoked by the Intrinsics and before that action procedure returns, and if the event pointer has the same value as the event pointer passed to that action routine, and if the event is a <function>KeyPress</function> @@ -2131,45 +1840,35 @@ else it returns <function>NoSymbol</function> and does not examine <emphasis remap='I'>modifiers_return</emphasis>. </para> + <para> -<!-- .LP --> -Note that if an action procedure invoked by the (xI +Note that if an action procedure invoked by the Intrinsics invokes a subsequent action procedure (and so on) via -<function>XtCallActionProc ,</function> +<function>XtCallActionProc</function>, the nested action procedure may also call <function>XtGetActionKeysym</function> -to retrieve the (xI' KeySym and modifiers. - +to retrieve the Intrinsics' KeySym and modifiers. </para> -</sect2> -<sect2 id="KeySym_to_KeyCode_Conversions"> +</sect1> + +<sect1 id="KeySym_to_KeyCode_Conversions"> <title>KeySym-to-KeyCode Conversions</title> -<!-- .XS --> -<!-- (SN KeySym-to-KeyCode Conversions --> -<!-- .XE --> <para> -<!-- .LP --> To return the list of KeyCodes that map to a particular KeySym in -the keyboard mapping table maintained by the (xI, use -<function>XtKeysymToKeycodeList .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtKeysymToKeycodeList" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -void XtKeysymToKeycodeList(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>keysym</emphasis>, <emphasis remap='I'>keycodes_return</emphasis>, \ -<emphasis remap='I'>keycount_return</emphasis>) -<!-- .br --> - Display *<emphasis remap='I'>display</emphasis>; -<!-- .br --> - KeySym <emphasis remap='I'>keysym</emphasis>; -<!-- .br --> - KeyCode **<emphasis remap='I'>keycodes_return</emphasis>; -<!-- .br --> - Cardinal *<emphasis remap='I'>keycount_return</emphasis>; -<!-- .FN --> +the keyboard mapping table maintained by the Intrinsics, use +<function>XtKeysymToKeycodeList</function>. +</para> + +<funcsynopsis id='XtKeysymToKeycodeList'> +<funcprototype> +<funcdef>void <function>XtKeysymToKeycodeList</function></funcdef> + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>KeySym <parameter>keysym</parameter></paramdef> + <paramdef>KeyCode **<parameter>keycodes_return</parameter></paramdef> + <paramdef>Cardinal *<parameter>keycount_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -2214,8 +1913,6 @@ Returns the number of KeyCodes in the keycode list. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> The <function>XtKeysymToKeycodeList</function> procedure returns all the KeyCodes that have <emphasis remap='I'>keysym</emphasis> @@ -2225,44 +1922,34 @@ table, the first four KeySyms (groups 1 and 2) are interpreted as specified by <emphasis remap='I'>(xP</emphasis>, Section 5. If no KeyCodes map to the specified KeySym, <emphasis remap='I'>keycount_return</emphasis> is zero and *<emphasis remap='I'>keycodes_return</emphasis> is NULL. </para> + <para> -<!-- .LP --> The caller should free the storage pointed to by <emphasis remap='I'>keycodes_return</emphasis> using <function>XtFree</function> when it is no longer useful. If the caller needs to examine the KeyCode-to-KeySym table for a particular KeyCode, it should call -<function>XtGetKeysymTable .</function> - +<function>XtGetKeysymTable</function>. </para> -</sect2> -<sect2 id="Registering_Button_and_Key_Grabs_for_Actions"> +</sect1> + +<sect1 id="Registering_Button_and_Key_Grabs_for_Actions"> <title>Registering Button and Key Grabs for Actions</title> -<!-- .XS --> -<!-- <function>(SN Registering Button and Key Grabs for Actions</function> --> -<!-- .XE --> <para> -<!-- .LP --> To register button and key grabs for a widget's window according to the event bindings in the widget's translation table, use -<function>XtRegisterGrabAction .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtRegisterGrabAction" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -void XtRegisterGrabAction(<emphasis remap='I'>action_proc</emphasis>, <emphasis remap='I'>owner_events</emphasis>, \ -<emphasis remap='I'>event_mask</emphasis>, <emphasis remap='I'>pointer_mode</emphasis>, <emphasis remap='I'>keyboard_mode</emphasis>) -<!-- .br --> - XtActionProc <emphasis remap='I'>action_proc</emphasis>; -<!-- .br --> - Boolean <emphasis remap='I'>owner_events</emphasis>; -<!-- .br --> - unsigned int <emphasis remap='I'>event_mask</emphasis>; -<!-- .br --> - int <emphasis remap='I'>pointer_mode</emphasis>, <emphasis remap='I'>keyboard_mode</emphasis>; -<!-- .FN --> +<function>XtRegisterGrabAction</function>. +</para> + +<funcsynopsis id='XtRegisterGrabAction'> +<funcprototype> +<funcdef>void <function>XtRegisterGrabAction</function></funcdef> + <paramdef>XtActionProc <parameter>action_proc</parameter></paramdef> + <paramdef>Boolean <parameter>owner_events</parameter></paramdef> + <paramdef>unsigned int <parameter>event_mask</parameter></paramdef> + <paramdef>int <parameter>pointer_mode</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -2271,7 +1958,6 @@ void XtRegisterGrabAction(<emphasis remap='I'>action_proc</emphasis>, <emphasis <listitem> <para> Specifies the action procedure to search for in translation tables. -<!-- .sp --> </para> </listitem> </varlistentry> @@ -2280,10 +1966,8 @@ Specifies the action procedure to search for in translation tables. <emphasis remap='I'>owner_events</emphasis> </term> <listitem> - <para> -<!-- .br --> -<!-- .ns --> - </para> + <para></para> + </listitem> </varlistentry> <varlistentry> @@ -2291,10 +1975,8 @@ Specifies the action procedure to search for in translation tables. <emphasis remap='I'>event_mask</emphasis> </term> <listitem> - <para> -<!-- .br --> -<!-- .ns --> - </para> + <para></para> + </listitem> </varlistentry> <varlistentry> @@ -2302,10 +1984,7 @@ Specifies the action procedure to search for in translation tables. <emphasis remap='I'>pointer_mode</emphasis> </term> <listitem> - <para> -<!-- .br --> -<!-- .ns --> - </para> + <para></para> </listitem> </varlistentry> <varlistentry> @@ -2317,14 +1996,12 @@ Specifies the action procedure to search for in translation tables. Specify arguments to <function>XtGrabButton</function> or -<function>XtGrabKey .</function> +<function>XtGrabKey</function>. </para> </listitem> </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> <function>XtRegisterGrabAction</function> adds the specified <emphasis remap='I'>action_proc</emphasis> to a list known to the translation manager. When a widget is realized, or when the @@ -2336,7 +2013,7 @@ If any are invoked on or <function>KeyPress</function> events as the only or final event -in a sequence, the (xI will call +in a sequence, the Intrinsics will call <function>XtGrabButton</function> or <function>XtGrabKey</function> @@ -2347,7 +2024,7 @@ event detail field, passing the specified <emphasis remap='I'>owner_events</emph events, the modifiers specified in the grab are determined directly from the translation specification and <emphasis remap='I'>confine_to</emphasis> and <emphasis remap='I'>cursor</emphasis> are specified as -<function>None .</function> +<function>None</function>. For <function>KeyPress</function> events, if the translation table entry specifies colon (:) in @@ -2366,57 +2043,46 @@ and events, don't-care modifiers are ignored unless the translation entry explicitly specifies ``Any'' in the <emphasis remap='I'>modifiers</emphasis> field. </para> + <para> -<!-- .LP --> If the specified <emphasis remap='I'>action_proc</emphasis> is already registered for the calling process, the new values will replace the previously specified values for any widgets that become realized following the call, but existing grabs are not altered on currently realized widgets. </para> + <para> -<!-- .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 <function>XtGrabKey</function> or -<function>XtGrabButton .</function> - +<function>XtGrabButton</function>. </para> -</sect2> -<sect2 id="Invoking_Actions_Directly"> +</sect1> + +<sect1 id="Invoking_Actions_Directly"> <title>Invoking Actions Directly</title> -<!-- .XS --> -<!-- <function>(SN Invoking Actions Directly</function> --> -<!-- .XE --> <para> -<!-- .LP --> -Normally action procedures are invoked by the (xI when an +Normally action procedures are invoked by the Intrinsics when an event or event sequence arrives for a widget. To invoke an action procedure directly, without generating (or synthesizing) events, use -<function>XtCallActionProc .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtCallActionProc" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -void XtCallActionProc(<emphasis remap='I'>widget</emphasis>, <emphasis remap='I'>action</emphasis>, <emphasis remap='I'>event</emphasis>, <emphasis remap='I'>params</emphasis>, \ -<emphasis remap='I'>num_params</emphasis>) -<!-- .br --> - Widget <emphasis remap='I'>widget</emphasis>; -<!-- .br --> - String <emphasis remap='I'>action</emphasis>; -<!-- .br --> - XEvent *<emphasis remap='I'>event</emphasis>; -<!-- .br --> - String *<emphasis remap='I'>params</emphasis>; -<!-- .br --> - Cardinal <emphasis remap='I'>num_params</emphasis>; -<!-- .FN --> +<function>XtCallActionProc</function>. +</para> + +<funcsynopsis id='XtCallActionProc'> +<funcprototype> +<funcdef>void <function>XtCallActionProc</function></funcdef> + <paramdef>Widget <parameter>widget</parameter></paramdef> + <paramdef>String <parameter>action</parameter></paramdef> + <paramdef>XEvent *<parameter>event</parameter></paramdef> + <paramdef>String *<parameter>params</parameter></paramdef> + <paramdef>Cardinal <parameter>num_params</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -2424,7 +2090,7 @@ void XtCallActionProc(<emphasis remap='I'>widget</emphasis>, <emphasis remap='I' </term> <listitem> <para> -Specifies the widget in which the action is to be invoked. (cI +Specifies the widget in which the action is to be invoked. Must be of class Core or any subclass thereof. </para> </listitem> </varlistentry> @@ -2470,14 +2136,12 @@ Specifies the number of entries in <emphasis remap='I'>params</emphasis>. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> <function>XtCallActionProc</function> 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 -<function>XtCallActionProc .</function> +<function>XtCallActionProc</function>. 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 @@ -2487,38 +2151,29 @@ the specified widget is realized or sensitive. If the named action routine cannot be found, <function>XtCallActionProc</function> generates a warning message and returns. - </para> -</sect2> -<sect2 id="Obtaining_a_Widget_s_Action_List"> +</sect1> + +<sect1 id="Obtaining_a_Widget_s_Action_List"> <title>Obtaining a Widget's Action List</title> -<!-- .XS --> -<!-- (SN Obtaining a Widget's Action List --> -<!-- .XE --> <para> -<!-- .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 <emphasis remap='I'>actions</emphasis> field, use -<function>XtGetActionList .</function> -</para> -<para> -<!-- .LP --> -<!-- .IN "XtGetActionList" "" "@DEF@" --> -<!-- .sM --> -</para> -<!-- .FD 0 --> -void XtGetActionList(<emphasis remap='I'>widget_class</emphasis>, <emphasis remap='I'>actions_return</emphasis>, \ -<emphasis remap='I'>num_actions_return</emphasis>) -<!-- .br --> - WidgetClass <emphasis remap='I'>widget_class</emphasis>; -<!-- .br --> - XtActionList *<emphasis remap='I'>actions_return</emphasis>; -<!-- .br --> - Cardinal *<emphasis remap='I'>num_actions_return</emphasis>; -<!-- .FN --> +<function>XtGetActionList</function>. +</para> + +<funcsynopsis id='XtGetActionList'> +<funcprototype> +<funcdef>void <function>XtGetActionList</function></funcdef> + <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef> + <paramdef>XtActionList *<parameter>actions_return</parameter></paramdef> + <paramdef>Cardinal *<parameter>num_actions_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> + <variablelist> <varlistentry> <term> @@ -2552,8 +2207,6 @@ Returns the number of action procedures declared by the class. </varlistentry> </variablelist> <para> -<!-- .LP --> -<!-- .eM --> <function>XtGetActionList</function> returns the action table defined by the specified widget class. This table does not include actions defined by the @@ -2566,56 +2219,6 @@ If *<emphasis remap='I'>actions_return</emphasis> is non-NULL the client is resp the table using <function>XtFree</function> when it is no longer needed. -<!-- .bp --> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - </para> -</sect2> +</sect1> </chapter> -</book> |