home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xt / CH10 < prev    next >
Encoding:
Text File  |  1991-08-27  |  43.9 KB  |  1,420 lines

  1. .\" $XConsortium: CH10,v 1.8 91/08/26 13:38:16 swick Exp $
  2. .\"
  3. .\" Copyright 1985, 1986, 1987, 1988, 1991
  4. .\" Massachusetts Institute of Technology, Cambridge, Massachusetts,
  5. .\" and Digital Equipment Corporation, Maynard, Massachusetts.
  6. .\"
  7. .\" Permission to use, copy, modify and distribute this documentation for any
  8. .\" purpose and without fee is hereby granted, provided that the above copyright
  9. .\" notice appears in all copies and that both that copyright notice and this
  10. .\" permission notice appear in supporting documentation, and that the name of
  11. .\" M.I.T. or Digital not be used in in advertising or publicity pertaining
  12. .\" to distribution of the software without specific, written prior permission.
  13. .\" M.I.T and Digital makes no representations about the suitability of the
  14. .\" software described herein for any purpose.
  15. .\" It is provided ``as is'' without express or implied warranty.
  16. \&
  17. .sp 1
  18. .ce 3
  19. \s+1\fBChapter 10\fP\s-1
  20.  
  21. \s+1\fBTranslation Management\s-1 
  22. .sp 2
  23. .nr H1 10
  24. .nr H2 0
  25. .nr H3 0
  26. .nr H4 0
  27. .nr H5 0
  28. .LP
  29. .XS
  30. Chapter 10 \- Translation Management 
  31. .XE
  32. Except under unusual circumstances,
  33. widgets do not hardwire the mapping of user events into widget behavior
  34. by using the event manager.
  35. Instead, they provide a default mapping of events into behavior
  36. that you can override.
  37. .LP
  38. The translation manager provides an interface to specify and manage the
  39. mapping of X event sequences into widget-supplied functionality,
  40. for example, calling procedure \fIAbc\fP when the \fIy\fP key 
  41. is pressed.
  42. .LP
  43. The translation manager uses two kinds of tables to perform translations:
  44. .IP \(bu 5
  45. The action tables, which are in the widget class structure,
  46. specify the mapping of externally available procedure name strings
  47. to the corresponding procedure implemented by the widget class.
  48. .IP \(bu 5
  49. A translation table, which is in the widget class structure,
  50. specifies the mapping of event sequences to procedure name strings.
  51. .LP
  52. You can override the translation table in the class structure 
  53. for a specific widget instance by supplying a different translation table
  54. for the widget instance.  The resources
  55. XtNtranslations and XtNbaseTranslations are used to modify the class
  56. default translation table; see Section 10.3.
  57.  
  58. .NH 2
  59. Action Tables
  60. .XS
  61. \fB\*(SN Action Tables\fP
  62. .XE
  63. .LP
  64. All widget class records contain an action table,
  65. an array of
  66. .PN XtActionsRec
  67. entries.
  68. In addition,
  69. an application can register its own action tables with the translation manager
  70. so that the translation tables it provides to widget instances can access
  71. application functionality directly.
  72. The translation action procedure pointer is of type
  73. .PN XtActionProc .
  74. .IN "action_proc procedure" "" "@DEF@"
  75. .IN "XtActionProc" "" "@DEF@"
  76. .FD 0
  77. typedef void (*XtActionProc)(Widget, XEvent*, String*, Cardinal*);
  78. .br
  79.       Widget \fIw\fP;
  80. .br
  81.       XEvent *\fIevent\fP;
  82. .br
  83.       String *\fIparams\fP;
  84. .br
  85.       Cardinal *\fInum_params\fP;
  86. .FN
  87. .IP \fIw\fP 1i
  88. Specifies the widget that caused the action to be called.
  89. .IP \fIevent\fP 1i
  90. Specifies the event that caused the action to be called.
  91. If the action is called after a sequence of events,
  92. then the last event in the sequence is used.
  93. .IP \fIparams\fP 1i
  94. Specifies a pointer to the list of strings that were specified
  95. in the translation table as arguments to the action, or NULL.
  96. .IP \fInum_params\fP 1i
  97. Specifies the number of entries in \fIparams\fP.
  98. .IN "XtActionsRec"
  99. .IN "XtActionList"
  100. .LP
  101. .Ds 0
  102. .TA .5i 3i
  103. .ta .5i 3i
  104. typedef struct _XtActionsRec {
  105.     String string;
  106.     XtActionProc proc;
  107. } XtActionsRec, *XtActionList;
  108. .De
  109. The \fIstring\fP field is the name used in translation tables to access
  110. the procedure.
  111. The \fIproc\fP field is a pointer to a procedure that implements
  112. the functionality.
  113.  
  114. When the action list is specified as the
  115. .PN CoreClassPart
  116. \fIactions\fP field the string pointed to by \fIstring\fP must be
  117. permanently allocated prior to or during the execution of the class
  118. initialization procedure and must not be subsequently deallocated.
  119.  
  120. .LP
  121. Action procedures should not assume that the widget in which they
  122. are invoked is realized; an accelerator specification can cause
  123. an action procedure to be called for a widget that does not yet
  124. have a window.  Widget writers should also note which of a widget's
  125. callback lists are invoked from action procedures and warn clients
  126. not to assume the widget is realized in those callbacks.
  127. .LP
  128. For example, a Pushbutton widget has procedures to take the following actions:
  129. .IP \(bu 5
  130. Set the button to indicate it is activated.
  131. .IP \(bu 5
  132. Unset the button back to its normal mode.
  133. .IP \(bu 5
  134. Highlight the button borders.
  135. .IP \(bu 5
  136. Unhighlight the button borders.
  137. .IP \(bu 5
  138. Notify any callbacks that the button has been activated.
  139. .LP
  140. The action table for the Pushbutton widget class makes these functions
  141. available to translation tables written for Pushbutton or any subclass.
  142. The string entry is the name used in translation tables.
  143. The procedure entry (usually spelled identically to the string)
  144. is the name of the C procedure that implements that function:
  145. .LP
  146. .IN "Action Table"
  147. .Ds
  148. .TA .5i 1.5i
  149. .ta .5i 1.5i
  150. XtActionsRec actionTable[] = {
  151.     {"Set",    Set},
  152.     {"Unset",    Unset},
  153.     {"Highlight",    Highlight},
  154.     {"Unhighlight",    Unhighlight}
  155.     {"Notify",    Notify},
  156. };
  157. .De
  158. .LP
  159. The \*(xI reserve all action names and parameters starting with
  160. the characters ``Xt'' for future standard enhancements.  Users,
  161. applications, and widgets should not declare action names or pass
  162. parameters starting with these characters except to invoke specified
  163. built-in \*(xI functions.
  164.  
  165. .NH 3
  166. Action Table Registration
  167. .XS
  168. \fB\*(SN Action Table Registration\fP
  169. .XE
  170. .LP
  171. .IN "actions"
  172. The \fIactions\fP and \fInum_actions\fP fields of
  173. .PN CoreClassPart
  174. specify the actions implemented by a widget class.  These are
  175. automatically registered with the \*(xI when the class is initialized
  176. and must be allocated in writable storage prior to Core class_part
  177. initialization, and never deallocated.  To save memory and optimize
  178. access, the \*(xI may overwrite the storage in order to compile the
  179. list into an internal representation.
  180. .sp
  181.  
  182. .LP
  183. To declare an action table within an application
  184. and register it with the translation manager, use
  185. .PN XtAppAddActions .
  186. .IN "XtAppAddActions" "" "@DEF@"
  187. .FD 0
  188. void XtAppAddActions(\fIapp_context\fP, \fIactions\fP, \fInum_actions\fP)
  189. .br
  190.       XtAppContext \fIapp_context\fP;
  191. .br
  192.       XtActionList \fIactions\fP;
  193. .br
  194.       Cardinal \fInum_actions\fP;
  195. .FN
  196. .IP \fIapp_context\fP 1i
  197. Specifies the application context.
  198. .IP \fIactions\fP 1i
  199. Specifies the action table to register.
  200. .IP \fInum_actions\fP 1i
  201. Specifies the number of entries in this action table.
  202. .LP
  203. If more than one action is registered with the same name, 
  204. the most recently registered action is used.
  205. If duplicate actions exist in an action table,
  206. the first is used.
  207. The \*(xI register an action table containing
  208. .PN XtMenuPopup
  209. and
  210. .PN XtMenuPopdown
  211. as part of
  212. .PN XtCreateApplicationContext .
  213.  
  214. .NH 3
  215. Action Names to Procedure Translations
  216. .XS
  217. \fB\*(SN Action Names to Procedure Translations\fP
  218. .XE
  219. .LP
  220. The translation manager uses a simple algorithm to resolve the name of
  221. a procedure specified in a translation table into the
  222. actual procedure specified
  223. in an action table.
  224. When the widget
  225. is realized, the translation manager
  226. performs a search for the name in the following tables, in order:
  227. .IP \(bu 5
  228. The widget's class and all superclass action tables, in subclass-to-superclass
  229. order.
  230. .IP \(bu 5
  231. The parent's class and all superclass action tables, in subclass-to-superclass
  232. order, then on up the ancestor tree.
  233. .IP \(bu 5
  234. The action tables registered with
  235. .PN XtAppAddActions
  236. and
  237. .PN XtAddActions
  238. from the most recently added table to the oldest table.
  239. .LP
  240. As soon as it finds a name,
  241. the translation manager stops the search.
  242. If it cannot find a name,
  243. the translation manager generates a warning message.
  244.  
  245. .NH 3
  246. Action Hook Registration
  247. .XS
  248. \fB\*(SN Action Hook Registration\fP
  249. .XE
  250. .LP
  251. An application can specify a procedure that will be called just before
  252. every action routine is dispatched by the translation manager.  To do
  253. so, the application supplies a procedure pointer of type
  254. .PN XtActionHookProc .
  255. .IN "XtActionHookProc" "" "@DEF@"
  256. .FD 0
  257. typedef void (*XtActionHookProc)(Widget, XtPointer, String, XEvent*, \
  258. String*, Cardinal*);
  259. .br
  260.       Widget \fIw\fP;
  261. .br
  262.       XtPointer \fIclient_data\fP;
  263. .br
  264.       String \fIaction_name\fP;
  265. .br
  266.       XEvent* \fIevent\fP;
  267. .br
  268.       String* \fIparams\fP;
  269. .br
  270.       Cardinal* \fInum_params\fP;
  271. .FN
  272. .IP \fIw\fP 1i
  273. Specifies the widget whose action is about to be dispatched.
  274. .IP \fIclient_data\fP 1i
  275. Specifies the application-specific closure that was passed to
  276. .PN XtAppAddActionHook.
  277. .IP \fIaction_name\fP 1i
  278. Specifies the name of the action to be dispatched.
  279. .IP \fIevent\fP 1i
  280. Specifies the event argument that will be passed to the action routine.
  281. .IP \fIparams\fP 1i
  282. Specifies the action parameters that will be passed to the action routine.
  283. .IP \fInum_params\fP 1i
  284. Specifies the number of entries in \fIparams\fP.
  285. .LP
  286. Action hooks should not modify any of the data pointed to by the
  287. arguments other than the \fIclient_data\fP argument.
  288. .sp
  289. .LP
  290. To add an action hook, use
  291. .PN XtAppAddActionHook .
  292. .IN "XtAppAddActionHook" "" "@DEF@"
  293. .FD 0
  294. XtActionHookId XtAppAddActionHook(\fIapp\fP, \fIproc\fP, \fIclient_data\fP)
  295. .br
  296.       XtAppContext \fIapp\fP;
  297. .br
  298.       XtActionHookProc \fIproc\fP;
  299. .br
  300.       XtPointer \fIclient_data\fP;
  301. .FN
  302. .IP \fIapp\fP 1i
  303. Specifies the application context.
  304. .IP \fIproc\fP 1i
  305. Specifies the action hook procedure.
  306. .IP \fIclient_data\fP 1i
  307. Specifies application-specific data to be passed to the action hook.
  308. .LP
  309. .PN XtAppAddActionHook
  310. adds the specified procedure to the front of a list
  311. maintained in the application context.  In the future, when an action
  312. routine is about to be invoked for any widget in this application
  313. context, either through the translation manager or via
  314. .PN XtCallActionProc ,
  315. the action hook procedures will be called in reverse
  316. order of registration just prior to invoking the action routine.
  317. .LP
  318. Action hook procedures are removed automatically and the
  319. .PN XtActionHookId s
  320. destroyed when the application context in which
  321. they were added is destroyed.
  322. .sp
  323. .LP
  324. To remove an action hook procedure without destroying the application
  325. context, use
  326. .PN XtRemoveActionHook .
  327. .IN "XtRemoveActionHook" "" "@DEF@"
  328. .FD 0
  329. void XtRemoveActionHook(\fIid\fP)
  330. .br
  331.       XtActionHookId \fIid\fP;
  332. .FN
  333. .IP \fIid\fP 1i
  334. Specifies the action hook id returned by
  335. .PN XtAppAddActionHook .
  336. .LP
  337. .PN XtRemoveActionHook
  338. removes the specified action hook procedure from
  339. the list in which it was registered.
  340.  
  341. .NH 2
  342. Translation Tables
  343. .XS
  344. \fB\*(SN Translation Tables\fP
  345. .XE
  346. .LP
  347. All widget instance records contain a translation table,
  348. which is a resource with a default value specified elsewhere in the
  349. class record.
  350. A translation table specifies what action procedures are invoked for
  351. an event or a sequence of events.
  352. A translation table
  353. is a string containing a list of translations from an event sequence
  354. into one or more action procedure calls.
  355. The translations are separated from one another by newline characters
  356. (ASCII LF).
  357. The complete syntax of translation tables is specified in Appendix B.
  358. .LP
  359. As an example, the default behavior of Pushbutton is
  360. .IP \(bu 5
  361. Highlight on enter window.
  362. .IP \(bu 5
  363. Unhighlight on exit window.
  364. .IP \(bu 5
  365. Invert on left button down.
  366. .IP \(bu 5
  367. Call callbacks and reinvert on left button up.
  368. .LP
  369. The following illustrates Pushbutton's default translation table:
  370. .LP
  371. .IN "Translation tables"
  372. .Ds
  373. .TA .5i 1.5i
  374. .ta .5i 1.5i
  375. static String defaultTranslations =
  376.     "<EnterWindow>:    Highlight()\\n\\
  377.     <LeaveWindow>:    Unhighlight()\\n\\
  378.     <Btn1Down>:    Set()\\n\\
  379.     <Btn1Up>:    Notify() Unset()";
  380. .De
  381. .LP
  382. The \fItm_table\fP field of the
  383. .PN CoreClassPart
  384. should be filled in at class initialization time with
  385. the string containing the class's default translations.
  386. If a class wants to inherit its superclass's translations,
  387. it can store the special value
  388. .PN XtInheritTranslations
  389. into \fItm_table\fP.
  390. In Core's class part initialization procedure,
  391. the \*(xI compile this translation table into an efficient internal form.
  392. Then, at widget creation time,
  393. this default translation table is
  394. combined with the XtNtranslations
  395. and XtNbaseTranslations resources; see Section 10.3.
  396. .LP
  397. The resource conversion mechanism automatically compiles
  398. string translation tables that are specified in the resource database.
  399. If a client uses translation tables that are not retrieved via a
  400. resource conversion,
  401. it must compile them itself using
  402. .PN XtParseTranslationTable .
  403. .LP
  404. The \*(xI use the compiled form of the translation table to register the
  405. necessary events with the event manager.
  406. Widgets need do nothing other than specify the action and translation tables
  407. for events to be processed by the translation manager.
  408.  
  409. .NH 3
  410. Event Sequences
  411. .XS
  412. \fB\*(SN Event Sequences\fP
  413. .XE
  414. .LP
  415. An event sequence is a comma-separated list of X event descriptions 
  416. that describes a specific sequence of X events to map to a set of 
  417. program actions. 
  418. Each X event description consists of three parts: 
  419. The X event type, a prefix consisting of the X modifier bits, and
  420. an event-specific suffix.
  421. .LP
  422. Various abbreviations are supported to make translation tables easier
  423. to read.  The events must match incoming events in left-to-right order
  424. to trigger the action sequence.
  425.  
  426. .NH 3
  427. Action Sequences
  428. .XS
  429. \fB\*(SN Action Sequences\fP
  430. .XE
  431. .LP
  432. Action sequences specify what program or widget actions to take in response to
  433. incoming X events. An action sequence consists of space-separated
  434. action procedure call specifications.
  435. Each action procedure call consists of the name of an action procedure and a
  436. parenthesized list of zero or more comma-separated
  437. string parameters to pass to that procedure.
  438. The actions are invoked in left-to-right order as specified in the
  439. action sequence.
  440.  
  441. .NH 3
  442. Multi-click Time
  443. .XS
  444. \fB\*(SN Multi-click Time\fP
  445. .XE
  446. .LP
  447. Translation table entries may specify actions that are taken when two
  448. or more identical events occur consecutively within a short time
  449. interval, called the multi-click time.  The multi-click time value may
  450. be specified as an application resource with name ``multiClickTime'' and
  451. .IN "multiClickTime" "" "@DEF@"
  452. .IN "Resources" "multiClickTime"
  453. class ``MultiClickTime'' and may also be modified dynamically by the
  454. application.  The multi-click time is unique for each Display value and
  455. is retrieved from the resource database by
  456. .PN XtDisplayInitialize .
  457. If no value is specified, the initial value is 200 milliseconds.
  458. .sp
  459. .LP
  460. To set the multi-click time dynamically, use
  461. .PN XtSetMultiClickTime .
  462. .IN "XtSetMultiClickTime" "" "@DEF@"
  463. .FD 0
  464. void XtSetMultiClickTime(\fIdisplay\fP, \fItime\fP)
  465. .br
  466.       Display *\fIdisplay\fP;
  467. .br
  468.       int \fItime\fP;
  469. .FN
  470. .IP \fIdisplay\fP 1i
  471. Specifies the display connection.
  472. .IP \fItime\fP 1i
  473. Specifies the multi-click time in milliseconds.
  474. .LP
  475. .PN XtSetMultiClickTime
  476. sets the time interval used by the translation
  477. manager to determine when multiple events are interpreted as a
  478. repeated event.  When a repeat count is specified in a translation
  479. entry, the interval between the timestamps in each pair of repeated
  480. events (e.g., between two
  481. .PN ButtonPress
  482. events) must be less than the
  483. multi-click time in order for the translation actions to be taken. 
  484. .sp
  485. .LP
  486. To read the multi-click time, use
  487. .PN XtGetMultiClickTime .
  488. .IN "XtGetMultiClickTime" "" "@DEF@"
  489. .FD 0
  490. int XtGetMultiClickTime(\fIdisplay\fP)
  491. .br
  492.       Display *\fIdisplay\fP;
  493. .FN
  494. .IP \fIdisplay\fP 1i
  495. Specifies the display connection.
  496. .LP
  497. .PN XtGetMultiClickTime
  498. returns the time in milliseconds that the
  499. translation manager uses to determine if multiple events are to be
  500. interpreted as a repeated event for purposes of matching a translation
  501. entry containing a repeat count.
  502.  
  503. .NH 2
  504. Translation Table Management
  505. .XS
  506. \fB\*(SN Translation Table Management\fP
  507. .XE
  508. .LP
  509. Sometimes an application needs to merge
  510. its own translations with a widget's translations.
  511. For example, a window manager provides functions to move a window.
  512. The window manager wishes to bind this operation to a specific
  513. pointer button in the title bar without the possibility of user
  514. override and bind it to other buttons that may be overridden by the user.
  515. .LP
  516. To accomplish this,
  517. the window manager should first create the title bar
  518. and then should merge the two translation tables into
  519. the title bar's translations.
  520. One translation table contains the translations that the window manager
  521. wants only if the user has not specified a translation for a particular event
  522. or event sequence (i.e., those that may be overridden).
  523. The other translation table contains the translations that the
  524. window manager wants regardless of what the user has specified.
  525. .LP
  526. Three \*(xI functions support this merging:
  527. .TS
  528. lw(2i) lw(3.75i).
  529. T{
  530. .PN XtParseTranslationTable
  531. T}    T{
  532. Compiles a translation table.
  533. T}
  534. .sp
  535. T{
  536. .PN XtAugmentTranslations
  537. T}    T{
  538. Merges a compiled translation table into a widget's
  539. compiled translation table, ignoring any new translations that
  540. conflict with existing translations.
  541. T}
  542. .sp
  543. T{
  544. .PN XtOverrideTranslations
  545. T}    T{
  546. Merges a compiled translation table into a widget's
  547. compiled translation table, replacing any existing translations that
  548. conflict with new translations.
  549. T}
  550. .TE
  551. .sp
  552. .LP
  553. To compile a translation table, use
  554. .PN XtParseTranslationTable .
  555. .IN "XtParseTranslationTable" "" "@DEF@"
  556. .FD 0
  557. XtTranslations XtParseTranslationTable(\fItable\fP)
  558. .br
  559.       String \fItable\fP;
  560. .FN
  561. .IP \fItable\fP 1i
  562. Specifies the translation table to compile.
  563. .LP
  564. The
  565. .PN XtParseTranslationTable
  566. function compiles the translation table, provided in the format given
  567. in Appendix B, into an opaque internal representation
  568. of type
  569. .PN XtTranslations .
  570. Note that if an empty translation table is required for any purpose,
  571. one can be obtained by calling
  572. .PN XtParseTranslationTable
  573. and passing an empty string.
  574. .sp
  575. .LP
  576. To merge additional translations into an existing translation table, use
  577. .PN XtAugmentTranslations .
  578. .IN "XtAugmentTranslations" "" "@DEF@"
  579. .FD 0
  580. void XtAugmentTranslations(\fIw\fP, \fItranslations\fP)
  581. .br
  582.       Widget \fIw\fP;
  583. .br
  584.       XtTranslations \fItranslations\fP;
  585. .FN
  586. .IP \fIw\fP 1i
  587. Specifies the widget into which the new translations are to be merged.  \*(cI
  588. .IP \fItranslations\fP 1i
  589. Specifies the compiled translation table to merge in.
  590. .LP
  591. The
  592. .PN XtAugmentTranslations
  593. function merges the new translations into the existing widget
  594. translations, ignoring any
  595. .PN #replace ,
  596. .PN #augment ,
  597. or
  598. .PN #override
  599. directive that may have been specified
  600. in the translation string.  The translation table specified by
  601. \fItranslations\fP is not altered by this process.
  602. .PN XtAugmentTranslations
  603. logically appends the string representation of the new translations to
  604. the string representation of the widget's current translations and reparses
  605. the result with no warning messages about duplicate left-hand sides, then
  606. stores the result back into the widget instance; i.e.,
  607. if the new translations contain an event or event sequence that
  608. already exists in the widget's translations,
  609. the new translation is ignored.
  610. .sp
  611. .LP
  612. To overwrite existing translations with new translations, use
  613. .PN XtOverrideTranslations .
  614. .IN "XtOverrideTranslations" "" "@DEF@"
  615. .FD 0
  616. void XtOverrideTranslations(\fIw\fP, \fItranslations\fP)
  617. .br
  618.       Widget \fIw\fP;
  619. .br
  620.       XtTranslations \fItranslations\fP;
  621. .FN
  622. .IP \fIw\fP 1i
  623. Specifies the widget into which the new translations are to be merged. \*(cI
  624. .IP \fItranslations\fP 1i
  625. Specifies the compiled translation table to merge in.
  626. .LP
  627. The
  628. .PN XtOverrideTranslations
  629. function merges the new translations into the existing widget
  630. translations, ignoring any
  631. .PN #replace ,
  632. .PN #augment ,
  633. or
  634. .PN #override
  635. directive that may have been
  636. specified in the translation string.  The translation table
  637. specified by \fItranslations\fP is not altered by this process.
  638. .PN XtOverrideTranslations
  639. logically appends the string representation of the widget's current
  640. translations to the string representation of the new translations and
  641. reparses the result with no warning messages about duplicate left-hand
  642. sides, then stores the result back into the widget instance; i.e.,
  643. if the new translations contain an event or event sequence that
  644. already exists in the widget's translations,
  645. the new translation overrides the widget's translation.
  646. .LP
  647. To replace a widget's translations completely, use
  648. .PN XtSetValues
  649. on the XtNtranslations resource and specify a compiled translation table
  650. as the value.
  651. .sp
  652. .LP
  653. To make it possible for users to easily modify translation tables in their
  654. resource files, 
  655. the string-to-translation-table resource type converter
  656. allows the string to specify whether the table should replace,
  657. augment, or override any
  658. existing translation table in the widget. 
  659. To specify this,
  660. a sharp sign (#) is given as the first character of the table 
  661. followed by one of the keywords ``replace'', ``augment'', or
  662. ``override'' to indicate
  663. whether to replace, augment, or override the existing table.
  664. The replace or merge
  665. operation is performed during the
  666. Core
  667. instance initialization and
  668. during the
  669. Core
  670. set_values invocation.
  671. Each merge operation produces a new
  672. translation resource value; if the original tables were shared by
  673. other widgets, they are unaffected.  If no directive is
  674. specified, ``#replace'' is assumed.
  675.  
  676. At instance initialization
  677. the XtNtranslations resource is first fetched.  Then, if it was
  678. not specified or did not contain ``#replace'', the
  679. resource database is searched for the resource XtNbaseTranslations.
  680. If XtNbaseTranslations is found it is merged into the widget class
  681. translation table.  Then the widget \fItranslations\fP field is
  682. merged into the result, or into the class translation table if
  683. XtNbaseTranslations was not found.  This final table is then
  684. stored into the widget \fItranslations\fP field.  If the XtNtranslations
  685. resource specified ``#replace'' no merge is done.
  686. If neither XtNbaseTranslations or XtNtranslations are specified,
  687. the class translation table is copied into the widget instance.
  688.  
  689. .sp
  690. .LP
  691. To completely remove existing translations, use
  692. .PN XtUninstallTranslations .
  693. .IN "XtUninstallTranslations" "" "@DEF@"
  694. .FD 0
  695. void XtUninstallTranslations(\fIw\fP)
  696. .br
  697.       Widget \fIw\fP;
  698. .FN
  699. .IP \fIw\fP 1i
  700. Specifies the widget from which the translations are to be removed.   \*(cI
  701. .LP
  702. The
  703. .PN XtUninstallTranslations
  704. function causes the entire translation table for the widget to be removed.
  705.  
  706. .NH 2
  707. Using Accelerators
  708. .XS
  709. \fB\*(SN Using Accelerators\fP
  710. .XE
  711. .LP
  712. It is often desirable to be able to bind events in one widget to actions in
  713. another.
  714. In particular,
  715. it is often useful to be able to invoke menu actions from the keyboard.
  716. The \*(xI provide a facility, called accelerators, that lets you 
  717. accomplish this.
  718. .IN "Accelerator" "" "@DEF@"
  719. An accelerator table is a translation table that is bound with its
  720. actions in the context of a particular widget, the \fIsource\fP widget.
  721. The accelerator table can then be installed on one or more \fIdestination\fP widgets.
  722. When an event sequence in the destination widget would cause an
  723. accelerator action to be taken, and if the source widget is sensitive,
  724. the actions are executed as though triggered by the same event sequence
  725. in the accelerator source
  726. widget.  The event is
  727. passed to the action procedure without modification.  The action
  728. procedures used within accelerators must not assume that the source
  729. widget is realized nor that any fields of the event are in reference
  730. to the source widget's window if the widget is realized.
  731. .LP
  732. Each widget instance contains that widget's exported accelerator table
  733. as a resource.
  734. Each class of widget exports a method that takes a
  735. displayable string representation of the accelerators
  736. so that widgets can display their current accelerators.
  737. The representation is the accelerator table in canonical
  738. translation table form (see Appendix B).
  739. The display_accelerator procedure pointer is of type
  740. .PN XtStringProc .
  741. .IN "display_accelerator procedure" "" "@DEF@"
  742. .IN "XtStringProc" "" "@DEF@"
  743. .FD 0
  744. typedef void (*XtStringProc)(Widget, String);
  745. .br
  746.       Widget \fIw\fP;
  747. .br
  748.       String \fIstring\fP;
  749. .FN
  750. .IP \fIw\fP 1i
  751. Specifies the source widget that supplied the accelerators.
  752. .IP \fIstring\fP 1i
  753. Specifies the string representation of the accelerators for this widget.
  754. .LP
  755. Accelerators can be specified in resource files, 
  756. and the string representation is the same as for a translation table.
  757. However,
  758. the interpretation of the
  759. .PN #augment
  760. and
  761. .PN #override
  762. directives applies to
  763. what will happen when the accelerator is installed;
  764. that is, whether or not the accelerator translations will override the
  765. translations in the destination widget.
  766. The default is
  767. .PN #augment ,
  768. which means that the accelerator translations have lower priority
  769. than the destination translations.
  770. The
  771. .PN #replace
  772. directive is ignored for accelerator tables.
  773. .sp
  774. .LP
  775. To parse an accelerator table, use
  776. .PN XtParseAcceleratorTable .
  777. .IN "XtParseAcceleratorTable" "" "@DEF@"
  778. .FD 0
  779. XtAccelerators XtParseAcceleratorTable(\fIsource\fP)
  780. .br
  781.       String \fIsource\fP;
  782. .FN
  783. .IP \fIsource\fP 1i
  784. Specifies the accelerator table to compile.
  785. .LP
  786. The
  787. .PN XtParseAcceleratorTable
  788. function compiles the accelerator table into an opaque internal representation.
  789. The client
  790. should set the XtNaccelerators resource of
  791. each widget that is to be activated by these translations
  792. to the returned value.
  793. .sp
  794. .LP
  795. To install accelerators from a widget on another widget, use
  796. .PN XtInstallAccelerators .
  797. .IN "XtInstallAccelerators" "" "@DEF@"
  798. .FD 0
  799. void XtInstallAccelerators(\fIdestination\fP, \fIsource\fP)
  800. .br
  801.       Widget \fIdestination\fP;
  802. .br
  803.       Widget \fIsource\fP;
  804. .FN
  805. .IP \fIdestination\fP 1i
  806. Specifies the widget on which the accelerators are to be installed.  \*(cI
  807. .IP \fIsource\fP 1i
  808. Specifies the widget from which the accelerators are to come.  \*(cI
  809. .LP
  810. The
  811. .PN XtInstallAccelerators
  812. function installs the \fIaccelerators\fP resource value from
  813. \fIsource\fP onto \fIdestination\fP
  814. by merging the the source accelerators into the destination translations.
  815. If the source \fIdisplay_accelerator\fP field is non-NULL, 
  816. .PN XtInstallAccelerators
  817. calls it with the source widget and a string representation 
  818. of the accelerator table,
  819. which indicates that its accelerators have been installed 
  820. and that it should display them appropriately.
  821. The string representation of the accelerator table is its
  822. canonical translation table representation.
  823. .sp
  824. .LP
  825. As a convenience for installing all accelerators from a widget and all its
  826. descendants onto one destination, use
  827. .PN XtInstallAllAccelerators .
  828. .IN "XtInstallAllAccelerators" "" "@DEF@"
  829. .FD 0
  830. void XtInstallAllAccelerators(\fIdestination\fP, \fIsource\fP)
  831. .br
  832.       Widget \fIdestination\fP;
  833. .br
  834.       Widget \fIsource\fP;
  835. .FN
  836. .IP \fIdestination\fP 1i
  837. Specifies the widget on which the accelerators are to be installed.  \*(cI
  838. .IP \fIsource\fP 1i
  839. Specifies the root widget of the widget tree
  840. from which the accelerators are to come.  \*(cI
  841. .LP
  842. The
  843. .PN XtInstallAllAccelerators
  844. function recursively descends the widget tree rooted at \fIsource\fP 
  845. and installs the accelerators resource value
  846. of each widget encountered onto \fIdestination\fP.
  847. A common use is to call
  848. .PN XtInstallAllAccelerators
  849. and pass the application main window as the source.
  850.  
  851. .NH 2
  852. KeyCode-to-KeySym Conversions
  853. .XS
  854. \*(SN KeyCode-to-KeySym Conversions
  855. .XE
  856. .LP
  857. The translation manager provides support for automatically translating
  858. KeyCodes in incoming key events into KeySyms.
  859. KeyCode-to-KeySym translator procedure pointers are of type
  860. .PN XtKeyProc .
  861. .IN "XtKeyProc" "" "@DEF@"
  862. .FD 0
  863. typedef void (*XtKeyProc)(Display*, KeyCode, Modifiers, Modifiers*, \
  864. KeySym*);
  865. .br
  866.       Display *\fIdisplay\fP;
  867. .br
  868.       KeyCode \fIkeycode\fP;
  869. .br
  870.       Modifiers \fImodifiers\fP;
  871. .br
  872.       Modifiers *\fImodifiers_return\fP;
  873. .br
  874.       KeySym *\fIkeysym_return\fP;
  875. .FN
  876. .IP \fIdisplay\fP 1.1i
  877. Specifies the display that the KeyCode is from.
  878. .IP \fIkeycode\fP 1.1i
  879. Specifies the KeyCode to translate.
  880. .IP \fImodifiers\fP 1.1i
  881. Specifies the modifiers to the KeyCode.
  882. .IP \fImodifiers_return\fP 1.1i
  883. Specifies a location in which to store
  884. a mask that indicates the subset of all
  885. modifiers that are examined by the key translator.
  886. .IP \fIkeysym_return\fP 1.1i
  887. Specifies a location in which to store the resulting KeySym.
  888. .LP
  889. This procedure takes a KeyCode and modifiers and produces a KeySym.
  890. For any given key translator function,
  891. \fImodifiers_return\fP will be a constant that indicates the subset of all
  892. modifiers that are examined by the key translator.
  893. .LP
  894. The KeyCode-to-KeySym translator procedure
  895. must be implemented such that multiple calls with the same
  896. \fIdisplay\fP, \fIkeycode\fP, and \fImodifiers\fP return the same
  897. result until either a new case converter (
  898. .PN XtCaseProc )
  899. is installed or a
  900. .PN MappingNotify
  901. event is received.
  902.  
  903. .sp
  904. .LP
  905. The \*(xI maintain tables internally to map KeyCodes to KeySyms
  906. for each open display.  Translator procedures and other clients may
  907. share a single copy of this table to perform the same mapping.
  908. .LP
  909. To return a pointer to the KeySym-to-KeyCode mapping table for a
  910. particular display, use
  911. .PN XtGetKeysymTable .
  912. .IN "XtGetKeysymTable" "" "@DEF@"
  913. .FD 0
  914. KeySym *XtGetKeysymTable(\fIdisplay\fP, \fImin_keycode_return\fP, \
  915. \fIkeysyms_per_keycode_return\fP)
  916. .br
  917.       Display *\fIdisplay\fP;
  918. .br
  919.       KeyCode *\fImin_keycode_return\fP;
  920. .br
  921.       int *\fIkeysyms_per_keycode_return\fP;
  922. .FN
  923. .IP \fIdisplay\fP 1i
  924. Specifies the display whose table is required.
  925. .IP \fImin_keycode_return\fP 1i
  926. Returns the minimum KeyCode valid for the display.
  927. .IP \fIkeysyms_per_keycode_return\fP 1i
  928. Returns the number of KeySyms stored for each KeyCode.
  929. .LP
  930. .PN XtGetKeysymTable
  931. returns a pointer to the \*(xI' copy of the
  932. server's KeyCode-to-KeySym table.  This table must not be modified.
  933. There are \fIkeysyms_per_keycode_return\fP KeySyms associated with each
  934. KeyCode, located in the table with indices starting at index
  935. .IP
  936.     (test_keycode - min_keycode_return) * keysyms_per_keycode_return
  937. .LP
  938. for KeyCode \fItest_keycode\fP.  Any entries that have no KeySyms associated
  939. with them contain the value
  940. .PN NoSymbol .
  941. Clients should not cache the KeySym table but should call
  942. .PN XtGetKeysymTable
  943. each time the value is
  944. needed, as the table may change prior to dispatching each event.
  945. .LP
  946. For more information on this table, see Section 12.7 in \fI\*(xL\fP.
  947. .sp
  948. .LP
  949. To register a key translator, use
  950. .PN XtSetKeyTranslator .
  951. .IN "XtSetKeyTranslator" "" "@DEF@"
  952. .FD 0
  953. void XtSetKeyTranslator(\fIdisplay\fP, \fIproc\fP)
  954. .br
  955.       Display *\fIdisplay\fP;
  956. .br
  957.       XtKeyProc \fIproc\fP;
  958. .FN
  959. .IP \fIdisplay\fP 1i
  960. Specifies the display from which to translate the events.
  961. .IP \fIproc\fP 1i
  962. Specifies the procedure to perform key translations.
  963. .LP
  964. The
  965. .PN XtSetKeyTranslator
  966. function sets the specified procedure as the current key translator.
  967. The default translator is 
  968. .PN XtTranslateKey ,
  969. an
  970. .PN XtKeyProc
  971. that uses the Shift, Lock, and group modifiers with the interpretations
  972. defined in \fI\*(xP\fP, Section 5.
  973. It is provided so that new translators can call it to get default 
  974. KeyCode-to-KeySym translations and so that the default translator 
  975. can be reinstalled.
  976. .sp
  977. .LP
  978. To invoke the currently registered KeyCode-to-KeySym translator,
  979. use
  980. .PN XtTranslateKeycode .
  981. .IN "XtTranslateKeycode" "" "@DEF@"
  982. .FD 0
  983. void XtTranslateKeycode(\fIdisplay\fP, \fIkeycode\fP, \fImodifiers\fP, \
  984. \fImodifiers_return\fP, \fIkeysym_return\fP)
  985. .br
  986.       Display *\fIdisplay\fP;
  987. .br
  988.       KeyCode \fIkeycode\fP;
  989. .br
  990.       Modifiers \fImodifiers\fP;
  991. .br
  992.       Modifiers *\fImodifiers_return\fP;
  993. .br
  994.       KeySym *\fIkeysym_return\fP;
  995. .FN
  996. .IP \fIdisplay\fP 1.1i
  997. Specifies the display that the KeyCode is from.
  998. .IP \fIkeycode\fP 1.1i
  999. Specifies the KeyCode to translate.
  1000. .IP \fImodifiers\fP 1.1i
  1001. Specifies the modifiers to the KeyCode.
  1002. .IP \fImodifiers_return\fP 1.1i
  1003. Returns a mask that indicates the modifiers actually used 
  1004. to generate the KeySym.
  1005. .IP \fIkeysym_return\fP 1.1i
  1006. Returns the resulting KeySym.
  1007. .LP
  1008. The
  1009. .PN XtTranslateKeycode
  1010. function passes the specified arguments 
  1011. directly to the currently registered KeyCode-to-KeySym translator.
  1012. .sp
  1013. .LP
  1014. To handle capitalization of nonstandard KeySyms, the \*(xI allow
  1015. clients to register case conversion routines.
  1016. Case converter procedure pointers are of type
  1017. .PN XtCaseProc .
  1018. .IN "XtCaseProc" "" "@DEF@"
  1019. .FD 0
  1020. typedef void (*XtCaseProc)(Display*, KeySym, KeySym*, KeySym*);
  1021. .br
  1022.       Display *\fIdisplay\fP;
  1023. .br
  1024.       KeySym \fIkeysym\fP;
  1025. .br
  1026.       KeySym *\fIlower_return\fP;
  1027. .br
  1028.       KeySym *\fIupper_return\fP;
  1029. .FN
  1030. .IP \fIdisplay\fP 1i
  1031. Specifies the display connection for which the conversion is required.
  1032. .IP \fIkeysym\fP 1i
  1033. Specifies the KeySym to convert.
  1034. .IP \fIlower_return\fP 1i
  1035. Specifies a location into which to store the lower-case equivalent for
  1036. the KeySym.
  1037. .IP \fIupper_return\fP 1i
  1038. Specifies a location into which to store the upper-case equivalent for
  1039. the KeySym.
  1040. .LP
  1041. If there is no case distinction, 
  1042. this procedure should store the KeySym into both return values.
  1043. .sp
  1044. .LP
  1045. To register a case converter, use
  1046. .PN XtRegisterCaseConverter .
  1047. .IN "XtRegisterCaseConverter" "" "@DEF@"
  1048. .FD 0
  1049. void XtRegisterCaseConverter(\fIdisplay\fP, \fIproc\fP, \fIstart\fP, \fIstop\fP)
  1050. .br
  1051.     Display *\fIdisplay\fP;
  1052. .br
  1053.     XtCaseProc \fIproc\fP;
  1054. .br
  1055.     KeySym \fIstart\fP;
  1056. .br
  1057.     KeySym \fIstop\fP;
  1058. .FN
  1059. .IP \fIdisplay\fP 1i
  1060. Specifies the display from which the key events are to come.
  1061. .IP \fIproc\fP 1i
  1062. Specifies the 
  1063. .PN XtCaseProc 
  1064. to do the conversions.
  1065. .IP \fIstart\fP 1i
  1066. Specifies the first KeySym for which this converter is valid.
  1067. .IP \fIstop\fP 1i
  1068. Specifies the last KeySym for which this converter is valid.
  1069. .LP
  1070. The
  1071. .PN XtRegisterCaseConverter
  1072. registers the specified case converter.
  1073. The \fIstart\fP and \fIstop\fP arguments provide the inclusive range of KeySyms 
  1074. for which this converter is to be called.
  1075. The new converter overrides any previous converters for KeySyms in that range.
  1076. No interface exists to remove converters; 
  1077. you need to register an identity converter.
  1078. When a new converter is registered,
  1079. the \*(xI  refresh the keyboard state if necessary.
  1080. The default converter understands case conversion for all
  1081. Latin KeySyms defined in \fI\*(xP\fP, Appendix A.
  1082. .sp
  1083. .LP
  1084. To determine upper- and lower-case equivalents for a KeySym, use
  1085. .PN XtConvertCase .
  1086. .IN "XtConvertCase" "" "@DEF@"
  1087. .FD 0
  1088. void XtConvertCase(\fIdisplay\fP, \fIkeysym\fP, \fIlower_return\fP, \
  1089. \fIupper_return\fP)
  1090. .br
  1091.     Display *\fIdisplay\fP;
  1092. .br
  1093.     KeySym \fIkeysym\fP;
  1094. .br
  1095.     KeySym *\fIlower_return\fP;
  1096. .br
  1097.     KeySym *\fIupper_return\fP;
  1098. .FN
  1099. .IP \fIdisplay\fP 1i
  1100. Specifies the display that the KeySym came from.
  1101. .IP \fIkeysym\fP 1i
  1102. Specifies the KeySym to convert.
  1103. .IP \fIlower_return\fP 1i
  1104. Returns the lower-case equivalent of the KeySym.
  1105. .IP \fIupper_return\fP 1i
  1106. Returns the upper-case equivalent of the KeySym.
  1107. .LP
  1108. The
  1109. .PN XtConvertCase
  1110. function calls the appropriate converter and returns the results.
  1111. A user-supplied
  1112. .PN XtKeyProc 
  1113. may need to use this function.
  1114.  
  1115. .NH 2
  1116. Obtaining a KeySym in an Action Procedure
  1117. .XS
  1118. \fB\*(SN Obtaining a KeySym in an Action Procedure\fP
  1119. .XE
  1120. .LP
  1121. When an action procedure is invoked on a
  1122. .PN KeyPress
  1123. or
  1124. .PN KeyRelease
  1125. event, it often has a need to retrieve the KeySym and modifiers
  1126. corresponding to the event that caused it to be invoked.  In order to
  1127. avoid repeating the processing that was just performed by the
  1128. \*(xI to match the translation entry, the KeySym and modifiers
  1129. are stored for the duration of the action procedure and are made
  1130. available to the client.
  1131. .LP
  1132. To retrieve the KeySym and modifiers that matched the final event
  1133. specification in the translation table entry, use
  1134. .PN XtGetActionKeysym .
  1135. .IN "XtGetActionKeysym" "" "@DEF@"
  1136. .FD 0
  1137. KeySym XtGetActionKeysym(\fIevent\fP, \fImodifiers_return\fP)
  1138. .br
  1139.       XEvent *\fIevent\fP;
  1140. .br
  1141.       Modifiers *\fImodifiers_return\fP;
  1142. .FN
  1143. .IP \fIevent\fP 1.25i
  1144. Specifies the event pointer passed to the action procedure by the \*(xI.
  1145. .IP \fImodifiers_return\fP 1.25i
  1146. Returns the modifiers that caused the match, if non-NULL.
  1147. .LP
  1148. If
  1149. .PN XtGetActionKeysym
  1150. is called after an action procedure has been
  1151. invoked by the \*(xI and before that action procedure returns, and
  1152. if the event pointer has the same value as the event pointer passed to
  1153. that action routine, and if the event is a
  1154. .PN KeyPress
  1155. or
  1156. .PN KeyRelease
  1157. event, then
  1158. .PN XtGetActionKeysym
  1159. returns the KeySym that matched the final
  1160. event specification in the translation table and, if \fImodifiers_return\fP
  1161. is non-NULL, the modifier state actually used to generate this KeySym;
  1162. otherwise, if the event is a
  1163. .PN KeyPress
  1164. or
  1165. .PN KeyRelease
  1166. event, then
  1167. .PN XtGetActionKeysym
  1168. calls
  1169. .PN XtTranslateKeycode
  1170. and returns the results;
  1171. else it returns
  1172. .PN NoSymbol
  1173. and does not examine \fImodifiers_return\fP.
  1174. .LP
  1175. Note that if an action procedure invoked by the \*(xI
  1176. invokes a subsequent action procedure (and so on) via
  1177. .PN XtCallActionProc ,
  1178. the nested action procedure may also call
  1179. .PN XtGetActionKeysym
  1180. to retrieve the \*(xI' KeySym and modifiers.
  1181.  
  1182. .NH 2
  1183. KeySym-to-KeyCode Conversions
  1184. .XS
  1185. \*(SN KeySym-to-KeyCode Conversions
  1186. .XE
  1187. .LP
  1188. To return the list of KeyCodes that map to a particular KeySym in
  1189. the keyboard mapping table maintained by the \*(xI, use
  1190. .PN XtKeysymToKeycodeList .
  1191. .IN "XtKeysymToKeycodeList" "" "@DEF@"
  1192. .FD 0
  1193. void XtKeysymToKeycodeList(\fIdisplay\fP, \fIkeysym\fP, \fIkeycodes_return\fP, \
  1194. \fIkeycount_return\fP)
  1195. .br
  1196.       Display *\fIdisplay\fP;
  1197. .br
  1198.       KeySym \fIkeysym\fP;
  1199. .br
  1200.       KeyCode **\fIkeycodes_return\fP;
  1201. .br
  1202.       Cardinal *\fIkeycount_return\fP;
  1203. .FN
  1204. .IP \fIdisplay\fP 1.25i
  1205. Specifies the display whose table is required.
  1206. .IP \fIkeysym\fP 1.25i
  1207. Specifies the KeySym for which to search.
  1208. .IP \fIkeycodes_return\fP 1.25i
  1209. Returns a list of KeyCodes that have \fIkeysym\fP
  1210. associated with them, or NULL if \fIkeycount_return\fP is 0.
  1211. .IP \fIkeycount_return\fP 1.25i
  1212. Returns the number of KeyCodes in the keycode list.
  1213. .LP
  1214. The
  1215. .PN XtKeysymToKeycodeList
  1216. procedure returns all the KeyCodes that have \fIkeysym\fP
  1217. in their entry for the keyboard mapping table associated with \fIdisplay\fP.
  1218. For each entry in the
  1219. table, the first four KeySyms (groups 1 and 2) are interpreted as
  1220. specified by \fI\*(xP\fP, Section 5.  If no KeyCodes map to the
  1221. specified KeySym, \fIkeycount_return\fP is zero and *\fIkeycodes_return\fP is NULL.
  1222. .LP
  1223. The caller should free the storage pointed to by \fIkeycodes_return\fP using
  1224. .PN XtFree
  1225. when it is no longer useful.  If the caller needs to examine
  1226. the KeyCode-to-KeySym table for a particular KeyCode, it should call
  1227. .PN XtGetKeysymTable .
  1228.  
  1229. .NH 2
  1230. Registering Button and Key Grabs For Actions
  1231. .XS
  1232. \fB\*(SN Registering Button and Key Grabs For Actions\fP
  1233. .XE
  1234. .LP
  1235. To register button and key grabs for a widget's window according to the
  1236. event bindings in the widget's translation table, use
  1237. .PN XtRegisterGrabAction .
  1238. .IN "XtRegisterGrabAction" "" "@DEF@"
  1239. .FD 0
  1240. void XtRegisterGrabAction(\fIaction_proc\fP, \fIowner_events\fP, \
  1241. \fIevent_mask\fP, \fIpointer_mode\fP, \fIkeyboard_mode\fP)
  1242. .br
  1243.       XtActionProc \fIaction_proc\fP;
  1244. .br
  1245.       Boolean \fIowner_events\fP;
  1246. .br
  1247.       unsigned int \fIevent_mask\fP;
  1248. .br
  1249.       int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
  1250. .FN
  1251. .IP \fIaction_proc\fP 1i
  1252. Specifies the action procedure to search for in translation tables.
  1253. .sp
  1254. .IP \fIowner_events\fP
  1255. .br
  1256. .ns
  1257. .IP \fIevent_mask\fP
  1258. .br
  1259. .ns
  1260. .IP \fIpointer_mode\fP
  1261. .br
  1262. .ns
  1263. .IP \fIkeyboard_mode\fP 1i
  1264. Specify arguments to
  1265. .PN XtGrabButton
  1266. or 
  1267. .PN XtGrabKey .
  1268. .LP
  1269. .PN XtRegisterGrabAction
  1270. adds the specified \fIaction_proc\fP to a list known to
  1271. the translation manager.  When a widget is realized, or when the
  1272. translations of a realized widget or the accelerators installed on a
  1273. realized widget are modified, its translation table and any installed
  1274. accelerators are scanned for action procedures on this list.
  1275. If any are invoked on
  1276. .PN ButtonPress
  1277. or
  1278. .PN KeyPress
  1279. events as the only or final event
  1280. in a sequence, the \*(xI will call
  1281. .PN XtGrabButton
  1282. or
  1283. .PN XtGrabKey
  1284. for the widget with every button or KeyCode which maps to the
  1285. event detail field, passing the specified \fIowner_events\fP, \fIevent_mask\fP,
  1286. \fIpointer_mode\fP, and \fIkeyboard_mode\fP.  For
  1287. .PN ButtonPress
  1288. events, the modifiers
  1289. specified in the grab are determined directly from the translation
  1290. specification and \fIconfine_to\fP and \fIcursor\fP are specified as
  1291. .PN None .
  1292. For
  1293. .PN KeyPress
  1294. events, if the translation table entry specifies colon (:) in
  1295. the modifier list, the modifiers are determined by calling the key
  1296. translator procedure registered for the display and calling
  1297. .PN XtGrabKey
  1298. for every combination of standard modifiers which map the KeyCode to
  1299. the specified event detail KeySym, and ORing any modifiers specified in
  1300. the translation table entry, and \fIevent_mask\fP is ignored.  If the
  1301. translation table entry does not specify colon in the modifier list,
  1302. the modifiers specified in the grab are those specified in the
  1303. translation table entry only.  For both
  1304. .PN ButtonPress
  1305. and
  1306. .PN KeyPress
  1307. events, don't-care modifiers are ignored unless the translation entry
  1308. explicitly specifies ``Any'' in the \fImodifiers\fP field.
  1309. .LP
  1310. If the specified \fIaction_proc\fP is already registered for the calling
  1311. process, the new values will replace the previously specified values
  1312. for any widgets that become realized following the call, but existing
  1313. grabs are not altered on currently-realized widgets.
  1314. .LP
  1315. When translations or installed accelerators are modified for a
  1316. realized widget, any previous key or button grabs registered
  1317. as a result of the old bindings are released if they do not appear in
  1318. the new bindings and are not explicitly grabbed by the client with
  1319. .PN XtGrabKey
  1320. or
  1321. .PN XtGrabButton .
  1322.  
  1323. .NH 2
  1324. Invoking Actions Directly
  1325. .XS
  1326. \fB\*(SN Invoking Actions Directly\fP
  1327. .XE
  1328. .LP
  1329. Normally action procedures are invoked by the \*(xI when an
  1330. event or event sequence arrives for a widget. To
  1331. invoke an action procedure directly, without generating
  1332. (or synthesizing) events, use
  1333. .PN XtCallActionProc .
  1334. .IN "XtCallActionProc" "" "@DEF@"
  1335. .FD 0
  1336. void XtCallActionProc(\fIwidget\fP, \fIaction\fP, \fIevent\fP, \fIparams\fP, \
  1337. \fInum_params\fP)
  1338. .br
  1339.       Widget \fIwidget\fP;
  1340. .br
  1341.       String \fIaction\fP;
  1342. .br
  1343.       XEvent *\fIevent\fP;
  1344. .br
  1345.       String *\fIparams\fP;
  1346. .br
  1347.       Cardinal \fInum_params\fP;
  1348. .FN
  1349. .IP \fIwidget\fP 1i
  1350. Specifies the widget in which the action is to be invoked.  \*(cI
  1351. .IP \fIaction\fP 1i
  1352. Specifies the name of the action routine.
  1353. .IP \fIevent\fP 1i
  1354. Specifies the contents of the \fIevent\fP passed to the action routine.
  1355. .IP \fIparams\fP 1i
  1356. Specifies the contents of the \fIparams\fP passed to the action routine.
  1357. .IP \fInum_params\fP 1i
  1358. Specifies the number of entries in \fIparams\fP.
  1359. .LP
  1360. .PN XtCallActionProc
  1361. searches for the named action routine in the same
  1362. manner and order as translation tables are bound, as described in
  1363. Section 10.1.2, except that application action tables are searched, if
  1364. necessary, as of the time of the call to
  1365. .PN XtCallActionProc .
  1366. If found,
  1367. the action routine is invoked with the specified widget, event pointer,
  1368. and parameters.  It is the responsibility of the caller to ensure that
  1369. the contents of the \fIevent\fP, \fIparams\fP, and \fInum_params\fP arguments are
  1370. appropriate for the specified action routine and, if necessary, that
  1371. the specified widget is realized or sensitive.  If the named action
  1372. routine cannot be found,
  1373. .PN XtCallActionProc
  1374. generates a warning message and returns.
  1375.  
  1376. .NH 2
  1377. Obtaining a Widget's Action List
  1378. .XS
  1379. \*(SN Obtaining a Widget's Action List
  1380. .XE
  1381. .LP
  1382. Occasionally a subclass will require the pointers to one or more of
  1383. its superclass's action procedures.  This would be needed, for
  1384. example, in order to envelope the superclass's action.  To retrieve
  1385. the list of action procedures registered in the superclass's
  1386. \fIactions\fP field, use
  1387. .PN XtGetActionList .
  1388. .IN "XtGetActionList" "" "@DEF@"
  1389. .FD 0
  1390. void XtGetActionList(\fIwidget_class\fP, \fIactions_return\fP, \
  1391. \fInum_actions_return\fP)
  1392. .br
  1393.       WidgetClass \fIwidget_class\fP;
  1394. .br
  1395.       XtActionList *\fIactions_return\fP;
  1396. .br
  1397.       Cardinal *\fInum_actions_return\fP;
  1398. .FN
  1399. .IP \fIwidget_class\fP 1i
  1400. Specifies the widget class whose actions are to be returned.
  1401. .IP \fIactions_return\fP 1i
  1402. Returns the action list.
  1403. .IP \fInum_actions_return\fP 1i
  1404. Returns the number of action procedures declared by the class.
  1405. .LP
  1406. .PN XtGetActionList
  1407. returns the action table defined by the specified
  1408. widget class.  This table does not include actions defined by the
  1409. superclasses.  If \fIwidget_class\fP is not initialized, or is not
  1410. .PN coreWidgetClass
  1411. or a subclass thereof, or if the class does not define any actions,
  1412. *\fIactions_return\fP will be NULL and *\fInum_actions_return\fP
  1413. will be zero.
  1414. If *\fIactions_return\fP is non-NULL the client is responsible for freeing
  1415. the table using
  1416. .PN XtFree
  1417. when it is no longer needed.
  1418.  
  1419. .bp
  1420.