From 5f8448ef6b85a9ff72c5af4cec99183c8bb60dc6 Mon Sep 17 00:00:00 2001 From: marha Date: Tue, 10 Apr 2012 14:58:33 +0200 Subject: Updated following packages: bigreqsproto-1.1.2 fontsproto-2.1.2 recordproto-1.14.2 scrnsaverproto-1.2.2 xcmiscproto-1.2.2 libXt-1.1.3 xhost-1.0.5 kbproto-1.0.6 libXrender-0.9.7 libxkbfile-1.0.8 freetype-2.4.9 libXaw-1.0.10 libXpm-3.5.10 xproto-7.0.23 --- libXt/specs/CH10.xml | 2211 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 2211 insertions(+) create mode 100644 libXt/specs/CH10.xml (limited to 'libXt/specs/CH10.xml') diff --git a/libXt/specs/CH10.xml b/libXt/specs/CH10.xml new file mode 100644 index 000000000..a96d2c427 --- /dev/null +++ b/libXt/specs/CH10.xml @@ -0,0 +1,2211 @@ + +Translation Management + +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. + + + +The translation manager provides an interface to specify and manage the +mapping of X event sequences into widget-supplied functionality, +for example, calling procedure Abc when the y key +is pressed. + + + +The translation manager uses two kinds of tables to perform translations: + + + + +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. + + + + +A translation table, which is in the widget class structure, +specifies the mapping of event sequences to procedure name strings. + + + + +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 . + + +Action Tables + +All widget class records contain an action table, +an array of +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 +. + + + + +typedef void (*XtActionProc) + Widget w + XEvent *event + String *params + Cardinal *num_params + + + + + + + w + + + +Specifies the widget that caused the action to be called. + + + + + + event + + + +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. + + + + + + params + + + +Specifies a pointer to the list of strings that were specified +in the translation table as arguments to the action, or NULL. + + + + + + num_params + + + +Specifies the number of entries in params. + + + + + + +typedef struct _XtActionsRec { + String string; + XtActionProc proc; +} XtActionsRec, *XtActionList; + + +The string field is the name used in translation tables to access +the procedure. +The proc field is a pointer to a procedure that implements +the functionality. + + + +When the action list is specified as the +CoreClassPart +actions field, the string pointed to by string must be +permanently allocated prior to or during the execution of the class +initialization procedure and must not be subsequently deallocated. + + + +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. + + + +For example, a Pushbutton widget has procedures to take the following actions: + + + + +Set the button to indicate it is activated. + + + + +Unset the button back to its normal mode. + + + + +Highlight the button borders. + + + + +Unhighlight the button borders. + + + + +Notify any callbacks that the button has been activated. + + + + +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: + + +XtActionsRec actionTable[] = { + {"Set", Set}, + {"Unset", Unset}, + {"Highlight", Highlight}, + {"Unhighlight", Unhighlight} + {"Notify", Notify}, +}; + + +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 Intrinsics functions. + + +Action Table Registration + +The actions and num_actions fields of +CoreClassPart +specify the actions implemented by a widget class. These are +automatically registered with the Intrinsics when the class is initialized +and must be allocated in writable storage prior to Core class_part +initialization, and never deallocated. To save memory and optimize +access, the Intrinsics may overwrite the storage in order to compile the +list into an internal representation. + + + +To declare an action table within an application +and register it with the translation manager, use +. + + + + +void XtAppAddActions + XtAppContext app_context + XtActionList actions + Cardinal num_actions + + + + + + + app_context + + + +Specifies the application context. + + + + + + actions + + + +Specifies the action table to register. + + + + + + num_actions + + + +Specifies the number of entries in this action table. + + + + + + +If more than one action is registered with the same name, +the most recently registered action is used. +If duplicate actions exist in an action table, +the first is used. +The Intrinsics register an action table containing + +and + +as part of +. + + + + +Action Names to Procedure Translations + +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: + + + + +The widget's class and all superclass action tables, in subclass-to-superclass +order. + + + + +The parent's class and all superclass action tables, in subclass-to-superclass +order, then on up the ancestor tree. + + + + +The action tables registered with + +and + +from the most recently added table to the oldest table. + + + + +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. + + + + +Action Hook Registration + +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 +. + + + + +typedef void (*XtActionHookProc) + Widget w + XtPointer client_data + String action_name + XEvent* event + String* params + Cardinal* num_params + + + + + + + + + w + + + +Specifies the widget whose action is about to be dispatched. + + + + + + client_data + + + +Specifies the application-specific closure that was passed to +XtAppAddActionHook. + + + + + + action_name + + + +Specifies the name of the action to be dispatched. + + + + + + event + + + +Specifies the event argument that will be passed to the action routine. + + + + + + params + + + +Specifies the action parameters that will be passed to the action routine. + + + + + + num_params + + + +Specifies the number of entries in params. + + + + + + +Action hooks should not modify any of the data pointed to by the +arguments other than the client_data argument. + + + +To add an action hook, use +. + + + + +XtActionHookId XtAppAddActionHook + XtAppContext app + XtActionHookProc proc + XtPointer client_data + + + + + + + app + + + +Specifies the application context. + + + + + + proc + + + +Specifies the action hook procedure. + + + + + + client_data + + + +Specifies application-specific data to be passed to the action hook. + + + + + + + +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 +, +the action hook procedures will be called in reverse +order of registration just prior to invoking the action routine. + + + +Action hook procedures are removed automatically and the +XtActionHookId is +destroyed when the application context in which +they were added is destroyed. + + + +To remove an action hook procedure without destroying the application +context, use +. + + + + +void XtRemoveActionHook + XtActionHookId id + + + + + + + id + + + +Specifies the action hook id returned by +. + + + + + + + +removes the specified action hook procedure from +the list in which it was registered. + + + + + +Translation Tables + +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. + + + +As an example, the default behavior of Pushbutton is + + + + +Highlight on enter window. + + + + +Unhighlight on exit window. + + + + +Invert on left button down. + + + + +Call callbacks and reinvert on left button up. + + + + +The following illustrates Pushbutton's default translation table: + + +static String defaultTranslations = + "<EnterWindow>: Highlight()\\n\\ + <LeaveWindow>: Unhighlight()\\n\\ + <Btn1Down>: Set()\\n\\ + <Btn1Up>: Notify() Unset()"; + + +The tm_table field of the +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 +XtInheritTranslations +into tm_table. +In Core's class part initialization procedure, +the Intrinsics compile this translation table into an efficient internal form. +Then, at widget creation time, +this default translation table is +combined with the XtNtranslations +and XtNbaseTranslations resources; see +. + + + +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 +. + + + +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. + + +Event Sequences + +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. + + + +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. + + + + +Action Sequences + +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. + + + + +Multi-Click Time + +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 +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 +. +If no value is specified, the initial value is 200 milliseconds. + + + +To set the multi-click time dynamically, use +. + + + + +void XtSetMultiClickTime + Display *display + int time + + + + + + + display + + + +Specifies the display connection. + + + + + + time + + + +Specifies the multi-click time in milliseconds. + + + + + + + +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 +ButtonPress +events) must be less than the +multi-click time in order for the translation actions to be taken. + + + +To read the multi-click time, use +. + + + + +int XtGetMultiClickTime + Display *display + + + + + + + display + + + +Specifies the display connection. + + + + + + + +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. + + + + + +Translation Table Management + +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. + + + +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. + + + +Three Intrinsics functions support this merging: + + + + + + XtParseTranslationTable + + + Compiles a translation table. + + + + + XtAugmentTranslations + + + Merges a compiled translation table into a widget's + compiled translation table, ignoring any new translations that + conflict with existing translations. + + + + + + XtOverrideTranslations + + + Merges a compiled translation table into a widget's + compiled translation table, replacing any existing translations that + conflict with new translations. + + + + + + +To compile a translation table, use +. + + + + +XtTranslations XtParseTranslationTable + String table + + + + + + + table + + + +Specifies the translation table to compile. + + + + + + +The + +function compiles the translation table, provided in the format given +in Appendix B, into an opaque internal representation +of type +XtTranslations. +Note that if an empty translation table is required for any purpose, +one can be obtained by calling + +and passing an empty string. + + + +To merge additional translations into an existing translation table, use +. + + + + +void XtAugmentTranslations + Widget w + XtTranslations translations + + + + + + + w + + + +Specifies the widget into which the new translations are to be merged. Must be of class Core or any subclass thereof. + + + + + + translations + + + +Specifies the compiled translation table to merge in. + + + + + + +The + +function merges the new translations into the existing widget +translations, ignoring any +#replace, +#augment, +or +#override +directive that may have been specified +in the translation string. The translation table specified by +translations is not altered by this process. + +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. + + + +To overwrite existing translations with new translations, use +. + + + + +void XtOverrideTranslations + Widget w + XtTranslations translations + + + + + + + w + + + +Specifies the widget into which the new translations are to be merged. Must be of class Core or any subclass thereof. + + + + + + translations + + + +Specifies the compiled translation table to merge in. + + + + + + +The + +function merges the new translations into the existing widget +translations, ignoring any +#replace, +#augment, +or +#override +directive that may have been +specified in the translation string. The translation table +specified by translations is not altered by this process. + +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. + + + +To replace a widget's translations completely, use + +on the XtNtranslations resource and specify a compiled translation table +as the value. + + + +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. + + + +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 translations 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 translations 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. + + + +To completely remove existing translations, use +. + + + + +void XtUninstallTranslations + Widget w + + + + + + + w + + + +Specifies the widget from which the translations are to be removed. Must be of class Core or any subclass thereof. + + + + + + +The + +function causes the entire translation table for the widget to be removed. + + + + +Using Accelerators + +It is often desirable to be able to bind events in one widget to actions in +another. +In particular, +it is often useful to be able to invoke menu actions from the keyboard. +The Intrinsics provide a facility, called accelerators, that lets you +accomplish this. +An accelerator table is a translation table that is bound with its +actions in the context of a particular widget, the source widget. +The accelerator table can then be installed on one or more destination 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. + + + +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 +. + + + + +typedef void (*XtStringProc) + Widget w + String string + + + + + + + w + + + +Specifies the source widget that supplied the accelerators. + + + + + + string + + + +Specifies the string representation of the accelerators for this widget. + + + + + + +Accelerators can be specified in resource files, +and the string representation is the same as for a translation table. +However, +the interpretation of the +#augment +and +#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 +#augment, +which means that the accelerator translations have lower priority +than the destination translations. +The +#replace +directive is ignored for accelerator tables. + + + +To parse an accelerator table, use +. + + + + +XtAccelerators XtParseAcceleratorTable + String source + + + + + + + source + + + +Specifies the accelerator table to compile. + + + + + + +The + +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. + + + +To install accelerators from a widget on another widget, use +. + + + + +void XtInstallAccelerators + Widget destination + Widget source + + + + + + + destination + + + +Specifies the widget on which the accelerators are to be installed. Must be of class Core or any subclass thereof. + + + + + + source + + + +Specifies the widget from which the accelerators are to come. Must be of class Core or any subclass thereof. + + + + + + +The + +function installs the accelerators resource value from +source onto destination +by merging the source accelerators into the destination translations. +If the source display_accelerator field is non-NULL, + +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. + + + +As a convenience for installing all accelerators from a widget and all its +descendants onto one destination, use +. + + + + +void XtInstallAllAccelerators + Widget destination + Widget source + + + + + + + destination + + + +Specifies the widget on which the accelerators are to be installed. Must be of class Core or any subclass thereof. + + + + + + source + + + +Specifies the root widget of the widget tree +from which the accelerators are to come. Must be of class Core or any subclass thereof. + + + + + + +The + +function recursively descends the widget tree rooted at source +and installs the accelerators resource value +of each widget encountered onto destination. +A common use is to call + +and pass the application main window as the source. + + + + +KeyCode-to-KeySym Conversions + +The translation manager provides support for automatically translating +KeyCodes in incoming key events into KeySyms. +KeyCode-to-KeySym translator procedure pointers are of type +. + + + + +typedef void (*XtKeyProc) + Display *display + KeyCode keycode + Modifiers modifiers + Modifiers *modifiers_return + KeySym *keysym_return + + + + + + + display + + + +Specifies the display that the KeyCode is from. + + + + + + keycode + + + +Specifies the KeyCode to translate. + + + + + + modifiers + + + +Specifies the modifiers to the KeyCode. + + + + + + modifiers_return + + + +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. + + + + + + keysym_return + + + +Specifies a location in which to store the resulting KeySym. + + + + + + +This procedure takes a KeyCode and modifiers and produces a KeySym. +For any given key translator function and keyboard encoding, +modifiers_return will be a constant per KeyCode that indicates +the subset of all modifiers that are examined by the key translator +for that KeyCode. + + + +The KeyCode-to-KeySym translator procedure +must be implemented such that multiple calls with the same +display, keycode, and modifiers return the same +result until either a new case converter, an +, +is installed or a +MappingNotify +event is received. + + + +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. + + + +To return a pointer to the KeySym-to-KeyCode mapping table for a +particular display, use +. + + + + +KeySym *XtGetKeysymTable + Display *display + KeyCode *min_keycode_return + int *keysyms_per_keycode_return + + + + + + + display + + + +Specifies the display whose table is required. + + + + + + min_keycode_return + + + +Returns the minimum KeyCode valid for the display. + + + + + + keysyms_per_keycode_return + + + +Returns the number of KeySyms stored for each KeyCode. + + + + + + + +returns a pointer to the Intrinsics' copy of the +server's KeyCode-to-KeySym table. This table must not be modified. +There are keysyms_per_keycode_return KeySyms associated with each +KeyCode, located in the table with indices starting at index + + + (test_keycode - min_keycode_return) * keysyms_per_keycode_return + + +for KeyCode test_keycode. Any entries that have no KeySyms associated +with them contain the value +NoSymbol. +Clients should not cache the KeySym table but should call + +each time the value is +needed, as the table may change prior to dispatching each event. + + + +For more information on this table, see +Section 12.7 in +Xlib — C Language X Interface.. + + + +To register a key translator, use +. + + + + +void XtSetKeyTranslator + Display *display + XtKeyProc proc + + + + + + + display + + + +Specifies the display from which to translate the events. + + + + + + proc + + + +Specifies the procedure to perform key translations. + + + + + + +The + +function sets the specified procedure as the current key translator. +The default translator is +XtTranslateKey, +an + +that uses the Shift, Lock, numlock, and group modifiers +with the interpretations defined in X Window System Protocol, 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. + + + +To invoke the currently registered KeyCode-to-KeySym translator, +use +. + + + + +void XtTranslateKeycode + Display *display + KeyCode keycode + Modifiers modifiers + Modifiers *modifiers_return + KeySym *keysym_return + + + + + + + display + + + +Specifies the display that the KeyCode is from. + + + + + + keycode + + + +Specifies the KeyCode to translate. + + + + + + modifiers + + + +Specifies the modifiers to the KeyCode. + + + + + + modifiers_return + + + +Returns a mask that indicates the modifiers actually used +to generate the KeySym. + + + + + + keysym_return + + + +Returns the resulting KeySym. + + + + + + +The + +function passes the specified arguments +directly to the currently registered KeyCode-to-KeySym translator. + + + +To handle capitalization of nonstandard KeySyms, the Intrinsics allow +clients to register case conversion routines. +Case converter procedure pointers are of type +. + + + + +typedef void (*XtCaseProc) + Display *display + KeySym keysym + KeySym *lower_return + KeySym *upper_return + + + + + + + display + + + +Specifies the display connection for which the conversion is required. + + + + + + keysym + + + +Specifies the KeySym to convert. + + + + + + lower_return + + + +Specifies a location into which to store the lowercase equivalent for +the KeySym. + + + + + + upper_return + + + +Specifies a location into which to store the uppercase equivalent for +the KeySym. + + + + + + +If there is no case distinction, +this procedure should store the KeySym into both return values. + + + +To register a case converter, use +. + + + + +void XtRegisterCaseConverter + Display *display + XtCaseProc proc + KeySym start + KeySym stop + + + + + + + display + + + +Specifies the display from which the key events are to come. + + + + + + proc + + + +Specifies the + +to do the conversions. + + + + + + start + + + +Specifies the first KeySym for which this converter is valid. + + + + + + stop + + + +Specifies the last KeySym for which this converter is valid. + + + + + + +The + +registers the specified case converter. +The start and stop arguments provide the inclusive range of KeySyms +for which this converter is to be called. +The new converter overrides any previous converters for KeySyms in that range. +No interface exists to remove converters; +you need to register an identity converter. +When a new converter is registered, +the Intrinsics refresh the keyboard state if necessary. +The default converter understands case conversion for all +Latin KeySyms defined in X Window System Protocol, Appendix A. + + + +To determine uppercase and lowercase equivalents for a KeySym, use +. + + + + +void XtConvertCase + Display *display + KeySym keysym + KeySym *lower_return + KeySym *upper_return + + + + + + + display + + + +Specifies the display that the KeySym came from. + + + + + + keysym + + + +Specifies the KeySym to convert. + + + + + + lower_return + + + +Returns the lowercase equivalent of the KeySym. + + + + + + upper_return + + + +Returns the uppercase equivalent of the KeySym. + + + + + + +The + +function calls the appropriate converter and returns the results. +A user-supplied + +may need to use this function. + + + + +Obtaining a KeySym in an Action Procedure + +When an action procedure is invoked on a +KeyPress +or +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 +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. + + + +To retrieve the KeySym and modifiers that matched the final event +specification in the translation table entry, use +. + + + + +KeySym XtGetActionKeysym + XEvent *event + Modifiers *modifiers_return + + + + + + + event + + + +Specifies the event pointer passed to the action procedure by the Intrinsics. + + + + + + modifiers_return + + + +Returns the modifiers that caused the match, if non-NULL. + + + + + + +If + +is called after an action procedure has been +invoked by the Intrinsics and before that action procedure returns, and +if the event pointer has the same value as the event pointer passed to +that action routine, and if the event is a +KeyPress +or +KeyRelease +event, then + +returns the KeySym that matched the final +event specification in the translation table and, if modifiers_return +is non-NULL, the modifier state actually used to generate this KeySym; +otherwise, if the event is a +KeyPress +or +KeyRelease +event, then + +calls + +and returns the results; +else it returns +NoSymbol +and does not examine modifiers_return. + + + +Note that if an action procedure invoked by the Intrinsics +invokes a subsequent action procedure (and so on) via +, +the nested action procedure may also call + +to retrieve the Intrinsics' KeySym and modifiers. + + + + +KeySym-to-KeyCode Conversions + +To return the list of KeyCodes that map to a particular KeySym in +the keyboard mapping table maintained by the Intrinsics, use +. + + + + +void XtKeysymToKeycodeList + Display *display + KeySym keysym + KeyCode **keycodes_return + Cardinal *keycount_return + + + + + + + display + + + +Specifies the display whose table is required. + + + + + + keysym + + + +Specifies the KeySym for which to search. + + + + + + keycodes_return + + + +Returns a list of KeyCodes that have keysym +associated with them, or NULL if keycount_return is 0. + + + + + + keycount_return + + + +Returns the number of KeyCodes in the keycode list. + + + + + + +The + +procedure returns all the KeyCodes that have keysym +in their entry for the keyboard mapping table associated with display. +For each entry in the +table, the first four KeySyms (groups 1 and 2) are interpreted as +specified by X Window System Protocol, Section 5. If no KeyCodes map to the +specified KeySym, keycount_return is zero and *keycodes_return is NULL. + + + +The caller should free the storage pointed to by keycodes_return using + +when it is no longer useful. If the caller needs to examine +the KeyCode-to-KeySym table for a particular KeyCode, it should call +. + + + + +Registering Button and Key Grabs for Actions + +To register button and key grabs for a widget's window according to the +event bindings in the widget's translation table, use +. + + + + +void XtRegisterGrabAction + XtActionProc action_proc + Boolean owner_events + unsigned int event_mask + int pointer_mode + + + + + + + action_proc + + + +Specifies the action procedure to search for in translation tables. + + + + + + owner_events + + + + + + + + + event_mask + + + + + + + + + pointer_mode + + + + + + + + keyboard_mode + + + +Specify arguments to + +or +. + + + + + + + +adds the specified action_proc 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 +ButtonPress +or +KeyPress +events as the only or final event +in a sequence, the Intrinsics will call + +or + +for the widget with every button or KeyCode which maps to the +event detail field, passing the specified owner_events, event_mask, +pointer_mode, and keyboard_mode. For +ButtonPress +events, the modifiers +specified in the grab are determined directly from the translation +specification and confine_to and cursor are specified as +None. +For +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 + +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 event_mask 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 +ButtonPress +and +KeyPress +events, don't-care modifiers are ignored unless the translation entry +explicitly specifies ``Any'' in the modifiers field. + + + +If the specified action_proc 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. + + + +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 + +or +. + + + + +Invoking Actions Directly + +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 +. + + + + +void XtCallActionProc + Widget widget + String action + XEvent *event + String *params + Cardinal num_params + + + + + + + widget + + + +Specifies the widget in which the action is to be invoked. Must be of class Core or any subclass thereof. + + + + + + action + + + +Specifies the name of the action routine. + + + + + + event + + + +Specifies the contents of the event passed to the action routine. + + + + + + params + + + +Specifies the contents of the params passed to the action routine. + + + + + + num_params + + + +Specifies the number of entries in params. + + + + + + + +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 +. +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 event, params, and num_params 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, + +generates a warning message and returns. + + + + +Obtaining a Widget's Action List + +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 +actions field, use +. + + + + +void XtGetActionList + WidgetClass widget_class + XtActionList *actions_return + Cardinal *num_actions_return + + + + + + + widget_class + + + +Specifies the widget class whose actions are to be returned. + + + + + + actions_return + + + +Returns the action list. + + + + + + num_actions_return + + + +Returns the number of action procedures declared by the class. + + + + + + + +returns the action table defined by the specified +widget class. This table does not include actions defined by the +superclasses. If widget_class is not initialized, or is not +coreWidgetClass +or a subclass thereof, or if the class does not define any actions, +*actions_return will be NULL and *num_actions_return +will be zero. +If *actions_return is non-NULL the client is responsible for freeing +the table using + +when it is no longer needed. + + + -- cgit v1.2.3