« back to all changes in this revision
Viewing changes to specs/CH10.xml
- browse files at revision 12
- compare with another revision
- download diff
- download tarball
- view history from revision 12
- Committer: Package Import Robot
- Author(s): Julien Cristau
- Date: 2012-04-22 11:13:54 UTC
- mfrom: (1.1.9)
- Revision ID: package-import@ubuntu.com-20120422111354-bgq2l0n9x262ez70
Tags: 1:1.1.3-1
* New upstream release.
* Bump xutils-dev build-dep for newer macros.
* Enable unit tests.
* Drop -D_REENTRANT from CFLAGS, unneeded.
* No need to override dh_auto_install.
* Add a libxt-doc package for the specs.
* Remove David Nusinow from Uploaders.
* Bump xutils-dev build-dep for newer macros.
* Enable unit tests.
* Drop -D_REENTRANT from CFLAGS, unneeded.
* No need to override dh_auto_install.
* Add a libxt-doc package for the specs.
* Remove David Nusinow from Uploaders.
- files added:
- debian/libxt-doc.install
- test
- files removed:
- compile
- files modified:
- ChangeLog
added
removed
specs/CH10.xml
1
<chapter id='Translation_Management'>
2
<title>Translation Management</title>
3
<para>
4
Except under unusual circumstances,
5
widgets do not hardwire the mapping of user events into widget behavior
6
by using the event manager.
7
Instead, they provide a default mapping of events into behavior
8
that you can override.
9
</para>
10
11
<para>
12
The translation manager provides an interface to specify and manage the
13
mapping of X event sequences into widget-supplied functionality,
14
for example, calling procedure <emphasis remap='I'>Abc</emphasis> when the <emphasis remap='I'>y</emphasis> key
15
is pressed.
16
</para>
17
18
<para>
19
The translation manager uses two kinds of tables to perform translations:
20
</para>
21
<itemizedlist spacing='compact'>
22
<listitem>
23
<para>
24
The action tables, which are in the widget class structure,
25
specify the mapping of externally available procedure name strings
26
to the corresponding procedure implemented by the widget class.
27
</para>
28
</listitem>
29
<listitem>
30
<para>
31
A translation table, which is in the widget class structure,
32
specifies the mapping of event sequences to procedure name strings.
33
</para>
34
</listitem>
35
</itemizedlist>
36
<para>
37
You can override the translation table in the class structure
38
for a specific widget instance by supplying a different translation table
39
for the widget instance. The resources
40
XtNtranslations and XtNbaseTranslations are used to modify the class
41
default translation table; see <xref linkend='Translation_Table_Management' />.
42
</para>
43
<sect1 id="Action_Tables">
44
<title>Action Tables</title>
45
<para>
46
All widget class records contain an action table,
47
an array of
48
<function>XtActionsRec</function>
49
entries.
50
In addition,
51
an application can register its own action tables with the translation manager
52
so that the translation tables it provides to widget instances can access
53
application functionality directly.
54
The translation action procedure pointer is of type
55
<xref linkend='XtActionProc' xrefstyle='select: title'/>.
56
</para>
57
58
<funcsynopsis id='XtActionProc'>
59
<funcprototype>
60
<funcdef>typedef void <function>(*XtActionProc)</function></funcdef>
61
<paramdef>Widget <parameter>w</parameter></paramdef>
62
<paramdef>XEvent *<parameter>event</parameter></paramdef>
63
<paramdef>String *<parameter>params</parameter></paramdef>
64
<paramdef>Cardinal *<parameter>num_params</parameter></paramdef>
65
</funcprototype>
66
</funcsynopsis>
67
68
<variablelist>
69
<varlistentry>
70
<term>
71
<emphasis remap='I'>w</emphasis>
72
</term>
73
<listitem>
74
<para>
75
Specifies the widget that caused the action to be called.
76
</para>
77
</listitem>
78
</varlistentry>
79
<varlistentry>
80
<term>
81
<emphasis remap='I'>event</emphasis>
82
</term>
83
<listitem>
84
<para>
85
Specifies the event that caused the action to be called.
86
If the action is called after a sequence of events,
87
then the last event in the sequence is used.
88
</para>
89
</listitem>
90
</varlistentry>
91
<varlistentry>
92
<term>
93
<emphasis remap='I'>params</emphasis>
94
</term>
95
<listitem>
96
<para>
97
Specifies a pointer to the list of strings that were specified
98
in the translation table as arguments to the action, or NULL.
99
</para>
100
</listitem>
101
</varlistentry>
102
<varlistentry>
103
<term>
104
<emphasis remap='I'>num_params</emphasis>
105
</term>
106
<listitem>
107
<para>
108
Specifies the number of entries in <emphasis remap='I'>params</emphasis>.
109
</para>
110
</listitem>
111
</varlistentry>
112
</variablelist>
113
114
<literallayout >
115
typedef struct _XtActionsRec {
116
String string;
117
XtActionProc proc;
118
} XtActionsRec, *XtActionList;
119
</literallayout>
120
<para>
121
The <emphasis remap='I'>string</emphasis> field is the name used in translation tables to access
122
the procedure.
123
The <emphasis remap='I'>proc</emphasis> field is a pointer to a procedure that implements
124
the functionality.
125
</para>
126
127
<para>
128
When the action list is specified as the
129
<function>CoreClassPart</function>
130
<emphasis remap='I'>actions</emphasis> field, the string pointed to by <emphasis remap='I'>string</emphasis> must be
131
permanently allocated prior to or during the execution of the class
132
initialization procedure and must not be subsequently deallocated.
133
</para>
134
135
<para>
136
Action procedures should not assume that the widget in which they
137
are invoked is realized; an accelerator specification can cause
138
an action procedure to be called for a widget that does not yet
139
have a window. Widget writers should also note which of a widget's
140
callback lists are invoked from action procedures and warn clients
141
not to assume the widget is realized in those callbacks.
142
</para>
143
144
<para>
145
For example, a Pushbutton widget has procedures to take the following actions:
146
</para>
147
<itemizedlist spacing='compact'>
148
<listitem>
149
<para>
150
Set the button to indicate it is activated.
151
</para>
152
</listitem>
153
<listitem>
154
<para>
155
Unset the button back to its normal mode.
156
</para>
157
</listitem>
158
<listitem>
159
<para>
160
Highlight the button borders.
161
</para>
162
</listitem>
163
<listitem>
164
<para>
165
Unhighlight the button borders.
166
</para>
167
</listitem>
168
<listitem>
169
<para>
170
Notify any callbacks that the button has been activated.
171
</para>
172
</listitem>
173
</itemizedlist>
174
<para>
175
The action table for the Pushbutton widget class makes these functions
176
available to translation tables written for Pushbutton or any subclass.
177
The string entry is the name used in translation tables.
178
The procedure entry (usually spelled identically to the string)
179
is the name of the C procedure that implements that function:
180
</para>
181
<literallayout >
182
XtActionsRec actionTable[] = {
183
{"Set", Set},
184
{"Unset", Unset},
185
{"Highlight", Highlight},
186
{"Unhighlight", Unhighlight}
187
{"Notify", Notify},
188
};
189
</literallayout>
190
<para>
191
The Intrinsics reserve all action names and parameters starting with
192
the characters ``Xt'' for future standard enhancements. Users,
193
applications, and widgets should not declare action names or pass
194
parameters starting with these characters except to invoke specified
195
built-in Intrinsics functions.
196
</para>
197
<sect2 id="Action_Table_Registration">
198
<title>Action Table Registration</title>
199
<para>
200
The <emphasis remap='I'>actions</emphasis> and <emphasis remap='I'>num_actions</emphasis> fields of
201
<function>CoreClassPart</function>
202
specify the actions implemented by a widget class. These are
203
automatically registered with the Intrinsics when the class is initialized
204
and must be allocated in writable storage prior to Core class_part
205
initialization, and never deallocated. To save memory and optimize
206
access, the Intrinsics may overwrite the storage in order to compile the
207
list into an internal representation.
208
</para>
209
210
<para>
211
To declare an action table within an application
212
and register it with the translation manager, use
213
<xref linkend='XtAppAddActions' xrefstyle='select: title'/>.
214
</para>
215
216
<funcsynopsis id='XtAppAddActions'>
217
<funcprototype>
218
<funcdef>void <function>XtAppAddActions</function></funcdef>
219
<paramdef>XtAppContext <parameter>app_context</parameter></paramdef>
220
<paramdef>XtActionList <parameter>actions</parameter></paramdef>
221
<paramdef>Cardinal <parameter>num_actions</parameter></paramdef>
222
</funcprototype>
223
</funcsynopsis>
224
225
<variablelist>
226
<varlistentry>
227
<term>
228
<emphasis remap='I'>app_context</emphasis>
229
</term>
230
<listitem>
231
<para>
232
Specifies the application context.
233
</para>
234
</listitem>
235
</varlistentry>
236
<varlistentry>
237
<term>
238
<emphasis remap='I'>actions</emphasis>
239
</term>
240
<listitem>
241
<para>
242
Specifies the action table to register.
243
</para>
244
</listitem>
245
</varlistentry>
246
<varlistentry>
247
<term>
248
<emphasis remap='I'>num_actions</emphasis>
249
</term>
250
<listitem>
251
<para>
252
Specifies the number of entries in this action table.
253
</para>
254
</listitem>
255
</varlistentry>
256
</variablelist>
257
258
<para>
259
If more than one action is registered with the same name,
260
the most recently registered action is used.
261
If duplicate actions exist in an action table,
262
the first is used.
263
The Intrinsics register an action table containing
264
<xref linkend='XtMenuPopup' xrefstyle='select: title'/>
265
and
266
<xref linkend='XtMenuPopdown' xrefstyle='select: title'/>
267
as part of
268
<xref linkend='XtCreateApplicationContext' xrefstyle='select: title'/>.
269
</para>
270
</sect2>
271
272
<sect2 id="Action_Names_to_Procedure_Translations">
273
<title>Action Names to Procedure Translations</title>
274
<para>
275
The translation manager uses a simple algorithm to resolve the name of
276
a procedure specified in a translation table into the
277
actual procedure specified
278
in an action table.
279
When the widget
280
is realized, the translation manager
281
performs a search for the name in the following tables, in order:
282
</para>
283
<itemizedlist spacing='compact'>
284
<listitem>
285
<para>
286
The widget's class and all superclass action tables, in subclass-to-superclass
287
order.
288
</para>
289
</listitem>
290
<listitem>
291
<para>
292
The parent's class and all superclass action tables, in subclass-to-superclass
293
order, then on up the ancestor tree.
294
</para>
295
</listitem>
296
<listitem>
297
<para>
298
The action tables registered with
299
<xref linkend='XtAppAddActions' xrefstyle='select: title'/>
300
and
301
<xref linkend='XtAddActions' xrefstyle='select: title'/>
302
from the most recently added table to the oldest table.
303
</para>
304
</listitem>
305
</itemizedlist>
306
<para>
307
As soon as it finds a name,
308
the translation manager stops the search.
309
If it cannot find a name,
310
the translation manager generates a warning message.
311
</para>
312
</sect2>
313
314
<sect2 id="Action_Hook_Registration">
315
<title>Action Hook Registration</title>
316
<para>
317
An application can specify a procedure that will be called just before
318
every action routine is dispatched by the translation manager. To do
319
so, the application supplies a procedure pointer of type
320
<xref linkend='XtActionHookProc' xrefstyle='select: title'/>.
321
</para>
322
323
<funcsynopsis id='XtActionHookProc'>
324
<funcprototype>
325
<funcdef>typedef void <function>(*XtActionHookProc)</function></funcdef>
326
<paramdef>Widget <parameter>w</parameter></paramdef>
327
<paramdef>XtPointer <parameter>client_data</parameter></paramdef>
328
<paramdef>String <parameter>action_name</parameter></paramdef>
329
<paramdef>XEvent* <parameter>event</parameter></paramdef>
330
<paramdef>String* <parameter>params</parameter></paramdef>
331
<paramdef>Cardinal* <parameter>num_params</parameter></paramdef>
332
</funcprototype>
333
</funcsynopsis>
334
335
336
337
<variablelist>
338
<varlistentry>
339
<term>
340
<emphasis remap='I'>w</emphasis>
341
</term>
342
<listitem>
343
<para>
344
Specifies the widget whose action is about to be dispatched.
345
</para>
346
</listitem>
347
</varlistentry>
348
<varlistentry>
349
<term>
350
<emphasis remap='I'>client_data</emphasis>
351
</term>
352
<listitem>
353
<para>
354
Specifies the application-specific closure that was passed to
355
<function>XtAppAddActionHook.</function>
356
</para>
357
</listitem>
358
</varlistentry>
359
<varlistentry>
360
<term>
361
<emphasis remap='I'>action_name</emphasis>
362
</term>
363
<listitem>
364
<para>
365
Specifies the name of the action to be dispatched.
366
</para>
367
</listitem>
368
</varlistentry>
369
<varlistentry>
370
<term>
371
<emphasis remap='I'>event</emphasis>
372
</term>
373
<listitem>
374
<para>
375
Specifies the event argument that will be passed to the action routine.
376
</para>
377
</listitem>
378
</varlistentry>
379
<varlistentry>
380
<term>
381
<emphasis remap='I'>params</emphasis>
382
</term>
383
<listitem>
384
<para>
385
Specifies the action parameters that will be passed to the action routine.
386
</para>
387
</listitem>
388
</varlistentry>
389
<varlistentry>
390
<term>
391
<emphasis remap='I'>num_params</emphasis>
392
</term>
393
<listitem>
394
<para>
395
Specifies the number of entries in <emphasis remap='I'>params</emphasis>.
396
</para>
397
</listitem>
398
</varlistentry>
399
</variablelist>
400
401
<para>
402
Action hooks should not modify any of the data pointed to by the
403
arguments other than the <emphasis remap='I'>client_data</emphasis> argument.
404
</para>
405
406
<para>
407
To add an action hook, use
408
<xref linkend='XtAppAddActionHook' xrefstyle='select: title'/>.
409
</para>
410
411
<funcsynopsis id='XtAppAddActionHook'>
412
<funcprototype>
413
<funcdef>XtActionHookId <function>XtAppAddActionHook</function></funcdef>
414
<paramdef>XtAppContext <parameter>app</parameter></paramdef>
415
<paramdef>XtActionHookProc <parameter>proc</parameter></paramdef>
416
<paramdef>XtPointer <parameter>client_data</parameter></paramdef>
417
</funcprototype>
418
</funcsynopsis>
419
420
<variablelist>
421
<varlistentry>
422
<term>
423
<emphasis remap='I'>app</emphasis>
424
</term>
425
<listitem>
426
<para>
427
Specifies the application context.
428
</para>
429
</listitem>
430
</varlistentry>
431
<varlistentry>
432
<term>
433
<emphasis remap='I'>proc</emphasis>
434
</term>
435
<listitem>
436
<para>
437
Specifies the action hook procedure.
438
</para>
439
</listitem>
440
</varlistentry>
441
<varlistentry>
442
<term>
443
<emphasis remap='I'>client_data</emphasis>
444
</term>
445
<listitem>
446
<para>
447
Specifies application-specific data to be passed to the action hook.
448
</para>
449
</listitem>
450
</varlistentry>
451
</variablelist>
452
453
<para>
454
<xref linkend='XtAppAddActionHook' xrefstyle='select: title'/>
455
adds the specified procedure to the front of a list
456
maintained in the application context. In the future, when an action
457
routine is about to be invoked for any widget in this application
458
context, either through the translation manager or via
459
<xref linkend='XtCallActionProc' xrefstyle='select: title'/>,
460
the action hook procedures will be called in reverse
461
order of registration just prior to invoking the action routine.
462
</para>
463
464
<para>
465
Action hook procedures are removed automatically and the
466
<function>XtActionHookId is</function>
467
destroyed when the application context in which
468
they were added is destroyed.
469
</para>
470
471
<para>
472
To remove an action hook procedure without destroying the application
473
context, use
474
<xref linkend='XtRemoveActionHook' xrefstyle='select: title'/>.
475
</para>
476
477
<funcsynopsis id='XtRemoveActionHook'>
478
<funcprototype>
479
<funcdef>void <function>XtRemoveActionHook</function></funcdef>
480
<paramdef>XtActionHookId <parameter>id</parameter></paramdef>
481
</funcprototype>
482
</funcsynopsis>
483
484
<variablelist>
485
<varlistentry>
486
<term>
487
<emphasis remap='I'>id</emphasis>
488
</term>
489
<listitem>
490
<para>
491
Specifies the action hook id returned by
492
<xref linkend='XtAppAddActionHook' xrefstyle='select: title'/>.
493
</para>
494
</listitem>
495
</varlistentry>
496
</variablelist>
497
498
<para>
499
<xref linkend='XtRemoveActionHook' xrefstyle='select: title'/>
500
removes the specified action hook procedure from
501
the list in which it was registered.
502
</para>
503
</sect2>
504
</sect1>
505
506
<sect1 id="Translation_Tables">
507
<title>Translation Tables</title>
508
<para>
509
All widget instance records contain a translation table,
510
which is a resource with a default value specified elsewhere in the
511
class record.
512
A translation table specifies what action procedures are invoked for
513
an event or a sequence of events.
514
A translation table
515
is a string containing a list of translations from an event sequence
516
into one or more action procedure calls.
517
The translations are separated from one another by newline characters
518
(ASCII LF).
519
The complete syntax of translation tables is specified in Appendix B.
520
</para>
521
522
<para>
523
As an example, the default behavior of Pushbutton is
524
</para>
525
<itemizedlist spacing='compact'>
526
<listitem>
527
<para>
528
Highlight on enter window.
529
</para>
530
</listitem>
531
<listitem>
532
<para>
533
Unhighlight on exit window.
534
</para>
535
</listitem>
536
<listitem>
537
<para>
538
Invert on left button down.
539
</para>
540
</listitem>
541
<listitem>
542
<para>
543
Call callbacks and reinvert on left button up.
544
</para>
545
</listitem>
546
</itemizedlist>
547
<para>
548
The following illustrates Pushbutton's default translation table:
549
</para>
550
<literallayout >
551
static String defaultTranslations =
552
"<EnterWindow>: Highlight()\\n\\
553
<LeaveWindow>: Unhighlight()\\n\\
554
<Btn1Down>: Set()\\n\\
555
<Btn1Up>: Notify() Unset()";
556
</literallayout>
557
<para>
558
The <emphasis remap='I'>tm_table</emphasis> field of the
559
<function>CoreClassPart</function>
560
should be filled in at class initialization time with
561
the string containing the class's default translations.
562
If a class wants to inherit its superclass's translations,
563
it can store the special value
564
<function>XtInheritTranslations</function>
565
into <emphasis remap='I'>tm_table</emphasis>.
566
In Core's class part initialization procedure,
567
the Intrinsics compile this translation table into an efficient internal form.
568
Then, at widget creation time,
569
this default translation table is
570
combined with the XtNtranslations
571
and XtNbaseTranslations resources; see
572
<xref linkend='Translation_Table_Management' />.
573
</para>
574
575
<para>
576
The resource conversion mechanism automatically compiles
577
string translation tables that are specified in the resource database.
578
If a client uses translation tables that are not retrieved via a
579
resource conversion,
580
it must compile them itself using
581
<xref linkend='XtParseTranslationTable' xrefstyle='select: title'/>.
582
</para>
583
584
<para>
585
The Intrinsics use the compiled form of the translation table to register the
586
necessary events with the event manager.
587
Widgets need do nothing other than specify the action and translation tables
588
for events to be processed by the translation manager.
589
</para>
590
<sect2 id="Event_Sequences">
591
<title>Event Sequences</title>
592
<para>
593
An event sequence is a comma-separated list of X event descriptions
594
that describes a specific sequence of X events to map to a set of
595
program actions.
596
Each X event description consists of three parts:
597
The X event type, a prefix consisting of the X modifier bits, and
598
an event-specific suffix.
599
</para>
600
601
<para>
602
Various abbreviations are supported to make translation tables easier
603
to read. The events must match incoming events in left-to-right order
604
to trigger the action sequence.
605
</para>
606
</sect2>
607
608
<sect2 id="Action_Sequences">
609
<title>Action Sequences</title>
610
<para>
611
Action sequences specify what program or widget actions to take in response to
612
incoming X events. An action sequence consists of space-separated
613
action procedure call specifications.
614
Each action procedure call consists of the name of an action procedure and a
615
parenthesized list of zero or more comma-separated
616
string parameters to pass to that procedure.
617
The actions are invoked in left-to-right order as specified in the
618
action sequence.
619
</para>
620
</sect2>
621
622
<sect2 id="Multi_Click_Time">
623
<title>Multi-Click Time</title>
624
<para>
625
Translation table entries may specify actions that are taken when two
626
or more identical events occur consecutively within a short time
627
interval, called the multi-click time. The multi-click time value may
628
be specified as an application resource with name ``multiClickTime'' and
629
class ``MultiClickTime'' and may also be modified dynamically by the
630
application. The multi-click time is unique for each Display value and
631
is retrieved from the resource database by
632
<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>.
633
If no value is specified, the initial value is 200 milliseconds.
634
</para>
635
636
<para>
637
To set the multi-click time dynamically, use
638
<xref linkend='XtSetMultiClickTime' xrefstyle='select: title'/>.
639
</para>
640
641
<funcsynopsis id='XtSetMultiClickTime'>
642
<funcprototype>
643
<funcdef>void <function>XtSetMultiClickTime</function></funcdef>
644
<paramdef>Display *<parameter>display</parameter></paramdef>
645
<paramdef>int <parameter>time</parameter></paramdef>
646
</funcprototype>
647
</funcsynopsis>
648
649
<variablelist>
650
<varlistentry>
651
<term>
652
<emphasis remap='I'>display</emphasis>
653
</term>
654
<listitem>
655
<para>
656
Specifies the display connection.
657
</para>
658
</listitem>
659
</varlistentry>
660
<varlistentry>
661
<term>
662
<emphasis remap='I'>time</emphasis>
663
</term>
664
<listitem>
665
<para>
666
Specifies the multi-click time in milliseconds.
667
</para>
668
</listitem>
669
</varlistentry>
670
</variablelist>
671
672
<para>
673
<xref linkend='XtSetMultiClickTime' xrefstyle='select: title'/>
674
sets the time interval used by the translation
675
manager to determine when multiple events are interpreted as a
676
repeated event. When a repeat count is specified in a translation
677
entry, the interval between the timestamps in each pair of repeated
678
events (e.g., between two
679
<function>ButtonPress</function>
680
events) must be less than the
681
multi-click time in order for the translation actions to be taken.
682
</para>
683
684
<para>
685
To read the multi-click time, use
686
<xref linkend='XtGetMultiClickTime' xrefstyle='select: title'/>.
687
</para>
688
689
<funcsynopsis id='XtGetMultiClickTime'>
690
<funcprototype>
691
<funcdef>int <function>XtGetMultiClickTime</function></funcdef>
692
<paramdef>Display *<parameter>display</parameter></paramdef>
693
</funcprototype>
694
</funcsynopsis>
695
696
<variablelist>
697
<varlistentry>
698
<term>
699
<emphasis remap='I'>display</emphasis>
700
</term>
701
<listitem>
702
<para>
703
Specifies the display connection.
704
</para>
705
</listitem>
706
</varlistentry>
707
</variablelist>
708
709
<para>
710
<xref linkend='XtGetMultiClickTime' xrefstyle='select: title'/>
711
returns the time in milliseconds that the
712
translation manager uses to determine if multiple events are to be
713
interpreted as a repeated event for purposes of matching a translation
714
entry containing a repeat count.
715
</para>
716
</sect2>
717
</sect1>
718
719
<sect1 id="Translation_Table_Management">
720
<title>Translation Table Management</title>
721
<para>
722
Sometimes an application needs to merge
723
its own translations with a widget's translations.
724
For example, a window manager provides functions to move a window.
725
The window manager wishes to bind this operation to a specific
726
pointer button in the title bar without the possibility of user
727
override and bind it to other buttons that may be overridden by the user.
728
</para>
729
730
<para>
731
To accomplish this,
732
the window manager should first create the title bar
733
and then should merge the two translation tables into
734
the title bar's translations.
735
One translation table contains the translations that the window manager
736
wants only if the user has not specified a translation for a particular event
737
or event sequence (i.e., those that may be overridden).
738
The other translation table contains the translations that the
739
window manager wants regardless of what the user has specified.
740
</para>
741
742
<para>
743
Three Intrinsics functions support this merging:
744
</para>
745
746
<variablelist>
747
<varlistentry>
748
<term>
749
<emphasis remap='I'>XtParseTranslationTable</emphasis>
750
</term>
751
<listitem>
752
<para>Compiles a translation table.</para>
753
</listitem>
754
</varlistentry>
755
<varlistentry>
756
<term>
757
<emphasis remap='I'>XtAugmentTranslations</emphasis>
758
</term>
759
<listitem>
760
<para>Merges a compiled translation table into a widget's
761
compiled translation table, ignoring any new translations that
762
conflict with existing translations.
763
</para>
764
</listitem>
765
</varlistentry>
766
<varlistentry>
767
<term>
768
<emphasis remap='I'>XtOverrideTranslations</emphasis>
769
</term>
770
<listitem>
771
<para>Merges a compiled translation table into a widget's
772
compiled translation table, replacing any existing translations that
773
conflict with new translations.
774
</para>
775
</listitem>
776
</varlistentry>
777
</variablelist>
778
779
<para>
780
To compile a translation table, use
781
<xref linkend='XtParseTranslationTable' xrefstyle='select: title'/>.
782
</para>
783
784
<funcsynopsis id='XtParseTranslationTable'>
785
<funcprototype>
786
<funcdef>XtTranslations <function>XtParseTranslationTable</function></funcdef>
787
<paramdef>String <parameter>table</parameter></paramdef>
788
</funcprototype>
789
</funcsynopsis>
790
791
<variablelist>
792
<varlistentry>
793
<term>
794
<emphasis remap='I'>table</emphasis>
795
</term>
796
<listitem>
797
<para>
798
Specifies the translation table to compile.
799
</para>
800
</listitem>
801
</varlistentry>
802
</variablelist>
803
804
<para>
805
The
806
<xref linkend='XtParseTranslationTable' xrefstyle='select: title'/>
807
function compiles the translation table, provided in the format given
808
in Appendix B, into an opaque internal representation
809
of type
810
<function>XtTranslations</function>.
811
Note that if an empty translation table is required for any purpose,
812
one can be obtained by calling
813
<xref linkend='XtParseTranslationTable' xrefstyle='select: title'/>
814
and passing an empty string.
815
</para>
816
817
<para>
818
To merge additional translations into an existing translation table, use
819
<xref linkend='XtAugmentTranslations' xrefstyle='select: title'/>.
820
</para>
821
822
<funcsynopsis id='XtAugmentTranslations'>
823
<funcprototype>
824
<funcdef>void <function>XtAugmentTranslations</function></funcdef>
825
<paramdef>Widget <parameter>w</parameter></paramdef>
826
<paramdef>XtTranslations <parameter>translations</parameter></paramdef>
827
</funcprototype>
828
</funcsynopsis>
829
830
<variablelist>
831
<varlistentry>
832
<term>
833
<emphasis remap='I'>w</emphasis>
834
</term>
835
<listitem>
836
<para>
837
Specifies the widget into which the new translations are to be merged. Must be of class Core or any subclass thereof.
838
</para>
839
</listitem>
840
</varlistentry>
841
<varlistentry>
842
<term>
843
<emphasis remap='I'>translations</emphasis>
844
</term>
845
<listitem>
846
<para>
847
Specifies the compiled translation table to merge in.
848
</para>
849
</listitem>
850
</varlistentry>
851
</variablelist>
852
853
<para>
854
The
855
<xref linkend='XtAugmentTranslations' xrefstyle='select: title'/>
856
function merges the new translations into the existing widget
857
translations, ignoring any
858
<function>#replace</function>,
859
<function>#augment</function>,
860
or
861
<function>#override</function>
862
directive that may have been specified
863
in the translation string. The translation table specified by
864
<emphasis remap='I'>translations</emphasis> is not altered by this process.
865
<xref linkend='XtAugmentTranslations' xrefstyle='select: title'/>
866
logically appends the string representation of the new translations to
867
the string representation of the widget's current translations and reparses
868
the result with no warning messages about duplicate left-hand sides, then
869
stores the result back into the widget instance; i.e.,
870
if the new translations contain an event or event sequence that
871
already exists in the widget's translations,
872
the new translation is ignored.
873
</para>
874
875
<para>
876
To overwrite existing translations with new translations, use
877
<xref linkend='XtOverrideTranslations' xrefstyle='select: title'/>.
878
</para>
879
880
<funcsynopsis id='XtOverrideTranslations'>
881
<funcprototype>
882
<funcdef>void <function>XtOverrideTranslations</function></funcdef>
883
<paramdef>Widget <parameter>w</parameter></paramdef>
884
<paramdef>XtTranslations <parameter>translations</parameter></paramdef>
885
</funcprototype>
886
</funcsynopsis>
887
888
<variablelist>
889
<varlistentry>
890
<term>
891
<emphasis remap='I'>w</emphasis>
892
</term>
893
<listitem>
894
<para>
895
Specifies the widget into which the new translations are to be merged. Must be of class Core or any subclass thereof.
896
</para>
897
</listitem>
898
</varlistentry>
899
<varlistentry>
900
<term>
901
<emphasis remap='I'>translations</emphasis>
902
</term>
903
<listitem>
904
<para>
905
Specifies the compiled translation table to merge in.
906
</para>
907
</listitem>
908
</varlistentry>
909
</variablelist>
910
911
<para>
912
The
913
<xref linkend='XtOverrideTranslations' xrefstyle='select: title'/>
914
function merges the new translations into the existing widget
915
translations, ignoring any
916
<function>#replace</function>,
917
<function>#augment</function>,
918
or
919
<function>#override</function>
920
directive that may have been
921
specified in the translation string. The translation table
922
specified by <emphasis remap='I'>translations</emphasis> is not altered by this process.
923
<xref linkend='XtOverrideTranslations' xrefstyle='select: title'/>
924
logically appends the string representation of the widget's current
925
translations to the string representation of the new translations and
926
reparses the result with no warning messages about duplicate left-hand
927
sides, then stores the result back into the widget instance; i.e.,
928
if the new translations contain an event or event sequence that
929
already exists in the widget's translations,
930
the new translation overrides the widget's translation.
931
</para>
932
933
<para>
934
To replace a widget's translations completely, use
935
<xref linkend='XtSetValues' xrefstyle='select: title'/>
936
on the XtNtranslations resource and specify a compiled translation table
937
as the value.
938
</para>
939
940
<para>
941
To make it possible for users to easily modify translation tables in their
942
resource files,
943
the string-to-translation-table resource type converter
944
allows the string to specify whether the table should replace,
945
augment, or override any
946
existing translation table in the widget.
947
To specify this,
948
a pound sign (#) is given as the first character of the table
949
followed by one of the keywords ``replace'', ``augment'', or
950
``override'' to indicate
951
whether to replace, augment, or override the existing table.
952
The replace or merge
953
operation is performed during the
954
Core
955
instance initialization.
956
Each merge operation produces a new
957
translation resource value; if the original tables were shared by
958
other widgets, they are unaffected. If no directive is
959
specified, ``#replace'' is assumed.
960
</para>
961
962
<para>
963
At instance initialization
964
the XtNtranslations resource is first fetched. Then, if it was
965
not specified or did not contain ``#replace'', the
966
resource database is searched for the resource XtNbaseTranslations.
967
If XtNbaseTranslations is found, it is merged into the widget class
968
translation table. Then the widget <emphasis remap='I'>translations</emphasis> field is
969
merged into the result or into the class translation table if
970
XtNbaseTranslations was not found. This final table is then
971
stored into the widget <emphasis remap='I'>translations</emphasis> field. If the XtNtranslations
972
resource specified ``#replace'', no merge is done.
973
If neither XtNbaseTranslations or XtNtranslations are specified,
974
the class translation table is copied into the widget instance.
975
</para>
976
977
<para>
978
To completely remove existing translations, use
979
<xref linkend='XtUninstallTranslations' xrefstyle='select: title'/>.
980
</para>
981
982
<funcsynopsis id='XtUninstallTranslations'>
983
<funcprototype>
984
<funcdef>void <function>XtUninstallTranslations</function></funcdef>
985
<paramdef>Widget <parameter>w</parameter></paramdef>
986
</funcprototype>
987
</funcsynopsis>
988
989
<variablelist>
990
<varlistentry>
991
<term>
992
<emphasis remap='I'>w</emphasis>
993
</term>
994
<listitem>
995
<para>
996
Specifies the widget from which the translations are to be removed. Must be of class Core or any subclass thereof.
997
</para>
998
</listitem>
999
</varlistentry>
1000
</variablelist>
1001
1002
<para>
1003
The
1004
<xref linkend='XtUninstallTranslations' xrefstyle='select: title'/>
1005
function causes the entire translation table for the widget to be removed.
1006
</para>
1007
</sect1>
1008
1009
<sect1 id="Using_Accelerators">
1010
<title>Using Accelerators</title>
1011
<para>
1012
It is often desirable to be able to bind events in one widget to actions in
1013
another.
1014
In particular,
1015
it is often useful to be able to invoke menu actions from the keyboard.
1016
The Intrinsics provide a facility, called accelerators, that lets you
1017
accomplish this.
1018
An accelerator table is a translation table that is bound with its
1019
actions in the context of a particular widget, the <emphasis remap='I'>source</emphasis> widget.
1020
The accelerator table can then be installed on one or more <emphasis remap='I'>destination</emphasis> widgets.
1021
When an event sequence in the destination widget would cause an
1022
accelerator action to be taken, and if the source widget is sensitive,
1023
the actions are executed as though triggered by the same event sequence
1024
in the accelerator source
1025
widget. The event is
1026
passed to the action procedure without modification. The action
1027
procedures used within accelerators must not assume that the source
1028
widget is realized nor that any fields of the event are in reference
1029
to the source widget's window if the widget is realized.
1030
</para>
1031
1032
<para>
1033
Each widget instance contains that widget's exported accelerator table
1034
as a resource.
1035
Each class of widget exports a method that takes a
1036
displayable string representation of the accelerators
1037
so that widgets can display their current accelerators.
1038
The representation is the accelerator table in canonical
1039
translation table form (see Appendix B).
1040
The display_accelerator procedure pointer is of type
1041
<xref linkend='XtStringProc' xrefstyle='select: title'/>.
1042
</para>
1043
1044
<funcsynopsis id='XtStringProc'>
1045
<funcprototype>
1046
<funcdef>typedef void <function>(*XtStringProc)</function></funcdef>
1047
<paramdef>Widget <parameter>w</parameter></paramdef>
1048
<paramdef>String <parameter>string</parameter></paramdef>
1049
</funcprototype>
1050
</funcsynopsis>
1051
1052
<variablelist>
1053
<varlistentry>
1054
<term>
1055
<emphasis remap='I'>w</emphasis>
1056
</term>
1057
<listitem>
1058
<para>
1059
Specifies the source widget that supplied the accelerators.
1060
</para>
1061
</listitem>
1062
</varlistentry>
1063
<varlistentry>
1064
<term>
1065
<emphasis remap='I'>string</emphasis>
1066
</term>
1067
<listitem>
1068
<para>
1069
Specifies the string representation of the accelerators for this widget.
1070
</para>
1071
</listitem>
1072
</varlistentry>
1073
</variablelist>
1074
1075
<para>
1076
Accelerators can be specified in resource files,
1077
and the string representation is the same as for a translation table.
1078
However,
1079
the interpretation of the
1080
<function>#augment</function>
1081
and
1082
<function>#override</function>
1083
directives applies to
1084
what will happen when the accelerator is installed;
1085
that is, whether or not the accelerator translations will override the
1086
translations in the destination widget.
1087
The default is
1088
<function>#augment</function>,
1089
which means that the accelerator translations have lower priority
1090
than the destination translations.
1091
The
1092
<function>#replace</function>
1093
directive is ignored for accelerator tables.
1094
</para>
1095
1096
<para>
1097
To parse an accelerator table, use
1098
<xref linkend='XtParseAcceleratorTable' xrefstyle='select: title'/>.
1099
</para>
1100
1101
<funcsynopsis id='XtParseAcceleratorTable'>
1102
<funcprototype>
1103
<funcdef>XtAccelerators <function>XtParseAcceleratorTable</function></funcdef>
1104
<paramdef>String <parameter>source</parameter></paramdef>
1105
</funcprototype>
1106
</funcsynopsis>
1107
1108
<variablelist>
1109
<varlistentry>
1110
<term>
1111
<emphasis remap='I'>source</emphasis>
1112
</term>
1113
<listitem>
1114
<para>
1115
Specifies the accelerator table to compile.
1116
</para>
1117
</listitem>
1118
</varlistentry>
1119
</variablelist>
1120
1121
<para>
1122
The
1123
<xref linkend='XtParseAcceleratorTable' xrefstyle='select: title'/>
1124
function compiles the accelerator table into an opaque internal representation.
1125
The client
1126
should set the XtNaccelerators resource of
1127
each widget that is to be activated by these translations
1128
to the returned value.
1129
</para>
1130
1131
<para>
1132
To install accelerators from a widget on another widget, use
1133
<xref linkend='XtInstallAccelerators' xrefstyle='select: title'/>.
1134
</para>
1135
1136
<funcsynopsis id='XtInstallAccelerators'>
1137
<funcprototype>
1138
<funcdef>void <function>XtInstallAccelerators</function></funcdef>
1139
<paramdef>Widget <parameter>destination</parameter></paramdef>
1140
<paramdef>Widget <parameter>source</parameter></paramdef>
1141
</funcprototype>
1142
</funcsynopsis>
1143
1144
<variablelist>
1145
<varlistentry>
1146
<term>
1147
<emphasis remap='I'>destination</emphasis>
1148
</term>
1149
<listitem>
1150
<para>
1151
Specifies the widget on which the accelerators are to be installed. Must be of class Core or any subclass thereof.
1152
</para>
1153
</listitem>
1154
</varlistentry>
1155
<varlistentry>
1156
<term>
1157
<emphasis remap='I'>source</emphasis>
1158
</term>
1159
<listitem>
1160
<para>
1161
Specifies the widget from which the accelerators are to come. Must be of class Core or any subclass thereof.
1162
</para>
1163
</listitem>
1164
</varlistentry>
1165
</variablelist>
1166
1167
<para>
1168
The
1169
<xref linkend='XtInstallAccelerators' xrefstyle='select: title'/>
1170
function installs the <emphasis remap='I'>accelerators</emphasis> resource value from
1171
<emphasis remap='I'>source</emphasis> onto <emphasis remap='I'>destination</emphasis>
1172
by merging the source accelerators into the destination translations.
1173
If the source <emphasis remap='I'>display_accelerator</emphasis> field is non-NULL,
1174
<xref linkend='XtInstallAccelerators' xrefstyle='select: title'/>
1175
calls it with the source widget and a string representation
1176
of the accelerator table,
1177
which indicates that its accelerators have been installed
1178
and that it should display them appropriately.
1179
The string representation of the accelerator table is its
1180
canonical translation table representation.
1181
</para>
1182
1183
<para>
1184
As a convenience for installing all accelerators from a widget and all its
1185
descendants onto one destination, use
1186
<xref linkend='XtInstallAllAccelerators' xrefstyle='select: title'/>.
1187
</para>
1188
1189
<funcsynopsis id='XtInstallAllAccelerators'>
1190
<funcprototype>
1191
<funcdef>void <function>XtInstallAllAccelerators</function></funcdef>
1192
<paramdef>Widget <parameter>destination</parameter></paramdef>
1193
<paramdef>Widget <parameter>source</parameter></paramdef>
1194
</funcprototype>
1195
</funcsynopsis>
1196
1197
<variablelist>
1198
<varlistentry>
1199
<term>
1200
<emphasis remap='I'>destination</emphasis>
1201
</term>
1202
<listitem>
1203
<para>
1204
Specifies the widget on which the accelerators are to be installed. Must be of class Core or any subclass thereof.
1205
</para>
1206
</listitem>
1207
</varlistentry>
1208
<varlistentry>
1209
<term>
1210
<emphasis remap='I'>source</emphasis>
1211
</term>
1212
<listitem>
1213
<para>
1214
Specifies the root widget of the widget tree
1215
from which the accelerators are to come. Must be of class Core or any subclass thereof.
1216
</para>
1217
</listitem>
1218
</varlistentry>
1219
</variablelist>
1220
1221
<para>
1222
The
1223
<xref linkend='XtInstallAllAccelerators' xrefstyle='select: title'/>
1224
function recursively descends the widget tree rooted at <emphasis remap='I'>source</emphasis>
1225
and installs the accelerators resource value
1226
of each widget encountered onto <emphasis remap='I'>destination</emphasis>.
1227
A common use is to call
1228
<xref linkend='XtInstallAllAccelerators' xrefstyle='select: title'/>
1229
and pass the application main window as the source.
1230
</para>
1231
</sect1>
1232
1233
<sect1 id="KeyCode_to_KeySym_Conversions">
1234
<title>KeyCode-to-KeySym Conversions</title>
1235
<para>
1236
The translation manager provides support for automatically translating
1237
KeyCodes in incoming key events into KeySyms.
1238
KeyCode-to-KeySym translator procedure pointers are of type
1239
<xref linkend='XtKeyProc' xrefstyle='select: title'/>.
1240
</para>
1241
1242
<funcsynopsis id='XtKeyProc'>
1243
<funcprototype>
1244
<funcdef>typedef void <function>(*XtKeyProc)</function></funcdef>
1245
<paramdef>Display *<parameter>display</parameter></paramdef>
1246
<paramdef>KeyCode <parameter>keycode</parameter></paramdef>
1247
<paramdef>Modifiers <parameter>modifiers</parameter></paramdef>
1248
<paramdef>Modifiers *<parameter>modifiers_return</parameter></paramdef>
1249
<paramdef>KeySym *<parameter>keysym_return</parameter></paramdef>
1250
</funcprototype>
1251
</funcsynopsis>
1252
1253
<variablelist>
1254
<varlistentry>
1255
<term>
1256
<emphasis remap='I'>display</emphasis>
1257
</term>
1258
<listitem>
1259
<para>
1260
Specifies the display that the KeyCode is from.
1261
</para>
1262
</listitem>
1263
</varlistentry>
1264
<varlistentry>
1265
<term>
1266
<emphasis remap='I'>keycode</emphasis>
1267
</term>
1268
<listitem>
1269
<para>
1270
Specifies the KeyCode to translate.
1271
</para>
1272
</listitem>
1273
</varlistentry>
1274
<varlistentry>
1275
<term>
1276
<emphasis remap='I'>modifiers</emphasis>
1277
</term>
1278
<listitem>
1279
<para>
1280
Specifies the modifiers to the KeyCode.
1281
</para>
1282
</listitem>
1283
</varlistentry>
1284
<varlistentry>
1285
<term>
1286
<emphasis remap='I'>modifiers_return</emphasis>
1287
</term>
1288
<listitem>
1289
<para>
1290
Specifies a location in which to store
1291
a mask that indicates the subset of all
1292
modifiers that are examined by the key translator for the specified keycode.
1293
</para>
1294
</listitem>
1295
</varlistentry>
1296
<varlistentry>
1297
<term>
1298
<emphasis remap='I'>keysym_return</emphasis>
1299
</term>
1300
<listitem>
1301
<para>
1302
Specifies a location in which to store the resulting KeySym.
1303
</para>
1304
</listitem>
1305
</varlistentry>
1306
</variablelist>
1307
1308
<para>
1309
This procedure takes a KeyCode and modifiers and produces a KeySym.
1310
For any given key translator function and keyboard encoding,
1311
<emphasis remap='I'>modifiers_return</emphasis> will be a constant per KeyCode that indicates
1312
the subset of all modifiers that are examined by the key translator
1313
for that KeyCode.
1314
</para>
1315
1316
<para>
1317
The KeyCode-to-KeySym translator procedure
1318
must be implemented such that multiple calls with the same
1319
<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>keycode</emphasis>, and <emphasis remap='I'>modifiers</emphasis> return the same
1320
result until either a new case converter, an
1321
<xref linkend='XtCaseProc' xrefstyle='select: title'/>,
1322
is installed or a
1323
<function>MappingNotify</function>
1324
event is received.
1325
</para>
1326
1327
<para>
1328
The Intrinsics maintain tables internally to map KeyCodes to KeySyms
1329
for each open display. Translator procedures and other clients may
1330
share a single copy of this table to perform the same mapping.
1331
</para>
1332
1333
<para>
1334
To return a pointer to the KeySym-to-KeyCode mapping table for a
1335
particular display, use
1336
<xref linkend='XtGetKeysymTable' xrefstyle='select: title'/>.
1337
</para>
1338
1339
<funcsynopsis id='XtGetKeysymTable'>
1340
<funcprototype>
1341
<funcdef>KeySym *<function>XtGetKeysymTable</function></funcdef>
1342
<paramdef>Display *<parameter>display</parameter></paramdef>
1343
<paramdef>KeyCode *<parameter>min_keycode_return</parameter></paramdef>
1344
<paramdef>int *<parameter>keysyms_per_keycode_return</parameter></paramdef>
1345
</funcprototype>
1346
</funcsynopsis>
1347
1348
<variablelist>
1349
<varlistentry>
1350
<term>
1351
<emphasis remap='I'>display</emphasis>
1352
</term>
1353
<listitem>
1354
<para>
1355
Specifies the display whose table is required.
1356
</para>
1357
</listitem>
1358
</varlistentry>
1359
<varlistentry>
1360
<term>
1361
<emphasis remap='I'>min_keycode_return</emphasis>
1362
</term>
1363
<listitem>
1364
<para>
1365
Returns the minimum KeyCode valid for the display.
1366
</para>
1367
</listitem>
1368
</varlistentry>
1369
<varlistentry>
1370
<term>
1371
<emphasis remap='I'>keysyms_per_keycode_return</emphasis>
1372
</term>
1373
<listitem>
1374
<para>
1375
Returns the number of KeySyms stored for each KeyCode.
1376
</para>
1377
</listitem>
1378
</varlistentry>
1379
</variablelist>
1380
1381
<para>
1382
<xref linkend='XtGetKeysymTable' xrefstyle='select: title'/>
1383
returns a pointer to the Intrinsics' copy of the
1384
server's KeyCode-to-KeySym table. This table must not be modified.
1385
There are <emphasis remap='I'>keysyms_per_keycode_return</emphasis> KeySyms associated with each
1386
KeyCode, located in the table with indices starting at index
1387
</para>
1388
<literallayout>
1389
(test_keycode - min_keycode_return) * keysyms_per_keycode_return
1390
</literallayout>
1391
<para>
1392
for KeyCode <emphasis remap='I'>test_keycode</emphasis>. Any entries that have no KeySyms associated
1393
with them contain the value
1394
<function>NoSymbol</function>.
1395
Clients should not cache the KeySym table but should call
1396
<xref linkend='XtGetKeysymTable' xrefstyle='select: title'/>
1397
each time the value is
1398
needed, as the table may change prior to dispatching each event.
1399
</para>
1400
1401
<para>
1402
For more information on this table, see
1403
<olink targetdoc='libX11' targetptr='Manipulating_the_Keyboard_Encoding'>Section 12.7</olink> in
1404
<olink targetdoc='libX11' targetptr='libX11'>Xlib — C Language X Interface.</olink>.
1405
</para>
1406
1407
<para>
1408
To register a key translator, use
1409
<xref linkend='XtSetKeyTranslator' xrefstyle='select: title'/>.
1410
</para>
1411
1412
<funcsynopsis id='XtSetKeyTranslator'>
1413
<funcprototype>
1414
<funcdef>void <function>XtSetKeyTranslator</function></funcdef>
1415
<paramdef>Display *<parameter>display</parameter></paramdef>
1416
<paramdef>XtKeyProc <parameter>proc</parameter></paramdef>
1417
</funcprototype>
1418
</funcsynopsis>
1419
1420
<variablelist>
1421
<varlistentry>
1422
<term>
1423
<emphasis remap='I'>display</emphasis>
1424
</term>
1425
<listitem>
1426
<para>
1427
Specifies the display from which to translate the events.
1428
</para>
1429
</listitem>
1430
</varlistentry>
1431
<varlistentry>
1432
<term>
1433
<emphasis remap='I'>proc</emphasis>
1434
</term>
1435
<listitem>
1436
<para>
1437
Specifies the procedure to perform key translations.
1438
</para>
1439
</listitem>
1440
</varlistentry>
1441
</variablelist>
1442
1443
<para>
1444
The
1445
<xref linkend='XtSetKeyTranslator' xrefstyle='select: title'/>
1446
function sets the specified procedure as the current key translator.
1447
The default translator is
1448
<function>XtTranslateKey</function>,
1449
an
1450
<xref linkend='XtKeyProc' xrefstyle='select: title'/>
1451
that uses the Shift, Lock, numlock, and group modifiers
1452
with the interpretations defined in <emphasis remap='I'>X Window System Protocol</emphasis>, Section 5.
1453
It is provided so that new translators can call it to get default
1454
KeyCode-to-KeySym translations and so that the default translator
1455
can be reinstalled.
1456
</para>
1457
1458
<para>
1459
To invoke the currently registered KeyCode-to-KeySym translator,
1460
use
1461
<xref linkend='XtTranslateKeycode' xrefstyle='select: title'/>.
1462
</para>
1463
1464
<funcsynopsis id='XtTranslateKeycode'>
1465
<funcprototype>
1466
<funcdef>void <function>XtTranslateKeycode</function></funcdef>
1467
<paramdef>Display *<parameter>display</parameter></paramdef>
1468
<paramdef>KeyCode <parameter>keycode</parameter></paramdef>
1469
<paramdef>Modifiers <parameter>modifiers</parameter></paramdef>
1470
<paramdef>Modifiers *<parameter>modifiers_return</parameter></paramdef>
1471
<paramdef>KeySym *<parameter>keysym_return</parameter></paramdef>
1472
</funcprototype>
1473
</funcsynopsis>
1474
1475
<variablelist>
1476
<varlistentry>
1477
<term>
1478
<emphasis remap='I'>display</emphasis>
1479
</term>
1480
<listitem>
1481
<para>
1482
Specifies the display that the KeyCode is from.
1483
</para>
1484
</listitem>
1485
</varlistentry>
1486
<varlistentry>
1487
<term>
1488
<emphasis remap='I'>keycode</emphasis>
1489
</term>
1490
<listitem>
1491
<para>
1492
Specifies the KeyCode to translate.
1493
</para>
1494
</listitem>
1495
</varlistentry>
1496
<varlistentry>
1497
<term>
1498
<emphasis remap='I'>modifiers</emphasis>
1499
</term>
1500
<listitem>
1501
<para>
1502
Specifies the modifiers to the KeyCode.
1503
</para>
1504
</listitem>
1505
</varlistentry>
1506
<varlistentry>
1507
<term>
1508
<emphasis remap='I'>modifiers_return</emphasis>
1509
</term>
1510
<listitem>
1511
<para>
1512
Returns a mask that indicates the modifiers actually used
1513
to generate the KeySym.
1514
</para>
1515
</listitem>
1516
</varlistentry>
1517
<varlistentry>
1518
<term>
1519
<emphasis remap='I'>keysym_return</emphasis>
1520
</term>
1521
<listitem>
1522
<para>
1523
Returns the resulting KeySym.
1524
</para>
1525
</listitem>
1526
</varlistentry>
1527
</variablelist>
1528
1529
<para>
1530
The
1531
<xref linkend='XtTranslateKeycode' xrefstyle='select: title'/>
1532
function passes the specified arguments
1533
directly to the currently registered KeyCode-to-KeySym translator.
1534
</para>
1535
1536
<para>
1537
To handle capitalization of nonstandard KeySyms, the Intrinsics allow
1538
clients to register case conversion routines.
1539
Case converter procedure pointers are of type
1540
<xref linkend='XtCaseProc' xrefstyle='select: title'/>.
1541
</para>
1542
1543
<funcsynopsis id='XtCaseProc'>
1544
<funcprototype>
1545
<funcdef>typedef void <function>(*XtCaseProc)</function></funcdef>
1546
<paramdef>Display *<parameter>display</parameter></paramdef>
1547
<paramdef>KeySym <parameter>keysym</parameter></paramdef>
1548
<paramdef>KeySym *<parameter>lower_return</parameter></paramdef>
1549
<paramdef>KeySym *<parameter>upper_return</parameter></paramdef>
1550
</funcprototype>
1551
</funcsynopsis>
1552
1553
<variablelist>
1554
<varlistentry>
1555
<term>
1556
<emphasis remap='I'>display</emphasis>
1557
</term>
1558
<listitem>
1559
<para>
1560
Specifies the display connection for which the conversion is required.
1561
</para>
1562
</listitem>
1563
</varlistentry>
1564
<varlistentry>
1565
<term>
1566
<emphasis remap='I'>keysym</emphasis>
1567
</term>
1568
<listitem>
1569
<para>
1570
Specifies the KeySym to convert.
1571
</para>
1572
</listitem>
1573
</varlistentry>
1574
<varlistentry>
1575
<term>
1576
<emphasis remap='I'>lower_return</emphasis>
1577
</term>
1578
<listitem>
1579
<para>
1580
Specifies a location into which to store the lowercase equivalent for
1581
the KeySym.
1582
</para>
1583
</listitem>
1584
</varlistentry>
1585
<varlistentry>
1586
<term>
1587
<emphasis remap='I'>upper_return</emphasis>
1588
</term>
1589
<listitem>
1590
<para>
1591
Specifies a location into which to store the uppercase equivalent for
1592
the KeySym.
1593
</para>
1594
</listitem>
1595
</varlistentry>
1596
</variablelist>
1597
1598
<para>
1599
If there is no case distinction,
1600
this procedure should store the KeySym into both return values.
1601
</para>
1602
1603
<para>
1604
To register a case converter, use
1605
<xref linkend='XtRegisterCaseConverter' xrefstyle='select: title'/>.
1606
</para>
1607
1608
<funcsynopsis id='XtRegisterCaseConverter'>
1609
<funcprototype>
1610
<funcdef>void <function>XtRegisterCaseConverter</function></funcdef>
1611
<paramdef>Display *<parameter>display</parameter></paramdef>
1612
<paramdef>XtCaseProc <parameter>proc</parameter></paramdef>
1613
<paramdef>KeySym <parameter>start</parameter></paramdef>
1614
<paramdef>KeySym <parameter>stop</parameter></paramdef>
1615
</funcprototype>
1616
</funcsynopsis>
1617
1618
<variablelist>
1619
<varlistentry>
1620
<term>
1621
<emphasis remap='I'>display</emphasis>
1622
</term>
1623
<listitem>
1624
<para>
1625
Specifies the display from which the key events are to come.
1626
</para>
1627
</listitem>
1628
</varlistentry>
1629
<varlistentry>
1630
<term>
1631
<emphasis remap='I'>proc</emphasis>
1632
</term>
1633
<listitem>
1634
<para>
1635
Specifies the
1636
<xref linkend='XtCaseProc' xrefstyle='select: title'/>
1637
to do the conversions.
1638
</para>
1639
</listitem>
1640
</varlistentry>
1641
<varlistentry>
1642
<term>
1643
<emphasis remap='I'>start</emphasis>
1644
</term>
1645
<listitem>
1646
<para>
1647
Specifies the first KeySym for which this converter is valid.
1648
</para>
1649
</listitem>
1650
</varlistentry>
1651
<varlistentry>
1652
<term>
1653
<emphasis remap='I'>stop</emphasis>
1654
</term>
1655
<listitem>
1656
<para>
1657
Specifies the last KeySym for which this converter is valid.
1658
</para>
1659
</listitem>
1660
</varlistentry>
1661
</variablelist>
1662
1663
<para>
1664
The
1665
<xref linkend='XtRegisterCaseConverter' xrefstyle='select: title'/>
1666
registers the specified case converter.
1667
The <emphasis remap='I'>start</emphasis> and <emphasis remap='I'>stop</emphasis> arguments provide the inclusive range of KeySyms
1668
for which this converter is to be called.
1669
The new converter overrides any previous converters for KeySyms in that range.
1670
No interface exists to remove converters;
1671
you need to register an identity converter.
1672
When a new converter is registered,
1673
the Intrinsics refresh the keyboard state if necessary.
1674
The default converter understands case conversion for all
1675
Latin KeySyms defined in <emphasis remap='I'>X Window System Protocol</emphasis>, Appendix A.
1676
</para>
1677
1678
<para>
1679
To determine uppercase and lowercase equivalents for a KeySym, use
1680
<xref linkend='XtConvertCase' xrefstyle='select: title'/>.
1681
</para>
1682
1683
<funcsynopsis id='XtConvertCase'>
1684
<funcprototype>
1685
<funcdef>void <function>XtConvertCase</function></funcdef>
1686
<paramdef>Display *<parameter>display</parameter></paramdef>
1687
<paramdef>KeySym <parameter>keysym</parameter></paramdef>
1688
<paramdef>KeySym *<parameter>lower_return</parameter></paramdef>
1689
<paramdef>KeySym *<parameter>upper_return</parameter></paramdef>
1690
</funcprototype>
1691
</funcsynopsis>
1692
1693
<variablelist>
1694
<varlistentry>
1695
<term>
1696
<emphasis remap='I'>display</emphasis>
1697
</term>
1698
<listitem>
1699
<para>
1700
Specifies the display that the KeySym came from.
1701
</para>
1702
</listitem>
1703
</varlistentry>
1704
<varlistentry>
1705
<term>
1706
<emphasis remap='I'>keysym</emphasis>
1707
</term>
1708
<listitem>
1709
<para>
1710
Specifies the KeySym to convert.
1711
</para>
1712
</listitem>
1713
</varlistentry>
1714
<varlistentry>
1715
<term>
1716
<emphasis remap='I'>lower_return</emphasis>
1717
</term>
1718
<listitem>
1719
<para>
1720
Returns the lowercase equivalent of the KeySym.
1721
</para>
1722
</listitem>
1723
</varlistentry>
1724
<varlistentry>
1725
<term>
1726
<emphasis remap='I'>upper_return</emphasis>
1727
</term>
1728
<listitem>
1729
<para>
1730
Returns the uppercase equivalent of the KeySym.
1731
</para>
1732
</listitem>
1733
</varlistentry>
1734
</variablelist>
1735
1736
<para>
1737
The
1738
<xref linkend='XtConvertCase' xrefstyle='select: title'/>
1739
function calls the appropriate converter and returns the results.
1740
A user-supplied
1741
<xref linkend='XtKeyProc' xrefstyle='select: title'/>
1742
may need to use this function.
1743
</para>
1744
</sect1>
1745
1746
<sect1 id="Obtaining_a_KeySym_in_an_Action_Procedure">
1747
<title>Obtaining a KeySym in an Action Procedure</title>
1748
<para>
1749
When an action procedure is invoked on a
1750
<function>KeyPress</function>
1751
or
1752
<function>KeyRelease</function>
1753
event, it often has a need to retrieve the KeySym and modifiers
1754
corresponding to the event that caused it to be invoked. In order to
1755
avoid repeating the processing that was just performed by the
1756
Intrinsics to match the translation entry, the KeySym and modifiers
1757
are stored for the duration of the action procedure and are made
1758
available to the client.
1759
</para>
1760
1761
<para>
1762
To retrieve the KeySym and modifiers that matched the final event
1763
specification in the translation table entry, use
1764
<xref linkend='XtGetActionKeysym' xrefstyle='select: title'/>.
1765
</para>
1766
1767
<funcsynopsis id='XtGetActionKeysym'>
1768
<funcprototype>
1769
<funcdef>KeySym <function>XtGetActionKeysym</function></funcdef>
1770
<paramdef>XEvent *<parameter>event</parameter></paramdef>
1771
<paramdef>Modifiers *<parameter>modifiers_return</parameter></paramdef>
1772
</funcprototype>
1773
</funcsynopsis>
1774
1775
<variablelist>
1776
<varlistentry>
1777
<term>
1778
<emphasis remap='I'>event</emphasis>
1779
</term>
1780
<listitem>
1781
<para>
1782
Specifies the event pointer passed to the action procedure by the Intrinsics.
1783
</para>
1784
</listitem>
1785
</varlistentry>
1786
<varlistentry>
1787
<term>
1788
<emphasis remap='I'>modifiers_return</emphasis>
1789
</term>
1790
<listitem>
1791
<para>
1792
Returns the modifiers that caused the match, if non-NULL.
1793
</para>
1794
</listitem>
1795
</varlistentry>
1796
</variablelist>
1797
1798
<para>
1799
If
1800
<xref linkend='XtGetActionKeysym' xrefstyle='select: title'/>
1801
is called after an action procedure has been
1802
invoked by the Intrinsics and before that action procedure returns, and
1803
if the event pointer has the same value as the event pointer passed to
1804
that action routine, and if the event is a
1805
<function>KeyPress</function>
1806
or
1807
<function>KeyRelease</function>
1808
event, then
1809
<xref linkend='XtGetActionKeysym' xrefstyle='select: title'/>
1810
returns the KeySym that matched the final
1811
event specification in the translation table and, if <emphasis remap='I'>modifiers_return</emphasis>
1812
is non-NULL, the modifier state actually used to generate this KeySym;
1813
otherwise, if the event is a
1814
<function>KeyPress</function>
1815
or
1816
<function>KeyRelease</function>
1817
event, then
1818
<xref linkend='XtGetActionKeysym' xrefstyle='select: title'/>
1819
calls
1820
<xref linkend='XtTranslateKeycode' xrefstyle='select: title'/>
1821
and returns the results;
1822
else it returns
1823
<function>NoSymbol</function>
1824
and does not examine <emphasis remap='I'>modifiers_return</emphasis>.
1825
</para>
1826
1827
<para>
1828
Note that if an action procedure invoked by the Intrinsics
1829
invokes a subsequent action procedure (and so on) via
1830
<xref linkend='XtCallActionProc' xrefstyle='select: title'/>,
1831
the nested action procedure may also call
1832
<xref linkend='XtGetActionKeysym' xrefstyle='select: title'/>
1833
to retrieve the Intrinsics' KeySym and modifiers.
1834
</para>
1835
</sect1>
1836
1837
<sect1 id="KeySym_to_KeyCode_Conversions">
1838
<title>KeySym-to-KeyCode Conversions</title>
1839
<para>
1840
To return the list of KeyCodes that map to a particular KeySym in
1841
the keyboard mapping table maintained by the Intrinsics, use
1842
<xref linkend='XtKeysymToKeycodeList' xrefstyle='select: title'/>.
1843
</para>
1844
1845
<funcsynopsis id='XtKeysymToKeycodeList'>
1846
<funcprototype>
1847
<funcdef>void <function>XtKeysymToKeycodeList</function></funcdef>
1848
<paramdef>Display *<parameter>display</parameter></paramdef>
1849
<paramdef>KeySym <parameter>keysym</parameter></paramdef>
1850
<paramdef>KeyCode **<parameter>keycodes_return</parameter></paramdef>
1851
<paramdef>Cardinal *<parameter>keycount_return</parameter></paramdef>
1852
</funcprototype>
1853
</funcsynopsis>
1854
1855
<variablelist>
1856
<varlistentry>
1857
<term>
1858
<emphasis remap='I'>display</emphasis>
1859
</term>
1860
<listitem>
1861
<para>
1862
Specifies the display whose table is required.
1863
</para>
1864
</listitem>
1865
</varlistentry>
1866
<varlistentry>
1867
<term>
1868
<emphasis remap='I'>keysym</emphasis>
1869
</term>
1870
<listitem>
1871
<para>
1872
Specifies the KeySym for which to search.
1873
</para>
1874
</listitem>
1875
</varlistentry>
1876
<varlistentry>
1877
<term>
1878
<emphasis remap='I'>keycodes_return</emphasis>
1879
</term>
1880
<listitem>
1881
<para>
1882
Returns a list of KeyCodes that have <emphasis remap='I'>keysym</emphasis>
1883
associated with them, or NULL if <emphasis remap='I'>keycount_return</emphasis> is 0.
1884
</para>
1885
</listitem>
1886
</varlistentry>
1887
<varlistentry>
1888
<term>
1889
<emphasis remap='I'>keycount_return</emphasis>
1890
</term>
1891
<listitem>
1892
<para>
1893
Returns the number of KeyCodes in the keycode list.
1894
</para>
1895
</listitem>
1896
</varlistentry>
1897
</variablelist>
1898
1899
<para>
1900
The
1901
<xref linkend='XtKeysymToKeycodeList' xrefstyle='select: title'/>
1902
procedure returns all the KeyCodes that have <emphasis remap='I'>keysym</emphasis>
1903
in their entry for the keyboard mapping table associated with <emphasis remap='I'>display</emphasis>.
1904
For each entry in the
1905
table, the first four KeySyms (groups 1 and 2) are interpreted as
1906
specified by <emphasis remap='I'>X Window System Protocol</emphasis>, Section 5. If no KeyCodes map to the
1907
specified KeySym, <emphasis remap='I'>keycount_return</emphasis> is zero and *<emphasis remap='I'>keycodes_return</emphasis> is NULL.
1908
</para>
1909
1910
<para>
1911
The caller should free the storage pointed to by <emphasis remap='I'>keycodes_return</emphasis> using
1912
<xref linkend='XtFree' xrefstyle='select: title'/>
1913
when it is no longer useful. If the caller needs to examine
1914
the KeyCode-to-KeySym table for a particular KeyCode, it should call
1915
<xref linkend='XtGetKeysymTable' xrefstyle='select: title'/>.
1916
</para>
1917
</sect1>
1918
1919
<sect1 id="Registering_Button_and_Key_Grabs_for_Actions">
1920
<title>Registering Button and Key Grabs for Actions</title>
1921
<para>
1922
To register button and key grabs for a widget's window according to the
1923
event bindings in the widget's translation table, use
1924
<xref linkend='XtRegisterGrabAction' xrefstyle='select: title'/>.
1925
</para>
1926
1927
<funcsynopsis id='XtRegisterGrabAction'>
1928
<funcprototype>
1929
<funcdef>void <function>XtRegisterGrabAction</function></funcdef>
1930
<paramdef>XtActionProc <parameter>action_proc</parameter></paramdef>
1931
<paramdef>Boolean <parameter>owner_events</parameter></paramdef>
1932
<paramdef>unsigned int <parameter>event_mask</parameter></paramdef>
1933
<paramdef>int <parameter>pointer_mode</parameter></paramdef>
1934
</funcprototype>
1935
</funcsynopsis>
1936
1937
<variablelist>
1938
<varlistentry>
1939
<term>
1940
<emphasis remap='I'>action_proc</emphasis>
1941
</term>
1942
<listitem>
1943
<para>
1944
Specifies the action procedure to search for in translation tables.
1945
</para>
1946
</listitem>
1947
</varlistentry>
1948
<varlistentry>
1949
<term>
1950
<emphasis remap='I'>owner_events</emphasis>
1951
</term>
1952
<listitem>
1953
<para></para>
1954
1955
</listitem>
1956
</varlistentry>
1957
<varlistentry>
1958
<term>
1959
<emphasis remap='I'>event_mask</emphasis>
1960
</term>
1961
<listitem>
1962
<para></para>
1963
1964
</listitem>
1965
</varlistentry>
1966
<varlistentry>
1967
<term>
1968
<emphasis remap='I'>pointer_mode</emphasis>
1969
</term>
1970
<listitem>
1971
<para></para>
1972
</listitem>
1973
</varlistentry>
1974
<varlistentry>
1975
<term>
1976
<emphasis remap='I'>keyboard_mode</emphasis>
1977
</term>
1978
<listitem>
1979
<para>
1980
Specify arguments to
1981
<xref linkend='XtGrabButton' xrefstyle='select: title'/>
1982
or
1983
<xref linkend='XtGrabKey' xrefstyle='select: title'/>.
1984
</para>
1985
</listitem>
1986
</varlistentry>
1987
</variablelist>
1988
1989
<para>
1990
<xref linkend='XtRegisterGrabAction' xrefstyle='select: title'/>
1991
adds the specified <emphasis remap='I'>action_proc</emphasis> to a list known to
1992
the translation manager. When a widget is realized, or when the
1993
translations of a realized widget or the accelerators installed on a
1994
realized widget are modified, its translation table and any installed
1995
accelerators are scanned for action procedures on this list.
1996
If any are invoked on
1997
<function>ButtonPress</function>
1998
or
1999
<function>KeyPress</function>
2000
events as the only or final event
2001
in a sequence, the Intrinsics will call
2002
<xref linkend='XtGrabButton' xrefstyle='select: title'/>
2003
or
2004
<xref linkend='XtGrabKey' xrefstyle='select: title'/>
2005
for the widget with every button or KeyCode which maps to the
2006
event detail field, passing the specified <emphasis remap='I'>owner_events</emphasis>, <emphasis remap='I'>event_mask</emphasis>,
2007
<emphasis remap='I'>pointer_mode</emphasis>, and <emphasis remap='I'>keyboard_mode</emphasis>. For
2008
<function>ButtonPress</function>
2009
events, the modifiers
2010
specified in the grab are determined directly from the translation
2011
specification and <emphasis remap='I'>confine_to</emphasis> and <emphasis remap='I'>cursor</emphasis> are specified as
2012
<function>None</function>.
2013
For
2014
<function>KeyPress</function>
2015
events, if the translation table entry specifies colon (:) in
2016
the modifier list, the modifiers are determined by calling the key
2017
translator procedure registered for the display and calling
2018
<xref linkend='XtGrabKey' xrefstyle='select: title'/>
2019
for every combination of standard modifiers which map the KeyCode to
2020
the specified event detail KeySym, and ORing any modifiers specified in
2021
the translation table entry, and <emphasis remap='I'>event_mask</emphasis> is ignored. If the
2022
translation table entry does not specify colon in the modifier list,
2023
the modifiers specified in the grab are those specified in the
2024
translation table entry only. For both
2025
<function>ButtonPress</function>
2026
and
2027
<function>KeyPress</function>
2028
events, don't-care modifiers are ignored unless the translation entry
2029
explicitly specifies ``Any'' in the <emphasis remap='I'>modifiers</emphasis> field.
2030
</para>
2031
2032
<para>
2033
If the specified <emphasis remap='I'>action_proc</emphasis> is already registered for the calling
2034
process, the new values will replace the previously specified values
2035
for any widgets that become realized following the call, but existing
2036
grabs are not altered on currently realized widgets.
2037
</para>
2038
2039
<para>
2040
When translations or installed accelerators are modified for a
2041
realized widget, any previous key or button grabs registered
2042
as a result of the old bindings are released if they do not appear in
2043
the new bindings and are not explicitly grabbed by the client with
2044
<xref linkend='XtGrabKey' xrefstyle='select: title'/>
2045
or
2046
<xref linkend='XtGrabButton' xrefstyle='select: title'/>.
2047
</para>
2048
</sect1>
2049
2050
<sect1 id="Invoking_Actions_Directly">
2051
<title>Invoking Actions Directly</title>
2052
<para>
2053
Normally action procedures are invoked by the Intrinsics when an
2054
event or event sequence arrives for a widget. To
2055
invoke an action procedure directly, without generating
2056
(or synthesizing) events, use
2057
<xref linkend='XtCallActionProc' xrefstyle='select: title'/>.
2058
</para>
2059
2060
<funcsynopsis id='XtCallActionProc'>
2061
<funcprototype>
2062
<funcdef>void <function>XtCallActionProc</function></funcdef>
2063
<paramdef>Widget <parameter>widget</parameter></paramdef>
2064
<paramdef>String <parameter>action</parameter></paramdef>
2065
<paramdef>XEvent *<parameter>event</parameter></paramdef>
2066
<paramdef>String *<parameter>params</parameter></paramdef>
2067
<paramdef>Cardinal <parameter>num_params</parameter></paramdef>
2068
</funcprototype>
2069
</funcsynopsis>
2070
2071
<variablelist>
2072
<varlistentry>
2073
<term>
2074
<emphasis remap='I'>widget</emphasis>
2075
</term>
2076
<listitem>
2077
<para>
2078
Specifies the widget in which the action is to be invoked. Must be of class Core or any subclass thereof.
2079
</para>
2080
</listitem>
2081
</varlistentry>
2082
<varlistentry>
2083
<term>
2084
<emphasis remap='I'>action</emphasis>
2085
</term>
2086
<listitem>
2087
<para>
2088
Specifies the name of the action routine.
2089
</para>
2090
</listitem>
2091
</varlistentry>
2092
<varlistentry>
2093
<term>
2094
<emphasis remap='I'>event</emphasis>
2095
</term>
2096
<listitem>
2097
<para>
2098
Specifies the contents of the <emphasis remap='I'>event</emphasis> passed to the action routine.
2099
</para>
2100
</listitem>
2101
</varlistentry>
2102
<varlistentry>
2103
<term>
2104
<emphasis remap='I'>params</emphasis>
2105
</term>
2106
<listitem>
2107
<para>
2108
Specifies the contents of the <emphasis remap='I'>params</emphasis> passed to the action routine.
2109
</para>
2110
</listitem>
2111
</varlistentry>
2112
<varlistentry>
2113
<term>
2114
<emphasis remap='I'>num_params</emphasis>
2115
</term>
2116
<listitem>
2117
<para>
2118
Specifies the number of entries in <emphasis remap='I'>params</emphasis>.
2119
</para>
2120
</listitem>
2121
</varlistentry>
2122
</variablelist>
2123
2124
<para>
2125
<xref linkend='XtCallActionProc' xrefstyle='select: title'/>
2126
searches for the named action routine in the same
2127
manner and order as translation tables are bound, as described in
2128
Section 10.1.2, except that application action tables are searched, if
2129
necessary, as of the time of the call to
2130
<xref linkend='XtCallActionProc' xrefstyle='select: title'/>.
2131
If found,
2132
the action routine is invoked with the specified widget, event pointer,
2133
and parameters. It is the responsibility of the caller to ensure that
2134
the contents of the <emphasis remap='I'>event</emphasis>, <emphasis remap='I'>params</emphasis>, and <emphasis remap='I'>num_params</emphasis> arguments are
2135
appropriate for the specified action routine and, if necessary, that
2136
the specified widget is realized or sensitive. If the named action
2137
routine cannot be found,
2138
<xref linkend='XtCallActionProc' xrefstyle='select: title'/>
2139
generates a warning message and returns.
2140
</para>
2141
</sect1>
2142
2143
<sect1 id="Obtaining_a_Widget_s_Action_List">
2144
<title>Obtaining a Widget's Action List</title>
2145
<para>
2146
Occasionally a subclass will require the pointers to one or more of
2147
its superclass's action procedures. This would be needed, for
2148
example, in order to envelop the superclass's action. To retrieve
2149
the list of action procedures registered in the superclass's
2150
<emphasis remap='I'>actions</emphasis> field, use
2151
<xref linkend='XtGetActionList' xrefstyle='select: title'/>.
2152
</para>
2153
2154
<funcsynopsis id='XtGetActionList'>
2155
<funcprototype>
2156
<funcdef>void <function>XtGetActionList</function></funcdef>
2157
<paramdef>WidgetClass <parameter>widget_class</parameter></paramdef>
2158
<paramdef>XtActionList *<parameter>actions_return</parameter></paramdef>
2159
<paramdef>Cardinal *<parameter>num_actions_return</parameter></paramdef>
2160
</funcprototype>
2161
</funcsynopsis>
2162
2163
<variablelist>
2164
<varlistentry>
2165
<term>
2166
<emphasis remap='I'>widget_class</emphasis>
2167
</term>
2168
<listitem>
2169
<para>
2170
Specifies the widget class whose actions are to be returned.
2171
</para>
2172
</listitem>
2173
</varlistentry>
2174
<varlistentry>
2175
<term>
2176
<emphasis remap='I'>actions_return</emphasis>
2177
</term>
2178
<listitem>
2179
<para>
2180
Returns the action list.
2181
</para>
2182
</listitem>
2183
</varlistentry>
2184
<varlistentry>
2185
<term>
2186
<emphasis remap='I'>num_actions_return</emphasis>
2187
</term>
2188
<listitem>
2189
<para>
2190
Returns the number of action procedures declared by the class.
2191
</para>
2192
</listitem>
2193
</varlistentry>
2194
</variablelist>
2195
2196
<para>
2197
<xref linkend='XtGetActionList' xrefstyle='select: title'/>
2198
returns the action table defined by the specified
2199
widget class. This table does not include actions defined by the
2200
superclasses. If <emphasis remap='I'>widget_class</emphasis> is not initialized, or is not
2201
<function>coreWidgetClass</function>
2202
or a subclass thereof, or if the class does not define any actions,
2203
*<emphasis remap='I'>actions_return</emphasis> will be NULL and *<emphasis remap='I'>num_actions_return</emphasis>
2204
will be zero.
2205
If *<emphasis remap='I'>actions_return</emphasis> is non-NULL the client is responsible for freeing
2206
the table using
2207
<xref linkend='XtFree' xrefstyle='select: title'/>
2208
when it is no longer needed.
2209
</para>
2210
</sect1>
2211
</chapter>
Loggerhead is a web-based interface for Breezy
Version: 2.0.1