« back to all changes in this revision
Viewing changes to specs/libX11/CH13.xml
- browse files at revision 46
- compare with another revision
- download diff
- download tarball
- view history from revision 46
- Committer: Bazaar Package Importer
- Author(s): Timo Aaltonen
- Date: 2011-02-24 12:02:14 UTC
- mfrom: (1.1.12 upstream) (2.1.12 sid)
- Revision ID: james.westby@ubuntu.com-20110224120214-a86d0lv48wk8itl6
Tags: 2:1.4.1-5ubuntu1
* Merge from debian unstable. Remaining changes:
- Add Latin locale.
- Add Klingon locale.
- Add 102_double_arrows_Compose.patch: compose keys for double arrows
(LP: 680143)
- Add Latin locale.
- Add Klingon locale.
- Add 102_double_arrows_Compose.patch: compose keys for double arrows
(LP: 680143)
- files added:
- debian/patches/020_keep_xorg_css.diff
- m4
- specs/XKB
- specs/i18n/framework
- specs/i18n/localedb
- specs/i18n/trans
- files removed:
- acinclude.m4
- files modified:
- COPYING
added
removed
specs/libX11/CH13.xml
1
<?xml version="1.0" encoding="UTF-8" ?>
2
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
3
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
4
<chapter id="locales_and_internationalized_text_functions">
5
<title>Locales and Internationalized Text Functions</title>
6
7
<para>
8
An internationalized application is one that is adaptable to the requirements of different native
9
languages, local customs, and character string encodings. The process of adapting the operation
10
to a particular native language, local custom, or string encoding is called localization. A goal of
11
internationalization is to permit localization without program source modifications or recompila-
12
tion.
13
</para>
14
<para>
15
As one of the localization mechanisms, Xlib provides an X Input Method (<acronym>XIM</acronym>) functional inter-
16
face for internationalized text input and an X Output Method (<acronym>XOM</acronym>) functional interface for
17
internationalized text output.
18
</para>
19
<para>
20
Internationalization in X is based on the concept of a locale. A locale defines the localized
21
behavior of a program at run time. Locales affect Xlib in its:
22
</para>
23
24
<itemizedlist>
25
<listitem><para>Encoding and processing of input method text</para></listitem>
26
<listitem><para>Encoding of resource files and values</para></listitem>
27
<listitem><para>Encoding and imaging of text strings</para></listitem>
28
<listitem><para>Encoding and decoding for inter-client text communication</para></listitem>
29
</itemizedlist>
30
31
32
<para>
33
•
34
Encoding and decoding for inter-client text communication
35
Characters from various languages are represented in a computer using an encoding. Different
36
languages have different encodings, and there are even different encodings for the same charac-
37
ters in the same language.
38
</para>
39
<para>
40
This chapter defines support for localized text imaging and text input and describes the locale
41
mechanism that controls all locale-dependent Xlib functions. Sets of functions are provided for
42
multibyte (char *) text as well as wide character (wchar_t) text in the form supported by the host
43
C language environment. The multibyte and wide character functions are equivalent except for
44
the form of the text argument.
45
</para>
46
<para>
47
The Xlib internationalization functions are not meant to provide support for multilingual applica-
48
tions (mixing multiple languages within a single piece of text), but they make it possible to imple-
49
ment applications that work in limited fashion with more than one language in independent con-
50
texts.
51
</para>
52
<para>
53
The remainder of this chapter discusses:
54
</para>
55
56
<itemizedlist>
57
<listitem><para>X locale management</para></listitem>
58
<listitem><para>Locale and modifier dependencies</para></listitem>
59
<listitem><para>Variable argument lists</para></listitem>
60
<listitem><para>Output methods</para></listitem>
61
<listitem><para>Input methods</para></listitem>
62
<listitem><para>String constants</para></listitem>
63
</itemizedlist>
64
65
66
<sect1 id="X_Locale_Management">
67
<title>X Locale Management</title>
68
<!-- .XS -->
69
<!-- (SN X Locale Management -->
70
<!-- .XE -->
71
<para>
72
<!-- .LP -->
73
X supports one or more of the locales defined by the host environment.
74
On implementations that conform to the ANSI C library,
75
the locale announcement method is
76
<function>setlocale</function>.
77
This function configures the locale operation of both
78
the host C library and Xlib.
79
The operation of Xlib is governed by the LC_CTYPE category;
80
this is called the <emphasis remap='I'>current locale</emphasis>.
81
An implementation is permitted to provide implementation-dependent
82
mechanisms for announcing the locale in addition to
83
<function>setlocale</function>.
84
</para>
85
<para>
86
<!-- .LP -->
87
On implementations that do not conform to the ANSI C library,
88
the locale announcement method is Xlib implementation-dependent.
89
</para>
90
<para>
91
<!-- .LP -->
92
The mechanism by which the semantic operation of Xlib is defined
93
for a specific locale is implementation-dependent.
94
</para>
95
<para>
96
<!-- .LP -->
97
<!-- .sp -->
98
X is not required to support all the locales supported by the host.
99
To determine if the current locale is supported by X, use
100
<function>XSupportsLocale</function>.
101
</para>
102
103
<para>Bool XSupportsLocale()</para>
104
105
<para>
106
<!-- .LP -->
107
<!-- .eM -->
108
The
109
<function>XSupportsLocale</function>
110
function returns
111
<symbol>True</symbol>
112
if Xlib functions are capable of operating under the current locale.
113
If it returns
114
<symbol>False</symbol>,
115
Xlib locale-dependent functions for which the
116
<symbol>XLocaleNotSupported</symbol>
117
return status is defined will return
118
<symbol>XLocaleNotSupported</symbol>.
119
Other Xlib locale-dependent routines will operate in the ``C'' locale.
120
</para>
121
<para>
122
<!-- .LP -->
123
The client is responsible for selecting its locale and X modifiers.
124
Clients should provide a means for the user to override the clients'
125
locale selection at client invocation.
126
Most single-display X clients operate in a single locale
127
for both X and the host processing environment.
128
They will configure the locale by calling three functions:
129
the host locale configuration function,
130
<function>XSupportsLocale</function>,
131
and
132
<function>XSetLocaleModifiers</function>.
133
</para>
134
<para>
135
<!-- .LP -->
136
The semantics of certain categories of X internationalization capabilities
137
can be configured by setting modifiers.
138
Modifiers are named by implementation-dependent and locale-specific strings.
139
The only standard use for this capability at present
140
is selecting one of several styles of keyboard input method.
141
</para>
142
<para>
143
<!-- .LP -->
144
<!-- .sp -->
145
To configure Xlib locale modifiers for the current locale, use
146
<function>XSetLocaleModifiers</function>.
147
<indexterm significance="preferred"><primary>XSetLocaleModifiers</primary></indexterm>
148
<!-- .sM -->
149
<funcsynopsis>
150
<funcprototype>
151
<funcdef>char *<function>XSetLocaleModifiers</function></funcdef>
152
<paramdef>char<parameter> *modifier_list</parameter></paramdef>
153
</funcprototype>
154
</funcsynopsis>
155
<!-- .FN -->
156
<variablelist>
157
<varlistentry>
158
<term>
159
<emphasis remap='I'>modifier_list</emphasis>
160
</term>
161
<listitem>
162
<para>
163
Specifies the modifiers.
164
</para>
165
</listitem>
166
</varlistentry>
167
</variablelist>
168
</para>
169
<para>
170
<!-- .LP -->
171
<!-- .eM -->
172
The
173
<function>XSetLocaleModifiers</function>
174
function sets the X modifiers for the current locale setting.
175
The modifier_list argument is a null-terminated string of the form
176
``{@<emphasis remap='I'>category</emphasis>=<emphasis remap='I'>value</emphasis>}'', that is,
177
having zero or more concatenated ``@<emphasis remap='I'>category</emphasis>=<emphasis remap='I'>value</emphasis>''
178
entries, where <emphasis remap='I'>category</emphasis> is a category name
179
and <emphasis remap='I'>value</emphasis> is the (possibly empty) setting for that category.
180
The values are encoded in the current locale.
181
Category names are restricted to the <acronym>POSIX</acronym> Portable Filename Character Set.
182
</para>
183
<para>
184
<!-- .LP -->
185
The local host X locale modifiers announcer (on <acronym>POSIX</acronym>-compliant systems,
186
the XMODIFIERS environment variable) is appended to the modifier_list to
187
provide default values on the local host.
188
If a given category appears more than once in the list,
189
the first setting in the list is used.
190
If a given category is not included in the full modifier list,
191
the category is set to an implementation-dependent default
192
for the current locale.
193
An empty value for a category explicitly specifies the
194
implementation-dependent default.
195
</para>
196
<para>
197
<!-- .LP -->
198
If the function is successful, it returns a pointer to a string.
199
The contents of the string are such that a subsequent call with that string
200
(in the same locale) will restore the modifiers to the same settings.
201
If modifier_list is a NULL pointer,
202
<function>XSetLocaleModifiers</function>
203
also returns a pointer to such a string,
204
and the current locale modifiers are not changed.
205
</para>
206
<para>
207
<!-- .LP -->
208
If invalid values are given for one or more modifier categories supported by
209
the locale, a NULL pointer is returned, and none of the
210
current modifiers are changed.
211
</para>
212
<para>
213
<!-- .LP -->
214
At program startup,
215
the modifiers that are in effect are unspecified until
216
the first successful call to set them. Whenever the locale is changed, the
217
modifiers that are in effect become unspecified until the next successful call
218
to set them.
219
Clients should always call
220
<function>XSetLocaleModifiers</function>
221
with a non-NULL modifier_list after setting the locale
222
before they call any locale-dependent Xlib routine.
223
</para>
224
<para>
225
<!-- .LP -->
226
The only standard modifier category currently defined is ``im'',
227
which identifies the desired input method.
228
The values for input method are not standardized.
229
A single locale may use multiple input methods,
230
switching input method under user control.
231
The modifier may specify the initial input method in effect
232
or an ordered list of input methods.
233
Multiple input methods may be specified in a single im value string
234
in an implementation-dependent manner.
235
</para>
236
<para>
237
<!-- .LP -->
238
The returned modifiers string is owned by Xlib and should not be modified or
239
freed by the client.
240
It may be freed by Xlib after the current locale or modifiers are changed.
241
Until freed, it will not be modified by Xlib.
242
</para>
243
<para>
244
<!-- .LP -->
245
The recommended procedure for clients initializing their locale and modifiers
246
is to obtain locale and modifier announcers separately from
247
one of the following prioritized sources:
248
</para>
249
<itemizedlist>
250
<listitem>
251
<para>
252
A command line option
253
</para>
254
</listitem>
255
<listitem>
256
<para>
257
A resource
258
</para>
259
</listitem>
260
<listitem>
261
<para>
262
The empty string ("")
263
</para>
264
</listitem>
265
</itemizedlist>
266
<para>
267
<!-- .LP -->
268
The first of these that is defined should be used.
269
Note that when a locale command line option or locale resource is defined,
270
the effect should be to set all categories to the specified locale,
271
overriding any category-specific settings in the local host environment.
272
</para>
273
</sect1>
274
<sect1 id="Locale_and_Modifier_Dependencies">
275
<title>Locale and Modifier Dependencies</title>
276
<!-- .XS -->
277
<!-- (SN Locale and Modifier Dependencies -->
278
<!-- .XE -->
279
<para>
280
<!-- .LP -->
281
The internationalized Xlib functions operate in the current locale
282
configured by the host environment and X locale modifiers set by
283
<function>XSetLocaleModifiers</function>
284
or in the locale and modifiers configured at the time
285
some object supplied to the function was created.
286
For each locale-dependent function,
287
the following table describes the locale (and modifiers) dependency:
288
</para>
289
290
<informaltable>
291
<tgroup cols='3' align='center'>
292
<colspec colname='c1'/>
293
<colspec colname='c2'/>
294
<colspec colname='c3'/>
295
<thead>
296
<row>
297
<entry>Locale from</entry>
298
<entry>Affects the Function</entry>
299
<entry>In</entry>
300
</row>
301
</thead>
302
<tbody>
303
<row>
304
<entry></entry>
305
<entry>Locale Query/Configuration:</entry>
306
</row>
307
<row>
308
<entry><function>setlocale</function></entry>
309
<entry><function>XSupportsLocale</function></entry>
310
<entry>Locale queried</entry>
311
</row>
312
<row>
313
<entry></entry>
314
<entry><function>XSetLocaleModifiers</function></entry>
315
<entry>Locale modified</entry>
316
</row>
317
<row>
318
<entry></entry>
319
</row>
320
<row>
321
<entry></entry>
322
<entry>Resources:</entry>
323
</row>
324
<row>
325
<entry><function>setlocale</function></entry>
326
<entry><function>XrmGetFileDatabase</function></entry>
327
<entry>Locale of <type>XrmDatabase</type></entry>
328
</row>
329
<row>
330
<entry></entry>
331
<entry><function>XrmGetStringDatabase</function></entry>
332
</row>
333
<row>
334
<entry><type>XrmDatabase</type></entry>
335
<entry><function>XrmPutFileDatabase</function></entry>
336
<entry>Locale of <type>XrmDatabase</type></entry>
337
</row>
338
<row>
339
<entry></entry>
340
<entry><function>XrmLocaleOfDatabase</function></entry>
341
</row>
342
<row>
343
<entry></entry>
344
</row>
345
<row>
346
<entry></entry>
347
<entry>Setting Standard Properties:</entry>
348
</row>
349
<row>
350
<entry><function>setlocale</function></entry>
351
<entry><function>XmbSetWMProperties</function></entry>
352
<entry>Encoding of supplied/returned
353
text (some WM_ property
354
text in environment locale)</entry>
355
</row>
356
<row>
357
<entry><function>setlocale</function></entry>
358
<entry><function>XmbTextPropertyToTextList</function></entry>
359
<entry>Encoding of supplied/returned text</entry>
360
</row>
361
<row>
362
<entry></entry>
363
<entry><function>XwcTextPropertyToTextList</function></entry>
364
</row>
365
<row>
366
<entry></entry>
367
<entry><function>XmbTextListToTextProperty</function></entry>
368
</row>
369
<row>
370
<entry></entry>
371
<entry><function>XwcTextListToTextProperty</function></entry>
372
</row>
373
<row>
374
<entry></entry>
375
</row>
376
<row>
377
<entry></entry>
378
<entry>Text Input:</entry>
379
</row>
380
<row>
381
<entry><function>setlocale</function></entry>
382
<entry><function>XOpenIM</function></entry>
383
<entry><acronym>XIM</acronym> input method selection</entry>
384
</row>
385
<row>
386
<entry></entry>
387
<entry><function>XRegisterIMInstantiateCallback</function></entry>
388
<entry><acronym>XIM</acronym> selection</entry>
389
</row>
390
<row>
391
<entry></entry>
392
<entry><function>XUnregisterIMInstantiateCallback</function></entry>
393
<entry><acronym>XIM</acronym> selection</entry>
394
</row>
395
<row>
396
<entry><type>XIM</type></entry>
397
<entry><function>XCreateIC</function></entry>
398
<entry><acronym>XIC</acronym> input method configuration</entry>
399
</row>
400
<row>
401
<entry></entry>
402
<entry><function>XLocaleOfIM</function>, and so on</entry>
403
<entry>Queried locale</entry>
404
</row>
405
<row>
406
<entry><type>XIC</type></entry>
407
<entry><function>XmbLookupString</function></entry>
408
<entry>Keyboard layout</entry>
409
</row>
410
<row>
411
<entry></entry>
412
<entry><function>XwcLookupString</function></entry>
413
<entry>Encoding of returned text</entry>
414
</row>
415
<row>
416
<entry></entry>
417
</row>
418
<row>
419
<entry></entry>
420
<entry>Text Drawing:</entry>
421
</row>
422
<row>
423
<entry><function>setlocale</function></entry>
424
<entry><function>XOpenOM</function></entry>
425
<entry><acronym>XOM</acronym> output method selection</entry>
426
</row>
427
<row>
428
<entry></entry>
429
<entry><function>XCreateFontSet</function></entry>
430
<entry>Charsets of fonts in XFontSet</entry>
431
</row>
432
<row>
433
<entry><type>XOM</type></entry>
434
<entry><function>XCreateOC</function></entry>
435
<entry><acronym>XOC</acronym> output method configuration</entry>
436
</row>
437
<row>
438
<entry></entry>
439
<entry><function>XLocaleOfOM</function>, and so on</entry>
440
<entry>Queried locale</entry>
441
</row>
442
<row>
443
<entry><type>XFontSet</type></entry>
444
<entry><function>XmbDrawText</function>,</entry>
445
<entry>Locale of supplied text</entry>
446
</row>
447
<row>
448
<entry></entry>
449
<entry><function>XwcDrawText</function>, and so on</entry>
450
<entry>Locale of supplied text</entry>
451
</row>
452
<row>
453
<entry></entry>
454
<entry><function>XExtentsOfFontSet</function>, and so on</entry>
455
<entry>Locale-dependent metrics</entry>
456
</row>
457
<row>
458
<entry></entry>
459
<entry><function>XmbTextExtents</function>,</entry>
460
</row>
461
<row>
462
<entry></entry>
463
<entry><function>XwcTextExtents</function>, and so on</entry>
464
</row>
465
<row>
466
<entry></entry>
467
</row>
468
<row>
469
<entry></entry>
470
<entry>Xlib Errors:</entry>
471
</row>
472
<row>
473
<entry><function>setlocale</function></entry>
474
<entry><function>XGetErrorDatabaseText</function></entry>
475
<entry>Locale of error message</entry>
476
</row>
477
<row>
478
<entry></entry>
479
<entry><function>XGetErrorText</function></entry>
480
</row>
481
</tbody>
482
</tgroup>
483
</informaltable>
484
485
<para>
486
<!-- .LP -->
487
Clients may assume that a locale-encoded text string returned
488
by an X function can be passed to a C library routine, or vice versa,
489
if the locale is the same at the two calls.
490
</para>
491
<para>
492
<!-- .LP -->
493
All text strings processed by internationalized Xlib functions are assumed
494
to begin in the initial state of the encoding of the locale, if the encoding
495
is state-dependent.
496
</para>
497
<para>
498
<!-- .LP -->
499
All Xlib functions behave as if they do not change the current locale
500
or X modifier setting.
501
(This means that if they do change locale or call
502
<function>XSetLocaleModifiers</function>
503
with a non-NULL argument, they must save and restore the current state on
504
entry and exit.)
505
Also, Xlib functions on implementations that conform to the ANSI C library do
506
not alter the global state associated with the ANSI C functions
507
<function>mblen</function>,
508
<function>mbtowc</function>,
509
<function>wctomb</function>,
510
and
511
<function>strtok</function>.
512
</para>
513
</sect1>
514
<sect1 id="Variable_Argument_Lists">
515
<title>Variable Argument Lists</title>
516
<!-- .XS -->
517
<!-- (SN Variable Argument Lists -->
518
<!-- .XE -->
519
<para>
520
<!-- .LP -->
521
Various functions in this chapter have arguments that conform
522
to the ANSI C variable argument list calling convention.
523
Each function denoted with an argument of the form ``...'' takes
524
a variable-length list of name and value pairs,
525
where each name is a string and each value is of type
526
<type>XPointer</type>.
527
A name argument that is NULL identifies the end of the list.
528
</para>
529
<para>
530
<!-- .LP -->
531
A variable-length argument list may contain a nested list.
532
If the name
533
<symbol>XNVaNestedList</symbol>
534
is specified in place of an argument name,
535
then the following value is interpreted as an
536
<type>XVaNestedList</type>
537
value that specifies a list of values logically inserted into the
538
original list at the point of declaration.
539
A NULL identifies the end of a nested list.
540
</para>
541
<para>
542
<!-- .LP -->
543
<!-- .sp -->
544
To allocate a nested variable argument list dynamically, use
545
<function>XVaCreateNestedList</function>.
546
<indexterm significance="preferred"><primary>XVaCreateNestedList</primary></indexterm>
547
<!-- .sM -->
548
<funcsynopsis>
549
<funcprototype>
550
<funcdef>XVaNestedList <function>XVaCreateNestedList</function></funcdef>
551
<paramdef>int<parameter> dummy</parameter></paramdef>
552
</funcprototype>
553
</funcsynopsis>
554
<!-- .FN -->
555
<variablelist>
556
<varlistentry>
557
<term>
558
<emphasis remap='I'>dummy</emphasis>
559
</term>
560
<listitem>
561
<para>
562
Specifies an unused argument (required by ANSI C).
563
<!-- .ds Al -->
564
</para>
565
</listitem>
566
</varlistentry>
567
<varlistentry>
568
<term>
569
...
570
</term>
571
<listitem>
572
<para>
573
Specifies the variable length argument list(Al.
574
</para>
575
</listitem>
576
</varlistentry>
577
</variablelist>
578
</para>
579
<para>
580
<!-- .LP -->
581
<!-- .eM -->
582
The
583
<function>XVaCreateNestedList</function>
584
function allocates memory and copies its arguments into
585
a single list pointer,
586
which may be used as a value for arguments requiring a list value.
587
Any entries are copied as specified.
588
Data passed by reference is not copied;
589
the caller must ensure data remains valid for the lifetime
590
of the nested list.
591
The list should be freed using
592
<function>XFree</function>
593
when it is no longer needed.
594
</para>
595
</sect1>
596
<sect1 id="Output_Methods">
597
<title>Output Methods</title>
598
<!-- .XS -->
599
<!-- (SN Output Methods -->
600
<!-- .XE -->
601
<para>
602
<!-- .LP -->
603
This section provides discussions of the following X Output Method
604
(<acronym>XOM</acronym>) topics:
605
</para>
606
<itemizedlist>
607
<listitem>
608
<para>
609
Output method overview
610
</para>
611
</listitem>
612
<listitem>
613
<para>
614
Output method functions
615
</para>
616
</listitem>
617
<listitem>
618
<para>
619
Output method values
620
</para>
621
</listitem>
622
<listitem>
623
<para>
624
Output context functions
625
</para>
626
</listitem>
627
<listitem>
628
<para>
629
Output context values
630
</para>
631
</listitem>
632
<listitem>
633
<para>
634
Creating and freeing a font set
635
</para>
636
</listitem>
637
<listitem>
638
<para>
639
Obtaining font set metrics
640
</para>
641
</listitem>
642
<listitem>
643
<para>
644
Drawing text using font sets
645
</para>
646
</listitem>
647
</itemizedlist>
648
<sect2 id="Output_Method_Overview">
649
<title>Output Method Overview</title>
650
<!-- .XS -->
651
<!-- (SN Output Method Overview -->
652
<!-- .XE -->
653
<para>
654
<!-- .LP -->
655
Locale-dependent text may include one or more text components, each of
656
which may require different fonts and character set encodings.
657
In some languages, each component might have a different
658
drawing direction, and some components might contain
659
context-dependent characters that change shape based on
660
relationships with neighboring characters.
661
</para>
662
<para>
663
<!-- .LP -->
664
When drawing such locale-dependent text, some locale-specific
665
knowledge is required;
666
for example, what fonts are required to draw the text,
667
how the text can be separated into components, and which
668
fonts are selected to draw each component.
669
Further, when bidirectional text must be drawn,
670
the internal representation order of the text must be changed
671
into the visual representation order to be drawn.
672
</para>
673
<para>
674
<!-- .LP -->
675
An X Output Method provides a functional interface so that clients
676
do not have to deal directly with such locale-dependent details.
677
Output methods provide the following capabilities:
678
</para>
679
<itemizedlist>
680
<listitem>
681
<para>
682
Creating a set of fonts required to draw locale-dependent text.
683
</para>
684
</listitem>
685
<listitem>
686
<para>
687
Drawing locale-dependent text with a font set without the caller
688
needing to be aware of locale dependencies.
689
</para>
690
</listitem>
691
<listitem>
692
<para>
693
Obtaining the escapement and extents in pixels of locale-dependent text.
694
</para>
695
</listitem>
696
<listitem>
697
<para>
698
Determining if bidirectional or context-dependent drawing is required
699
in a specific locale with a specific font set.
700
</para>
701
</listitem>
702
</itemizedlist>
703
<para>
704
<!-- .LP -->
705
Two different abstractions are used in the representation of
706
the output method for clients.
707
</para>
708
<para>
709
<!-- .LP -->
710
The abstraction used to communicate with an output method
711
is an opaque data structure represented by the
712
<type>XOM</type>
713
data type.
714
The abstraction for representing the state of a particular output thread
715
is called an <emphasis remap='I'>output context</emphasis>.
716
The Xlib representation of an output context is an
717
<type>XOC</type>,
718
which is compatible with
719
<type>XFontSet</type>
720
in terms of its functional interface, but is
721
a broader, more generalized abstraction.
722
</para>
723
</sect2>
724
<sect2 id="Output_Method_Functions">
725
<title>Output Method Functions</title>
726
<!-- .XS -->
727
<!-- (SN Output Method Functions -->
728
<!-- .XE -->
729
<para>
730
<!-- .LP -->
731
To open an output method, use
732
<function>XOpenOM</function>.
733
<indexterm significance="preferred"><primary>XOpenOM</primary></indexterm>
734
<!-- .sM -->
735
<funcsynopsis>
736
<funcprototype>
737
<funcdef>XOM <function>XOpenOM</function></funcdef>
738
<paramdef>Display<parameter> *display</parameter></paramdef>
739
<paramdef>XrmDatabase<parameter> db</parameter></paramdef>
740
<paramdef>char<parameter> *res_name</parameter></paramdef>
741
<paramdef>char<parameter> *res_class</parameter></paramdef>
742
</funcprototype>
743
</funcsynopsis>
744
<!-- .FN -->
745
<variablelist>
746
<varlistentry>
747
<term>
748
<emphasis remap='I'>display</emphasis>
749
</term>
750
<listitem>
751
<para>
752
Specifies the connection to the X server.
753
</para>
754
</listitem>
755
</varlistentry>
756
<varlistentry>
757
<term>
758
<emphasis remap='I'>db</emphasis>
759
</term>
760
<listitem>
761
<para>
762
Specifies a pointer to the resource database.
763
</para>
764
</listitem>
765
</varlistentry>
766
<varlistentry>
767
<term>
768
<emphasis remap='I'>res_name</emphasis>
769
</term>
770
<listitem>
771
<para>
772
Specifies the full resource name of the application.
773
</para>
774
</listitem>
775
</varlistentry>
776
<varlistentry>
777
<term>
778
<emphasis remap='I'>res_class</emphasis>
779
</term>
780
<listitem>
781
<para>
782
Specifies the full class name of the application.
783
</para>
784
</listitem>
785
</varlistentry>
786
</variablelist>
787
</para>
788
<para>
789
<!-- .LP -->
790
<!-- .eM -->
791
The
792
<function>XOpenOM</function>
793
function opens an output method
794
matching the current locale and modifiers specification.
795
The current locale and modifiers are bound to the output method
796
when
797
<function>XOpenOM</function>
798
is called.
799
The locale associated with an output method cannot be changed.
800
</para>
801
<para>
802
<!-- .LP -->
803
The specific output method to which this call will be routed
804
is identified on the basis of the current locale and modifiers.
805
<function>XOpenOM</function>
806
will identify a default output method corresponding to the
807
current locale.
808
That default can be modified using
809
<function>XSetLocaleModifiers</function>
810
to set the output method modifier.
811
</para>
812
<para>
813
<!-- .LP -->
814
The db argument is the resource database to be used by the output method
815
for looking up resources that are private to the output method.
816
It is not intended that this database be used to look
817
up values that can be set as OC values in an output context.
818
If db is NULL,
819
no database is passed to the output method.
820
</para>
821
<para>
822
<!-- .LP -->
823
The res_name and res_class arguments specify the resource name
824
and class of the application.
825
They are intended to be used as prefixes by the output method
826
when looking up resources that are common to all output contexts
827
that may be created for this output method.
828
The characters used for resource names and classes must be in the
829
X Portable Character Set.
830
The resources looked up are not fully specified
831
if res_name or res_class is NULL.
832
</para>
833
<para>
834
<!-- .LP -->
835
The res_name and res_class arguments are not assumed to exist beyond
836
the call to
837
<function>XOpenOM</function>.
838
The specified resource database is assumed to exist for the lifetime
839
of the output method.
840
</para>
841
<para>
842
<!-- .LP -->
843
<function>XOpenOM</function>
844
returns NULL if no output method could be opened.
845
</para>
846
<para>
847
<!-- .LP -->
848
<!-- .sp -->
849
To close an output method, use
850
<function>XCloseOM</function>.
851
<indexterm significance="preferred"><primary>XCloseOM</primary></indexterm>
852
<!-- .sM -->
853
<funcsynopsis>
854
<funcprototype>
855
<funcdef>Status <function>XCloseOM</function></funcdef>
856
<paramdef>XOM<parameter> om</parameter></paramdef>
857
</funcprototype>
858
</funcsynopsis>
859
<!-- .FN -->
860
<variablelist>
861
<varlistentry>
862
<term>
863
<emphasis remap='I'>om</emphasis>
864
</term>
865
<listitem>
866
<para>
867
Specifies the output method.
868
</para>
869
</listitem>
870
</varlistentry>
871
</variablelist>
872
</para>
873
<para>
874
<!-- .LP -->
875
<!-- .eM -->
876
The
877
<function>XCloseOM</function>
878
function closes the specified output method.
879
</para>
880
<para>
881
<!-- .LP -->
882
<!-- .sp -->
883
To set output method attributes, use
884
<function>XSetOMValues</function>.
885
<indexterm significance="preferred"><primary>XSetOMValues</primary></indexterm>
886
<!-- .sM -->
887
<funcsynopsis>
888
<funcprototype>
889
<funcdef>char *<function>XSetOMValues</function></funcdef>
890
<paramdef>XOM<parameter> om</parameter></paramdef>
891
</funcprototype>
892
</funcsynopsis>
893
<!-- .FN -->
894
<variablelist>
895
<varlistentry>
896
<term>
897
<emphasis remap='I'>om</emphasis>
898
</term>
899
<listitem>
900
<para>
901
Specifies the output method.
902
<!-- .ds Al \ to set <acronym>XOM</acronym> values -->
903
</para>
904
</listitem>
905
</varlistentry>
906
<varlistentry>
907
<term>
908
...
909
</term>
910
<listitem>
911
<para>
912
Specifies the variable-length argument list(Al.
913
</para>
914
</listitem>
915
</varlistentry>
916
</variablelist>
917
</para>
918
<para>
919
<!-- .LP -->
920
<!-- .eM -->
921
The
922
<function>XSetOMValues</function>
923
function presents a variable argument list programming interface
924
for setting properties or features of the specified output method.
925
This function returns NULL if it succeeds;
926
otherwise,
927
it returns the name of the first argument that could not be obtained.
928
</para>
929
<para>
930
<!-- .LP -->
931
No standard arguments are currently defined by Xlib.
932
</para>
933
<para>
934
<!-- .LP -->
935
<!-- .sp -->
936
To query an output method, use
937
<function>XGetOMValues</function>.
938
<indexterm significance="preferred"><primary>XGetOMValues</primary></indexterm>
939
<!-- .sM -->
940
<funcsynopsis>
941
<funcprototype>
942
<funcdef>char *<function>XGetOMValues</function></funcdef>
943
<paramdef>XOM<parameter> om</parameter></paramdef>
944
</funcprototype>
945
</funcsynopsis>
946
<!-- .FN -->
947
<variablelist>
948
<varlistentry>
949
<term>
950
<emphasis remap='I'>om</emphasis>
951
</term>
952
<listitem>
953
<para>
954
Specifies the output method.
955
<!-- .ds Al \ to get XOM values -->
956
</para>
957
</listitem>
958
</varlistentry>
959
<varlistentry>
960
<term>
961
...
962
</term>
963
<listitem>
964
<para>
965
Specifies the variable-length argument list(Al.
966
</para>
967
</listitem>
968
</varlistentry>
969
</variablelist>
970
</para>
971
<para>
972
<!-- .LP -->
973
<!-- .eM -->
974
The
975
<function>XGetOMValues</function>
976
function presents a variable argument list programming interface
977
for querying properties or features of the specified output method.
978
This function returns NULL if it succeeds;
979
otherwise,
980
it returns the name of the first argument that could not be obtained.
981
</para>
982
<para>
983
<!-- .LP -->
984
To obtain the display associated with an output method, use
985
<function>XDisplayOfOM</function>.
986
<indexterm significance="preferred"><primary>XDisplayOfOM</primary></indexterm>
987
<!-- .sM -->
988
<funcsynopsis>
989
<funcprototype>
990
<funcdef>Display *<function>XDisplayOfOM</function></funcdef>
991
<paramdef>XOM<parameter> om</parameter></paramdef>
992
</funcprototype>
993
</funcsynopsis>
994
<!-- .FN -->
995
<variablelist>
996
<varlistentry>
997
<term>
998
<emphasis remap='I'>om</emphasis>
999
</term>
1000
<listitem>
1001
<para>
1002
Specifies the output method.
1003
</para>
1004
</listitem>
1005
</varlistentry>
1006
</variablelist>
1007
</para>
1008
<para>
1009
<!-- .LP -->
1010
<!-- .eM -->
1011
The
1012
<function>XDisplayOfOM</function>
1013
function returns the display associated with the specified output method.
1014
</para>
1015
<para>
1016
<!-- .LP -->
1017
<!-- .sp -->
1018
To get the locale associated with an output method, use
1019
<function>XLocaleOfOM</function>.
1020
<indexterm significance="preferred"><primary>XLocaleOfOM</primary></indexterm>
1021
<!-- .sM -->
1022
<funcsynopsis>
1023
<funcprototype>
1024
<funcdef>char *<function>XLocaleOfOM</function></funcdef>
1025
<paramdef>XOM<parameter> om</parameter></paramdef>
1026
</funcprototype>
1027
</funcsynopsis>
1028
<!-- .FN -->
1029
<variablelist>
1030
<varlistentry>
1031
<term>
1032
<emphasis remap='I'>om</emphasis>
1033
</term>
1034
<listitem>
1035
<para>
1036
Specifies the output method.
1037
</para>
1038
</listitem>
1039
</varlistentry>
1040
</variablelist>
1041
</para>
1042
<para>
1043
<!-- .LP -->
1044
<!-- .eM -->
1045
The
1046
<function>XLocaleOfOM</function>
1047
returns the locale associated with the specified output method.
1048
</para>
1049
</sect2>
1050
<sect2 id="X_Output_Method_Values">
1051
<title>X Output Method Values</title>
1052
<!-- .XS -->
1053
<!-- (SN X Output Method Values -->
1054
<!-- .XE -->
1055
<para>
1056
<!-- .LP -->
1057
The following table describes how <acronym>XOM</acronym> values are interpreted by an
1058
output method.
1059
The first column lists the <acronym>XOM</acronym> values. The second column indicates
1060
how each of the <acronym>XOM</acronym> values are treated by a particular output style.
1061
</para>
1062
<para>
1063
<!-- .LP -->
1064
</para>
1065
<para>
1066
<!-- .LP -->
1067
The following key applies to this table.
1068
</para>
1069
1070
<informaltable>
1071
<tgroup cols='2' align='center'>
1072
<colspec colname='c1'/>
1073
<colspec colname='c2'/>
1074
<thead>
1075
<row>
1076
<entry>Key</entry>
1077
<entry>Explanation</entry>
1078
</row>
1079
</thead>
1080
<tbody>
1081
<row>
1082
<entry>G</entry>
1083
<entry>This value may be read using <function>XGetOMValues</function>.</entry>
1084
</row>
1085
</tbody>
1086
</tgroup>
1087
</informaltable>
1088
1089
<informaltable>
1090
<tgroup cols='2' align='center'>
1091
<colspec colname='c1'/>
1092
<colspec colname='c2'/>
1093
<thead>
1094
<row>
1095
<entry><acronym>XOM</acronym> Value</entry>
1096
<entry>Key</entry>
1097
</row>
1098
</thead>
1099
<tbody>
1100
<row>
1101
<entry><symbol>XNRequiredCharSet</symbol></entry>
1102
<entry>G</entry>
1103
</row>
1104
<row>
1105
<entry><symbol>XNQueryOrientation</symbol></entry>
1106
<entry>G</entry>
1107
</row>
1108
<row>
1109
<entry><symbol>XNDirectionalDependentDrawing</symbol></entry>
1110
<entry>G</entry>
1111
</row>
1112
<row>
1113
<entry><symbol>XNContextualDrawing</symbol></entry>
1114
<entry>G</entry>
1115
</row>
1116
</tbody>
1117
</tgroup>
1118
</informaltable>
1119
1120
<para>
1121
<!-- .LP -->
1122
</para>
1123
<sect3 id="Required_Char_Set">
1124
<title>Required Char Set</title>
1125
<!-- .XS -->
1126
<!-- (SN Required Char Set -->
1127
<!-- .XE -->
1128
<para>
1129
<!-- .LP -->
1130
The
1131
<symbol>XNRequiredCharSet</symbol>
1132
argument returns the list of charsets that are required for loading the fonts
1133
needed for the locale.
1134
The value of the argument is a pointer to a structure of type
1135
<structname>XOMCharSetList</structname>.
1136
</para>
1137
<para>
1138
<!-- .LP -->
1139
The
1140
<structname>XOMCharSetList</structname>
1141
structure is defined as follows:
1142
<indexterm significance="preferred"><primary>XOMCharSetList</primary></indexterm>
1143
<!-- .sM -->
1144
</para>
1145
<!-- .LP -->
1146
<literallayout class="monospaced">
1147
<!-- .TA .5i 2.5i -->
1148
<!-- .ta .5i 2.5i -->
1149
typedef struct {
1150
int charset_count;
1151
char **charset_list;
1152
} XOMCharSetList;
1153
</literallayout>
1154
1155
<para>
1156
<!-- .LP -->
1157
<!-- .eM -->
1158
The charset_list member is a list of one or more null-terminated
1159
charset names, and the charset_count member is the number of
1160
charset names.
1161
</para>
1162
<para>
1163
<!-- .LP -->
1164
The required charset list is owned by Xlib and should not be modified or
1165
freed by the client.
1166
It will be freed by a call to
1167
<function>XCloseOM</function>
1168
with the associated
1169
<type>XOM</type>.
1170
Until freed, its contents will not be modified by Xlib.
1171
</para>
1172
<para>
1173
<!-- .LP -->
1174
</para>
1175
</sect3>
1176
<sect3 id="Query_Orientation">
1177
<title>Query Orientation</title>
1178
<!-- .XS -->
1179
<!-- (SN Query Orientation -->
1180
<!-- .XE -->
1181
<para>
1182
<!-- .LP -->
1183
The
1184
<symbol>XNQueryOrientation</symbol>
1185
argument returns the global orientation of text when drawn.
1186
Other than
1187
<constant>XOMOrientation_LTR_TTB</constant>,
1188
the set of orientations supported is locale-dependent.
1189
The value of the argument is a pointer to a structure of type
1190
<structname>XOMOrientation</structname>.
1191
Clients are responsible for freeing the
1192
<structname>XOMOrientation</structname>
1193
structure by using
1194
<function>XFree</function>;
1195
this also frees the contents of the structure.
1196
</para>
1197
1198
<!-- .LP -->
1199
<!-- .sM -->
1200
<literallayout class="monospaced">
1201
<!-- .TA .5i 2.5i -->
1202
<!-- .ta .5i 2.5i -->
1203
typedef struct {
1204
int num_orientation;
1205
XOrientation *orientation; /* Input Text description */
1206
} XOMOrientation;
1207
1208
typedef enum {
1209
XOMOrientation_LTR_TTB,
1210
XOMOrientation_RTL_TTB,
1211
XOMOrientation_TTB_LTR,
1212
XOMOrientation_TTB_RTL,
1213
XOMOrientation_Context
1214
} XOrientation;
1215
</literallayout>
1216
1217
<para>
1218
<!-- .LP -->
1219
<!-- .eM -->
1220
The possible value for XOrientation may be:
1221
</para>
1222
<itemizedlist>
1223
<listitem>
1224
<para>
1225
<constant>XOMOrientation_LTR_TTB</constant>
1226
left-to-right, top-to-bottom global orientation
1227
</para>
1228
</listitem>
1229
<listitem>
1230
<para>
1231
<constant>XOMOrientation_RTL_TTB</constant>
1232
right-to-left, top-to-bottom global orientation
1233
</para>
1234
</listitem>
1235
<listitem>
1236
<para>
1237
<constant>XOMOrientation_TTB_LTR</constant>
1238
top-to-bottom, left-to-right global orientation
1239
</para>
1240
</listitem>
1241
<listitem>
1242
<para>
1243
<constant>XOMOrientation_TTB_RTL</constant>
1244
top-to-bottom, right-to-left global orientation
1245
</para>
1246
</listitem>
1247
<listitem>
1248
<para>
1249
<constant>XOMOrientation_Context</constant>
1250
contextual global orientation
1251
</para>
1252
</listitem>
1253
</itemizedlist>
1254
<para>
1255
<!-- .LP -->
1256
</para>
1257
</sect3>
1258
<sect3 id="Directional_Dependent_Drawing">
1259
<title>Directional Dependent Drawing</title>
1260
<!-- .XS -->
1261
<!-- (SN Directional Dependent Drawing -->
1262
<!-- .XE -->
1263
<para>
1264
<!-- .LP -->
1265
The
1266
<symbol>XNDirectionalDependentDrawing</symbol>
1267
argument indicates whether the text rendering functions
1268
implement implicit handling of directional text. If this value
1269
is
1270
<symbol>True</symbol>,
1271
the output method has knowledge of directional
1272
dependencies and reorders text as necessary when
1273
rendering text. If this value is
1274
<symbol>False</symbol>,
1275
the output method does not implement any directional text
1276
handling, and all character directions are assumed to be left-to-right.
1277
</para>
1278
<para>
1279
<!-- .LP -->
1280
Regardless of the rendering order of characters,
1281
the origins of all characters are on the primary draw direction side
1282
of the drawing origin.
1283
</para>
1284
<para>
1285
<!-- .LP -->
1286
This OM value presents functionality identical to the
1287
<function>XDirectionalDependentDrawing</function>
1288
function.
1289
</para>
1290
</sect3>
1291
<sect3 id="Context_Dependent_Drawing">
1292
<title>Context Dependent Drawing</title>
1293
<!-- .XS -->
1294
<!-- (SN Context Dependent Drawing -->
1295
<!-- .XE -->
1296
<para>
1297
<!-- .LP -->
1298
The
1299
<symbol>XNContextualDrawing</symbol>
1300
argument indicates whether the text rendering functions
1301
implement implicit context-dependent drawing. If this value is
1302
<symbol>True</symbol>,
1303
the output method has knowledge of context dependencies and
1304
performs character shape editing, combining glyphs to present
1305
a single character as necessary. The actual shape editing is
1306
dependent on the locale implementation and the font set used.
1307
</para>
1308
<para>
1309
<!-- .LP -->
1310
This OM value presents functionality identical to the
1311
<function>XContextualDrawing</function>
1312
function.
1313
</para>
1314
</sect3>
1315
</sect2>
1316
<sect2 id="Output_Context_Functions">
1317
<title>Output Context Functions</title>
1318
<!-- .XS -->
1319
<!-- (SN Output Context Functions -->
1320
<!-- .XE -->
1321
<para>
1322
<!-- .LP -->
1323
An output context is an abstraction that contains both the data
1324
required by an output method and the information required
1325
to display that data.
1326
There can be multiple output contexts for one output method.
1327
The programming interfaces for creating, reading, or modifying
1328
an output context use a variable argument list.
1329
The name elements of the argument lists are referred to as <acronym>XOC</acronym> values.
1330
It is intended that output methods be controlled by these <acronym>XOC</acronym> values.
1331
As new <acronym>XOC</acronym> values are created,
1332
they should be registered with the X Consortium.
1333
An
1334
<type>XOC</type>
1335
can be used anywhere an
1336
<type>XFontSet</type>
1337
can be used, and vice versa;
1338
<type>XFontSet</type>
1339
is retained for compatibility with previous releases.
1340
The concepts of output methods and output contexts include broader,
1341
more generalized abstraction than font set,
1342
supporting complex and more intelligent text display, and dealing not only
1343
with multiple fonts but also with context dependencies.
1344
However,
1345
<type>XFontSet</type>
1346
is widely used in several interfaces, so
1347
<type>XOC</type>
1348
is defined as an upward compatible type of
1349
<type>XFontSet</type>.
1350
</para>
1351
<para>
1352
<!-- .LP -->
1353
<!-- .sp -->
1354
To create an output context, use
1355
<function>XCreateOC</function>.
1356
<indexterm significance="preferred"><primary>XCreateOC</primary></indexterm>
1357
<!-- .sM -->
1358
<funcsynopsis>
1359
<funcprototype>
1360
<funcdef>XOC <function>XCreateOC</function></funcdef>
1361
<paramdef>XOM<parameter> om</parameter></paramdef>
1362
</funcprototype>
1363
</funcsynopsis>
1364
<!-- .FN -->
1365
<variablelist>
1366
<varlistentry>
1367
<term>
1368
<emphasis remap='I'>om</emphasis>
1369
</term>
1370
<listitem>
1371
<para>
1372
Specifies the output method.
1373
<!-- .ds Al \ to set <acronym>XOC</acronym> values -->
1374
</para>
1375
</listitem>
1376
</varlistentry>
1377
<varlistentry>
1378
<term>
1379
...
1380
</term>
1381
<listitem>
1382
<para>
1383
Specifies the variable-length argument list(Al.
1384
</para>
1385
</listitem>
1386
</varlistentry>
1387
</variablelist>
1388
</para>
1389
<para>
1390
<!-- .LP -->
1391
<!-- .eM -->
1392
The
1393
<function>XCreateOC</function>
1394
function creates an output context within the specified output method.
1395
</para>
1396
<para>
1397
<!-- .LP -->
1398
The base font names argument is mandatory at creation time, and
1399
the output context will not be created unless it is provided.
1400
All other output context values can be set later.
1401
</para>
1402
<para>
1403
<!-- .LP -->
1404
<function>XCreateOC</function>
1405
returns NULL if no output context could be created.
1406
NULL can be returned for any of the following reasons:
1407
</para>
1408
<itemizedlist>
1409
<listitem>
1410
<para>
1411
A required argument was not set.
1412
</para>
1413
</listitem>
1414
<listitem>
1415
<para>
1416
A read-only argument was set.
1417
</para>
1418
</listitem>
1419
<listitem>
1420
<para>
1421
An argument name is not recognized.
1422
</para>
1423
</listitem>
1424
<listitem>
1425
<para>
1426
The output method encountered an output method implementation-dependent error.
1427
</para>
1428
</listitem>
1429
</itemizedlist>
1430
<para>
1431
<!-- .LP -->
1432
<function>XCreateOC</function>
1433
can generate a
1434
<errorname>BadAtom</errorname>
1435
error.
1436
</para>
1437
<para>
1438
<!-- .LP -->
1439
<!-- .sp -->
1440
To destroy an output context, use
1441
<function>XDestroyOC</function>.
1442
<indexterm significance="preferred"><primary>XDestroyOC</primary></indexterm>
1443
<!-- .sM -->
1444
<funcsynopsis>
1445
<funcprototype>
1446
<funcdef>void <function>XDestroyOC</function></funcdef>
1447
<paramdef>XOC<parameter> oc</parameter></paramdef>
1448
</funcprototype>
1449
</funcsynopsis>
1450
<!-- .FN -->
1451
<variablelist>
1452
<varlistentry>
1453
<term>
1454
<emphasis remap='I'>oc</emphasis>
1455
</term>
1456
<listitem>
1457
<para>
1458
Specifies the output context.
1459
</para>
1460
</listitem>
1461
</varlistentry>
1462
</variablelist>
1463
</para>
1464
<para>
1465
<!-- .LP -->
1466
<!-- .eM -->
1467
The
1468
<function>XDestroyOC</function>
1469
function destroys the specified output context.
1470
</para>
1471
<para>
1472
<!-- .LP -->
1473
<!-- .sp -->
1474
To get the output method associated with an output context, use
1475
<function>XOMOfOC</function>.
1476
<indexterm significance="preferred"><primary>XOMOfOC</primary></indexterm>
1477
<!-- .sM -->
1478
<funcsynopsis>
1479
<funcprototype>
1480
<funcdef>XOM <function>XOMOfOC</function></funcdef>
1481
<paramdef>XOC<parameter> oc</parameter></paramdef>
1482
</funcprototype>
1483
</funcsynopsis>
1484
<!-- .FN -->
1485
<variablelist>
1486
<varlistentry>
1487
<term>
1488
<emphasis remap='I'>oc</emphasis>
1489
</term>
1490
<listitem>
1491
<para>
1492
Specifies the output context.
1493
</para>
1494
</listitem>
1495
</varlistentry>
1496
</variablelist>
1497
</para>
1498
<para>
1499
<!-- .LP -->
1500
<!-- .eM -->
1501
The
1502
<function>XOMOfOC</function>
1503
function returns the output method associated with the
1504
specified output context.
1505
</para>
1506
<para>
1507
<!-- .LP -->
1508
<!-- .sp -->
1509
Xlib provides two functions for setting and reading output context values,
1510
respectively,
1511
<function>XSetOCValues</function>
1512
and
1513
<function>XGetOCValues</function>.
1514
Both functions have a variable-length argument list.
1515
In that argument list, any <acronym>XOC</acronym> value's name must be denoted
1516
with a character string using the X Portable Character Set.
1517
</para>
1518
<para>
1519
<!-- .LP -->
1520
<!-- .sp -->
1521
To set <acronym>XOC</acronym> values, use
1522
<function>XSetOCValues</function>.
1523
<indexterm significance="preferred"><primary>XSetOCValues</primary></indexterm>
1524
<!-- .sM -->
1525
<funcsynopsis>
1526
<funcprototype>
1527
<funcdef>char *<function>XSetOCValues</function></funcdef>
1528
<paramdef>XOC<parameter> oc</parameter></paramdef>
1529
</funcprototype>
1530
</funcsynopsis>
1531
<!-- .FN -->
1532
<variablelist>
1533
<varlistentry>
1534
<term>
1535
<emphasis remap='I'>oc</emphasis>
1536
</term>
1537
<listitem>
1538
<para>
1539
Specifies the output context.
1540
<!-- .ds Al \ to set <acronym>XOC</acronym> values -->
1541
</para>
1542
</listitem>
1543
</varlistentry>
1544
<varlistentry>
1545
<term>
1546
...
1547
</term>
1548
<listitem>
1549
<para>
1550
Specifies the variable-length argument list(Al.
1551
</para>
1552
</listitem>
1553
</varlistentry>
1554
</variablelist>
1555
</para>
1556
<para>
1557
<!-- .LP -->
1558
<!-- .eM -->
1559
The
1560
<function>XSetOCValues</function>
1561
function returns NULL if no error occurred;
1562
otherwise,
1563
it returns the name of the first argument that could not be set.
1564
An argument might not be set for any of the following reasons:
1565
</para>
1566
<itemizedlist>
1567
<listitem>
1568
<para>
1569
The argument is read-only.
1570
</para>
1571
</listitem>
1572
<listitem>
1573
<para>
1574
The argument name is not recognized.
1575
</para>
1576
</listitem>
1577
<listitem>
1578
<para>
1579
An implementation-dependent error occurs.
1580
</para>
1581
</listitem>
1582
</itemizedlist>
1583
<para>
1584
<!-- .LP -->
1585
Each value to be set must be an appropriate datum,
1586
matching the data type imposed by the semantics of the argument.
1587
</para>
1588
<para>
1589
<!-- .LP -->
1590
<function>XSetOCValues</function>
1591
can generate a
1592
<errorname>BadAtom</errorname>
1593
error.
1594
</para>
1595
<para>
1596
<!-- .LP -->
1597
<!-- .sp -->
1598
To obtain <acronym>XOC</acronym> values, use
1599
<function>XGetOCValues</function>.
1600
<indexterm significance="preferred"><primary>XGetOCValues</primary></indexterm>
1601
<!-- .sM -->
1602
<funcsynopsis>
1603
<funcprototype>
1604
<funcdef>char *<function>XGetOCValues</function></funcdef>
1605
<paramdef>XOC<parameter> oc</parameter></paramdef>
1606
</funcprototype>
1607
</funcsynopsis>
1608
<!-- .FN -->
1609
<variablelist>
1610
<varlistentry>
1611
<term>
1612
<emphasis remap='I'>oc</emphasis>
1613
</term>
1614
<listitem>
1615
<para>
1616
Specifies the output context.
1617
<!-- .ds Al \ to get XOC values -->
1618
</para>
1619
</listitem>
1620
</varlistentry>
1621
<varlistentry>
1622
<term>
1623
...
1624
</term>
1625
<listitem>
1626
<para>
1627
Specifies the variable-length argument list(Al.
1628
</para>
1629
</listitem>
1630
</varlistentry>
1631
</variablelist>
1632
</para>
1633
<para>
1634
<!-- .LP -->
1635
<!-- .eM -->
1636
The
1637
<function>XGetOCValues</function>
1638
function returns NULL if no error occurred; otherwise,
1639
it returns the name of the first argument that could not be obtained.
1640
An argument might not be obtained for any of the following reasons:
1641
</para>
1642
<itemizedlist>
1643
<listitem>
1644
<para>
1645
The argument name is not recognized.
1646
</para>
1647
</listitem>
1648
<listitem>
1649
<para>
1650
An implementation-dependent error occurs.
1651
</para>
1652
</listitem>
1653
</itemizedlist>
1654
<para>
1655
<!-- .LP -->
1656
Each argument value
1657
following a name must point to a location where the value is to be stored.
1658
</para>
1659
</sect2>
1660
1661
<sect2 id="Output_Context_Values">
1662
<title>Output Context Values</title>
1663
<!-- .XS -->
1664
<!-- (SN Output Context Values -->
1665
<!-- .XE -->
1666
<para>
1667
<!-- .LP -->
1668
The following table describes how <acronym>XOC</acronym> values are interpreted
1669
by an output method.
1670
The first column lists the <acronym>XOC</acronym> values.
1671
The second column indicates the alternative interfaces that function
1672
identically and are provided for compatibility with previous releases.
1673
The third column indicates how each of the <acronym>XOC</acronym> values is treated.
1674
</para>
1675
<!-- .LP -->
1676
<para>
1677
The following keys apply to this table.
1678
</para>
1679
<informaltable>
1680
<tgroup cols='2' align='center'>
1681
<colspec colname='c1'/>
1682
<colspec colname='c2'/>
1683
<thead>
1684
<row>
1685
<entry>Key</entry>
1686
<entry>Explanation</entry>
1687
</row>
1688
</thead>
1689
<tbody>
1690
<row>
1691
<entry>C</entry>
1692
<entry>This value must be set with <function>XCreateOC</function>.</entry>
1693
</row>
1694
<row>
1695
<entry>D</entry>
1696
<entry>This value may be set using <function>XCreateOC</function>.
1697
If it is not set,a default is provided.</entry>
1698
</row>
1699
<row>
1700
<entry>G</entry>
1701
<entry>This value may be read using <function>XGetOCValues</function>.</entry>
1702
</row>
1703
<row>
1704
<entry>S</entry>
1705
<entry>This value must be set using <function>XSetOCValues</function>.</entry>
1706
</row>
1707
</tbody>
1708
</tgroup>
1709
</informaltable>
1710
1711
<!-- .LP -->
1712
<informaltable>
1713
<tgroup cols='3' align='center'>
1714
<colspec colname='c1'/>
1715
<colspec colname='c2'/>
1716
<colspec colname='c3'/>
1717
<thead>
1718
<row>
1719
<entry><acronym>XOC</acronym> Value</entry>
1720
<entry>Alternative Interface</entry>
1721
<entry>Key</entry>
1722
</row>
1723
</thead>
1724
<tbody>
1725
<row>
1726
<entry>BaseFontName</entry>
1727
<entry><function>XCreateFontSet</function></entry>
1728
<entry>C-G</entry>
1729
</row>
1730
<row>
1731
<entry>MissingCharSet</entry>
1732
<entry><function>XCreateFontSet</function></entry>
1733
<entry>G</entry>
1734
</row>
1735
<row>
1736
<entry>DefaultString</entry>
1737
<entry><function>XCreateFontSet</function></entry>
1738
<entry>G</entry>
1739
</row>
1740
<row>
1741
<entry>Orientation</entry>
1742
<entry>-</entry>
1743
<entry>D-S-G</entry>
1744
</row>
1745
<row>
1746
<entry>ResourceName</entry>
1747
<entry>-</entry>
1748
<entry>S-G</entry>
1749
</row>
1750
<row>
1751
<entry>ResourceClass</entry>
1752
<entry>-</entry>
1753
<entry>S-G</entry>
1754
</row>
1755
<row>
1756
<entry>FontInfo</entry>
1757
<entry><function>XFontsOfFontSet</function></entry>
1758
<entry>G</entry>
1759
</row>
1760
<row>
1761
<entry>OMAutomatic</entry>
1762
<entry>-</entry>
1763
<entry>G</entry>
1764
</row>
1765
</tbody>
1766
</tgroup>
1767
</informaltable>
1768
1769
<para>
1770
<!-- .LP -->
1771
</para>
1772
<sect3 id="Base_Font_Name">
1773
<title>Base Font Name</title>
1774
<!-- .XS -->
1775
<!-- (SN Base Font Name -->
1776
<!-- .XE -->
1777
<para>
1778
<!-- .LP -->
1779
The
1780
<symbol>XNBaseFontName</symbol>
1781
argument is a list of base font names that Xlib uses
1782
to load the fonts needed for the locale.
1783
The base font names are a comma-separated list. The string is null-terminated
1784
and is assumed to be in the Host Portable Character Encoding;
1785
otherwise, the result is implementation-dependent.
1786
White space immediately on either side of a separating comma is ignored.
1787
</para>
1788
<para>
1789
<!-- .LP -->
1790
Use of <acronym>XLFD</acronym> font names permits Xlib to obtain the fonts needed for a
1791
variety of locales from a single locale-independent base font name.
1792
The single base font name should name a family of fonts whose members
1793
are encoded in the various charsets needed by the locales of interest.
1794
</para>
1795
<para>
1796
<!-- .LP -->
1797
An <acronym>XLFD</acronym> base font name can explicitly name a charset needed for the locale.
1798
This allows the user to specify an exact font for use with a charset required
1799
by a locale, fully controlling the font selection.
1800
</para>
1801
<para>
1802
<!-- .LP -->
1803
If a base font name is not an <acronym>XLFD</acronym> name,
1804
Xlib will attempt to obtain an <acronym>XLFD</acronym> name from the font properties
1805
for the font.
1806
If Xlib is successful, the
1807
<function>XGetOCValues</function>
1808
function will return this <acronym>XLFD</acronym> name instead of the client-supplied name.
1809
</para>
1810
<para>
1811
<!-- .LP -->
1812
This argument must be set at creation time
1813
and cannot be changed.
1814
If no fonts exist for any of the required charsets,
1815
or if the locale definition in Xlib requires that a font exist
1816
for a particular charset and a font is not found for that charset,
1817
<function>XCreateOC</function>
1818
returns NULL.
1819
</para>
1820
<para>
1821
<!-- .LP -->
1822
When querying for the
1823
<symbol>XNBaseFontName</symbol>
1824
<acronym>XOC</acronym> value,
1825
<function>XGetOCValues</function>
1826
returns a null-terminated string identifying the base font names that
1827
Xlib used to load the fonts needed for the locale.
1828
This string is owned by Xlib and should not be modified or freed by
1829
the client.
1830
The string will be freed by a call to
1831
<function>XDestroyOC</function>
1832
with the associated
1833
<type>XOC</type>.
1834
Until freed, the string contents will not be modified by Xlib.
1835
</para>
1836
</sect3>
1837
<sect3 id="Missing_CharSet">
1838
<title>Missing CharSet</title>
1839
<!-- .XS -->
1840
<!-- (SN Missing CharSet -->
1841
<!-- .XE -->
1842
<para>
1843
<!-- .LP -->
1844
The
1845
<symbol>XNMissingCharSet</symbol>
1846
argument returns the list of required charsets that are missing from the
1847
font set.
1848
The value of the argument is a pointer to a structure of type
1849
<structname>XOMCharSetList</structname>.
1850
</para>
1851
<para>
1852
<!-- .LP -->
1853
If fonts exist for all of the charsets required by the current locale,
1854
charset_list is set to NULL and charset_count is set to zero.
1855
If no fonts exist for one or more of the required charsets,
1856
charset_list is set to a list of one or more null-terminated charset names
1857
for which no fonts exist, and charset_count is set to the number of
1858
missing charsets.
1859
The charsets are from the list of the required charsets for
1860
the encoding of the locale and do not include any charsets to which Xlib
1861
may be able to remap a required charset.
1862
</para>
1863
<para>
1864
<!-- .LP -->
1865
The missing charset list is owned by Xlib and should not be modified or
1866
freed by the client.
1867
It will be freed by a call to
1868
<function>XDestroyOC</function>
1869
with the associated
1870
<type>XOC</type>.
1871
Until freed, its contents will not be modified by Xlib.
1872
</para>
1873
</sect3>
1874
<sect3 id="Default_String">
1875
<title>Default String</title>
1876
<!-- .XS -->
1877
<!-- (SN Default String -->
1878
<!-- .XE -->
1879
<para>
1880
<!-- .LP -->
1881
When a drawing or measuring function is called with an
1882
<type>XOC</type>
1883
that has missing charsets, some characters in the locale will not be
1884
drawable.
1885
The
1886
<symbol>XNDefaultString</symbol>
1887
argument returns a pointer to a string that represents the glyphs
1888
that are drawn with this
1889
<type>XOC</type>
1890
when the charsets of the available fonts do not include all glyphs
1891
required to draw a character.
1892
The string does not necessarily consist of valid characters
1893
in the current locale and is not necessarily drawn with
1894
the fonts loaded for the font set,
1895
but the client can draw or measure the default glyphs
1896
by including this string in a string being drawn or measured with the
1897
<type>XOC</type>.
1898
</para>
1899
<para>
1900
<!-- .LP -->
1901
If the
1902
<symbol>XNDefaultString</symbol>
1903
argument returned the empty string (""),
1904
no glyphs are drawn and the escapement is zero.
1905
The returned string is null-terminated.
1906
It is owned by Xlib and should not be modified or freed by the client.
1907
It will be freed by a call to
1908
<function>XDestroyOC</function>
1909
with the associated
1910
<type>XOC</type>.
1911
Until freed, its contents will not be modified by Xlib.
1912
</para>
1913
</sect3>
1914
<sect3 id="Orientation">
1915
<title>Orientation</title>
1916
<!-- .XS -->
1917
<!-- (SN Orientation -->
1918
<!-- .XE -->
1919
<para>
1920
<!-- .LP -->
1921
The
1922
<symbol>XNOrientation</symbol>
1923
argument specifies the current orientation of text when drawn. The value of
1924
this argument is one of the values returned by the
1925
<function>XGetOMValues</function>
1926
function with the
1927
<symbol>XNQueryOrientation</symbol>
1928
argument specified in the
1929
<type>XOrientation</type>
1930
list.
1931
The value of the argument is of type
1932
<type>XOrientation</type>.
1933
When
1934
<symbol>XNOrientation</symbol>
1935
is queried, the value specifies the current orientation.
1936
When
1937
<symbol>XNOrientation</symbol>
1938
is set, a value is used to set the current orientation.
1939
</para>
1940
<para>
1941
<!-- .LP -->
1942
When
1943
<constant>XOMOrientation_Context</constant>
1944
is set, the text orientation of the
1945
text is determined according to an implementation-defined method
1946
(for example, ISO 6429 control sequences), and the initial text orientation for
1947
locale-dependent Xlib functions is assumed to
1948
be
1949
<constant>XOMOrientation_LTR_TTB</constant>.
1950
</para>
1951
<para>
1952
<!-- .LP -->
1953
The
1954
<symbol>XNOrientation</symbol>
1955
value does not change the prime drawing direction
1956
for Xlib drawing functions.
1957
</para>
1958
</sect3>
1959
<sect3 id="Resource_Name_and_Class">
1960
<title>Resource Name and Class</title>
1961
<!-- .XS -->
1962
<!-- (SN Resource Name and Class -->
1963
<!-- .XE -->
1964
<para>
1965
<!-- .LP -->
1966
The
1967
<symbol>XNResourceName</symbol>
1968
and
1969
<symbol>XNResourceClass</symbol>
1970
arguments are strings that specify the full name and class
1971
used by the client to obtain resources for the display of the output context.
1972
These values should be used as prefixes for name and class
1973
when looking up resources that may vary according to the output context.
1974
If these values are not set,
1975
the resources will not be fully specified.
1976
</para>
1977
<para>
1978
<!-- .LP -->
1979
It is not intended that values that can be set as <acronym>XOM</acronym> values be
1980
set as resources.
1981
</para>
1982
<para>
1983
<!-- .LP -->
1984
When querying for the
1985
<symbol>XNResourceName</symbol>
1986
or
1987
<symbol>XNResourceClass</symbol>
1988
<acronym>XOC</acronym> value,
1989
<function>XGetOCValues</function>
1990
returns a null-terminated string.
1991
This string is owned by Xlib and should not be modified or freed by
1992
the client.
1993
The string will be freed by a call to
1994
<function>XDestroyOC</function>
1995
with the associated
1996
<type>XOC</type>
1997
or when the associated value is changed via
1998
<function>XSetOCValues</function>.
1999
Until freed, the string contents will not be modified by Xlib.
2000
</para>
2001
</sect3>
2002
<sect3 id="Font_Info">
2003
<title>Font Info</title>
2004
<!-- .XS -->
2005
<!-- (SN Font Info -->
2006
<!-- .XE -->
2007
<para>
2008
<!-- .LP -->
2009
The
2010
<symbol>XNFontInfo</symbol>
2011
argument specifies a list of one or more
2012
<structname>XFontStruct</structname>
2013
structures
2014
and font names for the fonts used for drawing by the given output context.
2015
The value of the argument is a pointer to a structure of type
2016
<structname>XOMFontInfo</structname>.
2017
</para>
2018
<para>
2019
<!-- .LP -->
2020
<!-- .sM -->
2021
<literallayout class="monospaced">
2022
<!-- .TA .5i 2.5i -->
2023
<!-- .ta .5i 2.5i -->
2024
typedef struct {
2025
int num_font;
2026
XFontStruct **font_struct_list;
2027
char **font_name_list;
2028
} XOMFontInfo;
2029
</literallayout>
2030
</para>
2031
<para>
2032
<!-- .LP -->
2033
<!-- .eM -->
2034
A list of pointers to the
2035
<structname>XFontStruct</structname>
2036
structures is returned to font_struct_list.
2037
A list of pointers to null-terminated, fully-specified font name strings
2038
in the locale of the output context is returned to font_name_list.
2039
The font_name_list order corresponds to the font_struct_list order.
2040
The number of
2041
<structname>XFontStruct</structname>
2042
structures and font names is returned to num_font.
2043
</para>
2044
<para>
2045
<!-- .LP -->
2046
Because it is not guaranteed that a given character will be imaged using a
2047
single font glyph,
2048
there is no provision for mapping a character or default string
2049
to the font properties, font ID, or direction hint for the font
2050
for the character.
2051
The client may access the
2052
<structname>XFontStruct</structname>
2053
list to obtain these values for all the fonts currently in use.
2054
</para>
2055
<para>
2056
<!-- .LP -->
2057
Xlib does not guarantee that fonts are loaded from the server
2058
at the creation of an
2059
<type>XOC</type>.
2060
Xlib may choose to cache font data, loading it only as needed to draw text
2061
or compute text dimensions.
2062
Therefore, existence of the per_char metrics in the
2063
<structname>XFontStruct</structname>
2064
structures in the
2065
<structname>XFontStructSet</structname>
2066
is undefined.
2067
Also, note that all properties in the
2068
<structname>XFontStruct</structname>
2069
structures are in the STRING encoding.
2070
</para>
2071
<para>
2072
<!-- .LP -->
2073
The client must not free the
2074
<structname>XOMFontInfo</structname>
2075
struct itself; it will be freed when the
2076
<type>XOC</type>
2077
is closed.
2078
</para>
2079
</sect3>
2080
<sect3 id="OM_Automatic">
2081
<title>OM Automatic</title>
2082
<!-- .XS -->
2083
<!-- (SN OM Automatic -->
2084
<!-- .XE -->
2085
<para>
2086
<!-- .LP -->
2087
The
2088
<symbol>XNOMAutomatic</symbol>
2089
argument returns whether the associated output context was created by
2090
<function>XCreateFontSet</function>
2091
or not. Because the
2092
<function>XFreeFontSet</function>
2093
function not only destroys the output context but also closes the implicit
2094
output method associated with it,
2095
<function>XFreeFontSet</function>
2096
should be used with any output context created by
2097
<function>XCreateFontSet</function>.
2098
However, it is possible that a client does not know how the output context
2099
was created.
2100
Before a client destroys the output context,
2101
it can query whether
2102
<symbol>XNOMAutomatic</symbol>
2103
is set to determine whether
2104
<function>XFreeFontSet</function>
2105
or
2106
<function>XDestroyOC</function>
2107
should be used to destroy the output context.
2108
</para>
2109
</sect3>
2110
</sect2>
2111
<sect2 id="Creating_and_Freeing_a_Font_Set">
2112
<title>Creating and Freeing a Font Set</title>
2113
<!-- .XS -->
2114
<!-- (SN Creating and Freeing a Font Set -->
2115
<!-- .XE -->
2116
<para>
2117
<!-- .LP -->
2118
Xlib international text drawing is done using a set of one or more fonts,
2119
as needed for the locale of the text.
2120
Fonts are loaded according to a list of base font names
2121
supplied by the client and the charsets required by the locale.
2122
The
2123
<type>XFontSet</type>
2124
is an opaque type representing the state of a particular output thread
2125
and is equivalent to the type
2126
<type>XOC</type>.
2127
</para>
2128
<para>
2129
<!-- .LP -->
2130
<!-- .sp -->
2131
The
2132
<function>XCreateFontSet</function>
2133
function is a convenience function for creating an output context using
2134
only default values. The returned
2135
<type>XFontSet</type>
2136
has an implicitly created
2137
<type>XOM</type>.
2138
This
2139
<type>XOM</type>
2140
has an OM value
2141
<symbol>XNOMAutomatic</symbol>
2142
automatically set to
2143
<symbol>True</symbol>
2144
so that the output context self indicates whether it was created by
2145
<function>XCreateOC</function>
2146
or
2147
<function>XCreateFontSet</function>.
2148
<indexterm significance="preferred"><primary>XCreateFontSet</primary></indexterm>
2149
<!-- .sM -->
2150
<funcsynopsis>
2151
<funcprototype>
2152
<funcdef>XFontSet <function>XCreateFontSet</function></funcdef>
2153
<paramdef>Display<parameter> *display</parameter></paramdef>
2154
<paramdef>char<parameter> *base_font_name_list</parameter></paramdef>
2155
<paramdef>char<parameter> ***missing_charset_list_return</parameter></paramdef>
2156
<paramdef>int<parameter> *missing_charset_count_return</parameter></paramdef>
2157
<paramdef>char<parameter> **def_string_return</parameter></paramdef>
2158
</funcprototype>
2159
</funcsynopsis>
2160
<!-- .FN -->
2161
<variablelist>
2162
<varlistentry>
2163
<term>
2164
<emphasis remap='I'>display</emphasis>
2165
</term>
2166
<listitem>
2167
<para>
2168
Specifies the connection to the X server.
2169
</para>
2170
</listitem>
2171
</varlistentry>
2172
<varlistentry>
2173
<term>
2174
<emphasis remap='I'>base_font_name_list</emphasis>
2175
</term>
2176
<listitem>
2177
<para>
2178
Specifies the base font names.
2179
</para>
2180
</listitem>
2181
</varlistentry>
2182
<varlistentry>
2183
<term>
2184
<emphasis remap='I'>missing_charset_list_return</emphasis>
2185
</term>
2186
<listitem>
2187
<para>
2188
Returns the missing charsets.
2189
</para>
2190
</listitem>
2191
</varlistentry>
2192
<varlistentry>
2193
<term>
2194
<emphasis remap='I'>missing_charset_count_return</emphasis>
2195
</term>
2196
<listitem>
2197
<para>
2198
Returns the number of missing charsets.
2199
</para>
2200
</listitem>
2201
</varlistentry>
2202
<varlistentry>
2203
<term>
2204
<emphasis remap='I'>def_string_return</emphasis>
2205
</term>
2206
<listitem>
2207
<para>
2208
Returns the string drawn for missing charsets.
2209
</para>
2210
</listitem>
2211
</varlistentry>
2212
</variablelist>
2213
</para>
2214
<para>
2215
<!-- .LP -->
2216
<!-- .eM -->
2217
The
2218
<function>XCreateFontSet</function>
2219
function creates a font set for the specified display.
2220
The font set is bound to the current locale when
2221
<function>XCreateFontSet</function>
2222
is called.
2223
The font set may be used in subsequent calls to obtain font
2224
and character information and to image text in the locale of the font set.
2225
</para>
2226
<para>
2227
<!-- .LP -->
2228
The base_font_name_list argument is a list of base font names
2229
that Xlib uses to load the fonts needed for the locale.
2230
The base font names are a comma-separated list.
2231
The string is null-terminated
2232
and is assumed to be in the Host Portable Character Encoding;
2233
otherwise, the result is implementation-dependent.
2234
White space immediately on either side of a separating comma is ignored.
2235
</para>
2236
<para>
2237
<!-- .LP -->
2238
Use of <acronym>XLFD</acronym> font names permits Xlib to obtain the fonts needed for a
2239
variety of locales from a single locale-independent base font name.
2240
The single base font name should name a family of fonts whose members
2241
are encoded in the various charsets needed by the locales of interest.
2242
</para>
2243
<para>
2244
<!-- .LP -->
2245
An <acronym>XLFD</acronym> base font name can explicitly name a charset needed for the locale.
2246
This allows the user to specify an exact font for use with a charset required
2247
by a locale, fully controlling the font selection.
2248
</para>
2249
<para>
2250
<!-- .LP -->
2251
If a base font name is not an <acronym>XLFD</acronym> name,
2252
Xlib will attempt to obtain an <acronym>XLFD</acronym> name from the font properties
2253
for the font.
2254
If this action is successful in obtaining an <acronym>XLFD</acronym> name, the
2255
<function>XBaseFontNameListOfFontSet</function>
2256
function will return this <acronym>XLFD</acronym> name instead of the client-supplied name.
2257
</para>
2258
<para>
2259
<!-- .LP -->
2260
Xlib uses the following algorithm to select the fonts
2261
that will be used to display text with the
2262
<type>XFontSet</type>.
2263
</para>
2264
<para>
2265
<!-- .LP -->
2266
For each font charset required by the locale,
2267
the base font name list is searched for the first appearance of one
2268
of the following cases that names a set of fonts that exist at the server:
2269
</para>
2270
<itemizedlist>
2271
<listitem>
2272
<para>
2273
The first <acronym>XLFD</acronym>-conforming base font name that specifies the required
2274
charset or a superset of the required charset in its
2275
<structfield>CharSetRegistry</structfield>
2276
and
2277
<structfield>CharSetEncoding</structfield>
2278
fields.
2279
The implementation may use a base font name whose specified charset
2280
is a superset of the required charset, for example,
2281
an ISO8859-1 font for an ASCII charset.
2282
</para>
2283
</listitem>
2284
<listitem>
2285
<para>
2286
The first set of one or more <acronym>XLFD</acronym>-conforming base font names
2287
that specify one or more charsets that can be remapped to support the
2288
required charset.
2289
The Xlib implementation may recognize various mappings
2290
from a required charset to one or more other charsets
2291
and use the fonts for those charsets.
2292
For example, JIS Roman is ASCII with tilde and backslash replaced
2293
by yen and overbar;
2294
Xlib may load an ISO8859-1 font to support this character set
2295
if a JIS Roman font is not available.
2296
</para>
2297
</listitem>
2298
<listitem>
2299
<para>
2300
The first <acronym>XLFD</acronym>-conforming font name or the first non-<acronym>XLFD</acronym> font name
2301
for which an <acronym>XLFD</acronym> font name can be obtained, combined with the
2302
required charset (replacing the
2303
<structfield>CharSetRegistry</structfield>
2304
and
2305
<structfield>CharSetEncoding</structfield>
2306
fields in the <acronym>XLFD</acronym> font name).
2307
As in case 1,
2308
the implementation may use a charset that is a superset
2309
of the required charset.
2310
</para>
2311
</listitem>
2312
<listitem>
2313
<para>
2314
The first font name that can be mapped in some implementation-dependent
2315
manner to one or more fonts that support imaging text in the charset.
2316
</para>
2317
</listitem>
2318
</itemizedlist>
2319
<para>
2320
<!-- .LP -->
2321
For example, assume that a locale required the charsets:
2322
</para>
2323
<para>
2324
<!-- .LP -->
2325
<literallayout class="monospaced">
2326
ISO8859-1
2327
JISX0208.1983
2328
JISX0201.1976
2329
GB2312-1980.0
2330
</literallayout>
2331
</para>
2332
<para>
2333
<!-- .LP -->
2334
The user could supply a base_font_name_list that explicitly specifies the
2335
charsets, ensuring that specific fonts are used if they exist.
2336
For example:
2337
</para>
2338
<para>
2339
<!-- .LP -->
2340
<literallayout class="monospaced">
2341
"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240-JISX0208.1983-0,\\
2342
-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120-JISX0201.1976-0,\\
2343
-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240-GB2312-1980.0,\\
2344
-Adobe-Courier-Bold-R-Normal--25-180-75-75-M-150-ISO8859-1"
2345
</literallayout>
2346
</para>
2347
<para>
2348
<!-- .LP -->
2349
Alternatively, the user could supply a base_font_name_list
2350
that omits the charsets,
2351
letting Xlib select font charsets required for the locale.
2352
For example:
2353
</para>
2354
<para>
2355
<!-- .LP -->
2356
<literallayout class="monospaced">
2357
"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\
2358
-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120,\\
2359
-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\
2360
-Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150"
2361
</literallayout>
2362
</para>
2363
<para>
2364
<!-- .LP -->
2365
Alternatively, the user could simply supply a single base font name
2366
that allows Xlib to select from all available fonts
2367
that meet certain minimum <acronym>XLFD</acronym> property requirements.
2368
For example:
2369
</para>
2370
<para>
2371
<!-- .LP -->
2372
<literallayout class="monospaced">
2373
"-*-*-*-R-Normal--*-180-100-100-*-*"
2374
</literallayout>
2375
</para>
2376
<para>
2377
<!-- .LP -->
2378
If
2379
<function>XCreateFontSet</function>
2380
is unable to create the font set,
2381
either because there is insufficient memory or because the current locale
2382
is not supported,
2383
<function>XCreateFontSet</function>
2384
returns NULL, missing_charset_list_return is set to NULL,
2385
and missing_charset_count_return
2386
is set to zero.
2387
If fonts exist for all of the charsets required by the current locale,
2388
<function>XCreateFontSet</function>
2389
returns a valid
2390
<type>XFontSet</type>,
2391
missing_charset_list_return is set to NULL,
2392
and missing_charset_count_return is set to zero.
2393
</para>
2394
<para>
2395
<!-- .LP -->
2396
If no font exists for one or more of the required charsets,
2397
<function>XCreateFontSet</function>
2398
sets missing_charset_list_return to a
2399
list of one or more null-terminated charset names for which no font exists
2400
and sets missing_charset_count_return to the number of missing fonts.
2401
The charsets are from the list of the required charsets for
2402
the encoding of the locale and do not include any charsets to which Xlib
2403
may be able to remap a required charset.
2404
</para>
2405
<para>
2406
<!-- .LP -->
2407
If no font exists for any of the required charsets
2408
or if the locale definition in Xlib requires that a font exist
2409
for a particular charset and a font is not found for that charset,
2410
<function>XCreateFontSet</function>
2411
returns NULL.
2412
Otherwise,
2413
<function>XCreateFontSet</function>
2414
returns a valid
2415
<type>XFontSet</type>
2416
to font_set.
2417
</para>
2418
<para>
2419
<!-- .LP -->
2420
When an Xmb/wc drawing or measuring function is called with an
2421
<type>XFontSet</type>
2422
that has missing charsets, some characters in the locale will not be
2423
drawable.
2424
If def_string_return is non-NULL,
2425
<function>XCreateFontSet</function>
2426
returns a pointer to a string that represents the glyphs
2427
that are drawn with this
2428
<type>XFontSet</type>
2429
when the charsets of the available fonts do not include all font glyphs
2430
required to draw a codepoint.
2431
The string does not necessarily consist of valid characters
2432
in the current locale and is not necessarily drawn with
2433
the fonts loaded for the font set,
2434
but the client can draw and measure the default glyphs
2435
by including this string in a string being drawn or measured with the
2436
<type>XFontSet</type>.
2437
</para>
2438
<para>
2439
<!-- .LP -->
2440
If the string returned to def_string_return is the empty string (""),
2441
no glyphs are drawn, and the escapement is zero.
2442
The returned string is null-terminated.
2443
It is owned by Xlib and should not be modified or freed by the client.
2444
It will be freed by a call to
2445
<function>XFreeFontSet</function>
2446
with the associated
2447
<type>XFontSet</type>.
2448
Until freed, its contents will not be modified by Xlib.
2449
</para>
2450
<para>
2451
<!-- .LP -->
2452
The client is responsible for constructing an error message from the
2453
missing charset and default string information and may choose to continue
2454
operation in the case that some fonts did not exist.
2455
</para>
2456
<para>
2457
<!-- .LP -->
2458
The returned
2459
<type>XFontSet</type>
2460
and missing charset list should be freed with
2461
<function>XFreeFontSet</function>
2462
and
2463
<function>XFreeStringList</function>,
2464
respectively.
2465
The client-supplied base_font_name_list may be freed
2466
by the client after calling
2467
<function>XCreateFontSet</function>.
2468
</para>
2469
<para>
2470
<!-- .LP -->
2471
<!-- .sp -->
2472
To obtain a list of
2473
<structname>XFontStruct</structname>
2474
structures and full font names given an
2475
<type>XFontSet</type>,
2476
use
2477
<function>XFontsOfFontSet</function>.
2478
<indexterm significance="preferred"><primary>XFontsOfFontSet</primary></indexterm>
2479
<!-- .sM -->
2480
<funcsynopsis>
2481
<funcprototype>
2482
<funcdef>int <function>XFontsOfFontSet</function></funcdef>
2483
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
2484
<paramdef>XFontStruct<parameter> ***font_struct_list_return</parameter></paramdef>
2485
<paramdef>char<parameter> ***font_name_list_return</parameter></paramdef>
2486
</funcprototype>
2487
</funcsynopsis>
2488
<!-- .FN -->
2489
<variablelist>
2490
<varlistentry>
2491
<term>
2492
<emphasis remap='I'>font_set</emphasis>
2493
</term>
2494
<listitem>
2495
<para>
2496
Specifies the font set.
2497
</para>
2498
</listitem>
2499
</varlistentry>
2500
<varlistentry>
2501
<term>
2502
<emphasis remap='I'>font_struct_list_return</emphasis>
2503
</term>
2504
<listitem>
2505
<para>
2506
Returns the list of font structs.
2507
</para>
2508
</listitem>
2509
</varlistentry>
2510
<varlistentry>
2511
<term>
2512
<emphasis remap='I'>font_name_list_return</emphasis>
2513
</term>
2514
<listitem>
2515
<para>
2516
Returns the list of font names.
2517
</para>
2518
</listitem>
2519
</varlistentry>
2520
</variablelist>
2521
</para>
2522
<para>
2523
<!-- .LP -->
2524
<!-- .eM -->
2525
The
2526
<function>XFontsOfFontSet</function>
2527
function returns a list of one or more
2528
<structname>XFontStruct</structname>s
2529
and font names for the fonts used by the Xmb and Xwc layers
2530
for the given font set.
2531
A list of pointers to the
2532
<structname>XFontStruct</structname>
2533
structures is returned to font_struct_list_return.
2534
A list of pointers to null-terminated, fully specified font name strings
2535
in the locale of the font set is returned to font_name_list_return.
2536
The font_name_list order corresponds to the font_struct_list order.
2537
The number of
2538
<structname>XFontStruct</structname>
2539
structures and font names is returned as the value of the function.
2540
</para>
2541
<para>
2542
<!-- .LP -->
2543
Because it is not guaranteed that a given character will be imaged using a
2544
single font glyph,
2545
there is no provision for mapping a character or default string
2546
to the font properties, font ID, or direction hint for the font
2547
for the character.
2548
The client may access the
2549
<structname>XFontStruct</structname>
2550
list to obtain these values for all the fonts currently in use.
2551
</para>
2552
<para>
2553
<!-- .LP -->
2554
Xlib does not guarantee that fonts are loaded from the server
2555
at the creation of an
2556
<type>XFontSet</type>.
2557
Xlib may choose to cache font data, loading it only as needed to draw text
2558
or compute text dimensions.
2559
Therefore, existence of the per_char metrics in the
2560
<structname>XFontStruct</structname>
2561
structures in the
2562
<structname>XFontStructSet</structname>
2563
is undefined.
2564
Also, note that all properties in the
2565
<structname>XFontStruct</structname>
2566
structures are in the STRING encoding.
2567
</para>
2568
<para>
2569
<!-- .LP -->
2570
The
2571
<structname>XFontStruct</structname>
2572
and font name lists are owned by Xlib
2573
and should not be modified or freed by the client.
2574
They will be freed by a call to
2575
<function>XFreeFontSet</function>
2576
with the associated
2577
<type>XFontSet</type>.
2578
Until freed, their contents will not be modified by Xlib.
2579
</para>
2580
<para>
2581
<!-- .LP -->
2582
<!-- .sp -->
2583
To obtain the base font name list and the selected font name list given an
2584
<type>XFontSet</type>,
2585
use
2586
<function>XBaseFontNameListOfFontSet</function>.
2587
<indexterm significance="preferred"><primary>XBaseFontNameListOfFontSet</primary></indexterm>
2588
<!-- .sM -->
2589
<funcsynopsis>
2590
<funcprototype>
2591
<funcdef>char *<function>XBaseFontNameListOfFontSet</function></funcdef>
2592
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
2593
</funcprototype>
2594
</funcsynopsis>
2595
<!-- .FN -->
2596
<variablelist>
2597
<varlistentry>
2598
<term>
2599
<emphasis remap='I'>font_set</emphasis>
2600
</term>
2601
<listitem>
2602
<para>
2603
Specifies the font set.
2604
</para>
2605
</listitem>
2606
</varlistentry>
2607
</variablelist>
2608
</para>
2609
<para>
2610
<!-- .LP -->
2611
<!-- .eM -->
2612
The
2613
<function>XBaseFontNameListOfFontSet</function>
2614
function returns the original base font name list supplied
2615
by the client when the
2616
<type>XFontSet</type>
2617
was created.
2618
A null-terminated string containing a list of
2619
comma-separated font names is returned
2620
as the value of the function.
2621
White space may appear immediately on either side of separating commas.
2622
</para>
2623
<para>
2624
<!-- .LP -->
2625
If
2626
<function>XCreateFontSet</function>
2627
obtained an <acronym>XLFD</acronym> name from the font properties for the font specified
2628
by a non-<acronym>XLFD</acronym> base name, the
2629
<function>XBaseFontNameListOfFontSet</function>
2630
function will return the <acronym>XLFD</acronym> name instead of the non-<acronym>XLFD</acronym> base name.
2631
</para>
2632
<para>
2633
<!-- .LP -->
2634
The base font name list is owned by Xlib and should not be modified or
2635
freed by the client.
2636
It will be freed by a call to
2637
<function>XFreeFontSet</function>
2638
with the associated
2639
<type>XFontSet</type>.
2640
Until freed, its contents will not be modified by Xlib.
2641
</para>
2642
<para>
2643
<!-- .LP -->
2644
<!-- .sp -->
2645
To obtain the locale name given an
2646
<type>XFontSet</type>,
2647
use
2648
<function>XLocaleOfFontSet</function>.
2649
<indexterm significance="preferred"><primary>XLocaleOfFontSet</primary></indexterm>
2650
<!-- .sM -->
2651
<funcsynopsis>
2652
<funcprototype>
2653
<funcdef>char *<function>XLocaleOfFontSet</function></funcdef>
2654
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
2655
</funcprototype>
2656
</funcsynopsis>
2657
<!-- .FN -->
2658
<variablelist>
2659
<varlistentry>
2660
<term>
2661
<emphasis remap='I'>font_set</emphasis>
2662
</term>
2663
<listitem>
2664
<para>
2665
Specifies the font set.
2666
</para>
2667
</listitem>
2668
</varlistentry>
2669
</variablelist>
2670
</para>
2671
<para>
2672
<!-- .LP -->
2673
<!-- .eM -->
2674
The
2675
<function>XLocaleOfFontSet</function>
2676
function
2677
returns the name of the locale bound to the specified
2678
<type>XFontSet</type>,
2679
as a null-terminated string.
2680
</para>
2681
<para>
2682
<!-- .LP -->
2683
The returned locale name string is owned by Xlib
2684
and should not be modified or freed by the client.
2685
It may be freed by a call to
2686
<function>XFreeFontSet</function>
2687
with the associated
2688
<type>XFontSet</type>.
2689
Until freed, it will not be modified by Xlib.
2690
</para>
2691
<para>
2692
<!-- .LP -->
2693
<!-- .sp -->
2694
The
2695
<function>XFreeFontSet</function>
2696
function is a convenience function for freeing an output context.
2697
<function>XFreeFontSet</function>
2698
also frees its associated
2699
<type>XOM</type>
2700
if the output context was created by
2701
<function>XCreateFontSet</function>.
2702
<indexterm significance="preferred"><primary>XFreeFontSet</primary></indexterm>
2703
<!-- .sM -->
2704
<funcsynopsis>
2705
<funcprototype>
2706
<funcdef>void <function>XFreeFontSet</function></funcdef>
2707
<paramdef>Display<parameter> *display</parameter></paramdef>
2708
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
2709
</funcprototype>
2710
</funcsynopsis>
2711
<!-- .FN -->
2712
<variablelist>
2713
<varlistentry>
2714
<term>
2715
<emphasis remap='I'>display</emphasis>
2716
</term>
2717
<listitem>
2718
<para>
2719
Specifies the connection to the X server.
2720
</para>
2721
</listitem>
2722
</varlistentry>
2723
<varlistentry>
2724
<term>
2725
<emphasis remap='I'>font_set</emphasis>
2726
</term>
2727
<listitem>
2728
<para>
2729
Specifies the font set.
2730
</para>
2731
</listitem>
2732
</varlistentry>
2733
</variablelist>
2734
</para>
2735
<para>
2736
<!-- .LP -->
2737
<!-- .eM -->
2738
The
2739
<function>XFreeFontSet</function>
2740
function frees the specified font set.
2741
The associated base font name list, font name list,
2742
<structname>XFontStruct</structname>
2743
list, and
2744
<structname>XFontSetExtents</structname>,
2745
if any, are freed.
2746
</para>
2747
</sect2>
2748
<sect2 id="Obtaining_Font_Set_Metrics">
2749
<title>Obtaining Font Set Metrics</title>
2750
<!-- .XS -->
2751
<!-- (SN Obtaining Font Set Metrics -->
2752
<!-- .XE -->
2753
<para>
2754
<!-- .LP -->
2755
Metrics for the internationalized text drawing functions
2756
are defined in terms of a primary draw direction,
2757
which is the default direction in which the character origin advances
2758
for each succeeding character in the string.
2759
The Xlib interface is currently defined to support only a left-to-right
2760
primary draw direction.
2761
The drawing origin is the position passed to the drawing function
2762
when the text is drawn.
2763
The baseline is a line drawn through the drawing origin parallel
2764
to the primary draw direction.
2765
Character ink is the pixels painted in the foreground color
2766
and does not include interline or intercharacter spacing
2767
or image text background pixels.
2768
</para>
2769
<para>
2770
<!-- .LP -->
2771
The drawing functions are allowed to implement implicit text
2772
directionality control, reversing the order in which characters are
2773
rendered along the primary draw direction in response to locale-specific
2774
lexical analysis of the string.
2775
</para>
2776
<para>
2777
<!-- .LP -->
2778
Regardless of the character rendering order,
2779
the origins of all characters are on the primary draw direction side
2780
of the drawing origin.
2781
The screen location of a particular character image may be determined with
2782
<function>XmbTextPerCharExtents</function>
2783
or
2784
<function>XwcTextPerCharExtents</function>.
2785
</para>
2786
<para>
2787
<!-- .LP -->
2788
The drawing functions are allowed to implement context-dependent
2789
rendering, where the glyphs drawn for a string are not simply a
2790
concatenation of the glyphs that represent each individual character.
2791
A string of two characters drawn with
2792
<function>XmbDrawString</function>
2793
may render differently than if the two characters
2794
were drawn with separate calls to
2795
<function>XmbDrawString</function>.
2796
If the client appends or inserts a character
2797
in a previously drawn string,
2798
the client may need to redraw some adjacent characters
2799
to obtain proper rendering.
2800
</para>
2801
<para>
2802
<!-- .LP -->
2803
<!-- .sp -->
2804
To find out about direction-dependent rendering, use
2805
<function>XDirectionalDependentDrawing</function>.
2806
<indexterm significance="preferred"><primary>XDirectionalDependentDrawing</primary></indexterm>
2807
<!-- .sM -->
2808
<funcsynopsis>
2809
<funcprototype>
2810
<funcdef>Bool <function>XDirectionalDependentDrawing</function></funcdef>
2811
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
2812
</funcprototype>
2813
</funcsynopsis>
2814
<!-- .FN -->
2815
<variablelist>
2816
<varlistentry>
2817
<term>
2818
<emphasis remap='I'>font_set</emphasis>
2819
</term>
2820
<listitem>
2821
<para>
2822
Specifies the font set.
2823
</para>
2824
</listitem>
2825
</varlistentry>
2826
</variablelist>
2827
</para>
2828
<para>
2829
<!-- .LP -->
2830
<!-- .eM -->
2831
The
2832
<function>XDirectionalDependentDrawing</function>
2833
function returns
2834
<symbol>True</symbol>
2835
if the drawing functions implement implicit text directionality;
2836
otherwise, it returns
2837
<symbol>False</symbol>.
2838
</para>
2839
<para>
2840
<!-- .LP -->
2841
<!-- .sp -->
2842
To find out about context-dependent rendering, use
2843
<function>XContextualDrawing</function>.
2844
<indexterm significance="preferred"><primary>XContextualDrawing</primary></indexterm>
2845
<!-- .sM -->
2846
<funcsynopsis>
2847
<funcprototype>
2848
<funcdef>Bool <function>XContextualDrawing</function></funcdef>
2849
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
2850
</funcprototype>
2851
</funcsynopsis>
2852
<!-- .FN -->
2853
<variablelist>
2854
<varlistentry>
2855
<term>
2856
<emphasis remap='I'>font_set</emphasis>
2857
</term>
2858
<listitem>
2859
<para>
2860
Specifies the font set.
2861
</para>
2862
</listitem>
2863
</varlistentry>
2864
</variablelist>
2865
</para>
2866
<para>
2867
<!-- .LP -->
2868
<!-- .eM -->
2869
The
2870
<function>XContextualDrawing</function>
2871
function returns
2872
<symbol>True</symbol>
2873
if text drawn with the font set might include context-dependent drawing;
2874
otherwise, it returns
2875
<symbol>False</symbol>.
2876
</para>
2877
<para>
2878
<!-- .LP -->
2879
<!-- .sp -->
2880
To find out about context-dependent or direction-dependent rendering, use
2881
<function>XContextDependentDrawing</function>.
2882
<indexterm significance="preferred"><primary>XContextDependentDrawing</primary></indexterm>
2883
<!-- .sM -->
2884
<funcsynopsis>
2885
<funcprototype>
2886
<funcdef>Bool <function>XContextDependentDrawing</function></funcdef>
2887
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
2888
</funcprototype>
2889
</funcsynopsis>
2890
<!-- .FN -->
2891
<variablelist>
2892
<varlistentry>
2893
<term>
2894
<emphasis remap='I'>font_set</emphasis>
2895
</term>
2896
<listitem>
2897
<para>
2898
Specifies the font set.
2899
</para>
2900
</listitem>
2901
</varlistentry>
2902
</variablelist>
2903
</para>
2904
<para>
2905
<!-- .LP -->
2906
<!-- .eM -->
2907
The
2908
<function>XContextDependentDrawing</function>
2909
function returns
2910
<symbol>True</symbol>
2911
if the drawing functions implement implicit text directionality or
2912
if text drawn with the font_set might include context-dependent drawing;
2913
otherwise, it returns
2914
<symbol>False</symbol>.
2915
</para>
2916
<para>
2917
<!-- .LP -->
2918
The drawing functions do not interpret newline, tab, or other control
2919
characters.
2920
The behavior when nonprinting characters other than space are drawn
2921
is implementation-dependent.
2922
It is the client's responsibility to interpret control characters
2923
in a text stream.
2924
</para>
2925
<para>
2926
<!-- .LP -->
2927
The maximum character extents for the fonts that are used by the text
2928
drawing layers can be accessed by the
2929
<structname>XFontSetExtents</structname>
2930
structure:
2931
<indexterm significance="preferred"><primary>XFontSetExtents</primary></indexterm>
2932
</para>
2933
<para>
2934
<!-- .LP -->
2935
<literallayout class="monospaced">
2936
<!-- .TA .5i 3i -->
2937
<!-- .ta .5i 3i -->
2938
typedef struct {
2939
XRectangle max_ink_extent; /* over all drawable characters */
2940
XRectangle max_logical_extent; /* over all drawable characters */
2941
} XFontSetExtents;
2942
</literallayout>
2943
</para>
2944
<para>
2945
<!-- .LP -->
2946
The
2947
<structname>XRectangle</structname>
2948
structures used to return font set metrics are the usual Xlib screen-oriented
2949
rectangles
2950
with x, y giving the upper left corner, and width and height always positive.
2951
</para>
2952
<para>
2953
<!-- .LP -->
2954
The max_ink_extent member gives the maximum extent, over all drawable characters, of
2955
the rectangles that bound the character glyph image drawn in the
2956
foreground color, relative to a constant origin.
2957
See
2958
<function>XmbTextExtents</function>
2959
and
2960
<function>XwcTextExtents</function>
2961
for detailed semantics.
2962
</para>
2963
<para>
2964
<!-- .LP -->
2965
The max_logical_extent member gives the maximum extent,
2966
over all drawable characters, of the rectangles
2967
that specify minimum spacing to other graphical features,
2968
relative to a constant origin.
2969
Other graphical features drawn by the client, for example,
2970
a border surrounding the text, should not intersect this rectangle.
2971
The max_logical_extent member should be used to compute minimum
2972
interline spacing and the minimum area that must be allowed
2973
in a text field to draw a given number of arbitrary characters.
2974
</para>
2975
<para>
2976
<!-- .LP -->
2977
Due to context-dependent rendering,
2978
appending a given character to a string may change
2979
the string's extent by an amount other than that character's
2980
individual extent.
2981
</para>
2982
<para>
2983
<!-- .LP -->
2984
The rectangles for a given character in a string can be obtained from
2985
<function>XmbTextPerCharExtents</function>
2986
or
2987
<function>XwcTextPerCharExtents</function>.
2988
</para>
2989
<para>
2990
<!-- .LP -->
2991
<!-- .sp -->
2992
To obtain the maximum extents structure given an
2993
<type>XFontSet</type>,
2994
use
2995
<function>XExtentsOfFontSet</function>.
2996
<indexterm significance="preferred"><primary>XExtentsOfFontSet</primary></indexterm>
2997
<!-- .sM -->
2998
<funcsynopsis>
2999
<funcprototype>
3000
<funcdef>XFontSetExtents *<function>XExtentsOfFontSet</function></funcdef>
3001
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
3002
</funcprototype>
3003
</funcsynopsis>
3004
<!-- .FN -->
3005
<variablelist>
3006
<varlistentry>
3007
<term>
3008
<emphasis remap='I'>font_set</emphasis>
3009
</term>
3010
<listitem>
3011
<para>
3012
Specifies the font set.
3013
</para>
3014
</listitem>
3015
</varlistentry>
3016
</variablelist>
3017
</para>
3018
<para>
3019
<!-- .LP -->
3020
<!-- .eM -->
3021
The
3022
<function>XExtentsOfFontSet</function>
3023
function returns an
3024
<structname>XFontSetExtents</structname>
3025
structure for the fonts used by the Xmb and Xwc layers
3026
for the given font set.
3027
</para>
3028
<para>
3029
<!-- .LP -->
3030
The
3031
<structname>XFontSetExtents</structname>
3032
structure is owned by Xlib and should not be modified
3033
or freed by the client.
3034
It will be freed by a call to
3035
<function>XFreeFontSet</function>
3036
with the associated
3037
<type>XFontSet</type>.
3038
Until freed, its contents will not be modified by Xlib.
3039
</para>
3040
<para>
3041
<!-- .LP -->
3042
<!-- .sp -->
3043
To obtain the escapement in pixels of the specified text as a value,
3044
use
3045
<function>XmbTextEscapement</function>
3046
or
3047
<function>XwcTextEscapement</function>.
3048
<indexterm significance="preferred"><primary>XmbTextEscapement</primary></indexterm>
3049
<indexterm significance="preferred"><primary>XwcTextEscapement</primary></indexterm>
3050
<!-- .sM -->
3051
<funcsynopsis>
3052
<funcprototype>
3053
<funcdef>int <function>XmbTextEscapement</function></funcdef>
3054
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
3055
<paramdef>char<parameter> *string</parameter></paramdef>
3056
<paramdef>int<parameter> num_bytes</parameter></paramdef>
3057
</funcprototype>
3058
</funcsynopsis>
3059
<!-- .FN -->
3060
<funcsynopsis>
3061
<funcprototype>
3062
<funcdef>int <function>XwcTextEscapement</function></funcdef>
3063
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
3064
<paramdef>wchar_t<parameter> *string</parameter></paramdef>
3065
<paramdef>int<parameter> num_wchars</parameter></paramdef>
3066
</funcprototype>
3067
</funcsynopsis>
3068
<!-- .FN -->
3069
<variablelist>
3070
<varlistentry>
3071
<term>
3072
<emphasis remap='I'>font_set</emphasis>
3073
</term>
3074
<listitem>
3075
<para>
3076
Specifies the font set.
3077
</para>
3078
</listitem>
3079
</varlistentry>
3080
<varlistentry>
3081
<term>
3082
<emphasis remap='I'>string</emphasis>
3083
</term>
3084
<listitem>
3085
<para>
3086
Specifies the character string.
3087
</para>
3088
</listitem>
3089
</varlistentry>
3090
<varlistentry>
3091
<term>
3092
<emphasis remap='I'>num_bytes</emphasis>
3093
</term>
3094
<listitem>
3095
<para>
3096
Specifies the number of bytes in the string argument.
3097
</para>
3098
</listitem>
3099
</varlistentry>
3100
<varlistentry>
3101
<term>
3102
<emphasis remap='I'>num_wchars</emphasis>
3103
</term>
3104
<listitem>
3105
<para>
3106
Specifies the number of characters in the string argument.
3107
</para>
3108
</listitem>
3109
</varlistentry>
3110
</variablelist>
3111
</para>
3112
<para>
3113
<!-- .LP -->
3114
<!-- .eM -->
3115
The
3116
<function>XmbTextEscapement</function>
3117
and
3118
<function>XwcTextEscapement</function>
3119
functions return the escapement in pixels of the specified string as a value,
3120
using the fonts loaded for the specified font set.
3121
The escapement is the distance in pixels in the primary draw
3122
direction from the drawing origin to the origin of the next character to
3123
be drawn, assuming that the rendering of the next character is not
3124
dependent on the supplied string.
3125
</para>
3126
<para>
3127
<!-- .LP -->
3128
Regardless of the character rendering order,
3129
the escapement is always positive.
3130
</para>
3131
<para>
3132
<!-- .LP -->
3133
<!-- .sp -->
3134
To obtain the overall_ink_return and overall_logical_return arguments,
3135
the overall bounding box of the string's image, and a logical bounding box,
3136
use
3137
<function>XmbTextExtents</function>
3138
or
3139
<function>XwcTextExtents</function>.
3140
<indexterm significance="preferred"><primary>XmbTextExtents</primary></indexterm>
3141
<indexterm significance="preferred"><primary>XwcTextExtents</primary></indexterm>
3142
<!-- .sM -->
3143
<funcsynopsis>
3144
<funcprototype>
3145
<funcdef>int <function>XmbTextExtents</function></funcdef>
3146
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
3147
<paramdef>char<parameter> *string</parameter></paramdef>
3148
<paramdef>int<parameter> num_bytes</parameter></paramdef>
3149
<paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef>
3150
<paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef>
3151
</funcprototype>
3152
</funcsynopsis>
3153
<!-- .FN -->
3154
<funcsynopsis>
3155
<funcprototype>
3156
<funcdef>int <function>XwcTextExtents</function></funcdef>
3157
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
3158
<paramdef>wchar_t<parameter> *string</parameter></paramdef>
3159
<paramdef>int<parameter> num_wchars</parameter></paramdef>
3160
<paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef>
3161
<paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef>
3162
</funcprototype>
3163
</funcsynopsis>
3164
<!-- .FN -->
3165
<variablelist>
3166
<varlistentry>
3167
<term>
3168
<emphasis remap='I'>font_set</emphasis>
3169
</term>
3170
<listitem>
3171
<para>
3172
Specifies the font set.
3173
</para>
3174
</listitem>
3175
</varlistentry>
3176
<varlistentry>
3177
<term>
3178
<emphasis remap='I'>string</emphasis>
3179
</term>
3180
<listitem>
3181
<para>
3182
Specifies the character string.
3183
</para>
3184
</listitem>
3185
</varlistentry>
3186
<varlistentry>
3187
<term>
3188
<emphasis remap='I'>num_bytes</emphasis>
3189
</term>
3190
<listitem>
3191
<para>
3192
Specifies the number of bytes in the string argument.
3193
</para>
3194
</listitem>
3195
</varlistentry>
3196
<varlistentry>
3197
<term>
3198
<emphasis remap='I'>num_wchars</emphasis>
3199
</term>
3200
<listitem>
3201
<para>
3202
Specifies the number of characters in the string argument.
3203
<!-- .ds Ov dimensions -->
3204
</para>
3205
</listitem>
3206
</varlistentry>
3207
<varlistentry>
3208
<term>
3209
<emphasis remap='I'>overall_ink_return</emphasis>
3210
</term>
3211
<listitem>
3212
<para>
3213
Returns the overall ink dimensions.
3214
</para>
3215
</listitem>
3216
</varlistentry>
3217
<varlistentry>
3218
<term>
3219
<emphasis remap='I'>overall_logical_return</emphasis>
3220
</term>
3221
<listitem>
3222
<para>
3223
Returns the overall logical dimensions.
3224
</para>
3225
</listitem>
3226
</varlistentry>
3227
</variablelist>
3228
</para>
3229
<para>
3230
<!-- .LP -->
3231
<!-- .eM -->
3232
The
3233
<function>XmbTextExtents</function>
3234
and
3235
<function>XwcTextExtents</function>
3236
functions set the components of the specified overall_ink_return and
3237
overall_logical_return
3238
arguments to the overall bounding box of the string's image
3239
and a logical bounding box for spacing purposes, respectively.
3240
They return the value returned by
3241
<function>XmbTextEscapement</function>
3242
or
3243
<function>XwcTextEscapement</function>.
3244
These metrics are relative to the drawing origin of the string,
3245
using the fonts loaded for the specified font set.
3246
</para>
3247
<para>
3248
<!-- .LP -->
3249
If the overall_ink_return argument is non-NULL,
3250
it is set to the bounding box of the string's character ink.
3251
The overall_ink_return for a nondescending, horizontally drawn
3252
Latin character is conventionally entirely above the baseline;
3253
that is, overall_ink_return.height <= -overall_ink_return.y.
3254
The overall_ink_return for a nonkerned character
3255
is entirely at, and to the right of, the origin;
3256
that is, overall_ink_return.x >= 0.
3257
A character consisting of a single pixel at the origin would set
3258
overall_ink_return fields y = 0, x = 0, width = 1, and height = 1.
3259
</para>
3260
<para>
3261
<!-- .LP -->
3262
If the overall_logical_return argument is non-NULL,
3263
it is set to the bounding box that provides minimum spacing
3264
to other graphical features for the string.
3265
Other graphical features, for example, a border surrounding the text,
3266
should not intersect this rectangle.
3267
</para>
3268
<para>
3269
<!-- .LP -->
3270
When the
3271
<type>XFontSet</type>
3272
has missing charsets,
3273
metrics for each unavailable character are taken
3274
from the default string returned by
3275
<function>XCreateFontSet</function>
3276
so that the metrics represent the text as it will actually be drawn.
3277
The behavior for an invalid codepoint is undefined.
3278
</para>
3279
<para>
3280
<!-- .LP -->
3281
To determine the effective drawing origin for a character in a drawn string,
3282
the client should call
3283
<function>XmbTextPerCharExtents</function>
3284
on the entire string, then on the character,
3285
and subtract the x values of the returned
3286
rectangles for the character.
3287
This is useful to redraw portions of a line of text
3288
or to justify words, but for context-dependent rendering,
3289
the client should not assume that it can redraw the character by itself
3290
and get the same rendering.
3291
</para>
3292
<para>
3293
<!-- .LP -->
3294
<!-- .sp -->
3295
To obtain per-character information for a text string,
3296
use
3297
<function>XmbTextPerCharExtents</function>
3298
or
3299
<function>XwcTextPerCharExtents</function>.
3300
<indexterm significance="preferred"><primary>XmbTextPerCharExtents</primary></indexterm>
3301
<indexterm significance="preferred"><primary>XwcTextPerCharExtents</primary></indexterm>
3302
<!-- .sM -->
3303
<funcsynopsis>
3304
<funcprototype>
3305
<funcdef>Status <function>XmbTextPerCharExtents</function></funcdef>
3306
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
3307
<paramdef>char<parameter> *string</parameter></paramdef>
3308
<paramdef>int<parameter> num_bytes</parameter></paramdef>
3309
<paramdef>XRectangle<parameter> *ink_array_return</parameter></paramdef>
3310
<paramdef>XRectangle<parameter> *logical_array_return</parameter></paramdef>
3311
<paramdef>int<parameter> array_size</parameter></paramdef>
3312
<paramdef>int<parameter> *num_chars_return</parameter></paramdef>
3313
<paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef>
3314
<paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef>
3315
</funcprototype>
3316
</funcsynopsis>
3317
<!-- .FN -->
3318
<funcsynopsis>
3319
<funcprototype>
3320
<funcdef>Status <function>XwcTextPerCharExtents</function></funcdef>
3321
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
3322
<paramdef>wchar_t<parameter> *string</parameter></paramdef>
3323
<paramdef>int<parameter> num_wchars</parameter></paramdef>
3324
<paramdef>XRectangle<parameter> *ink_array_return</parameter></paramdef>
3325
<paramdef>XRectangle<parameter> *logical_array_return</parameter></paramdef>
3326
<paramdef>int<parameter> array_size</parameter></paramdef>
3327
<paramdef>int<parameter> *num_chars_return</parameter></paramdef>
3328
<paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef>
3329
<paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef>
3330
</funcprototype>
3331
</funcsynopsis>
3332
<!-- .FN -->
3333
<variablelist>
3334
<varlistentry>
3335
<term>
3336
<emphasis remap='I'>font_set</emphasis>
3337
</term>
3338
<listitem>
3339
<para>
3340
Specifies the font set.
3341
</para>
3342
</listitem>
3343
</varlistentry>
3344
<varlistentry>
3345
<term>
3346
<emphasis remap='I'>string</emphasis>
3347
</term>
3348
<listitem>
3349
<para>
3350
Specifies the character string.
3351
</para>
3352
</listitem>
3353
</varlistentry>
3354
<varlistentry>
3355
<term>
3356
<emphasis remap='I'>num_bytes</emphasis>
3357
</term>
3358
<listitem>
3359
<para>
3360
Specifies the number of bytes in the string argument.
3361
</para>
3362
</listitem>
3363
</varlistentry>
3364
<varlistentry>
3365
<term>
3366
<emphasis remap='I'>num_wchars</emphasis>
3367
</term>
3368
<listitem>
3369
<para>
3370
Specifies the number of characters in the string argument.
3371
</para>
3372
</listitem>
3373
</varlistentry>
3374
<varlistentry>
3375
<term>
3376
<emphasis remap='I'>ink_array_return</emphasis>
3377
</term>
3378
<listitem>
3379
<para>
3380
Returns the ink dimensions for each character.
3381
</para>
3382
</listitem>
3383
</varlistentry>
3384
<varlistentry>
3385
<term>
3386
<emphasis remap='I'>logical_array_return</emphasis>
3387
</term>
3388
<listitem>
3389
<para>
3390
Returns the logical dimensions for each character.
3391
</para>
3392
</listitem>
3393
</varlistentry>
3394
<varlistentry>
3395
<term>
3396
<emphasis remap='I'>array_size</emphasis>
3397
</term>
3398
<listitem>
3399
<para>
3400
Specifies the size of ink_array_return and logical_array_return.
3401
The caller must pass in arrays of this size.
3402
</para>
3403
</listitem>
3404
</varlistentry>
3405
<varlistentry>
3406
<term>
3407
<emphasis remap='I'>num_chars_return</emphasis>
3408
</term>
3409
<listitem>
3410
<para>
3411
Returns the number of characters in the string argument.
3412
<!-- .ds Ov extents of the entire string -->
3413
</para>
3414
</listitem>
3415
</varlistentry>
3416
<varlistentry>
3417
<term>
3418
<emphasis remap='I'>overall_ink_return</emphasis>
3419
</term>
3420
<listitem>
3421
<para>
3422
Returns the overall ink dimensions.
3423
</para>
3424
</listitem>
3425
</varlistentry>
3426
<varlistentry>
3427
<term>
3428
<emphasis remap='I'>overall_logical_return</emphasis>
3429
</term>
3430
<listitem>
3431
<para>
3432
Returns the overall logical dimensions.
3433
</para>
3434
</listitem>
3435
</varlistentry>
3436
</variablelist>
3437
</para>
3438
<para>
3439
<!-- .LP -->
3440
<!-- .eM -->
3441
The
3442
<function>XmbTextPerCharExtents</function>
3443
and
3444
<function>XwcTextPerCharExtents</function>
3445
functions return the text dimensions of each character of the specified text,
3446
using the fonts loaded for the specified font set.
3447
Each successive element of ink_array_return and logical_array_return
3448
is set to the successive character's drawn metrics,
3449
relative to the drawing origin of the string and one
3450
rectangle
3451
for each character in the supplied text string.
3452
The number of elements of ink_array_return and logical_array_return
3453
that have been set is returned to num_chars_return.
3454
</para>
3455
<para>
3456
<!-- .LP -->
3457
Each element of ink_array_return is set to the bounding box
3458
of the corresponding character's drawn foreground color.
3459
Each element of logical_array_return is set to the bounding box
3460
that provides minimum spacing to other graphical features
3461
for the corresponding character.
3462
Other graphical features should not intersect any of the
3463
logical_array_return rectangles.
3464
</para>
3465
<para>
3466
<!-- .LP -->
3467
Note that an
3468
<structname>XRectangle</structname>
3469
represents the effective drawing dimensions of the character,
3470
regardless of the number of font glyphs that are used to draw
3471
the character or the direction in which the character is drawn.
3472
If multiple characters map to a single character glyph,
3473
the dimensions of all the
3474
<structname>XRectangle</structname>s
3475
of those characters are the same.
3476
</para>
3477
<para>
3478
<!-- .LP -->
3479
When the
3480
<type>XFontSet</type>
3481
has missing charsets, metrics for each unavailable
3482
character are taken from the default string returned by
3483
<function>XCreateFontSet</function>
3484
so that the metrics represent the text as it will actually be drawn.
3485
The behavior for an invalid codepoint is undefined.
3486
</para>
3487
<para>
3488
<!-- .LP -->
3489
If the array_size is too small for the number of characters in the
3490
supplied text, the functions return zero
3491
and num_chars_return is set to the number of rectangles required.
3492
Otherwise, the functions return a nonzero value.
3493
</para>
3494
<para>
3495
<!-- .LP -->
3496
If the overall_ink_return or overall_logical_return argument is non-NULL,
3497
<function>XmbTextPerCharExtents</function>
3498
and
3499
<function>XwcTextPerCharExtents</function>
3500
return the maximum extent of the string's metrics to overall_ink_return
3501
or overall_logical_return, as returned by
3502
<function>XmbTextExtents</function>
3503
or
3504
<function>XwcTextExtents</function>.
3505
</para>
3506
</sect2>
3507
<sect2 id="Drawing_Text_Using_Font_Sets">
3508
<title>Drawing Text Using Font Sets</title>
3509
<!-- .XS -->
3510
<!-- (SN Drawing Text Using Font Sets -->
3511
<!-- .XE -->
3512
<para>
3513
<!-- .LP -->
3514
The functions defined in this section
3515
draw text at a specified location in a drawable.
3516
They are similar to the functions
3517
<function>XDrawText</function>,
3518
<function>XDrawString</function>,
3519
and
3520
<function>XDrawImageString</function>
3521
except that they work with font sets instead of single fonts
3522
and interpret the text based on the locale of the font set
3523
instead of treating the bytes of the string as direct font indexes.
3524
See section 8.6 for details of the use of Graphics Contexts (GCs)
3525
and possible protocol errors.
3526
If a
3527
<errorname>BadFont</errorname>
3528
error is generated,
3529
characters prior to the offending character may have been drawn.
3530
</para>
3531
<para>
3532
<!-- .LP -->
3533
The text is drawn using the fonts loaded for the specified font set;
3534
the font in the GC is ignored and may be modified by the functions.
3535
No validation that all fonts conform to some width rule is performed.
3536
</para>
3537
<para>
3538
<!-- .LP -->
3539
The text functions
3540
<function>XmbDrawText</function>
3541
and
3542
<function>XwcDrawText</function>
3543
use the following structures:
3544
</para>
3545
<para>
3546
<!-- .LP -->
3547
<indexterm significance="preferred"><primary>XmbTextItem</primary></indexterm>
3548
<!-- .sM -->
3549
<literallayout class="monospaced">
3550
<!-- .TA .5i 2.5i -->
3551
<!-- .ta .5i 2.5i -->
3552
typedef struct {
3553
char *chars; /* pointer to string */
3554
int nchars; /* number of bytes */
3555
int delta; /* pixel delta between strings */
3556
XFontSet font_set; /* fonts, None means don't change */
3557
} XmbTextItem;
3558
</literallayout>
3559
</para>
3560
<para>
3561
<!-- .LP -->
3562
<indexterm significance="preferred"><primary>XwcTextItem</primary></indexterm>
3563
<literallayout class="monospaced">
3564
<!-- .TA .5i 2.5i -->
3565
<!-- .ta .5i 2.5i -->
3566
typedef struct {
3567
wchar_t *chars; /* pointer to wide char string */
3568
int nchars; /* number of wide characters */
3569
int delta; /* pixel delta between strings */
3570
XFontSet font_set; /* fonts, None means don't change */
3571
} XwcTextItem;
3572
</literallayout>
3573
</para>
3574
<para>
3575
<!-- .LP -->
3576
<!-- .eM -->
3577
<!-- .sp -->
3578
To draw text using multiple font sets in a given drawable, use
3579
<function>XmbDrawText</function>
3580
or
3581
<function>XwcDrawText</function>.
3582
<indexterm significance="preferred"><primary>XmbDrawText</primary></indexterm>
3583
<indexterm significance="preferred"><primary>XwcDrawText</primary></indexterm>
3584
<!-- .sM -->
3585
<funcsynopsis>
3586
<funcprototype>
3587
<funcdef>void <function>XmbDrawText</function></funcdef>
3588
<paramdef>Display<parameter> *display</parameter></paramdef>
3589
<paramdef>Drawable<parameter> d</parameter></paramdef>
3590
<paramdef>GC<parameter> gc</parameter></paramdef>
3591
<paramdef>intx,<parameter> y</parameter></paramdef>
3592
<paramdef>XmbTextItem<parameter> *items</parameter></paramdef>
3593
<paramdef>int<parameter> nitems</parameter></paramdef>
3594
</funcprototype>
3595
</funcsynopsis>
3596
<!-- .FN -->
3597
<funcsynopsis>
3598
<funcprototype>
3599
<funcdef>void <function>XwcDrawText</function></funcdef>
3600
<paramdef>Display<parameter> *display</parameter></paramdef>
3601
<paramdef>Drawable<parameter> d</parameter></paramdef>
3602
<paramdef>GC<parameter> gc</parameter></paramdef>
3603
<paramdef>intx,<parameter> y</parameter></paramdef>
3604
<paramdef>XwcTextItem<parameter> *items</parameter></paramdef>
3605
<paramdef>int<parameter> nitems</parameter></paramdef>
3606
</funcprototype>
3607
</funcsynopsis>
3608
<!-- .FN -->
3609
<variablelist>
3610
<varlistentry>
3611
<term>
3612
<emphasis remap='I'>display</emphasis>
3613
</term>
3614
<listitem>
3615
<para>
3616
Specifies the connection to the X server.
3617
</para>
3618
</listitem>
3619
</varlistentry>
3620
<varlistentry>
3621
<term>
3622
<emphasis remap='I'>d</emphasis>
3623
</term>
3624
<listitem>
3625
<para>
3626
Specifies the drawable.
3627
</para>
3628
</listitem>
3629
</varlistentry>
3630
<varlistentry>
3631
<term>
3632
<emphasis remap='I'>gc</emphasis>
3633
</term>
3634
<listitem>
3635
<para>
3636
Specifies the GC.
3637
<!-- .ds Xy -->
3638
</para>
3639
</listitem>
3640
</varlistentry>
3641
<varlistentry>
3642
<term>
3643
<emphasis remap='I'>x</emphasis>
3644
</term>
3645
<listitem>
3646
<para>
3647
<!-- .br -->
3648
<!-- .ns -->
3649
</para>
3650
</listitem>
3651
</varlistentry>
3652
<varlistentry>
3653
<term>
3654
<emphasis remap='I'>y</emphasis>
3655
</term>
3656
<listitem>
3657
<para>
3658
Specify the x and y coordinates(Xy.
3659
</para>
3660
</listitem>
3661
</varlistentry>
3662
<varlistentry>
3663
<term>
3664
<emphasis remap='I'>items</emphasis>
3665
</term>
3666
<listitem>
3667
<para>
3668
Specifies an array of text items.
3669
</para>
3670
</listitem>
3671
</varlistentry>
3672
<varlistentry>
3673
<term>
3674
<emphasis remap='I'>nitems</emphasis>
3675
</term>
3676
<listitem>
3677
<para>
3678
Specifies the number of text items in the array.
3679
</para>
3680
</listitem>
3681
</varlistentry>
3682
</variablelist>
3683
</para>
3684
<para>
3685
<!-- .LP -->
3686
<!-- .eM -->
3687
The
3688
<function>XmbDrawText</function>
3689
and
3690
<function>XwcDrawText</function>
3691
functions allow complex spacing and font set shifts between text strings.
3692
Each text item is processed in turn, with the origin of a text
3693
element advanced in the primary draw direction by the escapement of the
3694
previous text item.
3695
A text item delta specifies an additional escapement of the text item
3696
drawing origin in the primary draw direction.
3697
A font_set member other than
3698
<symbol>None</symbol>
3699
in an item causes the font set to be used for this and subsequent text items
3700
in the text_items list.
3701
Leading text items with a font_set member set to
3702
<symbol>None</symbol>
3703
will not be drawn.
3704
</para>
3705
<para>
3706
<!-- .LP -->
3707
<function>XmbDrawText</function>
3708
and
3709
<function>XwcDrawText</function>
3710
do not perform any context-dependent rendering between text segments.
3711
Clients may compute the drawing metrics by passing each text segment to
3712
<function>XmbTextExtents</function>
3713
and
3714
<function>XwcTextExtents</function>
3715
or
3716
<function>XmbTextPerCharExtents</function>
3717
and
3718
<function>XwcTextPerCharExtents</function>.
3719
When the
3720
<type>XFontSet</type>
3721
has missing charsets, each unavailable character is drawn
3722
with the default string returned by
3723
<function>XCreateFontSet</function>.
3724
The behavior for an invalid codepoint is undefined.
3725
</para>
3726
<para>
3727
<!-- .LP -->
3728
<!-- .sp -->
3729
To draw text using a single font set in a given drawable, use
3730
<function>XmbDrawString</function>
3731
or
3732
<function>XwcDrawString</function>.
3733
<indexterm significance="preferred"><primary>XmbDrawString</primary></indexterm>
3734
<indexterm significance="preferred"><primary>XwcDrawString</primary></indexterm>
3735
<!-- .sM -->
3736
<funcsynopsis>
3737
<funcprototype>
3738
<funcdef>void <function>XmbDrawString</function></funcdef>
3739
<paramdef>Display<parameter> *display</parameter></paramdef>
3740
<paramdef>Drawable<parameter> d</parameter></paramdef>
3741
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
3742
<paramdef>GC<parameter> gc</parameter></paramdef>
3743
<paramdef>intx,<parameter> y</parameter></paramdef>
3744
<paramdef>char<parameter> *string</parameter></paramdef>
3745
<paramdef>int<parameter> num_bytes</parameter></paramdef>
3746
</funcprototype>
3747
</funcsynopsis>
3748
<!-- .FN -->
3749
<funcsynopsis>
3750
<funcprototype>
3751
<funcdef>void <function>XwcDrawString</function></funcdef>
3752
<paramdef>Display<parameter> *display</parameter></paramdef>
3753
<paramdef>Drawable<parameter> d</parameter></paramdef>
3754
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
3755
<paramdef>GC<parameter> gc</parameter></paramdef>
3756
<paramdef>intx,<parameter> y</parameter></paramdef>
3757
<paramdef>wchar_t<parameter> *string</parameter></paramdef>
3758
<paramdef>int<parameter> num_wchars</parameter></paramdef>
3759
</funcprototype>
3760
</funcsynopsis>
3761
<!-- .FN -->
3762
<variablelist>
3763
<varlistentry>
3764
<term>
3765
<emphasis remap='I'>display</emphasis>
3766
</term>
3767
<listitem>
3768
<para>
3769
Specifies the connection to the X server.
3770
</para>
3771
</listitem>
3772
</varlistentry>
3773
<varlistentry>
3774
<term>
3775
<emphasis remap='I'>d</emphasis>
3776
</term>
3777
<listitem>
3778
<para>
3779
Specifies the drawable.
3780
</para>
3781
</listitem>
3782
</varlistentry>
3783
<varlistentry>
3784
<term>
3785
<emphasis remap='I'>font_set</emphasis>
3786
</term>
3787
<listitem>
3788
<para>
3789
Specifies the font set.
3790
</para>
3791
</listitem>
3792
</varlistentry>
3793
<varlistentry>
3794
<term>
3795
<emphasis remap='I'>gc</emphasis>
3796
</term>
3797
<listitem>
3798
<para>
3799
Specifies the GC.
3800
<!-- .ds Xy -->
3801
</para>
3802
</listitem>
3803
</varlistentry>
3804
<varlistentry>
3805
<term>
3806
<emphasis remap='I'>x</emphasis>
3807
</term>
3808
<listitem>
3809
<para>
3810
<!-- .br -->
3811
<!-- .ns -->
3812
</para>
3813
</listitem>
3814
</varlistentry>
3815
<varlistentry>
3816
<term>
3817
<emphasis remap='I'>y</emphasis>
3818
</term>
3819
<listitem>
3820
<para>
3821
Specify the x and y coordinates(Xy.
3822
</para>
3823
</listitem>
3824
</varlistentry>
3825
<varlistentry>
3826
<term>
3827
<emphasis remap='I'>string</emphasis>
3828
</term>
3829
<listitem>
3830
<para>
3831
Specifies the character string.
3832
</para>
3833
</listitem>
3834
</varlistentry>
3835
<varlistentry>
3836
<term>
3837
<emphasis remap='I'>num_bytes</emphasis>
3838
</term>
3839
<listitem>
3840
<para>
3841
Specifies the number of bytes in the string argument.
3842
</para>
3843
</listitem>
3844
</varlistentry>
3845
<varlistentry>
3846
<term>
3847
<emphasis remap='I'>num_wchars</emphasis>
3848
</term>
3849
<listitem>
3850
<para>
3851
Specifies the number of characters in the string argument.
3852
</para>
3853
</listitem>
3854
</varlistentry>
3855
</variablelist>
3856
</para>
3857
<para>
3858
<!-- .LP -->
3859
<!-- .eM -->
3860
The
3861
<function>XmbDrawString</function>
3862
and
3863
<function>XwcDrawString</function>
3864
functions draw the specified text with the foreground pixel.
3865
When the
3866
<type>XFontSet</type>
3867
has missing charsets, each unavailable character is drawn
3868
with the default string returned by
3869
<function>XCreateFontSet</function>.
3870
The behavior for an invalid codepoint is undefined.
3871
</para>
3872
<para>
3873
<!-- .LP -->
3874
<!-- .sp -->
3875
To draw image text using a single font set in a given drawable, use
3876
<function>XmbDrawImageString</function>
3877
or
3878
<function>XwcDrawImageString</function>.
3879
<indexterm significance="preferred"><primary>XmbDrawImageString</primary></indexterm>
3880
<indexterm significance="preferred"><primary>XwcDrawImageString</primary></indexterm>
3881
<!-- .sM -->
3882
<funcsynopsis>
3883
<funcprototype>
3884
<funcdef>void <function>XmbDrawImageString</function></funcdef>
3885
<paramdef>Display<parameter> *display</parameter></paramdef>
3886
<paramdef>Drawable<parameter> d</parameter></paramdef>
3887
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
3888
<paramdef>GC<parameter> gc</parameter></paramdef>
3889
<paramdef>intx,<parameter> y</parameter></paramdef>
3890
<paramdef>char<parameter> *string</parameter></paramdef>
3891
<paramdef>int<parameter> num_bytes</parameter></paramdef>
3892
</funcprototype>
3893
</funcsynopsis>
3894
<!-- .FN -->
3895
<funcsynopsis>
3896
<funcprototype>
3897
<funcdef>void <function>XwcDrawImageString</function></funcdef>
3898
<paramdef>Display<parameter> *display</parameter></paramdef>
3899
<paramdef>Drawable<parameter> d</parameter></paramdef>
3900
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
3901
<paramdef>GC<parameter> gc</parameter></paramdef>
3902
<paramdef>intx,<parameter> y</parameter></paramdef>
3903
<paramdef>wchar_t<parameter> *string</parameter></paramdef>
3904
<paramdef>int<parameter> num_wchars</parameter></paramdef>
3905
</funcprototype>
3906
</funcsynopsis>
3907
<!-- .FN -->
3908
<variablelist>
3909
<varlistentry>
3910
<term>
3911
<emphasis remap='I'>display</emphasis>
3912
</term>
3913
<listitem>
3914
<para>
3915
Specifies the connection to the X server.
3916
</para>
3917
</listitem>
3918
</varlistentry>
3919
<varlistentry>
3920
<term>
3921
<emphasis remap='I'>d</emphasis>
3922
</term>
3923
<listitem>
3924
<para>
3925
Specifies the drawable.
3926
</para>
3927
</listitem>
3928
</varlistentry>
3929
<varlistentry>
3930
<term>
3931
<emphasis remap='I'>font_set</emphasis>
3932
</term>
3933
<listitem>
3934
<para>
3935
Specifies the font set.
3936
</para>
3937
</listitem>
3938
</varlistentry>
3939
<varlistentry>
3940
<term>
3941
<emphasis remap='I'>gc</emphasis>
3942
</term>
3943
<listitem>
3944
<para>
3945
Specifies the GC.
3946
<!-- .ds Xy -->
3947
</para>
3948
</listitem>
3949
</varlistentry>
3950
<varlistentry>
3951
<term>
3952
<emphasis remap='I'>x</emphasis>
3953
</term>
3954
<listitem>
3955
<para>
3956
<!-- .br -->
3957
<!-- .ns -->
3958
</para>
3959
</listitem>
3960
</varlistentry>
3961
<varlistentry>
3962
<term>
3963
<emphasis remap='I'>y</emphasis>
3964
</term>
3965
<listitem>
3966
<para>
3967
Specify the x and y coordinates(Xy.
3968
</para>
3969
</listitem>
3970
</varlistentry>
3971
<varlistentry>
3972
<term>
3973
<emphasis remap='I'>string</emphasis>
3974
</term>
3975
<listitem>
3976
<para>
3977
Specifies the character string.
3978
</para>
3979
</listitem>
3980
</varlistentry>
3981
<varlistentry>
3982
<term>
3983
<emphasis remap='I'>num_bytes</emphasis>
3984
</term>
3985
<listitem>
3986
<para>
3987
Specifies the number of bytes in the string argument.
3988
</para>
3989
</listitem>
3990
</varlistentry>
3991
<varlistentry>
3992
<term>
3993
<emphasis remap='I'>num_wchars</emphasis>
3994
</term>
3995
<listitem>
3996
<para>
3997
Specifies the number of characters in the string argument.
3998
</para>
3999
</listitem>
4000
</varlistentry>
4001
</variablelist>
4002
</para>
4003
<para>
4004
<!-- .LP -->
4005
<!-- .eM -->
4006
The
4007
<function>XmbDrawImageString</function>
4008
and
4009
<function>XwcDrawImageString</function>
4010
functions fill a destination rectangle with the background pixel defined
4011
in the GC and then paint the text with the foreground pixel.
4012
The filled rectangle is the rectangle returned to overall_logical_return by
4013
<function>XmbTextExtents</function>
4014
or
4015
<function>XwcTextExtents</function>
4016
for the same text and
4017
<type>XFontSet</type>.
4018
</para>
4019
<para>
4020
<!-- .LP -->
4021
When the
4022
<type>XFontSet</type>
4023
has missing charsets, each unavailable character is drawn
4024
with the default string returned by
4025
<function>XCreateFontSet</function>.
4026
The behavior for an invalid codepoint is undefined.
4027
</para>
4028
</sect2>
4029
</sect1>
4030
<sect1 id="Input_Methods">
4031
<title>Input Methods</title>
4032
<!-- .XS -->
4033
<!-- (SN Input Methods -->
4034
<!-- .XE -->
4035
<para>
4036
<!-- .LP -->
4037
This section provides discussions of the following X Input Method
4038
(<acronym>XIM</acronym>) topics:
4039
</para>
4040
<itemizedlist>
4041
<listitem>
4042
<para>
4043
Input method overview
4044
</para>
4045
</listitem>
4046
<listitem>
4047
<para>
4048
Input method management
4049
</para>
4050
</listitem>
4051
<listitem>
4052
<para>
4053
Input method functions
4054
</para>
4055
</listitem>
4056
<listitem>
4057
<para>
4058
Input method values
4059
</para>
4060
</listitem>
4061
<listitem>
4062
<para>
4063
Input context functions
4064
</para>
4065
</listitem>
4066
<listitem>
4067
<para>
4068
Input context values
4069
</para>
4070
</listitem>
4071
<listitem>
4072
<para>
4073
Input method callback semantics
4074
</para>
4075
</listitem>
4076
<listitem>
4077
<para>
4078
Event filtering
4079
</para>
4080
</listitem>
4081
<listitem>
4082
<para>
4083
Getting keyboard input
4084
</para>
4085
</listitem>
4086
<listitem>
4087
<para>
4088
Input method conventions
4089
</para>
4090
</listitem>
4091
</itemizedlist>
4092
<sect2 id="Input_Method_Overview">
4093
<title>Input Method Overview</title>
4094
<!-- .XS -->
4095
<!-- (SN Input Method Overview -->
4096
<!-- .XE -->
4097
<para>
4098
<!-- .LP -->
4099
This section provides definitions for terms and concepts used
4100
for internationalized text input and a brief overview of the
4101
intended use of the mechanisms provided by Xlib.
4102
</para>
4103
<para>
4104
<!-- .LP -->
4105
A large number of languages in the world use alphabets
4106
consisting of a small set of symbols (letters) to form words.
4107
To enter text into a computer in an alphabetic language,
4108
a user usually has a keyboard on which there exist key symbols corresponding
4109
to the alphabet.
4110
Sometimes, a few characters of an alphabetic language are missing
4111
on the keyboard.
4112
Many computer users who speak a Latin-alphabet-based language
4113
only have an English-based keyboard.
4114
They need to hit a combination of keystrokes
4115
to enter a character that does not exist directly on the keyboard.
4116
A number of algorithms have been developed for entering such characters.
4117
These are known as European input methods, compose input methods,
4118
or dead-key input methods.
4119
</para>
4120
<para>
4121
<!-- .LP -->
4122
Japanese is an example of a language with a phonetic symbol set,
4123
where each symbol represents a specific sound.
4124
There are two phonetic symbol sets in Japanese: Katakana and Hiragana.
4125
In general,
4126
Katakana is used for words that are of foreign origin,
4127
and Hiragana is used for writing native Japanese words.
4128
Collectively, the two systems are called Kana.
4129
Each set consists of 48 characters.
4130
</para>
4131
<para>
4132
<!-- .LP -->
4133
Korean also has a phonetic symbol set, called Hangul.
4134
Each of the 24 basic phonetic symbols (14 consonants and 10 vowels)
4135
represents a specific sound.
4136
A syllable is composed of two or three parts:
4137
the initial consonants, the vowels, and the optional last consonants.
4138
With Hangul,
4139
syllables can be treated as the basic units on which text processing is done.
4140
For example,
4141
a delete operation may work on a phonetic symbol or a syllable.
4142
Korean code sets include several thousands of these syllables.
4143
A user types the phonetic symbols that make up the syllables of the words
4144
to be entered.
4145
The display may change as each phonetic symbol is entered.
4146
For example,
4147
when the second phonetic symbol of a syllable is entered,
4148
the first phonetic symbol may change its shape and size.
4149
Likewise, when the third phonetic symbol is entered,
4150
the first two phonetic symbols may change their shape and size.
4151
</para>
4152
<para>
4153
<!-- .LP -->
4154
Not all languages rely solely on alphabetic or phonetic systems.
4155
Some languages, including Japanese and Korean, employ an
4156
ideographic writing system.
4157
In an ideographic system, rather than taking a small set of
4158
symbols and combining them in different ways to create words,
4159
each word consists of one unique symbol (or, occasionally, several symbols).
4160
The number of symbols can be very large:
4161
approximately 50,000 have been identified in Hanzi,
4162
the Chinese ideographic system.
4163
</para>
4164
<para>
4165
<!-- .LP -->
4166
Two major aspects of ideographic systems impact their use with computers.
4167
First, the standard computer character sets in Japan, China, and Korea
4168
include roughly 8,000 characters,
4169
while sets in Taiwan have between 15,000 and 30,000 characters.
4170
This makes it necessary to use more than one byte to represent a character.
4171
Second, it obviously is impractical to have a keyboard that includes
4172
all of a given language's ideographic symbols.
4173
Therefore, a mechanism is required for entering characters
4174
so that a keyboard with a reasonable number of keys can be used.
4175
Those input methods are usually based on phonetics,
4176
but there also exist methods based on the graphical properties of
4177
characters.
4178
</para>
4179
<para>
4180
<!-- .LP -->
4181
In Japan, both Kana and the ideographic system Kanji are used.
4182
In Korea, Hangul and sometimes the ideographic system Hanja are used.
4183
Now consider entering ideographs in Japan, Korea, China, and Taiwan.
4184
</para>
4185
<para>
4186
<!-- .LP -->
4187
In Japan, either Kana or English characters are typed and then a region
4188
is selected (sometimes automatically) for conversion to Kanji.
4189
Several Kanji characters may have the same phonetic representation.
4190
If that is the case with the string entered,
4191
a menu of characters is presented and
4192
the user must choose the appropriate one.
4193
If no choice is necessary or a preference has been established,
4194
the input method does the substitution directly.
4195
When Latin characters are converted to Kana or Kanji,
4196
it is called a romaji conversion.
4197
</para>
4198
<para>
4199
<!-- .LP -->
4200
In Korea, it is usually acceptable to keep Korean text in Hangul form,
4201
but some people may choose to write Hanja-originated words in Hanja
4202
rather than in Hangul.
4203
To change Hangul to Hanja,
4204
the user selects a region for conversion
4205
and then follows the same basic method as that described for Japanese.
4206
</para>
4207
<para>
4208
<!-- .LP -->
4209
Probably because there are well-accepted phonetic writing systems
4210
for Japanese and Korean,
4211
computer input methods in these countries for entering ideographs
4212
are fairly standard.
4213
Keyboard keys have both English characters and phonetic symbols
4214
engraved on them, and the user can switch between the two sets.
4215
</para>
4216
<para>
4217
<!-- .LP -->
4218
The situation is different for Chinese.
4219
While there is a phonetic system called Pinyin promoted by authorities,
4220
there is no consensus for entering Chinese text.
4221
Some vendors use a phonetic decomposition (Pinyin or another),
4222
others use ideographic decomposition of Chinese words,
4223
with various implementations and keyboard layouts.
4224
There are about 16 known methods, none of which is a clear standard.
4225
</para>
4226
<para>
4227
<!-- .LP -->
4228
Also, there are actually two ideographic sets used:
4229
Traditional Chinese (the original written Chinese)
4230
and Simplified Chinese.
4231
Several years ago,
4232
the People's Republic of China launched a campaign to simplify
4233
some ideographic characters and eliminate redundancies altogether.
4234
Under the plan,
4235
characters would be streamlined every five years.
4236
Characters have been revised several times now,
4237
resulting in the smaller, simpler set that makes up Simplified Chinese.
4238
</para>
4239
<sect3 id="Input_Method_Architecture">
4240
<title>Input Method Architecture</title>
4241
<!-- .XS -->
4242
<!-- (SN Input Method Architecture -->
4243
<!-- .XE -->
4244
<para>
4245
<!-- .LP -->
4246
As shown in the previous section,
4247
there are many different input methods in use today,
4248
each varying with language, culture, and history.
4249
A common feature of many input methods is that the user may type
4250
multiple keystrokes to compose a single character (or set
4251
of characters).
4252
The process of composing characters from keystrokes is called
4253
<emphasis remap='I'>preediting</emphasis>.
4254
It may require complex algorithms and large dictionaries
4255
involving substantial computer resources.
4256
</para>
4257
<para>
4258
<!-- .LP -->
4259
Input methods may require one or more areas in which to show the
4260
feedback of the actual keystrokes, to propose disambiguation to the
4261
user, to list dictionaries, and so on.
4262
The input method areas of concern are as follows:
4263
</para>
4264
<itemizedlist>
4265
<listitem>
4266
<para>
4267
The <emphasis remap='I'>status</emphasis> area is a logical extension of the
4268
LEDs that exist on the physical keyboard.
4269
It is a window that is intended to present the internal state
4270
of the input method that is critical to the user.
4271
The status area may consist of text data and bitmaps or some combination.
4272
</para>
4273
</listitem>
4274
<listitem>
4275
<para>
4276
The <emphasis remap='I'>preedit</emphasis> area displays the
4277
intermediate text for those languages that are composing prior to
4278
the client handling the data.
4279
</para>
4280
</listitem>
4281
<listitem>
4282
<para>
4283
The <emphasis remap='I'>auxiliary</emphasis> area is used for pop-up menus and customizing
4284
dialogs that may be required for an input method.
4285
There may be multiple auxiliary areas for an input method.
4286
Auxiliary areas are managed by the input method independent of the client.
4287
Auxiliary areas are assumed to be separate dialogs,
4288
which are maintained by the input method.
4289
</para>
4290
</listitem>
4291
</itemizedlist>
4292
<para>
4293
<!-- .LP -->
4294
There are various user interaction styles used for preediting.
4295
The ones supported by Xlib are as follows:
4296
</para>
4297
<itemizedlist>
4298
<listitem>
4299
<para>
4300
For <emphasis remap='I'>on-the-spot</emphasis> input methods,
4301
preediting data will be displayed directly in the application window.
4302
Application data is moved to allow preedit data to appear
4303
at the point of insertion.
4304
</para>
4305
</listitem>
4306
<listitem>
4307
<para>
4308
<emphasis remap='I'>Over-the-spot</emphasis> preediting means that the data is displayed in
4309
a preedit window that is placed over the point of insertion.
4310
</para>
4311
</listitem>
4312
<listitem>
4313
<para>
4314
<emphasis remap='I'>Off-the-spot</emphasis> preediting means that the preedit window is
4315
inside the application window but not at the point of insertion.
4316
Often, this type of window is placed at the bottom of the application window.
4317
</para>
4318
</listitem>
4319
<listitem>
4320
<para>
4321
<emphasis remap='I'>Root-window</emphasis> preediting refers to input methods that use a preedit
4322
window that is the child of
4323
<function>RootWindow</function>.
4324
</para>
4325
</listitem>
4326
</itemizedlist>
4327
<para>
4328
<!-- .LP -->
4329
It would require a lot of computing resources if portable applications
4330
had to include input methods for all the languages in the world.
4331
To avoid this,
4332
a goal of the Xlib design is to allow an application
4333
to communicate with an input method placed in a separate process.
4334
Such a process is called an <emphasis remap='I'>input server</emphasis>.
4335
The server to which the application should connect is dependent on
4336
the environment when the application is started up,
4337
that is, the user language and the actual encoding to be used for it.
4338
The input method connection is said to be <emphasis remap='I'>locale-dependent</emphasis>.
4339
It is also user-dependent.
4340
For a given language, the user can choose, to some extent,
4341
the user interface style of input method (if choice is possible among
4342
several).
4343
</para>
4344
<para>
4345
<!-- .LP -->
4346
Using an input server implies communication overhead,
4347
but applications can be migrated without relinking.
4348
Input methods can be implemented either as a
4349
stub communicating to an input server or as a local library.
4350
</para>
4351
<para>
4352
<!-- .LP -->
4353
An input method may be based on a <emphasis remap='I'>front-end</emphasis> or a <emphasis remap='I'>back-end</emphasis>
4354
architecture.
4355
In a front-end architecture,
4356
there are two separate connections to the X server:
4357
keystrokes go directly from the X server to the input method on
4358
one connection and other events to the regular client connection.
4359
The input method is then acting as a filter and sends composed strings
4360
to the client.
4361
A front-end architecture requires synchronization between the
4362
two connections to avoid lost key events or locking issues.
4363
</para>
4364
<para>
4365
<!-- .LP -->
4366
In a back-end architecture,
4367
a single X server connection is used.
4368
A dispatching mechanism must decide on this channel to delegate appropriate
4369
keystrokes to the input method.
4370
For instance,
4371
it may retain a Help keystroke for its own purpose.
4372
In the case where the input method is a separate process (that is, a server),
4373
there must be a special communication protocol between the back-end client
4374
and the input server.
4375
</para>
4376
<para>
4377
<!-- .LP -->
4378
A front-end architecture introduces synchronization issues
4379
and a filtering mechanism for noncharacter keystrokes
4380
(Function keys, Help, and so on).
4381
A back-end architecture sometimes implies more communication overhead
4382
and more process switching.
4383
If all three processes (X server, input server, client)
4384
are running on a single workstation,
4385
there are two process switches for each keystroke in a back-end
4386
architecture,
4387
but there is only one in a front-end architecture.
4388
</para>
4389
<para>
4390
<!-- .LP -->
4391
The abstraction used by a client to communicate with an input method
4392
is an opaque data structure represented by the
4393
<type>XIM</type>
4394
data type.
4395
This data structure is returned by the
4396
<function>XOpenIM</function>
4397
function, which opens an input method on a given display.
4398
Subsequent operations on this data structure encapsulate all communication
4399
between client and input method.
4400
There is no need for an X client to use any networking library
4401
or natural language package to use an input method.
4402
</para>
4403
<para>
4404
<!-- .LP -->
4405
A single input server may be used for one or more languages,
4406
supporting one or more encoding schemes.
4407
But the strings returned from an input method will always be encoded
4408
in the (single) locale associated with the
4409
<type>XIM</type>
4410
object.
4411
</para>
4412
</sect3>
4413
<sect3 id="Input_Contexts">
4414
<title>Input Contexts</title>
4415
<!-- .XS -->
4416
<!-- (SN Input Contexts -->
4417
<!-- .XE -->
4418
<para>
4419
<!-- .LP -->
4420
Xlib provides the ability to manage a multi-threaded state for text input.
4421
A client may be using multiple windows,
4422
each window with multiple text entry areas,
4423
and the user possibly switching among them at any time.
4424
The abstraction for representing the state of a particular input thread
4425
is called an <emphasis remap='I'>input context</emphasis>.
4426
The Xlib representation of an input context is an
4427
<type>XIC</type>.
4428
</para>
4429
<para>
4430
<!-- .LP -->
4431
An input context is the abstraction retaining the state, properties,
4432
and semantics of communication between a client and an input method.
4433
An input context is a combination of an input method, a locale
4434
specifying the encoding of the character strings to be returned,
4435
a client window, internal state information,
4436
and various layout or appearance characteristics.
4437
The input context concept somewhat matches for input the graphics context
4438
abstraction defined for graphics output.
4439
</para>
4440
<para>
4441
<!-- .LP -->
4442
One input context belongs to exactly one input method.
4443
Different input contexts may be associated with the same input method,
4444
possibly with the same client window.
4445
An
4446
<type>XIC</type>
4447
is created with the
4448
<function>XCreateIC</function>
4449
function, providing an
4450
<type>XIM</type>
4451
argument and affiliating the input context to the input method
4452
for its lifetime.
4453
When an input method is closed with
4454
<function>XCloseIM</function>,
4455
all of its affiliated input contexts should not be used any more
4456
(and should preferably be destroyed before closing the input method).
4457
</para>
4458
<para>
4459
<!-- .LP -->
4460
Considering the example of a client window with multiple text entry areas,
4461
the application programmer could, for example, choose to implement as follows:
4462
</para>
4463
<itemizedlist>
4464
<listitem>
4465
<para>
4466
As many input contexts are created as text entry areas, and the client
4467
will get the input accumulated on each context each time it looks up
4468
in that context.
4469
</para>
4470
</listitem>
4471
<listitem>
4472
<para>
4473
A single context is created for a top-level window in the application.
4474
If such a window contains several text entry areas,
4475
each time the user moves to another text entry area,
4476
the client has to indicate changes in the context.
4477
</para>
4478
</listitem>
4479
</itemizedlist>
4480
<para>
4481
<!-- .LP -->
4482
A range of choices can be made by application designers to use
4483
either a single or multiple input contexts,
4484
according to the needs of their application.
4485
</para>
4486
</sect3>
4487
<sect3 id="Getting_Keyboard_Input">
4488
<title>Getting Keyboard Input</title>
4489
<!-- .XS -->
4490
<!-- (SN Getting Keyboard Input -->
4491
<!-- .XE -->
4492
<para>
4493
<!-- .LP -->
4494
To obtain characters from an input method,
4495
a client must call the function
4496
<function>XmbLookupString</function>
4497
or
4498
<function>XwcLookupString</function>
4499
with an input context created from that input method.
4500
Both a locale and display are bound to an input method when it is opened,
4501
and an input context inherits this locale and display.
4502
Any strings returned by
4503
<function>XmbLookupString</function>
4504
or
4505
<function>XwcLookupString</function>
4506
will be encoded in that locale.
4507
</para>
4508
</sect3>
4509
<sect3 id="Focus_Management">
4510
<title>Focus Management</title>
4511
<!-- .XS -->
4512
<!-- (SN Focus Management -->
4513
<!-- .XE -->
4514
<para>
4515
<!-- .LP -->
4516
For each text entry area in which the
4517
<function>XmbLookupString</function>
4518
or
4519
<function>XwcLookupString</function>
4520
functions are used,
4521
there will be an associated input context.
4522
</para>
4523
<para>
4524
<!-- .LP -->
4525
When the application focus moves to a text entry area,
4526
the application must set the input context focus to the
4527
input context associated with that area.
4528
The input context focus is set by calling
4529
<function>XSetICFocus</function>
4530
with the appropriate input context.
4531
</para>
4532
<para>
4533
<!-- .LP -->
4534
Also, when the application focus moves out of a text entry area, the
4535
application should unset the focus for the associated input context
4536
by calling
4537
<function>XUnsetICFocus</function>.
4538
As an optimization, if
4539
<function>XSetICFocus</function>
4540
is called successively on two different input contexts,
4541
setting the focus on the second
4542
will automatically unset the focus on the first.
4543
</para>
4544
<para>
4545
<!-- .LP -->
4546
To set and unset the input context focus correctly,
4547
it is necessary to track application-level focus changes.
4548
Such focus changes do not necessarily correspond to X server focus changes.
4549
</para>
4550
<para>
4551
<!-- .LP -->
4552
If a single input context
4553
is being used to do input for
4554
multiple text entry areas, it will also be necessary
4555
to set the focus window of the
4556
input context whenever the focus window changes
4557
(see section 13.5.6.3).
4558
</para>
4559
</sect3>
4560
<sect3 id="Geometry_Management">
4561
<title>Geometry Management</title>
4562
<!-- .XS -->
4563
<!-- (SN Geometry Management -->
4564
<!-- .XE -->
4565
<para>
4566
<!-- .LP -->
4567
In most input method architectures
4568
(on-the-spot being the notable exception),
4569
the input method will perform the display of its own data.
4570
To provide better visual locality,
4571
it is often desirable to have the input method areas embedded within a client.
4572
To do this,
4573
the client may need to allocate space for an input method.
4574
Xlib provides support that allows the size and position of input method
4575
areas to be provided by a client.
4576
The input method areas that are supported for geometry management
4577
are the status area and the preedit area.
4578
</para>
4579
<para>
4580
<!-- .LP -->
4581
The fundamental concept on which geometry management for input method windows
4582
is based is the proper division of responsibilities between the
4583
client (or toolkit) and the input method.
4584
The division of responsibilities is as follows:
4585
</para>
4586
<itemizedlist>
4587
<listitem>
4588
<para>
4589
The client is responsible for the geometry of the input method window.
4590
</para>
4591
</listitem>
4592
<listitem>
4593
<para>
4594
The input method is responsible for the contents of the input method window.
4595
</para>
4596
</listitem>
4597
</itemizedlist>
4598
<para>
4599
<!-- .LP -->
4600
An input method is able to suggest a size to the client,
4601
but it cannot suggest a placement.
4602
Also the input method can only suggest a size.
4603
It does not determine the size,
4604
and it must accept the size it is given.
4605
</para>
4606
<para>
4607
<!-- .LP -->
4608
Before a client provides geometry management for an input method,
4609
it must determine if geometry management is needed.
4610
The input method indicates the need for geometry management
4611
by setting
4612
<symbol>XIMPreeditArea</symbol>
4613
or
4614
<symbol>XIMStatusArea</symbol>
4615
in its
4616
<structname>XIMStyles</structname>
4617
value returned by
4618
<function>XGetIMValues</function>.
4619
When a client has decided that it will provide geometry management
4620
for an input method,
4621
it indicates that decision by setting the
4622
<symbol>XNInputStyle</symbol>
4623
value in the
4624
<type>XIC</type>.
4625
</para>
4626
<para>
4627
<!-- .LP -->
4628
After a client has established with the input method
4629
that it will do geometry management,
4630
the client must negotiate the geometry with the input method.
4631
The geometry is negotiated by the following steps:
4632
</para>
4633
<itemizedlist>
4634
<listitem>
4635
<para>
4636
The client suggests an area to the input method by setting the
4637
<symbol>XNAreaNeeded</symbol>
4638
value for that area.
4639
If the client has no constraints for the input method,
4640
it either will not suggest an area or will set the width and height to zero.
4641
Otherwise, it will set one of the values.
4642
</para>
4643
</listitem>
4644
<listitem>
4645
<para>
4646
The client will get the <acronym>XIC</acronym> value
4647
<symbol>XNAreaNeeded</symbol>.
4648
The input method will return its suggested size in this value.
4649
The input method should pay attention to any constraints suggested
4650
by the client.
4651
</para>
4652
</listitem>
4653
<listitem>
4654
<para>
4655
The client sets the <acronym>XIC</acronym> value
4656
<symbol>XNArea</symbol>
4657
to inform the input method of the geometry of its window.
4658
The client should try to honor the geometry requested by the input method.
4659
The input method must accept this geometry.
4660
</para>
4661
</listitem>
4662
</itemizedlist>
4663
<para>
4664
<!-- .LP -->
4665
Clients doing geometry management must be aware that setting other
4666
<acronym>XIC</acronym> values may affect the geometry desired by an input method.
4667
For example,
4668
<symbol>XNFontSet</symbol>
4669
and
4670
<symbol>XNLineSpace</symbol>
4671
may change the geometry desired by the input method.
4672
</para>
4673
<para>
4674
<!-- .LP -->
4675
The table of <acronym>XIC</acronym> values (see section 13.5.6)
4676
indicates the values that can cause the desired geometry to change
4677
when they are set.
4678
It is the responsibility of the client to renegotiate the geometry
4679
of the input method window when it is needed.
4680
</para>
4681
<para>
4682
<!-- .LP -->
4683
In addition,
4684
a geometry management callback is provided
4685
by which an input method can initiate a geometry change.
4686
</para>
4687
</sect3>
4688
<sect3 id="Event_Filtering">
4689
<title>Event Filtering</title>
4690
<!-- .XS -->
4691
<!-- (SN Event Filtering -->
4692
<!-- .XE -->
4693
<para>
4694
<!-- .LP -->
4695
A filtering mechanism is provided to allow input methods
4696
to capture X events transparently to clients.
4697
It is expected that toolkits (or clients) using
4698
<function>XmbLookupString</function>
4699
or
4700
<function>XwcLookupString</function>
4701
will call this filter at some point in the event processing mechanism
4702
to make sure that events needed by an input method can be filtered
4703
by that input method.
4704
</para>
4705
<para>
4706
<!-- .LP -->
4707
If there were no filter,
4708
a client could receive and discard events that are necessary
4709
for the proper functioning of an input method.
4710
The following provides a few examples of such events:
4711
</para>
4712
<itemizedlist>
4713
<listitem>
4714
<para>
4715
Expose events on preedit window in local mode.
4716
</para>
4717
</listitem>
4718
<listitem>
4719
<para>
4720
Events may be used by an input method to communicate with an input server.
4721
Such input server protocol-related events have to be intercepted
4722
if one does not want to disturb client code.
4723
</para>
4724
</listitem>
4725
<listitem>
4726
<para>
4727
Key events can be sent to a filter before they are bound
4728
to translations such as those the X Toolkit Intrinsics library provides.
4729
</para>
4730
</listitem>
4731
</itemizedlist>
4732
<para>
4733
<!-- .LP -->
4734
Clients are expected to get the <acronym>XIC</acronym> value
4735
<symbol>XNFilterEvents</symbol>
4736
and augment the event mask for the client window with that event mask.
4737
This mask may be zero.
4738
</para>
4739
</sect3>
4740
<sect3 id="Callbacks">
4741
<title>Callbacks</title>
4742
<!-- .XS -->
4743
<!-- (SN Callbacks -->
4744
<!-- .XE -->
4745
<para>
4746
<!-- .LP -->
4747
When an on-the-spot input method is implemented,
4748
only the client can insert or delete preedit data in place
4749
and possibly scroll existing text.
4750
This means that the echo of the keystrokes has to be achieved
4751
by the client itself, tightly coupled with the input method logic.
4752
</para>
4753
<para>
4754
<!-- .LP -->
4755
When the user enters a keystroke,
4756
the client calls
4757
<function>XmbLookupString</function>
4758
or
4759
<function>XwcLookupString</function>.
4760
At this point, in the on-the-spot case,
4761
the echo of the keystroke in the preedit has not yet been done.
4762
Before returning to the client logic that handles the input characters,
4763
the look-up function
4764
must call the echoing logic to insert the new keystroke.
4765
If the keystrokes entered so far make up a character,
4766
the keystrokes entered need to be deleted,
4767
and the composed character will be returned.
4768
Hence, what happens is that, while being called by client code,
4769
the input method logic has to call back to the client before it returns.
4770
The client code, that is, a callback procedure,
4771
is called from the input method logic.
4772
</para>
4773
<para>
4774
<!-- .LP -->
4775
There are a number of cases where the input method logic has to
4776
call back the client.
4777
Each of those cases is associated with a well-defined callback action.
4778
It is possible for the client to specify, for each input context,
4779
what callback is to be called for each action.
4780
</para>
4781
<para>
4782
<!-- .LP -->
4783
There are also callbacks provided for feedback of status information
4784
and a callback to initiate a geometry request for an input method.
4785
</para>
4786
</sect3>
4787
<sect3 id="Visible_Position_Feedback_Masks">
4788
<title>Visible Position Feedback Masks</title>
4789
<!-- .XS -->
4790
<!-- (SN Visible Position Feedback Masks -->
4791
<!-- .XE -->
4792
<para>
4793
<!-- .LP -->
4794
In the on-the-spot input style, there is a problem when
4795
attempting to draw preedit strings that are longer than the
4796
available space. Once the display area is exceeded, it is not
4797
clear how best to display the preedit string.
4798
The visible position feedback masks of
4799
<structname>XIMText</structname>
4800
help resolve this problem by allowing the input method to specify hints that
4801
indicate the essential portions of the preedit string.
4802
For example, such hints can help developers implement
4803
scrolling of a long preedit string within a short preedit display area.
4804
</para>
4805
</sect3>
4806
<sect3 id="Preedit_String_Management">
4807
<title>Preedit String Management</title>
4808
<!-- .XS -->
4809
<!-- (SN Preedit String Management -->
4810
<!-- .XE -->
4811
<para>
4812
<!-- .LP -->
4813
As highlighted before, the input method architecture provides
4814
preediting, which supports a type of preprocessor input composition.
4815
In this case, composition consists of interpreting a sequence
4816
of key events and returning a committed string via
4817
<function>XmbLookupString</function>
4818
or
4819
<function>XwcLookupString</function>.
4820
This provides the basics for input methods.
4821
</para>
4822
<para>
4823
<!-- .LP -->
4824
In addition to preediting based on key events, a general framework
4825
is provided to give a client that desires it more advanced preediting based
4826
on the text within the client. This framework is called
4827
<emphasis remap='I'>string conversion</emphasis> and is provided using <acronym>XIC</acronym> values.
4828
The fundamental concept of string conversion
4829
is to allow the input method to manipulate the client's
4830
text independent of any user preediting operation.
4831
</para>
4832
<para>
4833
<!-- .LP -->
4834
The need for string conversion is based on
4835
language needs and input method capabilities.
4836
The following are some examples of string conversion:
4837
</para>
4838
<itemizedlist>
4839
<listitem>
4840
<para>
4841
Transliteration conversion provides language-specific conversions
4842
within the input method.
4843
In the case of Korean input, users wish to convert a Hangul string
4844
into a Hanja string while in preediting, after preediting,
4845
or in other situations (for example, on a selected string).
4846
The conversion is triggered when the user
4847
presses a Hangul-to-Hanja key sequence (which may be input method specific).
4848
Sometimes the user may want to invoke the conversion after finishing
4849
preediting or on a user-selected string.
4850
Thus, the string to be converted is in an application buffer, not in
4851
the preedit area of the input method. The string conversion services
4852
allow the client to request this transliteration conversion from the
4853
input method.
4854
There are many other transliteration conversions defined for
4855
various languages, for example, Kana-to-Kanji conversion in Japanese.
4856
<!-- .sp -->
4857
The key to remember is that transliteration conversions are triggered
4858
at the request of the user and returned to the client
4859
immediately without affecting the preedit area of the input method.
4860
</para>
4861
</listitem>
4862
<listitem>
4863
<para>
4864
Reconversion of a previously committed string or
4865
a selected string is supported by many input methods as a
4866
convenience to the user.
4867
For example, a user tends to mistype the commit key while
4868
preediting. In that case, some input methods provide a special
4869
key sequence to request a ``reconvert'' operation on the
4870
committed string, similiar to the undo facility provided by most
4871
text editors.
4872
Another example is where the user is proofreading a document
4873
that has some misconversions from preediting and wants to correct
4874
the misconverted text. Such reconversion is again triggered
4875
by the user invoking some special action, but reconversions should
4876
not affect the state of the preedit area.
4877
</para>
4878
</listitem>
4879
<listitem>
4880
<para>
4881
Context-sensitive conversion is required for some languages
4882
and input methods that need to retrieve text that surrounds the
4883
current spot location (cursor position) of the client's buffer.
4884
Such text is needed when the preediting operation depends on
4885
some surrounding characters (usually preceding the spot location).
4886
For example,
4887
in Thai language input, certain character sequences may be invalid and
4888
the input method may want to check whether characters constitute a
4889
valid word. Input methods that do such context-dependent
4890
checking need to retrieve the characters surrounding the current
4891
cursor position to obtain complete words.
4892
<!-- .sp -->
4893
Unlike other conversions, this conversion is not explicitly
4894
requested by the user.
4895
Input methods that provide such context-sensitive conversion
4896
continuously need to request context from the client, and any change
4897
in the context of the spot location may affect such conversions.
4898
The client's context would be needed if the user moves the cursor
4899
and starts editing again.
4900
<!-- .sp -->
4901
For this reason, an input method supporting this type of conversion
4902
should take notice of when the client calls
4903
<function>XmbResetIC</function>
4904
or
4905
<function>XwcResetIC</function>,
4906
which is usually an indication of a context change.
4907
</para>
4908
</listitem>
4909
</itemizedlist>
4910
<para>
4911
<!-- .LP -->
4912
Context-sensitive conversions just need a copy of the client's text,
4913
while other conversions replace the client's text with new text
4914
to achieve the reconversion or transliteration. Yet in all
4915
cases the result of a conversion, either immediately or via preediting,
4916
is returned by the
4917
<function>XmbLookupString</function>
4918
and
4919
<function>XwcLookupString</function>
4920
functions.
4921
</para>
4922
<para>
4923
<!-- .LP -->
4924
String conversion support is dependent on the availability of the
4925
<symbol>XNStringConversion</symbol>
4926
or
4927
<symbol>XNStringConversionCallback</symbol>
4928
<acronym>XIC</acronym> values.
4929
Because the input method may not support string conversions,
4930
clients have to query the availability of string conversion
4931
operations by checking the supported <acronym>XIC</acronym> values list by calling
4932
<function>XGetIMValues</function>
4933
with the
4934
<symbol>XNQueryICValuesList</symbol>
4935
IM value.
4936
</para>
4937
<para>
4938
<!-- .LP -->
4939
The difference between these two values is whether the
4940
conversion is invoked by the client or the input method.
4941
The
4942
<symbol>XNStringConversion</symbol>
4943
<acronym>XIC</acronym> value is used by clients to request
4944
a string conversion from the input method. The client
4945
is responsible for determining which events are used
4946
to trigger the string conversion and whether the string to be
4947
converted should be copied or deleted. The type of conversion
4948
is determined by the input method; the client can only
4949
pass the string to be converted. The client is guaranteed that
4950
no
4951
<symbol>XNStringConversionCallback</symbol>
4952
will be issued when this value is set; thus, the client need
4953
only set one of these values.
4954
</para>
4955
<para>
4956
<!-- .LP -->
4957
The
4958
<symbol>XNStringConversionCallback</symbol>
4959
<acronym>XIC</acronym> value is used by the client to notify the input method that
4960
it will accept requests from the input method for string conversion.
4961
If this value is set,
4962
it is the input method's responsibility to determine which
4963
events are used to trigger the string conversion.
4964
When such events occur, the input method issues a call to the
4965
client-supplied procedure to retrieve the string to be converted. The client's
4966
callback procedure is notified whether to copy or delete the string and
4967
is provided with hints as to the amount of text needed.
4968
The
4969
<structname>XIMStringConversionCallbackStruct</structname>
4970
specifies which text should be passed back to the input method.
4971
</para>
4972
<para>
4973
<!-- .LP -->
4974
Finally, the input method may call the client's
4975
<symbol>XNStringConversionCallback</symbol>
4976
procedure multiple times if the string returned from the callback is
4977
not sufficient to perform a successful conversion. The arguments
4978
to the client's procedure allow the input method to define a
4979
position (in character units) relative to the client's cursor position
4980
and the size of the text needed. By varying the position and size of
4981
the desired text in subsequent callbacks, the input method can retrieve
4982
additional text.
4983
</para>
4984
<para>
4985
<!-- .LP -->
4986
</para>
4987
</sect3>
4988
</sect2>
4989
<sect2 id="Input_Method_Management">
4990
<title>Input Method Management</title>
4991
<!-- .XS -->
4992
<!-- (SN Input Method Management -->
4993
<!-- .XE -->
4994
<para>
4995
<!-- .LP -->
4996
The interface to input methods might appear to be simply creating
4997
an input method
4998
(<function>XOpenIM</function>)
4999
and freeing an input method
5000
(<function>XCloseIM</function>).
5001
However, input methods may
5002
require complex communication with input method servers (IM servers),
5003
for example:
5004
</para>
5005
5006
<itemizedlist>
5007
<listitem>
5008
<para>
5009
If the X server, IM server, and X clients are started asynchronously,
5010
some clients may attempt to connect to the IM server before it is
5011
fully operational, and fail.
5012
Therefore, some mechanism is needed to allow clients to detect when an IM
5013
server has started.
5014
</para>
5015
</listitem>
5016
</itemizedlist>
5017
<para>
5018
<!-- .LP -->
5019
It is up to clients to decide what should be done when an IM server is
5020
not available (for example, wait, or use some other IM server).
5021
</para>
5022
<para>
5023
<!-- .LP -->
5024
</para>
5025
<itemizedlist>
5026
<listitem>
5027
<para>
5028
Some input methods may allow the underlying IM server to be switched.
5029
Such customization may be desired without restarting the entire client.
5030
</para>
5031
</listitem>
5032
</itemizedlist>
5033
<para>
5034
<!-- .LP -->
5035
To support management of input methods in these cases, the following
5036
functions are provided:
5037
</para>
5038
<informaltable>
5039
<tgroup cols='2' align='center'>
5040
<colspec colname='c1'/>
5041
<colspec colname='c2'/>
5042
<tbody>
5043
<row>
5044
<entry><function>XRegisterIMInstantiateCallback</function></entry>
5045
<entry>This function allows clients to register a callback procedure
5046
to be called when Xlib detects that an IM server is up and available.</entry>
5047
</row>
5048
<row>
5049
<entry><function>XOpenIM</function></entry>
5050
<entry>A client calls this function as a result of the callback procedure
5051
being called.</entry>
5052
</row>
5053
<row>
5054
<entry><function>XSetIMValues</function>, <function>XSetICValues</function></entry>
5055
<entry>These functions use the <acronym>XIM</acronym> and <acronym>XIC</acronym> values,
5056
<symbol>XNDestroyCallback</symbol>,
5057
to allow a client
5058
to register a callback procedure to be called when Xlib detects that
5059
an IM server that was associated with an opened
5060
input method is no longer available.
5061
In addition, this function can be used to switch IM servers for those input
5062
methods that support such functionality. The IM value for switching IM
5063
servers is implementation-dependent; see the description below about
5064
switching IM servers.</entry>
5065
</row>
5066
<row>
5067
<entry><function>XUnregisterIMInstantiateCallback</function></entry>
5068
<entry>This function removes a callback procedure registered by the client.</entry>
5069
</row>
5070
</tbody>
5071
</tgroup>
5072
</informaltable>
5073
5074
<para>
5075
<!-- .LP -->
5076
Input methods that support switching of IM servers may exhibit some
5077
side-effects:
5078
</para>
5079
<itemizedlist>
5080
<listitem>
5081
<para>
5082
The input method will ensure that any new IM server supports any of the
5083
input styles being used by input contexts already associated with the
5084
input method.
5085
However, the list of supported input styles may be different.
5086
</para>
5087
</listitem>
5088
</itemizedlist>
5089
<para>
5090
<!-- .LP -->
5091
</para>
5092
<itemizedlist>
5093
<listitem>
5094
<para>
5095
Geometry management requests on previously created input contexts
5096
may be initiated by the new IM server.
5097
</para>
5098
</listitem>
5099
</itemizedlist>
5100
<para>
5101
<!-- .LP -->
5102
</para>
5103
<sect3 id="Hot_Keys">
5104
<title>Hot Keys</title>
5105
<!-- .XS -->
5106
<!-- (SN Hot Keys -->
5107
<!-- .XE -->
5108
<para>
5109
<!-- .LP -->
5110
Some clients need to guarantee which keys can be used to escape from the
5111
input method, regardless of the input method state;
5112
for example, the client-specific Help key or the keys to move the
5113
input focus.
5114
The HotKey mechanism allows clients
5115
to specify a set of keys for this purpose. However, the input
5116
method might not allow clients to specify hot keys.
5117
Therefore, clients have to query support of hot keys by checking the
5118
supported <acronym>XIC</acronym> values list by calling
5119
<function>XGetIMValues</function>
5120
with the
5121
<symbol>XNQueryICValuesList</symbol>
5122
IM value.
5123
When the hot keys specified conflict with the key bindings of the
5124
input method, hot keys take precedence over the key bindings of the input
5125
method.
5126
</para>
5127
<para>
5128
<!-- .LP -->
5129
</para>
5130
</sect3>
5131
<sect3 id="Preedit_State_Operation">
5132
<title>Preedit State Operation</title>
5133
<!-- .XS -->
5134
<!-- (SN Preedit State Operation -->
5135
<!-- .XE -->
5136
<para>
5137
<!-- .LP -->
5138
An input method may have several internal states, depending on its
5139
implementation and the locale. However, one state that is
5140
independent of locale and implementation is whether the input method
5141
is currently performing a preediting operation.
5142
Xlib provides the ability for an application to manage the preedit state
5143
programmatically. Two methods are provided for
5144
retrieving the preedit state of an input context.
5145
One method is to query the state by calling
5146
<function>XGetICValues</function>
5147
with the
5148
<symbol>XNPreeditState</symbol>
5149
<acronym>XIC</acronym> value.
5150
Another method is to receive notification whenever
5151
the preedit state is changed. To receive such notification,
5152
an application needs to register a callback by calling
5153
<function>XSetICValues</function>
5154
with the
5155
<symbol>XNPreeditStateNotifyCallback</symbol>
5156
<acronym>XIC</acronym> value.
5157
In order to change the preedit state programmatically, an application
5158
needs to call
5159
<function>XSetICValues</function>
5160
with
5161
<symbol>XNPreeditState</symbol>.
5162
</para>
5163
<para>
5164
<!-- .LP -->
5165
Availability of the preedit state is input method dependent. The input
5166
method may not provide the ability to set the state or to
5167
retrieve the state programmatically. Therefore, clients have to
5168
query availability of preedit state operations by checking the
5169
supported <acronym>XIC</acronym> values list by calling
5170
<function>XGetIMValues</function>
5171
with the
5172
<symbol>XNQueryICValuesList</symbol>
5173
IM value.
5174
</para>
5175
</sect3>
5176
</sect2>
5177
<sect2 id="Input_Method_Functions">
5178
<title>Input Method Functions</title>
5179
<!-- .XS -->
5180
<!-- (SN Input Method Functions -->
5181
<!-- .XE -->
5182
<para>
5183
<!-- .LP -->
5184
To open a connection, use
5185
<function>XOpenIM</function>.
5186
<indexterm significance="preferred"><primary>XOpenIM</primary></indexterm>
5187
<!-- .sM -->
5188
<funcsynopsis>
5189
<funcprototype>
5190
<funcdef>XIM <function>XOpenIM</function></funcdef>
5191
<paramdef>Display<parameter> *display</parameter></paramdef>
5192
<paramdef>XrmDatabase<parameter> db</parameter></paramdef>
5193
<paramdef>char<parameter> *res_name</parameter></paramdef>
5194
<paramdef>char<parameter> *res_class</parameter></paramdef>
5195
</funcprototype>
5196
</funcsynopsis>
5197
<!-- .FN -->
5198
<variablelist>
5199
<varlistentry>
5200
<term>
5201
<emphasis remap='I'>display</emphasis>
5202
</term>
5203
<listitem>
5204
<para>
5205
Specifies the connection to the X server.
5206
</para>
5207
</listitem>
5208
</varlistentry>
5209
<varlistentry>
5210
<term>
5211
<emphasis remap='I'>db</emphasis>
5212
</term>
5213
<listitem>
5214
<para>
5215
Specifies a pointer to the resource database.
5216
</para>
5217
</listitem>
5218
</varlistentry>
5219
<varlistentry>
5220
<term>
5221
<emphasis remap='I'>res_name</emphasis>
5222
</term>
5223
<listitem>
5224
<para>
5225
Specifies the full resource name of the application.
5226
</para>
5227
</listitem>
5228
</varlistentry>
5229
<varlistentry>
5230
<term>
5231
<emphasis remap='I'>res_class</emphasis>
5232
</term>
5233
<listitem>
5234
<para>
5235
Specifies the full class name of the application.
5236
</para>
5237
</listitem>
5238
</varlistentry>
5239
</variablelist>
5240
</para>
5241
<para>
5242
<!-- .LP -->
5243
<!-- .eM -->
5244
The
5245
<function>XOpenIM</function>
5246
function opens an input method,
5247
matching the current locale and modifiers specification.
5248
Current locale and modifiers are bound to the input method at opening time.
5249
The locale associated with an input method cannot be changed dynamically.
5250
This implies that the strings returned by
5251
<function>XmbLookupString</function>
5252
or
5253
<function>XwcLookupString</function>,
5254
for any input context affiliated with a given input method,
5255
will be encoded in the locale current at the time the input method is opened.
5256
</para>
5257
<para>
5258
<!-- .LP -->
5259
The specific input method to which this call will be routed
5260
is identified on the basis of the current locale.
5261
<function>XOpenIM</function>
5262
will identify a default input method corresponding to the
5263
current locale.
5264
That default can be modified using
5265
<function>XSetLocaleModifiers</function>
5266
for the input method modifier.
5267
</para>
5268
<para>
5269
<!-- .LP -->
5270
The db argument is the resource database to be used by the input method
5271
for looking up resources that are private to the input method.
5272
It is not intended that this database be used to look
5273
up values that can be set as IC values in an input context.
5274
If db is NULL,
5275
no database is passed to the input method.
5276
</para>
5277
<para>
5278
<!-- .LP -->
5279
The res_name and res_class arguments specify the resource name
5280
and class of the application.
5281
They are intended to be used as prefixes by the input method
5282
when looking up resources that are common to all input contexts
5283
that may be created for this input method.
5284
The characters used for resource names and classes must be in the
5285
X Portable Character Set.
5286
The resources looked up are not fully specified
5287
if res_name or res_class is NULL.
5288
</para>
5289
<para>
5290
<!-- .LP -->
5291
The res_name and res_class arguments are not assumed to exist beyond
5292
the call to
5293
<function>XOpenIM</function>.
5294
The specified resource database is assumed to exist for the lifetime
5295
of the input method.
5296
</para>
5297
<para>
5298
<!-- .LP -->
5299
<function>XOpenIM</function>
5300
returns NULL if no input method could be opened.
5301
</para>
5302
<para>
5303
<!-- .LP -->
5304
<!-- .sp -->
5305
To close a connection, use
5306
<function>XCloseIM</function>.
5307
<indexterm significance="preferred"><primary>XCloseIM</primary></indexterm>
5308
<!-- .sM -->
5309
<funcsynopsis>
5310
<funcprototype>
5311
<funcdef>Status <function>XCloseIM</function></funcdef>
5312
<paramdef>XIM<parameter> im</parameter></paramdef>
5313
</funcprototype>
5314
</funcsynopsis>
5315
<!-- .FN -->
5316
<variablelist>
5317
<varlistentry>
5318
<term>
5319
<emphasis remap='I'>im</emphasis>
5320
</term>
5321
<listitem>
5322
<para>
5323
Specifies the input method.
5324
</para>
5325
</listitem>
5326
</varlistentry>
5327
</variablelist>
5328
</para>
5329
<para>
5330
<!-- .LP -->
5331
<!-- .eM -->
5332
The
5333
<function>XCloseIM</function>
5334
function closes the specified input method.
5335
</para>
5336
<para>
5337
<!-- .LP -->
5338
<!-- .sp -->
5339
To set input method attributes, use
5340
<function>XSetIMValues</function>.
5341
<indexterm significance="preferred"><primary>XSetIMValues</primary></indexterm>
5342
<!-- .sM -->
5343
<funcsynopsis>
5344
<funcprototype>
5345
<funcdef>char *<function>XSetIMValues</function></funcdef>
5346
<paramdef>XIM<parameter> im</parameter></paramdef>
5347
</funcprototype>
5348
</funcsynopsis>
5349
<!-- .FN -->
5350
<variablelist>
5351
<varlistentry>
5352
<term>
5353
<emphasis remap='I'>im</emphasis>
5354
</term>
5355
<listitem>
5356
<para>
5357
Specifies the input method.
5358
<!-- .ds Al \ to set <acronym>XIM</acronym> values -->
5359
</para>
5360
</listitem>
5361
</varlistentry>
5362
<varlistentry>
5363
<term>
5364
...
5365
</term>
5366
<listitem>
5367
<para>
5368
Specifies the variable-length argument list(Al.
5369
</para>
5370
</listitem>
5371
</varlistentry>
5372
</variablelist>
5373
</para>
5374
<para>
5375
<!-- .LP -->
5376
<!-- .eM -->
5377
The
5378
<function>XSetIMValues</function>
5379
function presents a variable argument list programming interface
5380
for setting attributes of the specified input method.
5381
It returns NULL if it succeeds;
5382
otherwise,
5383
it returns the name of the first argument that could not be set.
5384
Xlib does not attempt to set arguments from the supplied list that
5385
follow the failed argument;
5386
all arguments in the list preceding the failed argument have been set
5387
correctly.
5388
</para>
5389
<para>
5390
<!-- .LP -->
5391
<!-- .sp -->
5392
To query an input method, use
5393
<function>XGetIMValues</function>.
5394
<indexterm significance="preferred"><primary>XGetIMValues</primary></indexterm>
5395
<!-- .sM -->
5396
<funcsynopsis>
5397
<funcprototype>
5398
<funcdef>char *<function>XGetIMValues</function></funcdef>
5399
<paramdef>XIM<parameter> im</parameter></paramdef>
5400
</funcprototype>
5401
</funcsynopsis>
5402
<!-- .FN -->
5403
<variablelist>
5404
<varlistentry>
5405
<term>
5406
<emphasis remap='I'>im</emphasis>
5407
</term>
5408
<listitem>
5409
<para>
5410
Specifies the input method.
5411
<!-- .ds Al \ to get XIM values -->
5412
</para>
5413
</listitem>
5414
</varlistentry>
5415
<varlistentry>
5416
<term>
5417
...
5418
</term>
5419
<listitem>
5420
<para>
5421
Specifies the variable length argument list(Al.
5422
</para>
5423
</listitem>
5424
</varlistentry>
5425
</variablelist>
5426
</para>
5427
<para>
5428
<!-- .LP -->
5429
<!-- .eM -->
5430
The
5431
<function>XGetIMValues</function>
5432
function presents a variable argument list programming interface
5433
for querying properties or features of the specified input method.
5434
This function returns NULL if it succeeds;
5435
otherwise,
5436
it returns the name of the first argument that could not be obtained.
5437
</para>
5438
<para>
5439
<!-- .LP -->
5440
Each <acronym>XIM</acronym> value argument (following a name) must point to
5441
a location where the <acronym>XIM</acronym> value is to be stored.
5442
That is, if the <acronym>XIM</acronym> value is of type T,
5443
the argument must be of type T*.
5444
If T itself is a pointer type,
5445
then
5446
<function>XGetIMValues</function>
5447
allocates memory to store the actual data,
5448
and the client is responsible for freeing this data by calling
5449
<function>XFree</function>
5450
with the returned pointer.
5451
</para>
5452
<para>
5453
<!-- .LP -->
5454
<!-- .sp -->
5455
To obtain the display associated with an input method, use
5456
<function>XDisplayOfIM</function>.
5457
<indexterm significance="preferred"><primary>XDisplayOfIM</primary></indexterm>
5458
<!-- .sM -->
5459
<funcsynopsis>
5460
<funcprototype>
5461
<funcdef>Display *<function>XDisplayOfIM</function></funcdef>
5462
<paramdef>XIM<parameter> im</parameter></paramdef>
5463
</funcprototype>
5464
</funcsynopsis>
5465
<!-- .FN -->
5466
<variablelist>
5467
<varlistentry>
5468
<term>
5469
<emphasis remap='I'>im</emphasis>
5470
</term>
5471
<listitem>
5472
<para>
5473
Specifies the input method.
5474
</para>
5475
</listitem>
5476
</varlistentry>
5477
</variablelist>
5478
</para>
5479
<para>
5480
<!-- .LP -->
5481
<!-- .eM -->
5482
The
5483
<function>XDisplayOfIM</function>
5484
function returns the display associated with the specified input method.
5485
</para>
5486
<para>
5487
<!-- .LP -->
5488
<!-- .sp -->
5489
To get the locale associated with an input method, use
5490
<function>XLocaleOfIM</function>.
5491
<indexterm significance="preferred"><primary>XLocaleOfIM</primary></indexterm>
5492
<!-- .sM -->
5493
<funcsynopsis>
5494
<funcprototype>
5495
<funcdef>char *<function>XLocaleOfIM</function></funcdef>
5496
<paramdef>XIM<parameter> im</parameter></paramdef>
5497
</funcprototype>
5498
</funcsynopsis>
5499
<!-- .FN -->
5500
<variablelist>
5501
<varlistentry>
5502
<term>
5503
<emphasis remap='I'>im</emphasis>
5504
</term>
5505
<listitem>
5506
<para>
5507
Specifies the input method.
5508
</para>
5509
</listitem>
5510
</varlistentry>
5511
</variablelist>
5512
</para>
5513
<para>
5514
<!-- .LP -->
5515
<!-- .eM -->
5516
The
5517
<function>XLocaleOfIM</function>
5518
function returns the locale associated with the specified input method.
5519
</para>
5520
<para>
5521
<!-- .LP -->
5522
<!-- .sp -->
5523
To register an input method instantiate callback, use
5524
<function>XRegisterIMInstantiateCallback</function>.
5525
<indexterm significance="preferred"><primary>XRegisterIMInstantiateCallback</primary></indexterm>
5526
<!-- .sM -->
5527
<funcsynopsis>
5528
<funcprototype>
5529
<funcdef>Bool <function>XRegisterIMInstantiateCallback</function></funcdef>
5530
<paramdef>Display<parameter> *display</parameter></paramdef>
5531
<paramdef>XrmDatabase<parameter> db</parameter></paramdef>
5532
<paramdef>char<parameter> *res_name</parameter></paramdef>
5533
<paramdef>char<parameter> *res_class</parameter></paramdef>
5534
<paramdef>XIMProc<parameter> callback</parameter></paramdef>
5535
<paramdef>XPointer<parameter> *client_data</parameter></paramdef>
5536
</funcprototype>
5537
</funcsynopsis>
5538
<!-- .FN -->
5539
<variablelist>
5540
<varlistentry>
5541
<term>
5542
<emphasis remap='I'>display</emphasis>
5543
</term>
5544
<listitem>
5545
<para>
5546
Specifies the connection to the X server.
5547
</para>
5548
</listitem>
5549
</varlistentry>
5550
<varlistentry>
5551
<term>
5552
<emphasis remap='I'>db</emphasis>
5553
</term>
5554
<listitem>
5555
<para>
5556
Specifies a pointer to the resource database.
5557
</para>
5558
</listitem>
5559
</varlistentry>
5560
<varlistentry>
5561
<term>
5562
<emphasis remap='I'>res_name</emphasis>
5563
</term>
5564
<listitem>
5565
<para>
5566
Specifies the full resource name of the application.
5567
</para>
5568
</listitem>
5569
</varlistentry>
5570
<varlistentry>
5571
<term>
5572
<emphasis remap='I'>res_class</emphasis>
5573
</term>
5574
<listitem>
5575
<para>
5576
Specifies the full class name of the application.
5577
</para>
5578
</listitem>
5579
</varlistentry>
5580
<varlistentry>
5581
<term>
5582
<emphasis remap='I'>callback</emphasis>
5583
</term>
5584
<listitem>
5585
<para>
5586
Specifies a pointer to the input method instantiate callback.
5587
</para>
5588
</listitem>
5589
</varlistentry>
5590
<varlistentry>
5591
<term>
5592
<emphasis remap='I'>client_data</emphasis>
5593
</term>
5594
<listitem>
5595
<para>
5596
Specifies the additional client data.
5597
</para>
5598
</listitem>
5599
</varlistentry>
5600
</variablelist>
5601
</para>
5602
<para>
5603
<!-- .LP -->
5604
<!-- .eM -->
5605
The
5606
<function>XRegisterIMInstantiateCallback</function>
5607
function registers a callback to be invoked whenever a new input method
5608
becomes available for the specified display that matches the current
5609
locale and modifiers.
5610
</para>
5611
<para>
5612
<!-- .LP -->
5613
The function returns
5614
<symbol>True</symbol>
5615
if it succeeds; otherwise, it returns
5616
<symbol>False</symbol>.
5617
</para>
5618
<para>
5619
<!-- .LP -->
5620
The generic prototype is as follows:
5621
<indexterm significance="preferred"><primary>IMInstantiateCallback</primary></indexterm>
5622
<!-- .sM -->
5623
<funcsynopsis>
5624
<funcprototype>
5625
<funcdef>void <function><replaceable>IMInstantiateCallback</replaceable></function></funcdef>
5626
<paramdef>Display<parameter> *display</parameter></paramdef>
5627
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
5628
<paramdef>XPointer<parameter> call_data</parameter></paramdef>
5629
</funcprototype>
5630
</funcsynopsis>
5631
<!-- .FN -->
5632
<variablelist>
5633
<varlistentry>
5634
<term>
5635
<emphasis remap='I'>display</emphasis>
5636
</term>
5637
<listitem>
5638
<para>
5639
Specifies the connection to the X server.
5640
</para>
5641
</listitem>
5642
</varlistentry>
5643
<varlistentry>
5644
<term>
5645
<emphasis remap='I'>client_data</emphasis>
5646
</term>
5647
<listitem>
5648
<para>
5649
Specifies the additional client data.
5650
</para>
5651
</listitem>
5652
</varlistentry>
5653
<varlistentry>
5654
<term>
5655
<emphasis remap='I'>call_data</emphasis>
5656
</term>
5657
<listitem>
5658
<para>
5659
Not used for this callback and always passed as NULL.
5660
</para>
5661
</listitem>
5662
</varlistentry>
5663
</variablelist>
5664
</para>
5665
<para>
5666
<!-- .LP -->
5667
<!-- .eM -->
5668
To unregister an input method instantiation callback, use
5669
<function>XUnregisterIMInstantiateCallback</function>.
5670
<indexterm significance="preferred"><primary>XUnregisterIMInstantiateCallback</primary></indexterm>
5671
<!-- .sM -->
5672
<funcsynopsis>
5673
<funcprototype>
5674
<funcdef>Bool <function>XUnregisterIMInstantiateCallback</function></funcdef>
5675
<paramdef>Display<parameter> *display</parameter></paramdef>
5676
<paramdef>XrmDatabase<parameter> db</parameter></paramdef>
5677
<paramdef>char<parameter> *res_name</parameter></paramdef>
5678
<paramdef>char<parameter> *res_class</parameter></paramdef>
5679
<paramdef>XIMProc<parameter> callback</parameter></paramdef>
5680
<paramdef>XPointer<parameter> *client_data</parameter></paramdef>
5681
</funcprototype>
5682
</funcsynopsis>
5683
<!-- .FN -->
5684
<variablelist>
5685
<varlistentry>
5686
<term>
5687
<emphasis remap='I'>display</emphasis>
5688
</term>
5689
<listitem>
5690
<para>
5691
Specifies the connection to the X server.
5692
</para>
5693
</listitem>
5694
</varlistentry>
5695
<varlistentry>
5696
<term>
5697
<emphasis remap='I'>db</emphasis>
5698
</term>
5699
<listitem>
5700
<para>
5701
Specifies a pointer to the resource database.
5702
</para>
5703
</listitem>
5704
</varlistentry>
5705
<varlistentry>
5706
<term>
5707
<emphasis remap='I'>res_name</emphasis>
5708
</term>
5709
<listitem>
5710
<para>
5711
Specifies the full resource name of the application.
5712
</para>
5713
</listitem>
5714
</varlistentry>
5715
<varlistentry>
5716
<term>
5717
<emphasis remap='I'>res_class</emphasis>
5718
</term>
5719
<listitem>
5720
<para>
5721
Specifies the full class name of the application.
5722
</para>
5723
</listitem>
5724
</varlistentry>
5725
<varlistentry>
5726
<term>
5727
<emphasis remap='I'>callback</emphasis>
5728
</term>
5729
<listitem>
5730
<para>
5731
Specifies a pointer to the input method instantiate callback.
5732
</para>
5733
</listitem>
5734
</varlistentry>
5735
<varlistentry>
5736
<term>
5737
<emphasis remap='I'>client_data</emphasis>
5738
</term>
5739
<listitem>
5740
<para>
5741
Specifies the additional client data.
5742
</para>
5743
</listitem>
5744
</varlistentry>
5745
</variablelist>
5746
</para>
5747
<para>
5748
<!-- .LP -->
5749
<!-- .eM -->
5750
The
5751
<function>XUnregisterIMInstantiateCallback</function>
5752
function removes an input method instantiation callback previously
5753
registered.
5754
The function returns
5755
<symbol>True</symbol>
5756
if it succeeds; otherwise, it returns
5757
<symbol>False</symbol>.
5758
</para>
5759
</sect2>
5760
<sect2 id="Input_Method_Values">
5761
<title>Input Method Values</title>
5762
<!-- .XS -->
5763
<!-- (SN Input Method Values -->
5764
<!-- .XE -->
5765
<para>
5766
<!-- .LP -->
5767
The following table describes how <acronym>XIM</acronym> values are interpreted
5768
by an input method.
5769
The first column lists the <acronym>XIM</acronym> values.
5770
The second column indicates how each of the <acronym>XIM</acronym> values
5771
are treated by that input style.
5772
</para>
5773
<para>
5774
<!-- .LP -->
5775
</para>
5776
<para>
5777
<!-- .LP -->
5778
The following keys apply to this table.
5779
</para>
5780
<informaltable>
5781
<tgroup cols='2' align='center'>
5782
<colspec colname='c1'/>
5783
<colspec colname='c2'/>
5784
<thead>
5785
<row>
5786
<entry>Key</entry>
5787
<entry>Explanation</entry>
5788
</row>
5789
</thead>
5790
<tbody>
5791
<row>
5792
<entry>D</entry>
5793
<entry>This value may be set using
5794
<function>XSetIMValues</function>.
5795
If it is not set,
5796
a default is provided.</entry>
5797
</row>
5798
<row>
5799
<entry>S</entry>
5800
<entry>This value may be set using <function>XSetIMValues</function>.</entry>
5801
</row>
5802
<row>
5803
<entry>G</entry>
5804
<entry>This value may be read using <function>XGetIMValues</function>.</entry>
5805
</row>
5806
</tbody>
5807
</tgroup>
5808
</informaltable>
5809
5810
<!-- .LP -->
5811
<informaltable>
5812
<tgroup cols='2' align='center'>
5813
<colspec colname='c1'/>
5814
<colspec colname='c2'/>
5815
<thead>
5816
<row>
5817
<entry><acronym>XIM</acronym> Value</entry>
5818
<entry>Key</entry>
5819
</row>
5820
</thead>
5821
<tbody>
5822
<row>
5823
<entry><symbol>XNQueryInputStyle</symbol></entry>
5824
<entry>G</entry>
5825
</row>
5826
<row>
5827
<entry><symbol>XNResourceName</symbol></entry>
5828
<entry>D-S-G</entry>
5829
</row>
5830
<row>
5831
<entry><symbol>XNResourceClass</symbol></entry>
5832
<entry>D-S-G</entry>
5833
</row>
5834
<row>
5835
<entry><symbol>XNDestroyCallback</symbol></entry>
5836
<entry>D-S-G</entry>
5837
</row>
5838
<row>
5839
<entry><symbol>XNQueryIMValuesList</symbol></entry>
5840
<entry>G</entry>
5841
</row>
5842
<row>
5843
<entry><symbol>XNQueryICValuesList</symbol></entry>
5844
<entry>G</entry>
5845
</row>
5846
<row>
5847
<entry><symbol>XNVisiblePosition</symbol></entry>
5848
<entry>G</entry>
5849
</row>
5850
<row>
5851
<entry><symbol>XNR6PreeditCallback</symbol></entry>
5852
<entry>D-S-G</entry>
5853
</row>
5854
</tbody>
5855
</tgroup>
5856
</informaltable>
5857
5858
<para>
5859
<!-- .LP -->
5860
<symbol>XNR6PreeditCallback</symbol>
5861
is obsolete and its use is not recommended (see section 13.5.4.6).
5862
</para>
5863
5864
<sect3 id="Query_Input_Style">
5865
<title>Query Input Style</title>
5866
<!-- .XS -->
5867
<!-- (SN Query Input Style -->
5868
<!-- .XE -->
5869
<para>
5870
<!-- .LP -->
5871
A client should always query the input method to determine which input
5872
styles are supported.
5873
The client should then find an input style it is capable of supporting.
5874
</para>
5875
<para>
5876
<!-- .LP -->
5877
If the client cannot find an input style that it can support,
5878
it should negotiate with the user the continuation of the program
5879
(exit, choose another input method, and so on).
5880
</para>
5881
<para>
5882
<!-- .LP -->
5883
The argument value must be a pointer to a location
5884
where the returned value will be stored.
5885
The returned value is a pointer to a structure of type
5886
<structname>XIMStyles</structname>.
5887
Clients are responsible for freeing the
5888
<structname>XIMStyles</structname>
5889
structure.
5890
To do so, use
5891
<function>XFree</function>.
5892
</para>
5893
<para>
5894
<!-- .LP -->
5895
The
5896
<structname>XIMStyles</structname>
5897
structure is defined as follows:
5898
</para>
5899
5900
<!-- .LP -->
5901
<indexterm significance="preferred"><primary>XIMStyle</primary></indexterm>
5902
<indexterm significance="preferred"><primary>XIMPreeditArea</primary></indexterm>
5903
<indexterm significance="preferred"><primary>XIMPreeditCallbacks</primary></indexterm>
5904
<indexterm significance="preferred"><primary>XIMPreeditPosition</primary></indexterm>
5905
<indexterm significance="preferred"><primary>XIMPreeditNothing</primary></indexterm>
5906
<indexterm significance="preferred"><primary>XIMPreeditNone</primary></indexterm>
5907
<indexterm significance="preferred"><primary>XIMStatusArea</primary></indexterm>
5908
<indexterm significance="preferred"><primary>XIMStatusCallbacks</primary></indexterm>
5909
<indexterm significance="preferred"><primary>XIMStatusNothing</primary></indexterm>
5910
<indexterm significance="preferred"><primary>XIMStatusNone</primary></indexterm>
5911
<indexterm significance="preferred"><primary>XIMStyles</primary></indexterm>
5912
<!-- .sM -->
5913
<literallayout class="monospaced">
5914
typedef unsigned long XIMStyle;
5915
5916
5917
#define XIMPreeditArea 0x0001L
5918
#define XIMPreeditCallbacks 0x0002L
5919
#define XIMPreeditPosition 0x0004L
5920
#define XIMPreeditNothing 0x0008L
5921
#define XIMPreeditNone 0x0010L
5922
5923
#define XIMStatusArea 0x0100L
5924
#define XIMStatusCallbacks 0x0200L
5925
#define XIMStatusNothing 0x0400L
5926
#define XIMStatusNone 0x0800L
5927
5928
typedef struct {
5929
unsigned short count_styles;
5930
XIMStyle * supported_styles;
5931
} XIMStyles;
5932
5933
</literallayout>
5934
5935
5936
<para>
5937
<!-- .LP -->
5938
<!-- .eM -->
5939
An
5940
<structname>XIMStyles</structname>
5941
structure contains the number of input styles supported
5942
in its count_styles field.
5943
This is also the size of the supported_styles array.
5944
</para>
5945
<para>
5946
<!-- .LP -->
5947
The supported styles is a list of bitmask combinations,
5948
which indicate the combination of styles for each of the areas supported.
5949
These areas are described later.
5950
Each element in the list should select one of the bitmask values for
5951
each area.
5952
The list describes the complete set of combinations supported.
5953
Only these combinations are supported by the input method.
5954
</para>
5955
<para>
5956
<!-- .LP -->
5957
The preedit category defines what type of support is provided
5958
by the input method for preedit information.
5959
</para>
5960
<indexterm significance="preferred"><primary>XIMPreeditArea</primary></indexterm>
5961
<indexterm significance="preferred"><primary>XIMPreeditPosition</primary></indexterm>
5962
<indexterm significance="preferred"><primary>XIMPreeditCallbacks</primary></indexterm>
5963
<indexterm significance="preferred"><primary>XIMPreeditNothing</primary></indexterm>
5964
<indexterm significance="preferred"><primary>XIMPreeditNone</primary></indexterm>
5965
<informaltable>
5966
<tgroup cols='2' align='center'>
5967
<colspec colname='c1'/>
5968
<colspec colname='c2'/>
5969
<tbody>
5970
<row>
5971
<entry><symbol>XIMPreeditArea</symbol></entry>
5972
<entry>If chosen,
5973
the input method would require the client to provide some area values
5974
for it to do its preediting.
5975
Refer to <acronym>XIC</acronym> values
5976
<symbol>XNArea</symbol>
5977
and
5978
<symbol>XNAreaNeeded</symbol>.</entry>
5979
</row>
5980
<row>
5981
<entry><symbol>XIMPreeditPosition</symbol></entry>
5982
<entry>If chosen,
5983
the input method would require the client to provide positional values.
5984
Refer to <acronym>XIC</acronym> values
5985
<symbol>XNSpotLocation</symbol>
5986
and
5987
<symbol>XNFocusWindow</symbol>.</entry>
5988
</row>
5989
<row>
5990
<entry><symbol>XIMPreeditCallbacks</symbol></entry>
5991
<entry>If chosen,
5992
the input method would require the client to define the set of preedit callbacks.
5993
Refer to <acronym>XIC</acronym> values
5994
<symbol>XNPreeditStartCallback</symbol>,
5995
<symbol>XNPreeditDoneCallback</symbol>,
5996
<symbol>XNPreeditDrawCallback</symbol>,
5997
and
5998
<symbol>XNPreeditCaretCallback</symbol>.</entry>
5999
</row>
6000
<row>
6001
<entry><symbol>XIMPreeditNothing</symbol></entry>
6002
<entry>If chosen, the input method can function without any preedit values.</entry>
6003
</row>
6004
<row>
6005
<entry><symbol>XIMPreeditNone</symbol></entry>
6006
<entry>The input method does not provide any preedit feedback.
6007
Any preedit value is ignored.
6008
This style is mutually exclusive with the other preedit styles.</entry>
6009
</row>
6010
</tbody>
6011
</tgroup>
6012
</informaltable>
6013
6014
<para>
6015
<!-- .LP -->
6016
The status category defines what type of support is provided
6017
by the input method for status information.
6018
</para>
6019
<indexterm significance="preferred"><primary>XIMStatusArea</primary></indexterm>
6020
<indexterm significance="preferred"><primary>XIMStatusCallbacks</primary></indexterm>
6021
<indexterm significance="preferred"><primary>XIMStatusNothing</primary></indexterm>
6022
<indexterm significance="preferred"><primary>XIMStatusNone</primary></indexterm>
6023
<informaltable>
6024
<tgroup cols='2' align='center'>
6025
<colspec colname='c1'/>
6026
<colspec colname='c2'/>
6027
<tbody>
6028
<row>
6029
<entry><symbol>XIMStatusArea</symbol></entry>
6030
<entry>The input method requires the client to provide
6031
some area values for it to do its status feedback.
6032
See
6033
<symbol>XNArea</symbol>
6034
and
6035
<symbol>XNAreaNeeded</symbol>.</entry>
6036
</row>
6037
<row>
6038
<entry><symbol>XIMStatusCallbacks</symbol></entry>
6039
<entry>The input method requires the client to define the set of status callbacks,
6040
<symbol>XNStatusStartCallback</symbol>,
6041
<symbol>XNStatusDoneCallback</symbol>,
6042
and
6043
<symbol>XNStatusDrawCallback</symbol>.</entry>
6044
</row>
6045
<row>
6046
<entry><symbol>XIMStatusNothing</symbol></entry>
6047
<entry>The input method can function without any status values.</entry>
6048
</row>
6049
<row>
6050
<entry><symbol>XIMStatusNone</symbol></entry>
6051
<entry>The input method does not provide any status feedback.
6052
If chosen, any status value is ignored.
6053
This style is mutually exclusive with the other status styles.</entry>
6054
</row>
6055
</tbody>
6056
</tgroup>
6057
</informaltable>
6058
6059
</sect3>
6060
<sect3 id="Resource_Name_and_Class_c">
6061
<title>Resource Name and Class</title>
6062
<!-- .XS -->
6063
<!-- (SN Resource Name and Class -->
6064
<!-- .XE -->
6065
<para>
6066
<!-- .LP -->
6067
The
6068
<symbol>XNResourceName</symbol>
6069
and
6070
<symbol>XNResourceClass</symbol>
6071
arguments are strings that specify the full name and class
6072
used by the input method.
6073
These values should be used as prefixes for the name and class
6074
when looking up resources that may vary according to the input method.
6075
If these values are not set,
6076
the resources will not be fully specified.
6077
</para>
6078
<para>
6079
<!-- .LP -->
6080
It is not intended that values that can be set as <acronym>XIM</acronym> values be
6081
set as resources.
6082
</para>
6083
<para>
6084
<!-- .LP -->
6085
</para>
6086
</sect3>
6087
<sect3 id="Destroy_Callback">
6088
<title>Destroy Callback</title>
6089
<!-- .XS -->
6090
<!-- (SN Destroy Callback -->
6091
<!-- .XE -->
6092
<para>
6093
<!-- .LP -->
6094
The
6095
<symbol>XNDestroyCallback</symbol>
6096
argument is a pointer to a structure of type
6097
<structname>XIMCallback</structname>.
6098
<symbol>XNDestroyCallback</symbol>
6099
is triggered when an input method stops its service for any reason.
6100
After the callback is invoked, the input method is closed and the
6101
associated input context(s) are destroyed by Xlib.
6102
Therefore, the client should not call
6103
<function>XCloseIM</function>
6104
or
6105
<function>XDestroyIC</function>.
6106
</para>
6107
<para>
6108
<!-- .LP -->
6109
The generic prototype of this callback function is as follows:
6110
<indexterm significance="preferred"><primary>DestroyCallback</primary></indexterm>
6111
<!-- .sM -->
6112
<funcsynopsis>
6113
<funcprototype>
6114
<funcdef>void <function><replaceable>DestroyCallback</replaceable></function></funcdef>
6115
<paramdef>XIM<parameter> im</parameter></paramdef>
6116
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
6117
<paramdef>XPointer<parameter> call_data</parameter></paramdef>
6118
</funcprototype>
6119
</funcsynopsis>
6120
<!-- .FN -->
6121
<variablelist>
6122
<varlistentry>
6123
<term>
6124
<emphasis remap='I'>im</emphasis>
6125
</term>
6126
<listitem>
6127
<para>
6128
Specifies the input method.
6129
</para>
6130
</listitem>
6131
</varlistentry>
6132
<varlistentry>
6133
<term>
6134
<emphasis remap='I'>client_data</emphasis>
6135
</term>
6136
<listitem>
6137
<para>
6138
Specifies the additional client data.
6139
</para>
6140
</listitem>
6141
</varlistentry>
6142
<varlistentry>
6143
<term>
6144
<emphasis remap='I'>call_data</emphasis>
6145
</term>
6146
<listitem>
6147
<para>
6148
Not used for this callback and always passed as NULL.
6149
</para>
6150
</listitem>
6151
</varlistentry>
6152
</variablelist>
6153
</para>
6154
<para>
6155
<!-- .LP -->
6156
<!-- .eM -->
6157
A DestroyCallback is always called with a NULL call_data argument.
6158
</para>
6159
<para>
6160
<!-- .LP -->
6161
</para>
6162
</sect3>
6163
<sect3 id="Query_IM_IC_Values_List">
6164
<title>Query IM/IC Values List</title>
6165
<!-- .XS -->
6166
<!-- (SN Query IM/IC Values List -->
6167
<!-- .XE -->
6168
<para>
6169
<!-- .LP -->
6170
<symbol>XNQueryIMValuesList</symbol>
6171
and
6172
<symbol>XNQueryICValuesList</symbol>
6173
are used to query about <acronym>XIM</acronym> and <acronym>XIC</acronym> values supported by the input method.
6174
</para>
6175
<para>
6176
<!-- .LP -->
6177
The argument value must be a pointer to a location where the returned
6178
value will be stored. The returned value is a pointer to a structure
6179
of type
6180
<structname>XIMValuesList</structname>.
6181
Clients are responsible for freeing the
6182
<structname>XIMValuesList</structname>
6183
structure.
6184
To do so, use
6185
<function>XFree</function>.
6186
</para>
6187
<para>
6188
<!-- .LP -->
6189
The
6190
<structname>XIMValuesList</structname>
6191
structure is defined as follows:
6192
<!-- .sM -->
6193
<literallayout class="monospaced">
6194
<!-- .TA .5i 2.5i -->
6195
<!-- .ta .5i 2.5i -->
6196
typedef struct {
6197
unsigned short count_values;
6198
char **supported_values;
6199
} XIMValuesList;
6200
</literallayout>
6201
</para>
6202
<para>
6203
<!-- .LP -->
6204
<!-- .eM -->
6205
</para>
6206
</sect3>
6207
<sect3 id="Visible_Position">
6208
<title>Visible Position</title>
6209
<!-- .XS -->
6210
<!-- (SN Visible Position -->
6211
<!-- .XE -->
6212
<para>
6213
<!-- .LP -->
6214
The
6215
<symbol>XNVisiblePosition</symbol>
6216
argument indicates whether the visible position masks of
6217
<type>XIMFeedback</type>
6218
in
6219
<structname>XIMText</structname>
6220
are available.
6221
</para>
6222
<para>
6223
<!-- .LP -->
6224
The argument value must be a pointer to a location where the returned
6225
value will be stored. The returned value is of type
6226
<type>Bool</type>.
6227
If the returned value is
6228
<symbol>True</symbol>,
6229
the input method uses the visible position masks of
6230
<type>XIMFeedback</type>
6231
in
6232
<structname>XIMText</structname>;
6233
otherwise, the input method does not use the masks.
6234
</para>
6235
<para>
6236
<!-- .LP -->
6237
Because this <acronym>XIM</acronym> value is optional, a client should call
6238
<function>XGetIMValues</function>
6239
with argument
6240
<symbol>XNQueryIMValuesList</symbol>
6241
before using this argument.
6242
If the
6243
<symbol>XNVisiblePosition</symbol>
6244
does not exist in the IM values list returned from
6245
<symbol>XNQueryIMValuesList</symbol>,
6246
the visible position masks of
6247
<type>XIMFeedback</type>
6248
in
6249
<structname>XIMText</structname>
6250
are not used to indicate the visible position.
6251
</para>
6252
<para>
6253
<!-- .LP -->
6254
</para>
6255
</sect3>
6256
<sect3 id="Preedit_Callback_Behavior">
6257
<title>Preedit Callback Behavior</title>
6258
<!-- .XS -->
6259
<!-- (SN Preedit Callback Behavior -->
6260
<!-- .XE -->
6261
<para>
6262
<!-- .LP -->
6263
The
6264
<symbol>XNR6PreeditCallback</symbol>
6265
argument originally included in the X11R6 specification has been
6266
deprecated.\(dg
6267
<!-- .\" If XNR6PreeditCallbackBehavior is not deprecated, then its type -->
6268
<!-- .\" should be changed from *Bool to Bool. -->
6269
<!-- .FS \(dg -->
6270
During formulation of the X11R6 specification, the behavior of
6271
the R6 PreeditDrawCallbacks was going to differ significantly from
6272
that of the R5 callbacks.
6273
Late changes to the specification converged the R5 and R6 behaviors,
6274
eliminating the need for
6275
<symbol>XNR6PreeditCallback</symbol>.
6276
Unfortunately, this argument was not removed from the R6 specification
6277
before it was published.
6278
<!-- .FE -->
6279
</para>
6280
<para>
6281
<!-- .LP -->
6282
The
6283
<symbol>XNR6PreeditCallback</symbol>
6284
argument indicates whether the behavior of preedit callbacks regarding
6285
<structname>XIMPreeditDrawCallbackStruct</structname>
6286
values follows Release 5 or Release 6 semantics.
6287
</para>
6288
<para>
6289
<!-- .LP -->
6290
The value is of type
6291
<type>Bool</type>.
6292
When querying for
6293
<symbol>XNR6PreeditCallback</symbol>,
6294
if the returned value is
6295
<symbol>True</symbol>,
6296
the input method uses the Release 6 behavior;
6297
otherwise, it uses the Release 5 behavior.
6298
The default value is
6299
<symbol>False</symbol>.
6300
In order to use Release 6 semantics, the value of
6301
<symbol>XNR6PreeditCallback</symbol>
6302
must be set to
6303
<symbol>True</symbol>.
6304
</para>
6305
<para>
6306
<!-- .LP -->
6307
Because this <acronym>XIM</acronym> value is optional, a client should call
6308
<function>XGetIMValues</function>
6309
with argument
6310
<symbol>XNQueryIMValuesList</symbol>
6311
before using this argument.
6312
If the
6313
<symbol>XNR6PreeditCallback</symbol>
6314
does not exist in the IM values list returned from
6315
<symbol>XNQueryIMValuesList</symbol>,
6316
the PreeditCallback behavior is Release 5 semantics.
6317
</para>
6318
<para>
6319
<!-- .LP -->
6320
</para>
6321
</sect3>
6322
</sect2>
6323
<sect2 id="Input_Context_Functions">
6324
<title>Input Context Functions</title>
6325
<!-- .XS -->
6326
<!-- (SN Input Context Functions -->
6327
<!-- .XE -->
6328
<para>
6329
<!-- .LP -->
6330
An input context is an abstraction that is used to contain both the data
6331
required (if any) by an input method and the information required
6332
to display that data.
6333
There may be multiple input contexts for one input method.
6334
The programming interfaces for creating, reading, or modifying
6335
an input context use a variable argument list.
6336
The name elements of the argument lists are referred to as <acronym>XIC</acronym> values.
6337
It is intended that input methods be controlled by these <acronym>XIC</acronym> values.
6338
As new <acronym>XIC</acronym> values are created,
6339
they should be registered with the X Consortium.
6340
</para>
6341
<para>
6342
<!-- .LP -->
6343
<!-- .sp -->
6344
To create an input context, use
6345
<function>XCreateIC</function>.
6346
<indexterm significance="preferred"><primary>XCreateIC</primary></indexterm>
6347
<!-- .sM -->
6348
<funcsynopsis>
6349
<funcprototype>
6350
<funcdef>XIC <function>XCreateIC</function></funcdef>
6351
<paramdef>XIM<parameter> im</parameter></paramdef>
6352
</funcprototype>
6353
</funcsynopsis>
6354
<!-- .FN -->
6355
<variablelist>
6356
<varlistentry>
6357
<term>
6358
<emphasis remap='I'>im</emphasis>
6359
</term>
6360
<listitem>
6361
<para>
6362
Specifies the input method.
6363
<!-- .ds Al \ to set <acronym>XIC</acronym> values -->
6364
</para>
6365
</listitem>
6366
</varlistentry>
6367
<varlistentry>
6368
<term>
6369
...
6370
</term>
6371
<listitem>
6372
<para>
6373
Specifies the variable length argument list(Al.
6374
</para>
6375
</listitem>
6376
</varlistentry>
6377
</variablelist>
6378
</para>
6379
<para>
6380
<!-- .LP -->
6381
<!-- .eM -->
6382
The
6383
<function>XCreateIC</function>
6384
function creates a context within the specified input method.
6385
</para>
6386
<para>
6387
<!-- .LP -->
6388
Some of the arguments are mandatory at creation time, and
6389
the input context will not be created if those arguments are not provided.
6390
The mandatory arguments are the input style and the set of text callbacks
6391
(if the input style selected requires callbacks).
6392
All other input context values can be set later.
6393
</para>
6394
<para>
6395
<!-- .LP -->
6396
<function>XCreateIC</function>
6397
returns a NULL value if no input context could be created.
6398
A NULL value could be returned for any of the following reasons:
6399
</para>
6400
<itemizedlist>
6401
<listitem>
6402
<para>
6403
A required argument was not set.
6404
</para>
6405
</listitem>
6406
<listitem>
6407
<para>
6408
A read-only argument was set (for example,
6409
<symbol>XNFilterEvents</symbol>).
6410
</para>
6411
</listitem>
6412
<listitem>
6413
<para>
6414
The argument name is not recognized.
6415
</para>
6416
</listitem>
6417
<listitem>
6418
<para>
6419
The input method encountered an input method implementation-dependent error.
6420
</para>
6421
</listitem>
6422
</itemizedlist>
6423
<para>
6424
<!-- .LP -->
6425
<function>XCreateIC</function>
6426
can generate
6427
<errorname>BadAtom</errorname>,
6428
<errorname>BadColor</errorname>,
6429
<errorname>BadPixmap</errorname>,
6430
and
6431
<errorname>BadWindow</errorname>
6432
errors.
6433
</para>
6434
<para>
6435
<!-- .LP -->
6436
<!-- .sp -->
6437
To destroy an input context, use
6438
<function>XDestroyIC</function>.
6439
<indexterm significance="preferred"><primary>XDestroyIC</primary></indexterm>
6440
<!-- .sM -->
6441
<funcsynopsis>
6442
<funcprototype>
6443
<funcdef>void <function>XDestroyIC</function></funcdef>
6444
<paramdef>XIC<parameter> ic</parameter></paramdef>
6445
</funcprototype>
6446
</funcsynopsis>
6447
<!-- .FN -->
6448
<variablelist>
6449
<varlistentry>
6450
<term>
6451
<emphasis remap='I'>ic</emphasis>
6452
</term>
6453
<listitem>
6454
<para>
6455
Specifies the input context.
6456
</para>
6457
</listitem>
6458
</varlistentry>
6459
</variablelist>
6460
</para>
6461
<para>
6462
<!-- .LP -->
6463
<!-- .eM -->
6464
<function>XDestroyIC</function>
6465
destroys the specified input context.
6466
</para>
6467
<para>
6468
<!-- .LP -->
6469
<!-- .sp -->
6470
To communicate to and synchronize with input method
6471
for any changes in keyboard focus from the client side,
6472
use
6473
<function>XSetICFocus</function>
6474
and
6475
<function>XUnsetICFocus</function>.
6476
<indexterm significance="preferred"><primary>XSetICFocus</primary></indexterm>
6477
<!-- .sM -->
6478
<funcsynopsis>
6479
<funcprototype>
6480
<funcdef>void <function>XSetICFocus</function></funcdef>
6481
<paramdef>XIC<parameter> ic</parameter></paramdef>
6482
</funcprototype>
6483
</funcsynopsis>
6484
<!-- .FN -->
6485
<variablelist>
6486
<varlistentry>
6487
<term>
6488
<emphasis remap='I'>ic</emphasis>
6489
</term>
6490
<listitem>
6491
<para>
6492
Specifies the input context.
6493
</para>
6494
</listitem>
6495
</varlistentry>
6496
</variablelist>
6497
</para>
6498
<para>
6499
<!-- .LP -->
6500
<!-- .eM -->
6501
The
6502
<function>XSetICFocus</function>
6503
function allows a client to notify an input method that the focus window
6504
attached to the specified input context has received keyboard focus.
6505
The input method should take action to provide appropriate feedback.
6506
Complete feedback specification is a matter of user interface policy.
6507
</para>
6508
<para>
6509
<!-- .LP -->
6510
Calling
6511
<function>XSetICFocus</function>
6512
does not affect the focus window value.
6513
</para>
6514
<para>
6515
<!-- .LP -->
6516
<!-- .sp -->
6517
<indexterm significance="preferred"><primary>XUnsetICFocus</primary></indexterm>
6518
<!-- .sM -->
6519
<funcsynopsis>
6520
<funcprototype>
6521
<funcdef>void <function>XUnsetICFocus</function></funcdef>
6522
<paramdef>XIC<parameter> ic</parameter></paramdef>
6523
</funcprototype>
6524
</funcsynopsis>
6525
<!-- .FN -->
6526
<variablelist>
6527
<varlistentry>
6528
<term>
6529
<emphasis remap='I'>ic</emphasis>
6530
</term>
6531
<listitem>
6532
<para>
6533
Specifies the input context.
6534
</para>
6535
</listitem>
6536
</varlistentry>
6537
</variablelist>
6538
</para>
6539
<para>
6540
<!-- .LP -->
6541
<!-- .eM -->
6542
The
6543
<function>XUnsetICFocus</function>
6544
function allows a client to notify an input method that the specified input context
6545
has lost the keyboard focus and that no more input is expected on the focus window
6546
attached to that input context.
6547
The input method should take action to provide appropriate feedback.
6548
Complete feedback specification is a matter of user interface policy.
6549
</para>
6550
<para>
6551
<!-- .LP -->
6552
Calling
6553
<function>XUnsetICFocus</function>
6554
does not affect the focus window value;
6555
the client may still receive
6556
events from the input method that are directed to the focus window.
6557
</para>
6558
<para>
6559
<!-- .LP -->
6560
<!-- .sp -->
6561
To reset the state of an input context to its initial state, use
6562
<function>XmbResetIC</function>
6563
or
6564
<function>XwcResetIC</function>.
6565
<indexterm significance="preferred"><primary>XmbResetIC</primary></indexterm>
6566
<indexterm significance="preferred"><primary>XwcResetIC</primary></indexterm>
6567
<!-- .sM -->
6568
<funcsynopsis>
6569
<funcprototype>
6570
<funcdef>char *<function>XmbResetIC</function></funcdef>
6571
<paramdef>XIC<parameter> ic</parameter></paramdef>
6572
</funcprototype>
6573
</funcsynopsis>
6574
<!-- .FN -->
6575
<funcsynopsis>
6576
<funcprototype>
6577
<funcdef>wchar_t *<function>XwcResetIC</function></funcdef>
6578
<paramdef>XIC<parameter> ic</parameter></paramdef>
6579
</funcprototype>
6580
</funcsynopsis>
6581
<!-- .FN -->
6582
<variablelist>
6583
<varlistentry>
6584
<term>
6585
<emphasis remap='I'>ic</emphasis>
6586
</term>
6587
<listitem>
6588
<para>
6589
Specifies the input context.
6590
</para>
6591
</listitem>
6592
</varlistentry>
6593
</variablelist>
6594
</para>
6595
<para>
6596
<!-- .LP -->
6597
<!-- .eM -->
6598
When
6599
<symbol>XNResetState</symbol>
6600
is set to
6601
<symbol>XIMInitialState</symbol>,
6602
<function>XmbResetIC</function>
6603
and
6604
<function>XwcResetIC</function>
6605
reset an input context to its initial state;
6606
when
6607
<symbol>XNResetState</symbol>
6608
is set to
6609
<symbol>XIMPreserveState</symbol>,
6610
the current input context state is preserved.
6611
In both cases, any input pending on that context is deleted.
6612
The input method is required to clear the preedit area, if any,
6613
and update the status accordingly.
6614
Calling
6615
<function>XmbResetIC</function>
6616
or
6617
<function>XwcResetIC</function>
6618
does not change the focus.
6619
</para>
6620
<para>
6621
<!-- .LP -->
6622
The return value of
6623
<function>XmbResetIC</function>
6624
is its current preedit string as a multibyte string.
6625
If there is any preedit text drawn or visible to the user,
6626
then these procedures must return a non-NULL string.
6627
If there is no visible preedit text,
6628
then it is input method implementation-dependent
6629
whether these procedures return a non-NULL string or NULL.
6630
</para>
6631
<para>
6632
<!-- .LP -->
6633
The client should free the returned string by calling
6634
<function>XFree</function>.
6635
</para>
6636
<para>
6637
<!-- .LP -->
6638
<!-- .sp -->
6639
To get the input method associated with an input context, use
6640
<function>XIMOfIC</function>.
6641
<indexterm significance="preferred"><primary>XIMOfIC</primary></indexterm>
6642
<!-- .sM -->
6643
<funcsynopsis>
6644
<funcprototype>
6645
<funcdef>XIM <function>XIMOfIC</function></funcdef>
6646
<paramdef>XIC<parameter> ic</parameter></paramdef>
6647
</funcprototype>
6648
</funcsynopsis>
6649
<!-- .FN -->
6650
<variablelist>
6651
<varlistentry>
6652
<term>
6653
<emphasis remap='I'>ic</emphasis>
6654
</term>
6655
<listitem>
6656
<para>
6657
Specifies the input context.
6658
</para>
6659
</listitem>
6660
</varlistentry>
6661
</variablelist>
6662
</para>
6663
<para>
6664
<!-- .LP -->
6665
<!-- .eM -->
6666
The
6667
<function>XIMOfIC</function>
6668
function returns the input method associated with the specified input context.
6669
</para>
6670
<para>
6671
<!-- .LP -->
6672
<!-- .sp -->
6673
Xlib provides two functions for setting and reading <acronym>XIC</acronym> values, respectively,
6674
<function>XSetICValues</function>
6675
and
6676
<function>XGetICValues</function>.
6677
Both functions have a variable-length argument list.
6678
In that argument list, any <acronym>XIC</acronym> value's name must be denoted
6679
with a character string using the X Portable Character Set.
6680
</para>
6681
<para>
6682
<!-- .LP -->
6683
<!-- .sp -->
6684
To set <acronym>XIC</acronym> values, use
6685
<function>XSetICValues</function>.
6686
<indexterm significance="preferred"><primary>XSetICValues</primary></indexterm>
6687
<!-- .sM -->
6688
<funcsynopsis>
6689
<funcprototype>
6690
<funcdef>char *<function>XSetICValues</function></funcdef>
6691
<paramdef>XIC<parameter> ic</parameter></paramdef>
6692
</funcprototype>
6693
</funcsynopsis>
6694
<!-- .FN -->
6695
<variablelist>
6696
<varlistentry>
6697
<term>
6698
<emphasis remap='I'>ic</emphasis>
6699
</term>
6700
<listitem>
6701
<para>
6702
Specifies the input context.
6703
<!-- .ds Al \ to set <acronym>XIC</acronym> values -->
6704
</para>
6705
</listitem>
6706
</varlistentry>
6707
<varlistentry>
6708
<term>
6709
...
6710
</term>
6711
<listitem>
6712
<para>
6713
Specifies the variable length argument list(Al.
6714
</para>
6715
</listitem>
6716
</varlistentry>
6717
</variablelist>
6718
</para>
6719
<para>
6720
<!-- .LP -->
6721
<!-- .eM -->
6722
The
6723
<function>XSetICValues</function>
6724
function returns NULL if no error occurred;
6725
otherwise,
6726
it returns the name of the first argument that could not be set.
6727
An argument might not be set for any of the following reasons:
6728
</para>
6729
<itemizedlist>
6730
<listitem>
6731
<para>
6732
The argument is read-only (for example,
6733
<symbol>XNFilterEvents</symbol>).
6734
</para>
6735
</listitem>
6736
<listitem>
6737
<para>
6738
The argument name is not recognized.
6739
</para>
6740
</listitem>
6741
<listitem>
6742
<para>
6743
An implementation-dependent error occurs.
6744
</para>
6745
</listitem>
6746
</itemizedlist>
6747
<para>
6748
<!-- .LP -->
6749
Each value to be set must be an appropriate datum,
6750
matching the data type imposed by the semantics of the argument.
6751
</para>
6752
<para>
6753
<!-- .LP -->
6754
<function>XSetICValues</function>
6755
can generate
6756
<errorname>BadAtom</errorname>,
6757
<errorname>BadColor</errorname>,
6758
<errorname>BadCursor</errorname>,
6759
<errorname>BadPixmap</errorname>,
6760
and
6761
<errorname>BadWindow</errorname>
6762
errors.
6763
</para>
6764
<para>
6765
<!-- .LP -->
6766
<!-- .sp -->
6767
To obtain <acronym>XIC</acronym> values, use
6768
<function>XGetICValues</function>.
6769
<indexterm significance="preferred"><primary>XGetICValues</primary></indexterm>
6770
<!-- .sM -->
6771
<funcsynopsis>
6772
<funcprototype>
6773
<funcdef>char *<function>XGetICValues</function></funcdef>
6774
<paramdef>XIC<parameter> ic</parameter></paramdef>
6775
</funcprototype>
6776
</funcsynopsis>
6777
<!-- .FN -->
6778
<variablelist>
6779
<varlistentry>
6780
<term>
6781
<emphasis remap='I'>ic</emphasis>
6782
</term>
6783
<listitem>
6784
<para>
6785
Specifies the input context.
6786
<!-- .ds Al \ to get XIC values -->
6787
</para>
6788
</listitem>
6789
</varlistentry>
6790
<varlistentry>
6791
<term>
6792
...
6793
</term>
6794
<listitem>
6795
<para>
6796
Specifies the variable length argument list(Al.
6797
</para>
6798
</listitem>
6799
</varlistentry>
6800
</variablelist>
6801
</para>
6802
<para>
6803
<!-- .LP -->
6804
<!-- .eM -->
6805
The
6806
<function>XGetICValues</function>
6807
function returns NULL if no error occurred; otherwise,
6808
it returns the name of the first argument that could not be obtained.
6809
An argument could not be obtained for any of the following reasons:
6810
</para>
6811
<itemizedlist>
6812
<listitem>
6813
<para>
6814
The argument name is not recognized.
6815
</para>
6816
</listitem>
6817
<listitem>
6818
<para>
6819
The input method encountered an implementation-dependent error.
6820
</para>
6821
</listitem>
6822
</itemizedlist>
6823
<para>
6824
<!-- .LP -->
6825
Each IC attribute value argument (following a name) must point to
6826
a location where the IC value is to be stored.
6827
That is, if the IC value is of type T,
6828
the argument must be of type T*.
6829
If T itself is a pointer type,
6830
then
6831
<function>XGetICValues</function>
6832
allocates memory to store the actual data,
6833
and the client is responsible for freeing this data by calling
6834
<function>XFree</function>
6835
with the returned pointer.
6836
The exception to this rule is for an IC value of type
6837
<type>XVaNestedList</type>
6838
(for preedit and status attributes).
6839
In this case, the argument must also be of type
6840
<type>XVaNestedList</type>.
6841
Then, the rule of changing type T to T* and freeing the allocated data
6842
applies to each element of the nested list.
6843
</para>
6844
</sect2>
6845
<sect2 id="Input_Context_Values">
6846
<title>Input Context Values</title>
6847
<!-- .XS -->
6848
<!-- (SN Input Context Values -->
6849
<!-- .XE -->
6850
<para>
6851
<!-- .LP -->
6852
The following tables describe how <acronym>XIC</acronym> values are interpreted
6853
by an input method depending on the input style chosen by the
6854
user.
6855
</para>
6856
<para>
6857
<!-- .LP -->
6858
The first column lists the <acronym>XIC</acronym> values.
6859
The second column indicates which values are involved in affecting,
6860
negotiating, and setting the geometry of the input method windows.
6861
The subentries under the third column indicate the different
6862
input styles that are supported.
6863
Each of these columns indicates how each of the <acronym>XIC</acronym> values
6864
are treated by that input style.
6865
</para>
6866
<para>
6867
<!-- .LP -->
6868
The following keys apply to these tables.
6869
</para>
6870
<informaltable>
6871
<tgroup cols='2' align='center'>
6872
<colspec colname='c1'/>
6873
<colspec colname='c2'/>
6874
<thead>
6875
<row>
6876
<entry>Key</entry>
6877
<entry>Explanation</entry>
6878
</row>
6879
</thead>
6880
<tbody>
6881
<row>
6882
<entry>C</entry>
6883
<entry>This value must be set with <function>XCreateIC</function>.</entry>
6884
</row>
6885
<row>
6886
<entry>D</entry>
6887
<entry>This value may be set using
6888
<function>XCreateIC</function>.>
6889
If it is not set,>
6890
a default is provided.</entry>
6891
</row>
6892
<row>
6893
<entry>G</entry>
6894
<entry>This value may be read using
6895
<function>XGetICValues</function>.</entry>
6896
</row>
6897
<row>
6898
<entry>GN</entry>
6899
<entry>This value may cause geometry negotiation when its value is set by means of
6900
<function>XCreateIC</function>
6901
or
6902
<function>XSetICValues</function>.</entry>
6903
</row>
6904
<row>
6905
<entry>GR</entry>
6906
<entry>This value will be the response of the input method when any
6907
GN value is changed.</entry>
6908
</row>
6909
<row>
6910
<entry>GS</entry>
6911
<entry>This value will cause the geometry of the input method window to be set.</entry>
6912
</row>
6913
<row>
6914
<entry>O</entry>
6915
<entry>This value must be set once and only once.
6916
It need not be set at create time.</entry>
6917
</row>
6918
<row>
6919
<entry>S</entry>
6920
<entry>This value may be set with
6921
<function>XSetICValues</function>.</entry>
6922
</row>
6923
<row>
6924
<entry>Ignored</entry>
6925
<entry>This value is ignored by the input method for the given input style.</entry>
6926
</row>
6927
</tbody>
6928
</tgroup>
6929
</informaltable>
6930
6931
<!-- .LP -->
6932
<informaltable>
6933
<tgroup cols='7' align='center'>
6934
<colspec colname='c1'/>
6935
<colspec colname='c2'/>
6936
<colspec colname='c3'/>
6937
<colspec colname='c4'/>
6938
<colspec colname='c5'/>
6939
<colspec colname='c6'/>
6940
<colspec colname='c7'/>
6941
<tbody>
6942
<row>
6943
<entry><acronym>XIC</acronym> Value</entry>
6944
<entry>Geometry Mangement</entry>
6945
<entry>Preedit Callback</entry>
6946
<entry>Preedit Position</entry>
6947
<entry>Input Style Preedit Area</entry>
6948
<entry>Preedit Nothing</entry>
6949
<entry>Preedit None</entry>
6950
</row>
6951
<row>
6952
<entry>Input Style</entry>
6953
<entry></entry>
6954
<entry>C-G</entry>
6955
<entry>C-G</entry>
6956
<entry>C-G</entry>
6957
<entry>C-G</entry>
6958
<entry>C-G</entry>
6959
</row>
6960
<row>
6961
<entry>Client Window</entry>
6962
<entry></entry>
6963
<entry>O-G</entry>
6964
<entry>O-G</entry>
6965
<entry>O-G</entry>
6966
<entry>O-G</entry>
6967
<entry>Ignored</entry>
6968
</row>
6969
<row>
6970
<entry>Focus Window</entry>
6971
<entry>GN</entry>
6972
<entry>D-S-G</entry>
6973
<entry>D-S-G</entry>
6974
<entry>D-S-G</entry>
6975
<entry>D-S-G</entry>
6976
<entry>Ignored</entry>
6977
</row>
6978
<row>
6979
<entry>Resource Name</entry>
6980
<entry></entry>
6981
<entry>Ignored</entry>
6982
<entry>D-S-G</entry>
6983
<entry>D-S-G</entry>
6984
<entry>D-S-G</entry>
6985
<entry>Ignored</entry>
6986
</row>
6987
<row>
6988
<entry>Resource Class</entry>
6989
<entry></entry>
6990
<entry>Ignored</entry>
6991
<entry>D-S-G</entry>
6992
<entry>D-S-G</entry>
6993
<entry>D-S-G</entry>
6994
<entry>Ignored</entry>
6995
</row>
6996
<row>
6997
<entry>Geometry Callback</entry>
6998
<entry></entry>
6999
<entry>Ignored</entry>
7000
<entry>Ignored</entry>
7001
<entry>D-S-G</entry>
7002
<entry>Ignored</entry>
7003
<entry>Ignored</entry>
7004
</row>
7005
<row>
7006
<entry>Filter Events</entry>
7007
<entry></entry>
7008
<entry>G</entry>
7009
<entry>G</entry>
7010
<entry>G</entry>
7011
<entry>G</entry>
7012
<entry>Ignored</entry>
7013
</row>
7014
<row>
7015
<entry>Destroy Callback</entry>
7016
<entry></entry>
7017
<entry>D-S-G</entry>
7018
<entry>D-S-G</entry>
7019
<entry>D-S-G</entry>
7020
<entry>D-S-G</entry>
7021
<entry>D-S-G</entry>
7022
</row>
7023
<row>
7024
<entry>String Conversion Callback</entry>
7025
<entry></entry>
7026
<entry>S-G</entry>
7027
<entry>S-G</entry>
7028
<entry>S-G</entry>
7029
<entry>S-G</entry>
7030
<entry>S-G</entry>
7031
</row>
7032
<row>
7033
<entry>String Conversion</entry>
7034
<entry></entry>
7035
<entry>D-S-G</entry>
7036
<entry>D-S-G</entry>
7037
<entry>D-S-G</entry>
7038
<entry>D-S-G</entry>
7039
<entry>D-S-G</entry>
7040
</row>
7041
<row>
7042
<entry>Reset State</entry>
7043
<entry></entry>
7044
<entry>D-S-G</entry>
7045
<entry>D-S-G</entry>
7046
<entry>D-S-G</entry>
7047
<entry>D-S-G</entry>
7048
<entry>Ignored</entry>
7049
</row>
7050
<row>
7051
<entry>HotKey</entry>
7052
<entry></entry>
7053
<entry>S-G</entry>
7054
<entry>S-G</entry>
7055
<entry>S-G</entry>
7056
<entry>S-G</entry>
7057
<entry>Ignored</entry>
7058
</row>
7059
<row>
7060
<entry>HotKeyState</entry>
7061
<entry></entry>
7062
<entry>D-S-G</entry>
7063
<entry>D-S-G</entry>
7064
<entry>D-S-G</entry>
7065
<entry>D-S-G</entry>
7066
<entry>Ignored</entry>
7067
</row>
7068
<row>
7069
<entry><function>Preedit</function></entry>
7070
</row>
7071
<row>
7072
<entry>Area</entry>
7073
<entry>GS</entry>
7074
<entry>Ignored</entry>
7075
<entry>D-S-G</entry>
7076
<entry>D-S-G</entry>
7077
<entry>Ignored</entry>
7078
<entry>Ignored</entry>
7079
</row>
7080
<row>
7081
<entry>Area Needed</entry>
7082
<entry>GN-GR</entry>
7083
<entry>Ignored</entry>
7084
<entry>Ignored</entry>
7085
<entry>S-G</entry>
7086
<entry>Ignored</entry>
7087
<entry>Ignored</entry>
7088
</row>
7089
<row>
7090
<entry>Spot Location</entry>
7091
<entry></entry>
7092
<entry>Ignored</entry>
7093
<entry>D-S-G</entry>
7094
<entry>Ignored</entry>
7095
<entry>Ignored</entry>
7096
<entry>Ignored</entry>
7097
</row>
7098
<row>
7099
<entry>Colormap</entry>
7100
<entry></entry>
7101
<entry>Ignored</entry>
7102
<entry>D-S-G</entry>
7103
<entry>D-S-G</entry>
7104
<entry>D-S-G</entry>
7105
<entry>Ignored</entry>
7106
</row>
7107
<row>
7108
<entry>Foreground</entry>
7109
<entry></entry>
7110
<entry>Ignored</entry>
7111
<entry>D-S-G</entry>
7112
<entry>D-S-G</entry>
7113
<entry>D-S-G</entry>
7114
<entry>Ignored</entry>
7115
</row>
7116
<row>
7117
<entry>Background</entry>
7118
<entry></entry>
7119
<entry>Ignored</entry>
7120
<entry>D-S-G</entry>
7121
<entry>D-S-G</entry>
7122
<entry>D-S-G</entry>
7123
<entry>Ignored</entry>
7124
</row>
7125
<row>
7126
<entry>Background Pixmap</entry>
7127
<entry></entry>
7128
<entry>Ignored</entry>
7129
<entry>D-S-G</entry>
7130
<entry>D-S-G</entry>
7131
<entry>D-S-G</entry>
7132
<entry>Ignored</entry>
7133
</row>
7134
<row>
7135
<entry>Font Set</entry>
7136
<entry>GN</entry>
7137
<entry>Ignored</entry>
7138
<entry>D-S-G</entry>
7139
<entry>D-S-G</entry>
7140
<entry>D-S-G</entry>
7141
<entry>Ignored</entry>
7142
</row>
7143
<row>
7144
<entry>Line Spacing</entry>
7145
<entry>GN</entry>
7146
<entry>Ignored</entry>
7147
<entry>D-S-G</entry>
7148
<entry>D-S-G</entry>
7149
<entry>D-S-G</entry>
7150
<entry>Ignored</entry>
7151
</row>
7152
<row>
7153
<entry>Cursor</entry>
7154
<entry></entry>
7155
<entry>Ignored</entry>
7156
<entry>D-S-G</entry>
7157
<entry>D-S-G</entry>
7158
<entry>D-S-G</entry>
7159
<entry>Ignored</entry>
7160
</row>
7161
<row>
7162
<entry>Preedit State</entry>
7163
<entry></entry>
7164
<entry>D-S-G</entry>
7165
<entry>D-S-G</entry>
7166
<entry>D-S-G</entry>
7167
<entry>D-S-G</entry>
7168
<entry>Ignored</entry>
7169
</row>
7170
<row>
7171
<entry>Preedit State Notify Callback</entry>
7172
<entry></entry>
7173
<entry>S-G</entry>
7174
<entry>S-G</entry>
7175
<entry>S-G</entry>
7176
<entry>S-G</entry>
7177
<entry>Ignored</entry>
7178
</row>
7179
<row>
7180
<entry>Preedit Callbacks</entry>
7181
<entry></entry>
7182
<entry>C-S-G</entry>
7183
<entry>Ignored</entry>
7184
<entry>Ignored</entry>
7185
<entry>Ignored</entry>
7186
<entry>Ignored</entry>
7187
</row>
7188
</tbody>
7189
</tgroup>
7190
</informaltable>
7191
7192
<!-- .LP -->
7193
<informaltable>
7194
<tgroup cols='6' align='center'>
7195
<colspec colname='c1'/>
7196
<colspec colname='c2'/>
7197
<colspec colname='c3'/>
7198
<colspec colname='c4'/>
7199
<colspec colname='c5'/>
7200
<colspec colname='c6'/>
7201
<thead>
7202
<row>
7203
<entry><acronym>XIC</acronym> Value</entry>
7204
<entry>Geomentry Management</entry>
7205
<entry>Status Callback</entry>
7206
<entry>Status Area</entry>
7207
<entry>Status Nothing</entry>
7208
<entry>Status None</entry>
7209
</row>
7210
</thead>
7211
<tbody>
7212
<row>
7213
<entry>Input Style</entry>
7214
<entry></entry>
7215
<entry>C-G</entry>
7216
<entry>C-G</entry>
7217
<entry>C-G</entry>
7218
<entry>C-G</entry>
7219
</row>
7220
<row>
7221
<entry>Client Window</entry>
7222
<entry></entry>
7223
<entry>O-G</entry>
7224
<entry>O-G</entry>
7225
<entry>O-G</entry>
7226
<entry>Ignored</entry>
7227
</row>
7228
<row>
7229
<entry>Focus Window</entry>
7230
<entry>GN</entry>
7231
<entry>D-S-G</entry>
7232
<entry>D-S-G</entry>
7233
<entry>D-S-G</entry>
7234
<entry>Ignored</entry>
7235
</row>
7236
<row>
7237
<entry>Resource Name</entry>
7238
<entry></entry>
7239
<entry>Ignored</entry>
7240
<entry>D-S-G</entry>
7241
<entry>D-S-G</entry>
7242
<entry>Ignored</entry>
7243
</row>
7244
<row>
7245
<entry>Resource Class</entry>
7246
<entry></entry>
7247
<entry>Ignored</entry>
7248
<entry>D-S-G</entry>
7249
<entry>D-S-G</entry>
7250
<entry>Ignored</entry>
7251
</row>
7252
<row>
7253
<entry>Geometry Callback</entry>
7254
<entry></entry>
7255
<entry>Ignored</entry>
7256
<entry>D-S-G</entry>
7257
<entry>Ignored</entry>
7258
<entry>Ignored</entry>
7259
</row>
7260
<row>
7261
<entry>Filter Events</entry>
7262
<entry></entry>
7263
<entry>G</entry>
7264
<entry>G</entry>
7265
<entry>G</entry>
7266
<entry>G</entry>
7267
</row>
7268
<row>
7269
<entry><type>Status</type></entry>
7270
</row>
7271
<row>
7272
<entry>Area</entry>
7273
<entry>GS</entry>
7274
<entry>Ignored</entry>
7275
<entry>D-S-G</entry>
7276
<entry>Ignored</entry>
7277
<entry>Ignored</entry>
7278
</row>
7279
<row>
7280
<entry>Area Needed</entry>
7281
<entry>GN-GR</entry>
7282
<entry>Ignored</entry>
7283
<entry>S-G</entry>
7284
<entry>Ignored</entry>
7285
<entry>Ignored</entry>
7286
</row>
7287
<row>
7288
<entry>Colormap</entry>
7289
<entry></entry>
7290
<entry>Ignored</entry>
7291
<entry>D-S-G</entry>
7292
<entry>D-S-G</entry>
7293
<entry>Ignored</entry>
7294
</row>
7295
<row>
7296
<entry>Foreground</entry>
7297
<entry></entry>
7298
<entry>Ignored</entry>
7299
<entry>D-S-G</entry>
7300
<entry>D-S-G</entry>
7301
<entry>Ignored</entry>
7302
</row>
7303
<row>
7304
<entry>Background</entry>
7305
<entry></entry>
7306
<entry>Ignored</entry>
7307
<entry>D-S-G</entry>
7308
<entry>D-S-G</entry>
7309
<entry>Ignored</entry>
7310
</row>
7311
<row>
7312
<entry>Background Pixmap</entry>
7313
<entry></entry>
7314
<entry>Ignored</entry>
7315
<entry>D-S-G</entry>
7316
<entry>D-S-G</entry>
7317
<entry>Ignored</entry>
7318
</row>
7319
<row>
7320
<entry>Font Set</entry>
7321
<entry>GN</entry>
7322
<entry>Ignored</entry>
7323
<entry>D-S-G</entry>
7324
<entry>D-S-G</entry>
7325
<entry>Ignored</entry>
7326
</row>
7327
<row>
7328
<entry>Line Spacing</entry>
7329
<entry>GN</entry>
7330
<entry>Ignored</entry>
7331
<entry>D-S-G</entry>
7332
<entry>D-S-G</entry>
7333
<entry>Ignored</entry>
7334
</row>
7335
<row>
7336
<entry>Cursor</entry>
7337
<entry></entry>
7338
<entry>Ignored</entry>
7339
<entry>D-S-G</entry>
7340
<entry>D-S-G</entry>
7341
<entry>Ignored</entry>
7342
</row>
7343
<row>
7344
<entry>Status Callbacks</entry>
7345
<entry></entry>
7346
<entry>C-S-G</entry>
7347
<entry>Ignored</entry>
7348
<entry>Ignored</entry>
7349
<entry>Ignored</entry>
7350
</row>
7351
</tbody>
7352
</tgroup>
7353
</informaltable>
7354
<sect3 id="Input_Style">
7355
<title>Input Style</title>
7356
<!-- .XS -->
7357
<!-- (SN Input Style -->
7358
<!-- .XE -->
7359
<para>
7360
<!-- .LP -->
7361
The
7362
<symbol>XNInputStyle</symbol>
7363
argument specifies the input style to be used.
7364
The value of this argument must be one of the values returned by the
7365
<function>XGetIMValues</function>
7366
function with the
7367
<symbol>XNQueryInputStyle</symbol>
7368
argument specified in the supported_styles list.
7369
</para>
7370
<para>
7371
<!-- .LP -->
7372
Note that this argument must be set at creation time
7373
and cannot be changed.
7374
</para>
7375
</sect3>
7376
<sect3 id="Client_Window">
7377
<title>Client Window</title>
7378
<!-- .XS -->
7379
<!-- (SN Client Window -->
7380
<!-- .XE -->
7381
<para>
7382
<!-- .LP -->
7383
<indexterm significance="preferred"><primary>XNClientWindow</primary></indexterm>
7384
The
7385
<symbol>XNClientWindow</symbol>
7386
argument specifies to the input method the client window in
7387
which the input method
7388
can display data or create subwindows.
7389
Geometry values for input method areas are given with respect to the client
7390
window.
7391
Dynamic change of client window is not supported.
7392
This argument may be set only once and
7393
should be set before any input is done using this input context.
7394
If it is not set,
7395
the input method may not operate correctly.
7396
</para>
7397
<para>
7398
<!-- .LP -->
7399
If an attempt is made to set this value a second time with
7400
<function>XSetICValues</function>,
7401
the string
7402
<symbol>XNClientWindow</symbol>
7403
will be returned by
7404
<function>XSetICValues</function>,
7405
and the client window will not be changed.
7406
</para>
7407
<para>
7408
<!-- .LP -->
7409
If the client window is not a valid window ID on the display
7410
attached to the input method,
7411
a
7412
<errorname>BadWindow</errorname>
7413
error can be generated when this value is used by the input method.
7414
</para>
7415
</sect3>
7416
<sect3 id="Focus_Window">
7417
<title>Focus Window</title>
7418
<!-- .XS -->
7419
<!-- (SN Focus Window -->
7420
<!-- .XE -->
7421
<para>
7422
<!-- .LP -->
7423
<indexterm significance="preferred"><primary>XNFocusWindow</primary></indexterm>
7424
The
7425
<symbol>XNFocusWindow</symbol>
7426
argument specifies the focus window.
7427
The primary purpose of the
7428
<symbol>XNFocusWindow</symbol>
7429
is to identify the window that will receive the key event when input
7430
is composed.
7431
In addition, the input method may possibly affect the focus window
7432
as follows:
7433
</para>
7434
<itemizedlist>
7435
<listitem>
7436
<para>
7437
Select events on it
7438
</para>
7439
</listitem>
7440
<listitem>
7441
<para>
7442
Send events to it
7443
</para>
7444
</listitem>
7445
<listitem>
7446
<para>
7447
Modify its properties
7448
</para>
7449
</listitem>
7450
<listitem>
7451
<para>
7452
Grab the keyboard within that window
7453
</para>
7454
</listitem>
7455
</itemizedlist>
7456
<para>
7457
<!-- .LP -->
7458
The associated value must be of type
7459
<type>Window</type>.
7460
If the focus window is not a valid window ID on the display
7461
attached to the input method,
7462
a
7463
<errorname>BadWindow</errorname>
7464
error can be generated when this value is used by the input method.
7465
</para>
7466
<para>
7467
<!-- .LP -->
7468
When this <acronym>XIC</acronym> value is left unspecified,
7469
the input method will use the client window as the default focus window.
7470
</para>
7471
</sect3>
7472
<sect3 id="Resource_Name_and_Class_b">
7473
<title>Resource Name and Class</title>
7474
<!-- .XS -->
7475
<!-- (SN Resource Name and Class -->
7476
<!-- .XE -->
7477
<para>
7478
<!-- .LP -->
7479
<indexterm significance="preferred"><primary>XNResourceName</primary></indexterm>
7480
<indexterm significance="preferred"><primary>XNResourceClass</primary></indexterm>
7481
The
7482
<symbol>XNResourceName</symbol>
7483
and
7484
<symbol>XNResourceClass</symbol>
7485
arguments are strings that specify the full name and class
7486
used by the client to obtain resources for the client window.
7487
These values should be used as prefixes for name and class
7488
when looking up resources that may vary according to the input context.
7489
If these values are not set,
7490
the resources will not be fully specified.
7491
</para>
7492
<para>
7493
<!-- .LP -->
7494
It is not intended that values that can be set as <acronym>XIC</acronym> values be
7495
set as resources.
7496
</para>
7497
</sect3>
7498
<sect3 id="Geometry_Callback">
7499
<title>Geometry Callback</title>
7500
<!-- .XS -->
7501
<!-- (SN Geometry Callback -->
7502
<!-- .XE -->
7503
<para>
7504
<!-- .LP -->
7505
<indexterm significance="preferred"><primary>XNGeometryCallback</primary></indexterm>
7506
The
7507
<symbol>XNGeometryCallback</symbol>
7508
argument is a structure of type
7509
<structname>XIMCallback</structname>
7510
(see section 13.5.6.13.12).
7511
</para>
7512
<para>
7513
<!-- .LP -->
7514
The
7515
<symbol>XNGeometryCallback</symbol>
7516
argument specifies the geometry callback that a client can set.
7517
This callback is not required for correct operation of either
7518
an input method or a client.
7519
It can be set for a client whose user interface policy permits
7520
an input method to request the dynamic change of that input
7521
method's window.
7522
An input method that does dynamic change will need to filter any
7523
events that it uses to initiate the change.
7524
</para>
7525
</sect3>
7526
<sect3 id="Filter_Events">
7527
<title>Filter Events</title>
7528
<!-- .XS -->
7529
<!-- (SN Filter Events -->
7530
<!-- .XE -->
7531
<para>
7532
<!-- .LP -->
7533
<indexterm significance="preferred"><primary>XNFilterEvents</primary></indexterm>
7534
The
7535
<symbol>XNFilterEvents</symbol>
7536
argument returns the event mask that an input method needs
7537
to have selected for.
7538
The client is expected to augment its own event mask
7539
for the client window with this one.
7540
</para>
7541
<para>
7542
<!-- .LP -->
7543
This argument is read-only, is set by the input method at create time,
7544
and is never changed.
7545
</para>
7546
<para>
7547
<!-- .LP -->
7548
The type of this argument is
7549
<type>unsigned</type>
7550
<type>long</type>.
7551
Setting this value will cause an error.
7552
</para>
7553
</sect3>
7554
<sect3 id="Destroy_Callback_b">
7555
<title>Destroy Callback</title>
7556
<!-- .XS -->
7557
<!-- (SN Destroy Callback -->
7558
<!-- .XE -->
7559
<para>
7560
<!-- .LP -->
7561
The
7562
<symbol>XNDestroyCallback</symbol>
7563
argument is a pointer to a structure of type
7564
<structname>XIMCallback</structname>
7565
(see section 13.5.6.13.12). This callback is triggered when the input method
7566
stops its service for any reason; for example, when a connection to an IM
7567
server is broken. After the destroy callback is called,
7568
the input context is destroyed and the input method is closed.
7569
Therefore, the client should not call
7570
<function>XDestroyIC</function>
7571
and
7572
<function>XCloseIM</function>.
7573
</para>
7574
<para>
7575
<!-- .LP -->
7576
</para>
7577
</sect3>
7578
<sect3 id="String_Conversion_Callback">
7579
<title>String Conversion Callback</title>
7580
<!-- .XS -->
7581
<!-- (SN String Conversion Callback -->
7582
<!-- .XE -->
7583
<para>
7584
<!-- .LP -->
7585
The
7586
<symbol>XNStringConversionCallback</symbol>
7587
argument is a structure of type
7588
<structname>XIMCallback</structname>
7589
(see section 13.5.6.13.12).
7590
</para>
7591
<para>
7592
<!-- .LP -->
7593
The
7594
<symbol>XNStringConversionCallback</symbol>
7595
argument specifies a string conversion callback. This callback
7596
is not required for correct operation of
7597
either the input method or the client. It can be set by a client
7598
to support string conversions that may be requested
7599
by the input method. An input method that does string conversions
7600
will filter any events that it uses to initiate the conversion.
7601
</para>
7602
<para>
7603
<!-- .LP -->
7604
Because this <acronym>XIC</acronym> value is optional, a client should call
7605
<function>XGetIMValues</function>
7606
with argument
7607
<symbol>XNQueryICValuesList</symbol>
7608
before using this argument.
7609
</para>
7610
<para>
7611
<!-- .LP -->
7612
</para>
7613
</sect3>
7614
<sect3 id="String_Conversion_">
7615
<title>String Conversion </title>
7616
<!-- .XS -->
7617
<!-- (SN String Conversion -->
7618
<!-- .XE -->
7619
<para>
7620
<!-- .LP -->
7621
The
7622
<symbol>XNStringConversion</symbol>
7623
argument is a structure of type
7624
<structname>XIMStringConversionText</structname>.
7625
</para>
7626
<para>
7627
<!-- .LP -->
7628
The
7629
<symbol>XNStringConversion</symbol>
7630
argument specifies the string to be converted by an input method.
7631
This argument is not required for correct operation of either
7632
the input method or the client.
7633
</para>
7634
<para>
7635
<!-- .LP -->
7636
String conversion facilitates the manipulation of text independent
7637
of preediting.
7638
It is essential for some input methods and clients to manipulate
7639
text by performing context-sensitive conversion,
7640
reconversion, or transliteration conversion on it.
7641
</para>
7642
<para>
7643
<!-- .LP -->
7644
Because this <acronym>XIC</acronym> value is optional, a client should call
7645
<function>XGetIMValues</function>
7646
with argument
7647
<symbol>XNQueryICValuesList</symbol>
7648
before using this argument.
7649
</para>
7650
<para>
7651
<!-- .LP -->
7652
The
7653
<structname>XIMStringConversionText</structname>
7654
structure is defined as follows:
7655
</para>
7656
<para>
7657
<!-- .LP -->
7658
<!-- .sM -->
7659
<literallayout class="monospaced">
7660
7661
typedef struct _XIMStringConversionText {
7662
unsigned short length;
7663
XIMStringConversionFeedback *feedback;
7664
Bool encoding_is_wchar;
7665
union {
7666
char *mbs;
7667
wchar_t *wcs;
7668
} string;
7669
} XIMStringConversionText;
7670
7671
typedef unsigned long XIMStringConversionFeedback;
7672
</literallayout>
7673
</para>
7674
<para>
7675
<!-- .LP -->
7676
<!-- .eM -->
7677
The feedback member is reserved for future use. The text to be
7678
converted is defined by the string and length members. The length
7679
is indicated in characters. To prevent the library from freeing memory
7680
pointed to by an uninitialized pointer, the client should set the feedback
7681
element to NULL.
7682
</para>
7683
<para>
7684
<!-- .LP -->
7685
</para>
7686
</sect3>
7687
<sect3 id="Reset_State">
7688
<title>Reset State</title>
7689
<!-- .XS -->
7690
<!-- (SN Reset State -->
7691
<!-- .XE -->
7692
<para>
7693
<!-- .LP -->
7694
The
7695
<symbol>XNResetState</symbol>
7696
argument specifies the state the input context will return to after calling
7697
<function>XmbResetIC</function>
7698
or
7699
<function>XwcResetIC</function>.
7700
</para>
7701
<para>
7702
<!-- .LP -->
7703
The <acronym>XIC</acronym> state may be set to its initial state, as specified by the
7704
<symbol>XNPreeditState</symbol>
7705
value when
7706
<function>XCreateIC</function>
7707
was called, or it may be set to preserve the current state.
7708
</para>
7709
<para>
7710
<!-- .LP -->
7711
The valid masks for
7712
<type>XIMResetState</type>
7713
are as follows:
7714
</para>
7715
<para>
7716
<!-- .LP -->
7717
<indexterm significance="preferred"><primary>XIMInitialState</primary></indexterm>
7718
<indexterm significance="preferred"><primary>XINPreserveState</primary></indexterm>
7719
<!-- .sM -->
7720
</para>
7721
<literallayout class="monospaced">
7722
typedef unsigned long XIMResetState;
7723
7724
#define XIMInitialState (1L)
7725
#define XIMPreserveState (1L<<1)
7726
7727
</literallayout>
7728
7729
<para>
7730
<!-- .LP -->
7731
<!-- .eM -->
7732
If
7733
<symbol>XIMInitialState</symbol>
7734
is set, then
7735
<function>XmbResetIC</function>
7736
and
7737
<function>XwcResetIC</function>
7738
will return to the initial
7739
<symbol>XNPreeditState</symbol>
7740
state of the <acronym>XIC</acronym>.
7741
</para>
7742
<para>
7743
<!-- .LP -->
7744
If
7745
<symbol>XIMPreserveState</symbol>
7746
is set, then
7747
<function>XmbResetIC</function>
7748
and
7749
<function>XwcResetIC</function>
7750
will preserve the current state of the <acronym>XIC</acronym>.
7751
</para>
7752
<para>
7753
<!-- .LP -->
7754
If
7755
<symbol>XNResetState</symbol>
7756
is left unspecified, the default is
7757
<symbol>XIMInitialState</symbol>.
7758
</para>
7759
<para>
7760
<!-- .LP -->
7761
<type>XIMResetState</type>
7762
values other than those specified above will default to
7763
<symbol>XIMInitialState</symbol>.
7764
</para>
7765
<para>
7766
<!-- .LP -->
7767
Because this <acronym>XIC</acronym> value is optional, a client should call
7768
<function>XGetIMValues</function>
7769
with argument
7770
<symbol>XNQueryICValuesList</symbol>
7771
before using this argument.
7772
</para>
7773
<para>
7774
<!-- .LP -->
7775
</para>
7776
</sect3>
7777
<sect3 id="Hot_Keys_b">
7778
<title>Hot Keys</title>
7779
<!-- .XS -->
7780
<!-- (SN Hot Keys -->
7781
<!-- .XE -->
7782
<para>
7783
<!-- .LP -->
7784
The
7785
<symbol>XNHotKey</symbol>
7786
argument specifies the hot key list to the <acronym>XIC</acronym>.
7787
The hot key list is a pointer to the structure of type
7788
<structname>XIMHotKeyTriggers</structname>,
7789
which specifies the key events that must be received
7790
without any interruption of the input method.
7791
For the hot key list set with this argument to be utilized, the client
7792
must also set
7793
<symbol>XNHotKeyState</symbol>
7794
to
7795
<symbol>XIMHotKeyStateON</symbol>.
7796
</para>
7797
<para>
7798
<!-- .LP -->
7799
Because this <acronym>XIC</acronym> value is optional, a client should call
7800
<function>XGetIMValues</function>
7801
with argument
7802
<symbol>XNQueryICValuesList</symbol>
7803
before using this functionality.
7804
</para>
7805
<para>
7806
<!-- .LP -->
7807
The value of the argument is a pointer to a structure of type
7808
<structname>XIMHotKeyTriggers</structname>.
7809
</para>
7810
<para>
7811
<!-- .LP -->
7812
If an event for a key in the hot key list is found, then the process will
7813
receive the event and it will be processed inside the client.
7814
</para>
7815
<para>
7816
<!-- .LP -->
7817
<!-- .sM -->
7818
<literallayout class="monospaced">
7819
<!-- .TA .5i 2.5i -->
7820
<!-- .ta .5i 2.5i -->
7821
typedef struct {
7822
KeySym keysym;
7823
unsigned int modifier;
7824
unsigned int modifier_mask;
7825
} XIMHotKeyTrigger;
7826
7827
typedef struct {
7828
int num_hot_key;
7829
XIMHotKeyTrigger *key;
7830
} XIMHotKeyTriggers;
7831
</literallayout>
7832
</para>
7833
<para>
7834
<!-- .LP -->
7835
<!-- .eM -->
7836
</para>
7837
<para>
7838
<!-- .LP -->
7839
The combination of modifier and modifier_mask are used to represent one of
7840
three states for each modifier:
7841
either the modifier must be on, or the modifier must be off, or the modifier
7842
is a ``don't care'' - it may be on or off.
7843
When a modifier_mask bit is set to 0, the state of the associated modifier
7844
is ignored when evaluating whether the key is hot or not.
7845
</para>
7846
7847
<informaltable>
7848
<tgroup cols='3' align='center'>
7849
<colspec colname='c1'/>
7850
<colspec colname='c2'/>
7851
<colspec colname='c3'/>
7852
<thead>
7853
<row>
7854
<entry>Modifier Bit</entry>
7855
<entry>Mask Bit</entry>
7856
<entry>Meaning</entry>
7857
</row>
7858
</thead>
7859
<tbody>
7860
<row>
7861
<entry>0</entry>
7862
<entry>1</entry>
7863
<entry>The modifier must be off.</entry>
7864
</row>
7865
<row>
7866
<entry>1</entry>
7867
<entry>1</entry>
7868
<entry>The modifier must be on.</entry>
7869
</row>
7870
<row>
7871
<entry>n/a</entry>
7872
<entry>0</entry>
7873
<entry>Do not care if the modifier is on or off.</entry>
7874
</row>
7875
</tbody>
7876
</tgroup>
7877
</informaltable>
7878
7879
</sect3>
7880
<sect3 id="Hot_Key_State">
7881
<title>Hot Key State</title>
7882
<!-- .XS -->
7883
<!-- (SN Hot Key State -->
7884
<!-- .XE -->
7885
<para>
7886
<!-- .LP -->
7887
The
7888
<symbol>XNHotKeyState</symbol>
7889
argument specifies the hot key state of the input method.
7890
This is usually used to switch the input method between hot key
7891
operation and normal input processing.
7892
</para>
7893
<para>
7894
<!-- .LP -->
7895
The value of the argument is a pointer to a structure of type
7896
XIMHotKeyState .
7897
</para>
7898
<literallayout class="monospaced">
7899
typedef unsigned long XIMHotKeyState;
7900
7901
#define XIMHotKeyStateON (0x0001L)
7902
#define XIMHotKeyStateOFF (0x0002L)
7903
7904
</literallayout>
7905
7906
<para>
7907
<!-- .LP -->
7908
<!-- .eM -->
7909
</para>
7910
<para>
7911
<!-- .LP -->
7912
If not specified, the default is
7913
<symbol>XIMHotKeyStateOFF</symbol>.
7914
</para>
7915
<para>
7916
<!-- .LP -->
7917
</para>
7918
</sect3>
7919
<sect3 id="Preedit_and_Status_Attributes">
7920
<title>Preedit and Status Attributes</title>
7921
<!-- .XS -->
7922
<!-- (SN Preedit and Status Attributes -->
7923
<!-- .XE -->
7924
<para>
7925
<!-- .LP -->
7926
<indexterm significance="preferred"><primary>XNPreeditAttributes</primary></indexterm>
7927
<indexterm significance="preferred"><primary>XNStatusAttributes</primary></indexterm>
7928
The
7929
<symbol>XNPreeditAttributes</symbol>
7930
and
7931
<symbol>XNStatusAttributes</symbol>
7932
arguments specify to an input method the attributes to be used for the
7933
preedit and status areas,
7934
if any.
7935
Those attributes are passed to
7936
<function>XSetICValues</function>
7937
or
7938
<function>XGetICValues</function>
7939
as a nested variable-length list.
7940
The names to be used in these lists are described in the following sections.
7941
</para>
7942
<sect4 id="Area">
7943
<title>Area</title>
7944
<!-- .XS -->
7945
<!-- (SN Area -->
7946
<!-- .XE -->
7947
<para>
7948
<!-- .LP -->
7949
<indexterm significance="preferred"><primary>XNArea</primary></indexterm>
7950
The value of the
7951
<symbol>XNArea</symbol>
7952
argument must be a pointer to a structure of type
7953
<structname>XRectangle</structname>.
7954
The interpretation of the
7955
<symbol>XNArea</symbol>
7956
argument is dependent on the input method style that has been set.
7957
</para>
7958
<para>
7959
<!-- .LP -->
7960
If the input method style is
7961
<symbol>XIMPreeditPosition</symbol>,
7962
<symbol>XNArea</symbol>
7963
specifies the clipping region within which preediting will take place.
7964
If the focus window has been set,
7965
the coordinates are assumed to be relative to the focus window.
7966
Otherwise, the coordinates are assumed to be relative to the client window.
7967
If neither has been set,
7968
the results are undefined.
7969
</para>
7970
<para>
7971
<!-- .LP -->
7972
If
7973
<symbol>XNArea</symbol>
7974
is not specified, is set to NULL, or is invalid,
7975
the input method will default the clipping region
7976
to the geometry of the
7977
<symbol>XNFocusWindow</symbol>.
7978
If the area specified is NULL or invalid,
7979
the results are undefined.
7980
</para>
7981
<para>
7982
<!-- .LP -->
7983
If the input style is
7984
<symbol>XIMPreeditArea</symbol>
7985
or
7986
<symbol>XIMStatusArea</symbol>,
7987
<symbol>XNArea</symbol>
7988
specifies the geometry provided by the client to the input method.
7989
The input method may use this area to display its data,
7990
either preedit or status depending on the area designated.
7991
The input method may create a window as a child of the client window
7992
with dimensions that fit the
7993
<symbol>XNArea</symbol>.
7994
The coordinates are relative to the client window.
7995
If the client window has not been set yet,
7996
the input method should save these values
7997
and apply them when the client window is set.
7998
If
7999
<symbol>XNArea</symbol>
8000
is not specified, is set to NULL, or is invalid,
8001
the results are undefined.
8002
</para>
8003
</sect4>
8004
<sect4 id="Area_Needed">
8005
<title>Area Needed</title>
8006
<!-- .XS -->
8007
<!-- (SN Area Needed -->
8008
<!-- .XE -->
8009
<para>
8010
<!-- .LP -->
8011
<indexterm significance="preferred"><primary>XNAreaNeeded</primary></indexterm>
8012
When set, the
8013
<symbol>XNAreaNeeded</symbol>
8014
argument specifies the geometry suggested by the client for this area
8015
(preedit or status).
8016
The value associated with the argument must be a pointer to a
8017
structure of type
8018
<structname>XRectangle</structname>.
8019
Note that the x, y values are not used
8020
and that nonzero values for width or height are the constraints
8021
that the client wishes the input method to respect.
8022
</para>
8023
<para>
8024
<!-- .LP -->
8025
When read, the
8026
<symbol>XNAreaNeeded</symbol>
8027
argument specifies the preferred geometry desired by the input method
8028
for the area.
8029
</para>
8030
<para>
8031
<!-- .LP -->
8032
This argument is only valid if the input style is
8033
<symbol>XIMPreeditArea</symbol>
8034
or
8035
<symbol>XIMStatusArea</symbol>.
8036
It is used for geometry negotiation between the client and the input method
8037
and has no other effect on the input method
8038
(see section 13.5.1.5).
8039
</para>
8040
</sect4>
8041
<sect4 id="Spot_Location">
8042
<title>Spot Location</title>
8043
<!-- .XS -->
8044
<!-- (SN Spot Location -->
8045
<!-- .XE -->
8046
<para>
8047
<!-- .LP -->
8048
<indexterm significance="preferred"><primary>XNSpotLocation</primary></indexterm>
8049
The
8050
<symbol>XNSpotLocation</symbol>
8051
argument specifies to the input method the coordinates of the spot
8052
to be used by an input method executing with
8053
<symbol>XNInputStyle</symbol>
8054
set to
8055
<symbol>XIMPreeditPosition</symbol>.
8056
When specified to any input method other than
8057
<symbol>XIMPreeditPosition</symbol>,
8058
this <acronym>XIC</acronym> value is ignored.
8059
</para>
8060
<para>
8061
<!-- .LP -->
8062
The x coordinate specifies the position where the next character
8063
would be inserted.
8064
The y coordinate is the position of the baseline used
8065
by the current text line in the focus window.
8066
The x and y coordinates are relative to the focus window, if it has been set;
8067
otherwise, they are relative to the client window.
8068
If neither the focus window nor the client window has been set,
8069
the results are undefined.
8070
</para>
8071
<para>
8072
<!-- .LP -->
8073
The value of the argument is a pointer to a structure of type
8074
<structname>XPoint</structname>.
8075
</para>
8076
</sect4>
8077
<sect4 id="Colormap">
8078
<title>Colormap</title>
8079
<!-- .XS -->
8080
<!-- (SN Colormap -->
8081
<!-- .XE -->
8082
<para>
8083
<!-- .LP -->
8084
Two different arguments can be used to indicate what colormap the input method
8085
should use to allocate colors, a colormap ID, or a standard colormap name.
8086
</para>
8087
<para>
8088
<!-- .LP -->
8089
<indexterm significance="preferred"><primary>XNColormap</primary></indexterm>
8090
The
8091
<symbol>XNColormap</symbol>
8092
argument is used to specify a colormap ID.
8093
The argument value is of type
8094
<type>Colormap</type>.
8095
An invalid argument may generate a
8096
<errorname>BadColor</errorname>
8097
error when it is used by the input method.
8098
</para>
8099
<para>
8100
<!-- .LP -->
8101
<indexterm significance="preferred"><primary>XNStdColormap</primary></indexterm>
8102
The
8103
<symbol>XNStdColormap</symbol>
8104
argument is used to indicate the name of the standard colormap
8105
in which the input method should allocate colors.
8106
The argument value is an
8107
<type>Atom</type>
8108
that should be a valid atom for calling
8109
<function>XGetRGBColormaps</function>.
8110
An invalid argument may generate a
8111
<errorname>BadAtom</errorname>
8112
error when it is used by the input method.
8113
</para>
8114
<para>
8115
<!-- .LP -->
8116
If the colormap is left unspecified,
8117
the client window colormap becomes the default.
8118
</para>
8119
</sect4>
8120
<sect4 id="Foreground_and_Background">
8121
<title>Foreground and Background</title>
8122
<!-- .XS -->
8123
<!-- (SN Foreground and Background -->
8124
<!-- .XE -->
8125
<para>
8126
<!-- .LP -->
8127
<indexterm significance="preferred"><primary>XNForeground</primary></indexterm>
8128
<indexterm significance="preferred"><primary>XNBackground</primary></indexterm>
8129
The
8130
<symbol>XNForeground</symbol>
8131
and
8132
<symbol>XNBackground</symbol>
8133
arguments specify the foreground and background pixel, respectively.
8134
The argument value is of type
8135
<type>unsigned</type>
8136
<type>long</type>.
8137
It must be a valid pixel in the input method colormap.
8138
</para>
8139
<para>
8140
<!-- .LP -->
8141
If these values are left unspecified,
8142
the default is determined by the input method.
8143
</para>
8144
</sect4>
8145
<sect4 id="Background_Pixmap">
8146
<title>Background Pixmap</title>
8147
<!-- .XS -->
8148
<!-- (SN Background Pixmap -->
8149
<!-- .XE -->
8150
<para>
8151
<!-- .LP -->
8152
The
8153
<symbol>XNBackgroundPixmap</symbol>
8154
argument specifies a background pixmap to be used as the background of the
8155
window.
8156
The value must be of type
8157
<type>Pixmap</type>.
8158
An invalid argument may generate a
8159
<errorname>BadPixmap</errorname>
8160
error when it is used by the input method.
8161
</para>
8162
<para>
8163
<!-- .LP -->
8164
If this value is left unspecified,
8165
the default is determined by the input method.
8166
</para>
8167
</sect4>
8168
<sect4 id="Font_Set">
8169
<title>Font Set</title>
8170
<!-- .XS -->
8171
<!-- (SN Font Set -->
8172
<!-- .XE -->
8173
<para>
8174
<!-- .LP -->
8175
<indexterm significance="preferred"><primary>XNFontSet</primary></indexterm>
8176
The
8177
<symbol>XNFontSet</symbol>
8178
argument specifies to the input method what font set is to be used.
8179
The argument value is of type
8180
<type>XFontSet</type>.
8181
</para>
8182
<para>
8183
<!-- .LP -->
8184
If this value is left unspecified,
8185
the default is determined by the input method.
8186
</para>
8187
</sect4>
8188
<sect4 id="Line_Spacing">
8189
<title>Line Spacing</title>
8190
<!-- .XS -->
8191
<!-- (SN Line Spacing -->
8192
<!-- .XE -->
8193
<para>
8194
<!-- .LP -->
8195
The
8196
<symbol>XNLineSpace</symbol>
8197
argument specifies to the input method what line spacing is to be used
8198
in the preedit window if more than one line is to be used.
8199
This argument is of type
8200
<type>int</type>.
8201
</para>
8202
<para>
8203
<!-- .LP -->
8204
If this value is left unspecified,
8205
the default is determined by the input method.
8206
</para>
8207
</sect4>
8208
<sect4 id="Cursor">
8209
<title>Cursor</title>
8210
<!-- .XS -->
8211
<!-- (SN Cursor -->
8212
<!-- .XE -->
8213
<para>
8214
<!-- .LP -->
8215
<indexterm significance="preferred"><primary>XNCursor</primary></indexterm>
8216
The
8217
<symbol>XNCursor</symbol>
8218
argument specifies to the input method what cursor is to be used
8219
in the specified window.
8220
This argument is of type
8221
<type>Cursor</type>.
8222
</para>
8223
<para>
8224
<!-- .LP -->
8225
An invalid argument may generate a
8226
<errorname>BadCursor</errorname>
8227
error when it is used by the input method.
8228
If this value is left unspecified,
8229
the default is determined by the input method.
8230
</para>
8231
</sect4>
8232
<sect4 id="Preedit_State">
8233
<title>Preedit State</title>
8234
<!-- .XS -->
8235
<!-- (SN Preedit State -->
8236
<!-- .XE -->
8237
<para>
8238
<!-- .LP -->
8239
The
8240
<symbol>XNPreeditState</symbol>
8241
argument specifies the state of input preediting for the input method.
8242
Input preediting can be on or off.
8243
</para>
8244
<para>
8245
<!-- .LP -->
8246
The valid mask names for
8247
<symbol>XNPreeditState</symbol>
8248
are as follows:
8249
</para>
8250
<para>
8251
<!-- .LP -->
8252
<indexterm significance="preferred"><primary>XIMPreeditUnknown</primary></indexterm>
8253
<indexterm significance="preferred"><primary>XIMPreeditEnable</primary></indexterm>
8254
<indexterm significance="preferred"><primary>XIMPreeditDisable</primary></indexterm>
8255
<!-- .sM -->
8256
</para>
8257
<!-- .LP -->
8258
<literallayout class="monospaced">
8259
typedef unsigned long XIMPreeditState;
8260
8261
#define XIMPreeditUnknown 0L
8262
#define XIMPreeditEnable 1L
8263
#define XIMPreeditDisable (1L<<1)
8264
8265
</literallayout>
8266
8267
<para>
8268
<!-- .LP -->
8269
<!-- .eM -->
8270
If a value of
8271
<symbol>XIMPreeditEnable</symbol>
8272
is set, then input preediting is turned on by the input method.
8273
</para>
8274
<para>
8275
<!-- .LP -->
8276
If a value of
8277
<symbol>XIMPreeditDisable</symbol>
8278
is set, then input preediting is turned off by the input method.
8279
</para>
8280
<para>
8281
<!-- .LP -->
8282
If
8283
<symbol>XNPreeditState</symbol>
8284
is left unspecified, then the state will be implementation-dependent.
8285
</para>
8286
<para>
8287
<!-- .LP -->
8288
When
8289
<symbol>XNResetState</symbol>
8290
is set to
8291
<symbol>XIMInitialState</symbol>,
8292
the
8293
<symbol>XNPreeditState</symbol>
8294
value specified at the creation time will be reflected as the initial state for
8295
<function>XmbResetIC</function>
8296
and
8297
<function>XwcResetIC</function>.
8298
</para>
8299
<para>
8300
<!-- .LP -->
8301
Because this <acronym>XIC</acronym> value is optional, a client should call
8302
<function>XGetIMValues</function>
8303
with argument
8304
<symbol>XNQueryICValuesList</symbol>
8305
before using this argument.
8306
</para>
8307
</sect4>
8308
<sect4 id="Preedit_State_Notify_Callback">
8309
<title>Preedit State Notify Callback</title>
8310
<!-- .XS -->
8311
<!-- (SN Preedit State Notify Callback -->
8312
<!-- .XE -->
8313
<para>
8314
<!-- .LP -->
8315
The preedit state notify callback is triggered by the input method
8316
when the preediting state has changed.
8317
The value of the
8318
<symbol>XNPreeditStateNotifyCallback</symbol>
8319
argument is a pointer to a structure of type
8320
<structname>XIMCallback</structname>.
8321
The generic prototype is as follows:
8322
<indexterm significance="preferred"><primary>PreeditStateNotifyCallback</primary></indexterm>
8323
<!-- .sM -->
8324
<funcsynopsis>
8325
<funcprototype>
8326
<funcdef>void <function><replaceable>PreeditStateNotifyCallback</replaceable></function></funcdef>
8327
<paramdef>XIC<parameter> ic</parameter></paramdef>
8328
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
8329
<paramdef>XIMPreeditStateNotifyCallbackStruct<parameter> *call_data</parameter></paramdef>
8330
</funcprototype>
8331
</funcsynopsis>
8332
<!-- .FN -->
8333
<variablelist>
8334
<varlistentry>
8335
<term>
8336
<emphasis remap='I'>ic</emphasis>
8337
</term>
8338
<listitem>
8339
<para>
8340
Specifies the input context.
8341
</para>
8342
</listitem>
8343
</varlistentry>
8344
<varlistentry>
8345
<term>
8346
<emphasis remap='I'>client_data</emphasis>
8347
</term>
8348
<listitem>
8349
<para>
8350
Specifies the additional client data.
8351
</para>
8352
</listitem>
8353
</varlistentry>
8354
<varlistentry>
8355
<term>
8356
<emphasis remap='I'>call_data</emphasis>
8357
</term>
8358
<listitem>
8359
<para>
8360
Specifies the current preedit state.
8361
</para>
8362
</listitem>
8363
</varlistentry>
8364
</variablelist>
8365
</para>
8366
<para>
8367
<!-- .LP -->
8368
<!-- .eM -->
8369
The
8370
<structname>XIMPreeditStateNotifyCallbackStruct</structname>
8371
structure is defined as follows:
8372
</para>
8373
<para>
8374
<!-- .LP -->
8375
<indexterm significance="preferred"><primary>XIMPreeditStateNotifyCallbackStruct</primary></indexterm>
8376
<!-- .sM -->
8377
<literallayout class="monospaced">
8378
<!-- .TA .5i 2.5i -->
8379
<!-- .ta .5i 2.5i -->
8380
typedef struct _XIMPreeditStateNotifyCallbackStruct {
8381
XIMPreeditState state;
8382
} XIMPreeditStateNotifyCallbackStruct;
8383
</literallayout>
8384
</para>
8385
<para>
8386
<!-- .LP -->
8387
<!-- .eM -->
8388
</para>
8389
<para>
8390
<!-- .LP -->
8391
Because this <acronym>XIC</acronym> value is optional, a client should call
8392
<function>XGetIMValues</function>
8393
with argument
8394
<symbol>XNQueryICValuesList</symbol>
8395
before using this argument.
8396
</para>
8397
</sect4>
8398
<sect4 id="Preedit_and_Status_Callbacks">
8399
<title>Preedit and Status Callbacks</title>
8400
<!-- .XS -->
8401
<!-- (SN Preedit and Status Callbacks -->
8402
<!-- .XE -->
8403
<para>
8404
<!-- .LP -->
8405
A client that wants to support the input style
8406
<symbol>XIMPreeditCallbacks</symbol>
8407
must provide a set of preedit callbacks to the input method.
8408
The set of preedit callbacks is as follows:
8409
</para>
8410
<indexterm significance="preferred"><primary>XNPreeditStartCallback</primary></indexterm>
8411
<indexterm significance="preferred"><primary>XNPreeditDoneCallback</primary></indexterm>
8412
<indexterm significance="preferred"><primary>XNPreeditDrawCallback</primary></indexterm>
8413
<indexterm significance="preferred"><primary>XNPreeditCaretCallback</primary></indexterm>
8414
<informaltable>
8415
<tgroup cols='2' align='center'>
8416
<colspec colname='c1'/>
8417
<colspec colname='c2'/>
8418
<tbody>
8419
<row>
8420
<entry><symbol>XNPreeditStartCallback</symbol></entry>
8421
<entry>This is called when the input method starts preedit.</entry>
8422
</row>
8423
<row>
8424
<entry><symbol>XNPreeditDoneCallback</symbol></entry>
8425
<entry>This is called when the input method stops preedit.</entry>
8426
</row>
8427
<row>
8428
<entry><symbol>XNPreeditDrawCallback</symbol></entry>
8429
<entry>This is called when a number of preedit keystrokes should be echoed.</entry>
8430
</row>
8431
<row>
8432
<entry><symbol>XNPreeditCaretCallback</symbol></entry>
8433
<entry>This is called to move the text insertion point within the preedit string.</entry>
8434
</row>
8435
</tbody>
8436
</tgroup>
8437
</informaltable>
8438
8439
<para>
8440
<!-- .LP -->
8441
A client that wants to support the input style
8442
<symbol>XIMStatusCallbacks</symbol>
8443
must provide a set of status callbacks to the input method.
8444
The set of status callbacks is as follows:
8445
</para>
8446
8447
<indexterm significance="preferred"><primary>XNStatusStartCallback</primary></indexterm>
8448
<indexterm significance="preferred"><primary>XNStatusDoneCallback</primary></indexterm>
8449
<indexterm significance="preferred"><primary>XNStatusDrawCallback</primary></indexterm>
8450
<informaltable>
8451
<tgroup cols='2' align='center'>
8452
<colspec colname='c1'/>
8453
<colspec colname='c2'/>
8454
<tbody>
8455
<row>
8456
<entry><symbol>XNStatusStartCallback</symbol></entry>
8457
<entry>This is called when the input method initializes the status area.</entry>
8458
</row>
8459
<row>
8460
<entry><symbol>XNStatusDoneCallback</symbol></entry>
8461
<entry>This is called when the input method no longer needs the status area.</entry>
8462
</row>
8463
<row>
8464
<entry><symbol>XNStatusDrawCallback</symbol></entry>
8465
<entry>This is called when updating of the status area is required.</entry>
8466
</row>
8467
</tbody>
8468
</tgroup>
8469
</informaltable>
8470
<para>
8471
<!-- .LP -->
8472
The value of any status or preedit argument is a pointer
8473
to a structure of type
8474
<structname>XIMCallback</structname>.
8475
<indexterm significance="preferred"><primary>XIMProc</primary></indexterm>
8476
<indexterm significance="preferred"><primary>XIMCallback</primary></indexterm>
8477
<!-- .sM -->
8478
</para>
8479
<para>
8480
<!-- .LP -->
8481
<literallayout class="monospaced">
8482
<!-- .TA .5i 2.5i -->
8483
<!-- .ta .5i 2.5i -->
8484
typedef void (*XIMProc)();
8485
8486
typedef struct {
8487
XPointer client_data;
8488
XIMProc callback;
8489
} XIMCallback;
8490
</literallayout>
8491
</para>
8492
<para>
8493
<!-- .LP -->
8494
<!-- .eM -->
8495
Each callback has some particular semantics and will carry the data
8496
that expresses the environment necessary to the client
8497
into a specific data structure.
8498
This paragraph only describes the arguments to be used to set
8499
the callback.
8500
</para>
8501
<para>
8502
<!-- .LP -->
8503
Setting any of these values while doing preedit
8504
may cause unexpected results.
8505
</para>
8506
</sect4>
8507
</sect3>
8508
</sect2>
8509
<sect2 id="Input_Method_Callback_Semantics">
8510
<title>Input Method Callback Semantics</title>
8511
<!-- .XS -->
8512
<!-- (SN Input Method Callback Semantics -->
8513
<!-- .XE -->
8514
<para>
8515
<!-- .LP -->
8516
<acronym>XIM</acronym> callbacks are procedures defined by clients or text drawing packages
8517
that are to be called from the input method when selected events occur.
8518
Most clients will use a text editing package or a toolkit
8519
and, hence, will not need to define such callbacks.
8520
This section defines the callback semantics, when they are triggered,
8521
and what their arguments are.
8522
This information is mostly useful for X toolkit implementors.
8523
</para>
8524
<para>
8525
<!-- .LP -->
8526
Callbacks are mostly provided so that clients (or text editing
8527
packages) can implement on-the-spot preediting in their own window.
8528
In that case,
8529
the input method needs to communicate and synchronize with the client.
8530
The input method needs to communicate changes in the preedit window
8531
when it is under control of the client.
8532
Those callbacks allow the client to initialize the preedit area,
8533
display a new preedit string,
8534
move the text insertion point during preedit,
8535
terminate preedit, or update the status area.
8536
</para>
8537
<para>
8538
<!-- .LP -->
8539
All callback procedures follow the generic prototype:
8540
<indexterm significance="preferred"><primary>CallbackPrototype</primary></indexterm>
8541
<!-- .sM -->
8542
<funcsynopsis>
8543
<funcprototype>
8544
<funcdef>void <function><replaceable>CallbackPrototype</replaceable></function></funcdef>
8545
<paramdef>XIC<parameter> ic</parameter></paramdef>
8546
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
8547
<paramdef>SomeType<parameter> call_data</parameter></paramdef>
8548
</funcprototype>
8549
</funcsynopsis>
8550
<!-- .FN -->
8551
<variablelist>
8552
<varlistentry>
8553
<term>
8554
<emphasis remap='I'>ic</emphasis>
8555
</term>
8556
<listitem>
8557
<para>
8558
Specifies the input context.
8559
</para>
8560
</listitem>
8561
</varlistentry>
8562
<varlistentry>
8563
<term>
8564
<emphasis remap='I'>client_data</emphasis>
8565
</term>
8566
<listitem>
8567
<para>
8568
Specifies the additional client data.
8569
</para>
8570
</listitem>
8571
</varlistentry>
8572
<varlistentry>
8573
<term>
8574
<emphasis remap='I'>call_data</emphasis>
8575
</term>
8576
<listitem>
8577
<para>
8578
Specifies data specific to the callback.
8579
</para>
8580
</listitem>
8581
</varlistentry>
8582
</variablelist>
8583
</para>
8584
<para>
8585
<!-- .LP -->
8586
<!-- .eM -->
8587
The call_data argument is a structure that expresses the arguments needed
8588
to achieve the semantics;
8589
that is,
8590
it is a specific data structure appropriate to the callback.
8591
In cases where no data is needed in the callback,
8592
this call_data argument is NULL.
8593
The client_data argument is a closure that has been initially specified
8594
by the client when specifying the callback and passed back.
8595
It may serve, for example, to inherit application context in the callback.
8596
</para>
8597
<para>
8598
<!-- .LP -->
8599
The following paragraphs describe the programming semantics
8600
and specific data structure associated with the different reasons.
8601
</para>
8602
<sect3 id="Geometry_Callback_b">
8603
<title>Geometry Callback</title>
8604
<!-- .XS -->
8605
<!-- (SN Geometry Callback -->
8606
<!-- .XE -->
8607
<para>
8608
<!-- .LP -->
8609
The geometry callback is triggered by the input method
8610
to indicate that it wants the client to negotiate geometry.
8611
The generic prototype is as follows:
8612
<indexterm significance="preferred"><primary>GeometryCallback</primary></indexterm>
8613
<!-- .sM -->
8614
<funcsynopsis>
8615
<funcprototype>
8616
<funcdef>void <function><replaceable>GeometryCallback</replaceable></function></funcdef>
8617
<paramdef>XIC<parameter> ic</parameter></paramdef>
8618
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
8619
<paramdef>XPointer<parameter> call_data</parameter></paramdef>
8620
</funcprototype>
8621
</funcsynopsis>
8622
<!-- .FN -->
8623
<variablelist>
8624
<varlistentry>
8625
<term>
8626
<emphasis remap='I'>ic</emphasis>
8627
</term>
8628
<listitem>
8629
<para>
8630
Specifies the input context.
8631
</para>
8632
</listitem>
8633
</varlistentry>
8634
<varlistentry>
8635
<term>
8636
<emphasis remap='I'>client_data</emphasis>
8637
</term>
8638
<listitem>
8639
<para>
8640
Specifies the additional client data.
8641
</para>
8642
</listitem>
8643
</varlistentry>
8644
<varlistentry>
8645
<term>
8646
<emphasis remap='I'>call_data</emphasis>
8647
</term>
8648
<listitem>
8649
<para>
8650
Not used for this callback and always passed as NULL.
8651
</para>
8652
</listitem>
8653
</varlistentry>
8654
</variablelist>
8655
</para>
8656
<para>
8657
<!-- .LP -->
8658
<!-- .eM -->
8659
The callback is called with a NULL call_data argument.
8660
</para>
8661
</sect3>
8662
<sect3 id="Destroy_Callback_c">
8663
<title>Destroy Callback</title>
8664
<!-- .XS -->
8665
<!-- (SN Destroy Callback -->
8666
<!-- .XE -->
8667
<para>
8668
<!-- .LP -->
8669
The destroy callback is triggered by the input method
8670
when it stops service for any reason.
8671
After the callback is invoked, the input context will be freed by Xlib.
8672
The generic prototype is as follows:
8673
<indexterm significance="preferred"><primary>DestroyCallback</primary></indexterm>
8674
<!-- .sM -->
8675
<funcsynopsis>
8676
<funcprototype>
8677
<funcdef>void <function><replaceable>DestroyCallback</replaceable></function></funcdef>
8678
<paramdef>XIC<parameter> ic</parameter></paramdef>
8679
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
8680
<paramdef>XPointer<parameter> call_data</parameter></paramdef>
8681
</funcprototype>
8682
</funcsynopsis>
8683
<!-- .FN -->
8684
<variablelist>
8685
<varlistentry>
8686
<term>
8687
<emphasis remap='I'>ic</emphasis>
8688
</term>
8689
<listitem>
8690
<para>
8691
Specifies the input context.
8692
</para>
8693
</listitem>
8694
</varlistentry>
8695
<varlistentry>
8696
<term>
8697
<emphasis remap='I'>client_data</emphasis>
8698
</term>
8699
<listitem>
8700
<para>
8701
Specifies the additional client data.
8702
</para>
8703
</listitem>
8704
</varlistentry>
8705
<varlistentry>
8706
<term>
8707
<emphasis remap='I'>call_data</emphasis>
8708
</term>
8709
<listitem>
8710
<para>
8711
Not used for this callback and always passed as NULL.
8712
</para>
8713
</listitem>
8714
</varlistentry>
8715
</variablelist>
8716
</para>
8717
<para>
8718
<!-- .LP -->
8719
<!-- .eM -->
8720
The callback is called with a NULL call_data argument.
8721
</para>
8722
</sect3>
8723
<sect3 id="String_Conversion_Callback_b">
8724
<title>String Conversion Callback</title>
8725
<!-- .XS -->
8726
<!-- (SN String Conversion Callback -->
8727
<!-- .XE -->
8728
<para>
8729
<!-- .LP -->
8730
The string conversion callback is triggered by the input method
8731
to request the client to return the string to be converted. The
8732
returned string may be either a multibyte or wide character string,
8733
with an encoding matching the locale bound to the input context.
8734
The callback prototype is as follows:
8735
<indexterm significance="preferred"><primary>StringConversionCallback</primary></indexterm>
8736
<!-- .sM -->
8737
<funcsynopsis>
8738
<funcprototype>
8739
<funcdef>void <function><replaceable>StringConversionCallback</replaceable></function></funcdef>
8740
<paramdef>XIC<parameter> ic</parameter></paramdef>
8741
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
8742
<paramdef>XIMStringConversionCallbackStruct<parameter> *call_data</parameter></paramdef>
8743
</funcprototype>
8744
</funcsynopsis>
8745
<!-- .FN -->
8746
<variablelist>
8747
<varlistentry>
8748
<term>
8749
<emphasis remap='I'>ic</emphasis>
8750
</term>
8751
<listitem>
8752
<para>
8753
Specifies the input method.
8754
</para>
8755
</listitem>
8756
</varlistentry>
8757
<varlistentry>
8758
<term>
8759
<emphasis remap='I'>client_data</emphasis>
8760
</term>
8761
<listitem>
8762
<para>
8763
Specifies the additional client data.
8764
</para>
8765
</listitem>
8766
</varlistentry>
8767
<varlistentry>
8768
<term>
8769
<emphasis remap='I'>call_data</emphasis>
8770
</term>
8771
<listitem>
8772
<para>
8773
Specifies the amount of the string to be converted.
8774
</para>
8775
</listitem>
8776
</varlistentry>
8777
</variablelist>
8778
</para>
8779
<para>
8780
<!-- .LP -->
8781
<!-- .eM -->
8782
The callback is passed an
8783
<structname>XIMStringConversionCallbackStruct</structname>
8784
structure in the call_data argument.
8785
The text member is an
8786
<structname>XIMStringConversionText</structname>
8787
structure (see section 13.5.6.9) to be filled in by the client
8788
and describes the text to be sent to the input method.
8789
The data pointed to by the
8790
string and feedback elements of the
8791
<structname>XIMStringConversionText</structname>
8792
structure will be freed using
8793
<function>XFree</function>
8794
by the input method
8795
after the callback returns. So the client should not point to
8796
internal buffers that are critical to the client.
8797
Similarly, because the feedback element is currently reserved for future
8798
use, the client should set feedback to NULL to prevent the library from
8799
freeing memory at some random location due to an uninitialized pointer.
8800
</para>
8801
<para>
8802
<!-- .LP -->
8803
The
8804
<structname>XIMStringConversionCallbackStruct</structname>
8805
structure is defined as follows:
8806
</para>
8807
<para>
8808
<!-- .LP -->
8809
<indexterm significance="preferred"><primary>XIMStringConversionCallbackStruct</primary></indexterm>
8810
<!-- .sM -->
8811
</para>
8812
<!-- .LP -->
8813
<literallayout class="monospaced">
8814
typedef struct _XIMStringConversionCallbackStruct {
8815
XIMStringConversionPosition position;
8816
XIMCaretDirection direction;
8817
short factor;
8818
XIMStringConversionOperation operation;
8819
XIMStringConversionText *text;
8820
} XIMStringConversionCallbackStruct;
8821
8822
typedef short XIMStringConversionPosition;
8823
8824
typedef unsigned short XIMStringConversionOperation;
8825
8826
#define XIMStringConversionSubstitution (0x0001)
8827
#define XIMStringConversionRetrieval (0x0001)
8828
8829
</literallayout>
8830
8831
<para>
8832
<!-- .LP -->
8833
<!-- .eM -->
8834
<type>XIMStringConversionPosition</type>
8835
specifies the starting position of the string to be returned
8836
in the
8837
<structname>XIMStringConversionText</structname>
8838
structure. The value identifies a position, in units of characters,
8839
relative to the client's cursor position in the client's buffer.
8840
</para>
8841
<para>
8842
<!-- .LP -->
8843
The ending position of the text buffer is determined by
8844
the direction and factor members. Specifically, it is the character position
8845
relative to the starting point as defined by the
8846
<structname>XIMCaretDirection</structname>.
8847
The factor member of
8848
<structname>XIMStringConversionCallbackStruct</structname>
8849
specifies the number of
8850
<structname>XIMCaretDirection</structname>
8851
positions to be applied. For example, if the direction specifies
8852
<constant>XIMLineEnd</constant>
8853
and factor is 1, then all characters from the starting position to
8854
the end of the current display line are returned. If the direction
8855
specifies
8856
<constant>XIMForwardChar</constant>
8857
or
8858
<constant>XIMBackwardChar</constant>,
8859
then the factor specifies a relative position, indicated in characters,
8860
from the starting position.
8861
</para>
8862
<para>
8863
<!-- .LP -->
8864
<type>XIMStringConversionOperation</type>
8865
specifies whether the string to be converted should be
8866
deleted (substitution) or copied (retrieval) from the client's
8867
buffer. When the
8868
<type>XIMStringConversionOperation</type>
8869
is
8870
<symbol>XIMStringConversionSubstitution</symbol>,
8871
the client must delete the string to be converted from its own buffer.
8872
When the
8873
<type>XIMStringConversionOperation</type>
8874
is
8875
<symbol>XIMStringConversionRetrieval</symbol>,
8876
the client must not delete the string to be converted from its buffer.
8877
The substitute operation is typically used for reconversion and
8878
transliteration conversion,
8879
while the retrieval operation is typically used for context-sensitive
8880
conversion.
8881
</para>
8882
</sect3>
8883
<sect3 id="Preedit_State_Callbacks">
8884
<title>Preedit State Callbacks</title>
8885
<!-- .XS -->
8886
<!-- (SN Preedit State Callbacks -->
8887
<!-- .XE -->
8888
<para>
8889
<!-- .LP -->
8890
When the input method turns preediting on or off, a
8891
<function><replaceable>PreeditStartCallback</replaceable></function>
8892
or
8893
<function><replaceable>PreeditDoneCallback</replaceable></function>
8894
callback is triggered to let the toolkit do the setup
8895
or the cleanup for the preedit region.
8896
<indexterm significance="preferred"><primary>PreeditStartCallback</primary></indexterm>
8897
<!-- .sM -->
8898
<funcsynopsis>
8899
<funcprototype>
8900
<funcdef>int <function><replaceable>PreeditStartCallback</replaceable></function></funcdef>
8901
<paramdef>XIC<parameter> ic</parameter></paramdef>
8902
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
8903
<paramdef>XPointer<parameter> call_data</parameter></paramdef>
8904
</funcprototype>
8905
</funcsynopsis>
8906
<!-- .FN -->
8907
<variablelist>
8908
<varlistentry>
8909
<term>
8910
<emphasis remap='I'>ic</emphasis>
8911
</term>
8912
<listitem>
8913
<para>
8914
Specifies the input context.
8915
</para>
8916
</listitem>
8917
</varlistentry>
8918
<varlistentry>
8919
<term>
8920
<emphasis remap='I'>client_data</emphasis>
8921
</term>
8922
<listitem>
8923
<para>
8924
Specifies the additional client data.
8925
</para>
8926
</listitem>
8927
</varlistentry>
8928
<varlistentry>
8929
<term>
8930
<emphasis remap='I'>call_data</emphasis>
8931
</term>
8932
<listitem>
8933
<para>
8934
Not used for this callback and always passed as NULL.
8935
</para>
8936
</listitem>
8937
</varlistentry>
8938
</variablelist>
8939
</para>
8940
<para>
8941
<!-- .LP -->
8942
<!-- .eM -->
8943
When preedit starts on the specified input context,
8944
the callback is called with a NULL call_data argument.
8945
<function><replaceable>PreeditStartCallback</replaceable></function>
8946
will return the maximum size of the preedit string.
8947
A positive number indicates the maximum number of bytes allowed
8948
in the preedit string,
8949
and a value of -1 indicates there is no limit.
8950
<indexterm significance="preferred"><primary>PreeditDoneCallback</primary></indexterm>
8951
<!-- .sM -->
8952
<funcsynopsis>
8953
<funcprototype>
8954
<funcdef>void <function><replaceable>PreeditDoneCallback</replaceable></function></funcdef>
8955
<paramdef>XIC<parameter> ic</parameter></paramdef>
8956
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
8957
<paramdef>XPointer<parameter> call_data</parameter></paramdef>
8958
</funcprototype>
8959
</funcsynopsis>
8960
<!-- .FN -->
8961
<variablelist>
8962
<varlistentry>
8963
<term>
8964
<emphasis remap='I'>ic</emphasis>
8965
</term>
8966
<listitem>
8967
<para>
8968
Specifies the input context.
8969
</para>
8970
</listitem>
8971
</varlistentry>
8972
<varlistentry>
8973
<term>
8974
<emphasis remap='I'>client_data</emphasis>
8975
</term>
8976
<listitem>
8977
<para>
8978
Specifies the additional client data.
8979
</para>
8980
</listitem>
8981
</varlistentry>
8982
<varlistentry>
8983
<term>
8984
<emphasis remap='I'>call_data</emphasis>
8985
</term>
8986
<listitem>
8987
<para>
8988
Not used for this callback and always passed as NULL.
8989
</para>
8990
</listitem>
8991
</varlistentry>
8992
</variablelist>
8993
</para>
8994
<para>
8995
<!-- .LP -->
8996
<!-- .eM -->
8997
When preedit stops on the specified input context,
8998
the callback is called with a NULL call_data argument.
8999
The client can release the data allocated by
9000
<function><replaceable>PreeditStartCallback</replaceable></function>.
9001
</para>
9002
<para>
9003
<!-- .LP -->
9004
<function><replaceable>PreeditStartCallback</replaceable></function>
9005
should initialize appropriate data needed for
9006
displaying preedit information and for handling further
9007
<function><replaceable>PreeditDrawCallback</replaceable></function>
9008
calls.
9009
Once
9010
<function><replaceable>PreeditStartCallback</replaceable></function>
9011
is called, it will not be called again before
9012
<function><replaceable>PreeditDoneCallback</replaceable></function>
9013
has been called.
9014
</para>
9015
</sect3>
9016
<sect3 id="Preedit_Draw_Callback">
9017
<title>Preedit Draw Callback</title>
9018
<!-- .XS -->
9019
<!-- (SN Preedit Draw Callback -->
9020
<!-- .XE -->
9021
<para>
9022
<!-- .LP -->
9023
This callback is triggered to draw and insert, delete or replace,
9024
preedit text in the preedit region.
9025
The preedit text may include unconverted input text such as Japanese Kana,
9026
converted text such as Japanese Kanji characters, or characters of both kinds.
9027
That string is either a multibyte or wide character string,
9028
whose encoding matches the locale bound to the input context.
9029
The callback prototype
9030
is as follows:
9031
<indexterm significance="preferred"><primary>PreeditDrawCallback</primary></indexterm>
9032
<!-- .sM -->
9033
<funcsynopsis>
9034
<funcprototype>
9035
<funcdef>void <function><replaceable>PreeditDrawCallback</replaceable></function></funcdef>
9036
<paramdef>XIC<parameter> ic</parameter></paramdef>
9037
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
9038
<paramdef>XIMPreeditDrawCallbackStruct<parameter> *call_data</parameter></paramdef>
9039
</funcprototype>
9040
</funcsynopsis>
9041
<!-- .FN -->
9042
<variablelist>
9043
<varlistentry>
9044
<term>
9045
<emphasis remap='I'>ic</emphasis>
9046
</term>
9047
<listitem>
9048
<para>
9049
Specifies the input context.
9050
</para>
9051
</listitem>
9052
</varlistentry>
9053
<varlistentry>
9054
<term>
9055
<emphasis remap='I'>client_data</emphasis>
9056
</term>
9057
<listitem>
9058
<para>
9059
Specifies the additional client data.
9060
</para>
9061
</listitem>
9062
</varlistentry>
9063
<varlistentry>
9064
<term>
9065
<emphasis remap='I'>call_data</emphasis>
9066
</term>
9067
<listitem>
9068
<para>
9069
Specifies the preedit drawing information.
9070
</para>
9071
</listitem>
9072
</varlistentry>
9073
</variablelist>
9074
</para>
9075
<para>
9076
<!-- .LP -->
9077
<!-- .eM -->
9078
The callback is passed an
9079
<structname>XIMPreeditDrawCallbackStruct</structname>
9080
structure in the call_data argument.
9081
The text member of this structure contains the text to be drawn.
9082
After the string has been drawn,
9083
the caret should be moved to the specified location.
9084
</para>
9085
<para>
9086
<!-- .LP -->
9087
The
9088
<structname>XIMPreeditDrawCallbackStruct</structname>
9089
structure is defined as follows:
9090
</para>
9091
<para>
9092
<!-- .LP -->
9093
<indexterm significance="preferred"><primary>XIMPreeditDrawCallbackStruct</primary></indexterm>
9094
<!-- .sM -->
9095
<literallayout class="monospaced">
9096
<!-- .TA .5i 2.5i -->
9097
<!-- .ta .5i 2.5i -->
9098
typedef struct _XIMPreeditDrawCallbackStruct {
9099
int caret; /* Cursor offset within preedit string */
9100
int chg_first; /* Starting change position */
9101
int chg_length; /* Length of the change in character count */
9102
XIMText *text;
9103
} XIMPreeditDrawCallbackStruct;
9104
</literallayout>
9105
</para>
9106
<para>
9107
<!-- .LP -->
9108
<!-- .eM -->
9109
The client must keep updating a buffer of the preedit text
9110
and the callback arguments referring to indexes in that buffer.
9111
The call_data fields have specific meanings according to the operation,
9112
as follows:
9113
</para>
9114
<itemizedlist>
9115
<listitem>
9116
<para>
9117
To indicate text deletion,
9118
the call_data member specifies a NULL text field.
9119
The text to be deleted is then the current text in the buffer
9120
from position chg_first (starting at zero) on a character length
9121
of chg_length.
9122
</para>
9123
</listitem>
9124
<listitem>
9125
<para>
9126
When text is non-NULL,
9127
it indicates insertion or replacement of text in the buffer.
9128
</para>
9129
</listitem>
9130
<listitem>
9131
<para>
9132
The chg_length member
9133
identifies the number of characters in the current preedit buffer
9134
that are affected by this call.
9135
A positive chg_length indicates that chg_length number of characters, starting
9136
at chg_first, must be deleted or must be replaced by text, whose length is
9137
specified in the
9138
<structname>XIMText</structname>
9139
structure.
9140
</para>
9141
</listitem>
9142
<listitem>
9143
<para>
9144
A chg_length value of zero indicates that text must be inserted
9145
right at the position specified by chg_first.
9146
A value of zero for chg_first specifies the first character in the buffer.
9147
</para>
9148
</listitem>
9149
<listitem>
9150
<para>
9151
chg_length and chg_first combine to identify the modification required to
9152
the preedit buffer; beginning at chg_first, replace chg_length number of
9153
characters with the text in the supplied
9154
<structname>XIMText</structname>
9155
structure. For example, suppose the preedit buffer contains the string "ABCDE".
9156
</para>
9157
</listitem>
9158
<listitem>
9159
<para>
9160
<literallayout class="monospaced">
9161
<!-- .ft C -->
9162
Text: A B C D E
9163
^ ^ ^ ^ ^ ^
9164
CharPos: 0 1 2 3 4 5
9165
<!-- .sp -->
9166
<!-- .ft P -->
9167
</literallayout>
9168
The CharPos in the diagram shows the location of the character position
9169
relative to the character.
9170
</para>
9171
</listitem>
9172
<listitem>
9173
<para>
9174
If the value of chg_first is 1 and the value of chg_length is 3, this
9175
says to replace 3 characters beginning at character position 1 with the
9176
string in the
9177
<structname>XIMText</structname>
9178
structure.
9179
Hence, <acronym>BCD</acronym> would be replaced by the value in the structure.
9180
</para>
9181
</listitem>
9182
<listitem>
9183
<para>
9184
Though chg_length and chg_first are both signed integers they will
9185
never have a negative value.
9186
</para>
9187
</listitem>
9188
<listitem>
9189
<para>
9190
The caret member
9191
identifies the character position before which the cursor should
9192
be placed - after modification to the preedit buffer has been completed.
9193
For example, if caret is zero, the cursor is at
9194
the beginning of the buffer. If the caret is one, the cursor is between
9195
the first and second character.
9196
</para>
9197
</listitem>
9198
</itemizedlist>
9199
<para>
9200
<!-- .LP -->
9201
<indexterm significance="preferred"><primary>XIMText</primary></indexterm>
9202
<!-- .sM -->
9203
<literallayout class="monospaced">
9204
<!-- .TA .5i 1.5i 3i -->
9205
typedef struct _XIMText {
9206
unsigned short length;
9207
XIMFeedback * feedback;
9208
Bool encoding_is_wchar;
9209
union {
9210
char * multi_byte;
9211
wchar_t * wide_char;
9212
} string;
9213
} XIMText;
9214
</literallayout>
9215
</para>
9216
<para>
9217
<!-- .LP -->
9218
<!-- .eM -->
9219
The text string passed is actually a structure specifying as follows:
9220
</para>
9221
<itemizedlist>
9222
<listitem>
9223
<para>
9224
The length member is the text length in characters.
9225
</para>
9226
</listitem>
9227
<listitem>
9228
<para>
9229
The encoding_is_wchar member is a value that indicates
9230
if the text string is encoded in wide character or multibyte format.
9231
The text string may be passed either as multibyte or as wide character;
9232
the input method controls in which form data is passed.
9233
The client's
9234
callback routine must be able to handle data passed in either form.
9235
</para>
9236
</listitem>
9237
<listitem>
9238
<para>
9239
The string member is the text string.
9240
</para>
9241
</listitem>
9242
<listitem>
9243
<para>
9244
The feedback member indicates rendering type for each character in the
9245
string member.
9246
If string is NULL (indicating that only highlighting of the existing
9247
preedit buffer should be updated), feedback points to length highlight
9248
elements that should be applied to the existing preedit buffer, beginning
9249
at chg_first.
9250
</para>
9251
</listitem>
9252
</itemizedlist>
9253
<para>
9254
<!-- .LP -->
9255
The feedback member expresses the types of rendering feedback
9256
the callback should apply when drawing text.
9257
Rendering of the text to be drawn is specified either in generic ways
9258
(for example, primary, secondary) or in specific ways (reverse, underline).
9259
When generic indications are given,
9260
the client is free to choose the rendering style.
9261
It is necessary, however, that primary and secondary be mapped
9262
to two distinct rendering styles.
9263
</para>
9264
<para>
9265
<!-- .LP -->
9266
If an input method wants to control display of the preedit string, an
9267
input method can indicate the visibility hints using feedbacks in
9268
a specific way.
9269
The
9270
<symbol>XIMVisibleToForward</symbol>,
9271
<symbol>XIMVisibleToBackword</symbol>,
9272
and
9273
<symbol>XIMVisibleToCenter</symbol>
9274
masks are exclusively used for these visibility hints.
9275
The
9276
<symbol>XIMVisibleToForward</symbol>
9277
mask
9278
indicates that the preedit text is preferably displayed in the
9279
primary draw direction from the
9280
caret position in the preedit area forward.
9281
The
9282
<symbol>XIMVisibleToBackword</symbol>
9283
mask
9284
indicates that the preedit text is preferably displayed from
9285
the caret position in the preedit area backward, relative to the primary
9286
draw direction.
9287
The
9288
<symbol>XIMVisibleToCenter</symbol>
9289
mask
9290
indicates that the preedit text is preferably displayed with
9291
the caret position in the preedit area centered.
9292
</para>
9293
<para>
9294
<!-- .LP -->
9295
The insertion point of the preedit string could exist outside of
9296
the visible area when visibility hints are used.
9297
Only one of the
9298
masks
9299
is valid for the entire preedit string, and only one character
9300
can hold one of these feedbacks for a given input context at one time.
9301
This feedback may be OR'ed together with another highlight (such as
9302
<symbol>XIMReverse</symbol>).
9303
Only the most recently set feedback is valid, and any previous
9304
feedback is automatically canceled. This is a hint to the client, and
9305
the client is free to choose how to display the preedit string.
9306
</para>
9307
<para>
9308
<!-- .LP -->
9309
The feedback member also specifies how rendering of the text argument
9310
should be performed.
9311
If the feedback is NULL,
9312
the callback should apply the same feedback as is used for the surrounding
9313
characters in the preedit buffer; if chg_first is at a highlight boundary,
9314
the client can choose which of the two highlights to use.
9315
If feedback is not NULL, feedback specifies an array defining the
9316
rendering for each
9317
character of the string, and the length of the array is thus length.
9318
</para>
9319
<para>
9320
<!-- .LP -->
9321
If an input method wants to indicate that it is only updating the feedback of
9322
the preedit text without changing the content of it,
9323
the
9324
<structname>XIMText</structname>
9325
structure will contain a NULL value for the string field,
9326
the number of characters affected (relative to chg_first)
9327
will be in the length field,
9328
and the feedback field will point to an array of
9329
<type>XIMFeedback</type>.
9330
</para>
9331
<para>
9332
<!-- .LP -->
9333
Each element in the feedback array is a bitmask represented by a value of type
9334
<type>XIMFeedback</type>.
9335
The valid mask names are as follows:
9336
</para>
9337
<para>
9338
<!-- .LP -->
9339
<indexterm significance="preferred"><primary>XIMReverse</primary></indexterm>
9340
<indexterm significance="preferred"><primary>XIMUnderline</primary></indexterm>
9341
<indexterm significance="preferred"><primary>XIMHighlight</primary></indexterm>
9342
<indexterm significance="preferred"><primary>XIMPrimary</primary></indexterm>
9343
<indexterm significance="preferred"><primary>XIMSecondary</primary></indexterm>
9344
<indexterm significance="preferred"><primary>XIMTertiary</primary></indexterm>
9345
<indexterm significance="preferred"><primary>XIMVisibleToForward</primary></indexterm>
9346
<indexterm significance="preferred"><primary>XIMVisibleToBackward</primary></indexterm>
9347
<indexterm significance="preferred"><primary>XIMVisibleToCenter</primary></indexterm>
9348
<!-- .sM -->
9349
</para>
9350
<literallayout class="monospaced">
9351
typedef unsigned long XIMFeedback;
9352
9353
#define XIMReverse 1L
9354
#define XIMUnderline (1L<<1)
9355
#define XIMHighlight (1L<<2)
9356
#define XIMPrimary (1L<<5)*
9357
#define XIMSecondary (1L<<6)*
9358
#define XIMTertiary (1L<<7)*
9359
#define XIMVisibleToForward (1L<<8)
9360
#define XIMVisibleToBackward (1L<<9)
9361
#define XIMVisibleToCenter (1L<<10)
9362
9363
*† The values for XIMPrimary, XIMSecondary, and XIMTertiary were incorrectly defined in
9364
the R5 specification. The X Consortium’s X11R5 implementation correctly implemented the val-
9365
ues for these highlights. The value of these highlights has been corrected in this specification to
9366
agree with the values in the Consortium’s X11R5 and X11R6 implementations.
9367
9368
</literallayout>
9369
9370
<para>
9371
<!-- .LP -->
9372
Characters drawn with the
9373
<symbol>XIMReverse</symbol>
9374
highlight should be drawn by swapping the foreground and background colors
9375
used to draw normal, unhighlighted characters.
9376
Characters drawn with the
9377
<symbol>XIMUnderline</symbol>
9378
highlight should be underlined.
9379
Characters drawn with the
9380
<symbol>XIMHighlight</symbol>,
9381
<symbol>XIMPrimary</symbol>,
9382
<symbol>XIMSecondary</symbol>,
9383
and
9384
<symbol>XIMTertiary</symbol>
9385
highlights should be drawn in some unique manner that must be different
9386
from
9387
<symbol>XIMReverse</symbol>
9388
and
9389
<symbol>XIMUnderline</symbol>.
9390
<!-- .FS \(dg -->
9391
The values for
9392
<symbol>XIMPrimary</symbol>,
9393
<symbol>XIMSecondary</symbol>,
9394
and
9395
<symbol>XIMTertiary</symbol>
9396
were incorrectly defined in the R5 specification.
9397
The X Consortium's X11R5
9398
implementation correctly implemented the values for these highlights.
9399
The value of these highlights has been corrected in this specification
9400
to agree with the values in the Consortium's X11R5 and X11R6 implementations.
9401
<!-- .FE -->
9402
</para>
9403
</sect3>
9404
<sect3 id="Preedit_Caret_Callback">
9405
<title>Preedit Caret Callback</title>
9406
<!-- .XS -->
9407
<!-- (SN Preedit Caret Callback -->
9408
<!-- .XE -->
9409
<para>
9410
<!-- .LP -->
9411
An input method may have its own navigation keys to allow the user
9412
to move the text insertion point in the preedit area
9413
(for example, to move backward or forward).
9414
Consequently, input method needs to indicate to the client that it
9415
should move the text insertion point.
9416
It then calls the PreeditCaretCallback.
9417
<indexterm significance="preferred"><primary>PreeditCaretCallback</primary></indexterm>
9418
<!-- .sM -->
9419
<funcsynopsis>
9420
<funcprototype>
9421
<funcdef>void <function><replaceable>PreeditCaretCallback</replaceable></function></funcdef>
9422
<paramdef>XIC<parameter> ic</parameter></paramdef>
9423
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
9424
<paramdef>XIMPreeditCaretCallbackStruct<parameter> *call_data</parameter></paramdef>
9425
</funcprototype>
9426
</funcsynopsis>
9427
<!-- .FN -->
9428
<variablelist>
9429
<varlistentry>
9430
<term>
9431
<emphasis remap='I'>ic</emphasis>
9432
</term>
9433
<listitem>
9434
<para>
9435
Specifies the input context.
9436
</para>
9437
</listitem>
9438
</varlistentry>
9439
<varlistentry>
9440
<term>
9441
<emphasis remap='I'>client_data</emphasis>
9442
</term>
9443
<listitem>
9444
<para>
9445
Specifies the additional client data.
9446
</para>
9447
</listitem>
9448
</varlistentry>
9449
<varlistentry>
9450
<term>
9451
<emphasis remap='I'>call_data</emphasis>
9452
</term>
9453
<listitem>
9454
<para>
9455
Specifies the preedit caret information.
9456
</para>
9457
</listitem>
9458
</varlistentry>
9459
</variablelist>
9460
</para>
9461
<para>
9462
<!-- .LP -->
9463
<!-- .eM -->
9464
The input method will trigger PreeditCaretCallback
9465
to move the text insertion point during preedit.
9466
The call_data argument contains a pointer to an
9467
<structname>XIMPreeditCaretCallbackStruct</structname>
9468
structure,
9469
which indicates where the caret should be moved.
9470
The callback must move the insertion point to its new location
9471
and return, in field position, the new offset value from the initial position.
9472
</para>
9473
<para>
9474
<!-- .LP -->
9475
The
9476
<structname>XIMPreeditCaretCallbackStruct</structname>
9477
structure is defined as follows:
9478
<indexterm significance="preferred"><primary>XIMPreeditCaretCallbackStruct</primary></indexterm>
9479
</para>
9480
<para>
9481
<!-- .LP -->
9482
<!-- .sM -->
9483
<literallayout class="monospaced">
9484
<!-- .TA .5i 2.5i -->
9485
<!-- .ta .5i 2.5i -->
9486
typedef struct _XIMPreeditCaretCallbackStruct {
9487
int position; /* Caret offset within preedit string */
9488
XIMCaretDirection direction; /* Caret moves direction */
9489
XIMCaretStyle style; /* Feedback of the caret */
9490
} XIMPreeditCaretCallbackStruct;
9491
</literallayout>
9492
</para>
9493
<para>
9494
<!-- .LP -->
9495
<!-- .eM -->
9496
The
9497
<structname>XIMCaretStyle</structname>
9498
structure is defined as follows:
9499
</para>
9500
<para>
9501
<!-- .LP -->
9502
<indexterm significance="preferred"><primary>XIMCaretStyle</primary></indexterm>
9503
<!-- .sM -->
9504
<literallayout class="monospaced">
9505
<!-- .TA .5i 2.5i -->
9506
<!-- .ta .5i 2.5i -->
9507
typedef enum {
9508
XIMIsInvisible, /* Disable caret feedback */
9509
XIMIsPrimary, /* <acronym>UI</acronym> defined caret feedback */
9510
XIMIsSecondary, /* <acronym>UI</acronym> defined caret feedback */
9511
} XIMCaretStyle;
9512
</literallayout>
9513
</para>
9514
<para>
9515
<!-- .LP -->
9516
<!-- .eM -->
9517
The
9518
<structname>XIMCaretDirection</structname>
9519
structure is defined as follows:
9520
<indexterm significance="preferred"><primary>XIMCaretDirection</primary></indexterm>
9521
</para>
9522
<para>
9523
<!-- .LP -->
9524
<!-- .sM -->
9525
<literallayout class="monospaced">
9526
<!-- .TA .5i 2.5i -->
9527
<!-- .ta .5i 2.5i -->
9528
typedef enum {
9529
XIMForwardChar, XIMBackwardChar,
9530
XIMForwardWord, XIMBackwardWord,
9531
XIMCaretUp, XIMCaretDown,
9532
XIMNextLine, XIMPreviousLine,
9533
XIMLineStart, XIMLineEnd,
9534
XIMAbsolutePosition,
9535
XIMDontChange,
9536
} XIMCaretDirection;
9537
</literallayout>
9538
</para>
9539
<para>
9540
<!-- .LP -->
9541
<!-- .eM -->
9542
These values are defined as follows:
9543
</para>
9544
<indexterm significance="preferred"><primary>XIMForwardChar</primary></indexterm>
9545
<indexterm significance="preferred"><primary>XIMBackwardChar</primary></indexterm>
9546
<indexterm significance="preferred"><primary>XIMForwardWord</primary></indexterm>
9547
<indexterm significance="preferred"><primary>XIMBackwardWord</primary></indexterm>
9548
<indexterm significance="preferred"><primary>XIMCaretUp</primary></indexterm>
9549
<indexterm significance="preferred"><primary>XIMCaretDown</primary></indexterm>
9550
<informaltable>
9551
<tgroup cols='2' align='center'>
9552
<colspec colname='c1'/>
9553
<colspec colname='c2'/>
9554
<tbody>
9555
<row>
9556
<entry><constant>XIMForwardChar</constant></entry>
9557
<entry>Move the caret forward one character position.</entry>
9558
</row>
9559
<row>
9560
<entry><constant>XIMBackwardChar</constant></entry>
9561
<entry>Move the caret backward one character position.</entry>
9562
</row>
9563
<row>
9564
<entry><constant>XIMForwardWord</constant></entry>
9565
<entry>Move the caret forward one word.</entry>
9566
</row>
9567
<row>
9568
<entry><constant>XIMBackwardWord</constant></entry>
9569
<entry>Move the caret backward one word.</entry>
9570
</row>
9571
<row>
9572
<entry><constant>XIMCaretUp</constant></entry>
9573
<entry>Move the caret up one line keeping the current horizontal offset.</entry>
9574
</row>
9575
<row>
9576
<entry><constant>XIMCaretDown</constant></entry>
9577
<entry>Move the caret down one line keeping the current horizontal offset.</entry>
9578
</row>
9579
<row>
9580
<entry><constant>XIMPreviousLine</constant></entry>
9581
<entry>Move the caret to the beginning of the previous line.</entry>
9582
</row>
9583
<row>
9584
<entry><constant>XIMNextLine</constant></entry>
9585
<entry>Move the caret to the beginning of the next line.</entry>
9586
</row>
9587
<row>
9588
<entry><constant>XIMLineStart</constant></entry>
9589
<entry>Move the caret to the beginning of the current display line that contains the caret.</entry>
9590
</row>
9591
<row>
9592
<entry><constant>XIMLineEnd</constant></entry>
9593
<entry>Move the caret to the end of the current display line that contains the caret.</entry>
9594
</row>
9595
<row>
9596
<entry><constant>XIMAbsolutePosition</constant></entry>
9597
<entry>The callback must move to the location specified by the position field
9598
of the callback data, indicated in characters, starting from the beginning
9599
of the preedit text.
9600
Hence, a value of zero means move back to the beginning of the preedit text.</entry>
9601
</row>
9602
<row>
9603
<entry><constant>XIMDontChange</constant></entry>
9604
<entry>The caret position does not change.</entry>
9605
</row>
9606
</tbody>
9607
</tgroup>
9608
</informaltable>
9609
9610
<indexterm significance="preferred"><primary>XIMNextLine</primary></indexterm>
9611
<indexterm significance="preferred"><primary>XIMPreviousLine</primary></indexterm>
9612
<indexterm significance="preferred"><primary>XIMLineStart</primary></indexterm>
9613
<indexterm significance="preferred"><primary>XIMLineEnd</primary></indexterm>
9614
<indexterm significance="preferred"><primary>XIMAbsolutePosition</primary></indexterm>
9615
<indexterm significance="preferred"><primary>XIMDontChange</primary></indexterm>
9616
</sect3>
9617
<sect3 id="Status_Callbacks">
9618
<title>Status Callbacks</title>
9619
<!-- .XS -->
9620
<!-- (SN Status Callbacks -->
9621
<!-- .XE -->
9622
<para>
9623
<!-- .LP -->
9624
An input method may communicate changes in the status of an input context
9625
(for example, created, destroyed, or focus changes) with three status
9626
callbacks: StatusStartCallback, StatusDoneCallback, and StatusDrawCallback.
9627
</para>
9628
<para>
9629
<!-- .LP -->
9630
<!-- .sp -->
9631
When the input context is created or gains focus,
9632
the input method calls the StatusStartCallback callback.
9633
<indexterm significance="preferred"><primary>StatusStartCallback</primary></indexterm>
9634
<!-- .sM -->
9635
<funcsynopsis>
9636
<funcprototype>
9637
<funcdef>void <function><replaceable>StatusStartCallback</replaceable></function></funcdef>
9638
<paramdef>XIC<parameter> ic</parameter></paramdef>
9639
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
9640
<paramdef>XPointer<parameter> call_data</parameter></paramdef>
9641
</funcprototype>
9642
</funcsynopsis>
9643
<!-- .FN -->
9644
<variablelist>
9645
<varlistentry>
9646
<term>
9647
<emphasis remap='I'>ic</emphasis>
9648
</term>
9649
<listitem>
9650
<para>
9651
Specifies the input context.
9652
</para>
9653
</listitem>
9654
</varlistentry>
9655
<varlistentry>
9656
<term>
9657
<emphasis remap='I'>client_data</emphasis>
9658
</term>
9659
<listitem>
9660
<para>
9661
Specifies the additional client data.
9662
</para>
9663
</listitem>
9664
</varlistentry>
9665
<varlistentry>
9666
<term>
9667
<emphasis remap='I'>call_data</emphasis>
9668
</term>
9669
<listitem>
9670
<para>
9671
Not used for this callback and always passed as NULL.
9672
</para>
9673
</listitem>
9674
</varlistentry>
9675
</variablelist>
9676
</para>
9677
<para>
9678
<!-- .LP -->
9679
<!-- .eM -->
9680
The callback should initialize appropriate data for displaying status
9681
and for responding to StatusDrawCallback calls.
9682
Once StatusStartCallback is called,
9683
it will not be called again before StatusDoneCallback has been called.
9684
</para>
9685
<para>
9686
<!-- .LP -->
9687
<!-- .sp -->
9688
When an input context
9689
is destroyed or when it loses focus, the input method calls StatusDoneCallback.
9690
<indexterm significance="preferred"><primary>StatusDoneCallback</primary></indexterm>
9691
<!-- .sM -->
9692
<funcsynopsis>
9693
<funcprototype>
9694
<funcdef>void <function><replaceable>StatusDoneCallback</replaceable></function></funcdef>
9695
<paramdef>XIC<parameter> ic</parameter></paramdef>
9696
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
9697
<paramdef>XPointer<parameter> call_data</parameter></paramdef>
9698
</funcprototype>
9699
</funcsynopsis>
9700
<!-- .FN -->
9701
<variablelist>
9702
<varlistentry>
9703
<term>
9704
<emphasis remap='I'>ic</emphasis>
9705
</term>
9706
<listitem>
9707
<para>
9708
Specifies the input context.
9709
</para>
9710
</listitem>
9711
</varlistentry>
9712
<varlistentry>
9713
<term>
9714
<emphasis remap='I'>client_data</emphasis>
9715
</term>
9716
<listitem>
9717
<para>
9718
Specifies the additional client data.
9719
</para>
9720
</listitem>
9721
</varlistentry>
9722
<varlistentry>
9723
<term>
9724
<emphasis remap='I'>call_data</emphasis>
9725
</term>
9726
<listitem>
9727
<para>
9728
Not used for this callback and always passed as NULL.
9729
</para>
9730
</listitem>
9731
</varlistentry>
9732
</variablelist>
9733
</para>
9734
<para>
9735
<!-- .LP -->
9736
<!-- .eM -->
9737
The callback may release any data allocated on
9738
<function>StatusStart</function>.
9739
</para>
9740
<para>
9741
<!-- .LP -->
9742
<!-- .sp -->
9743
When an input context status has to be updated, the input method calls
9744
StatusDrawCallback.
9745
<indexterm significance="preferred"><primary>StatusDrawCallback</primary></indexterm>
9746
<!-- .sM -->
9747
<funcsynopsis>
9748
<funcprototype>
9749
<funcdef>void <function><replaceable>StatusDrawCallback</replaceable></function></funcdef>
9750
<paramdef>XIC<parameter> ic</parameter></paramdef>
9751
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
9752
<paramdef>XIMStatusDrawCallbackStruct<parameter> *call_data</parameter></paramdef>
9753
</funcprototype>
9754
</funcsynopsis>
9755
<!-- .FN -->
9756
<variablelist>
9757
<varlistentry>
9758
<term>
9759
<emphasis remap='I'>ic</emphasis>
9760
</term>
9761
<listitem>
9762
<para>
9763
Specifies the input context.
9764
</para>
9765
</listitem>
9766
</varlistentry>
9767
<varlistentry>
9768
<term>
9769
<emphasis remap='I'>client_data</emphasis>
9770
</term>
9771
<listitem>
9772
<para>
9773
Specifies the additional client data.
9774
</para>
9775
</listitem>
9776
</varlistentry>
9777
<varlistentry>
9778
<term>
9779
<emphasis remap='I'>call_data</emphasis>
9780
</term>
9781
<listitem>
9782
<para>
9783
Specifies the status drawing information.
9784
</para>
9785
</listitem>
9786
</varlistentry>
9787
</variablelist>
9788
</para>
9789
<para>
9790
<!-- .LP -->
9791
<!-- .eM -->
9792
The callback should update the status area by either drawing a string
9793
or imaging a bitmap in the status area.
9794
</para>
9795
<para>
9796
<!-- .LP -->
9797
The
9798
<structname>XIMStatusDataType</structname>
9799
and
9800
<structname>XIMStatusDrawCallbackStruct</structname>
9801
structures are defined as follows:
9802
<indexterm significance="preferred"><primary>XIMStatusDataType</primary></indexterm>
9803
<indexterm significance="preferred"><primary>XIMStatusDrawCallbackStruct</primary></indexterm>
9804
</para>
9805
<para>
9806
<!-- .LP -->
9807
<!-- .sM -->
9808
<literallayout class="monospaced">
9809
<!-- .TA .5i 1i 3i -->
9810
<!-- .ta .5i 1i 3i -->
9811
typedef enum {
9812
XIMTextType,
9813
XIMBitmapType,
9814
} XIMStatusDataType;
9815
9816
typedef struct _XIMStatusDrawCallbackStruct {
9817
XIMStatusDataType type;
9818
union {
9819
XIMText *text;
9820
Pixmap bitmap;
9821
} data;
9822
} XIMStatusDrawCallbackStruct;
9823
</literallayout>
9824
</para>
9825
<para>
9826
<!-- .LP -->
9827
<!-- .eM -->
9828
</para>
9829
<para>
9830
<!-- .LP -->
9831
The feedback styles
9832
<symbol>XIMVisibleToForward</symbol>,
9833
<symbol>XIMVisibleToBackword</symbol>,
9834
and
9835
<symbol>XIMVisibleToCenter</symbol>
9836
are not relevant and will not appear in the
9837
<type>XIMFeedback</type>
9838
element of the
9839
<structname>XIMText</structname>
9840
structure.
9841
</para>
9842
<para>
9843
<!-- .LP -->
9844
</para>
9845
</sect3>
9846
</sect2>
9847
<sect2 id="Event_Filtering_b">
9848
<title>Event Filtering</title>
9849
<!-- .XS -->
9850
<!-- (SN Event Filtering -->
9851
<!-- .XE -->
9852
<para>
9853
<!-- .LP -->
9854
Xlib provides the ability for an input method
9855
to register a filter internal to Xlib.
9856
This filter is called by a client (or toolkit) by calling
9857
<function>XFilterEvent</function>
9858
after calling
9859
<function>XNextEvent</function>.
9860
Any client that uses the
9861
<type>XIM</type>
9862
interface should call
9863
<function>XFilterEvent</function>
9864
to allow input methods to process their events without knowledge
9865
of the client's dispatching mechanism.
9866
A client's user interface policy may determine the priority
9867
of event filters with respect to other event-handling mechanisms
9868
(for example, modal grabs).
9869
</para>
9870
<para>
9871
<!-- .LP -->
9872
Clients may not know how many filters there are, if any,
9873
and what they do.
9874
They may only know if an event has been filtered on return of
9875
<function>XFilterEvent</function>.
9876
Clients should discard filtered events.
9877
<!-- .sp -->
9878
</para>
9879
<para>
9880
<!-- .LP -->
9881
To filter an event, use
9882
<function>XFilterEvent</function>.
9883
<indexterm significance="preferred"><primary>XFilterEvent</primary></indexterm>
9884
<!-- .sM -->
9885
<funcsynopsis>
9886
<funcprototype>
9887
<funcdef>Bool <function>XFilterEvent</function></funcdef>
9888
<paramdef>XEvent<parameter> *event</parameter></paramdef>
9889
<paramdef>Window<parameter> w</parameter></paramdef>
9890
</funcprototype>
9891
</funcsynopsis>
9892
<!-- .FN -->
9893
<!-- .ds Ev event to filter -->
9894
<variablelist>
9895
<varlistentry>
9896
<term>
9897
<emphasis remap='I'>event</emphasis>
9898
</term>
9899
<listitem>
9900
<para>
9901
Specifies the (Ev.
9902
<!-- .ds Wi for which the filter is to be applied -->
9903
</para>
9904
</listitem>
9905
</varlistentry>
9906
<varlistentry>
9907
<term>
9908
<emphasis remap='I'>w</emphasis>
9909
</term>
9910
<listitem>
9911
<para>
9912
Specifies the window (Wi.
9913
</para>
9914
</listitem>
9915
</varlistentry>
9916
</variablelist>
9917
</para>
9918
<para>
9919
<!-- .LP -->
9920
<!-- .eM -->
9921
If the window argument is
9922
<symbol>None</symbol>,
9923
<function>XFilterEvent</function>
9924
applies the filter to the window specified in the
9925
<structname>XEvent</structname>
9926
structure.
9927
The window argument is provided so that layers above Xlib
9928
that do event redirection can indicate to which window an event
9929
has been redirected.
9930
</para>
9931
<para>
9932
<!-- .LP -->
9933
If
9934
<function>XFilterEvent</function>
9935
returns
9936
<symbol>True</symbol>,
9937
then some input method has filtered the event,
9938
and the client should discard the event.
9939
If
9940
<function>XFilterEvent</function>
9941
returns
9942
<symbol>False</symbol>,
9943
then the client should continue processing the event.
9944
</para>
9945
<para>
9946
<!-- .LP -->
9947
If a grab has occurred in the client and
9948
<function>XFilterEvent</function>
9949
returns
9950
<symbol>True</symbol>,
9951
the client should ungrab the keyboard.
9952
</para>
9953
</sect2>
9954
<sect2 id="Getting_Keyboard_Input_b">
9955
<title>Getting Keyboard Input</title>
9956
<!-- .XS -->
9957
<!-- (SN Getting Keyboard Input -->
9958
<!-- .XE -->
9959
<para>
9960
<!-- .LP -->
9961
To get composed input from an input method,
9962
use
9963
<function>XmbLookupString</function>
9964
or
9965
<function>XwcLookupString</function>.
9966
<indexterm significance="preferred"><primary>XmbLookupString</primary></indexterm>
9967
<indexterm significance="preferred"><primary>XwcLookupString</primary></indexterm>
9968
<!-- .sM -->
9969
<funcsynopsis>
9970
<funcprototype>
9971
<funcdef>int <function>XmbLookupString</function></funcdef>
9972
<paramdef>XIC<parameter> ic</parameter></paramdef>
9973
<paramdef>XKeyPressedEvent<parameter> *event</parameter></paramdef>
9974
<paramdef>char<parameter> *buffer_return</parameter></paramdef>
9975
<paramdef>int<parameter> bytes_buffer</parameter></paramdef>
9976
<paramdef>KeySym<parameter> *keysym_return</parameter></paramdef>
9977
<paramdef>Status<parameter> *status_return</parameter></paramdef>
9978
</funcprototype>
9979
</funcsynopsis>
9980
<!-- .FN -->
9981
<funcsynopsis>
9982
<funcprototype>
9983
<funcdef>int <function>XwcLookupString</function></funcdef>
9984
<paramdef>XIC<parameter> ic</parameter></paramdef>
9985
<paramdef>XKeyPressedEvent<parameter> *event</parameter></paramdef>
9986
<paramdef>wchar_t<parameter> *buffer_return</parameter></paramdef>
9987
<paramdef>int<parameter> wchars_buffer</parameter></paramdef>
9988
<paramdef>KeySym<parameter> *keysym_return</parameter></paramdef>
9989
<paramdef>Status<parameter> *status_return</parameter></paramdef>
9990
</funcprototype>
9991
</funcsynopsis>
9992
<!-- .FN -->
9993
<variablelist>
9994
<varlistentry>
9995
<term>
9996
<emphasis remap='I'>ic</emphasis>
9997
</term>
9998
<listitem>
9999
<para>
10000
Specifies the input context.
10001
<!-- .ds Ev key event to be used -->
10002
</para>
10003
</listitem>
10004
</varlistentry>
10005
<varlistentry>
10006
<term>
10007
<emphasis remap='I'>event</emphasis>
10008
</term>
10009
<listitem>
10010
<para>
10011
Specifies the (Ev.
10012
</para>
10013
</listitem>
10014
</varlistentry>
10015
<varlistentry>
10016
<term>
10017
<emphasis remap='I'>buffer_return</emphasis>
10018
</term>
10019
<listitem>
10020
<para>
10021
Returns a multibyte string or wide character string (if any)
10022
from the input method.
10023
</para>
10024
</listitem>
10025
</varlistentry>
10026
<varlistentry>
10027
<term>
10028
<emphasis remap='I'>bytes_buffer</emphasis>
10029
</term>
10030
<listitem>
10031
<para>
10032
<!-- .br -->
10033
<!-- .ns -->
10034
</para>
10035
</listitem>
10036
</varlistentry>
10037
<varlistentry>
10038
<term>
10039
<emphasis remap='I'>wchars_buffer</emphasis>
10040
</term>
10041
<listitem>
10042
<para>
10043
Specifies space available in the return buffer.
10044
</para>
10045
</listitem>
10046
</varlistentry>
10047
<varlistentry>
10048
<term>
10049
<emphasis remap='I'>keysym_return</emphasis>
10050
</term>
10051
<listitem>
10052
<para>
10053
Returns the KeySym computed from the event if this argument is not NULL.
10054
</para>
10055
</listitem>
10056
</varlistentry>
10057
<varlistentry>
10058
<term>
10059
<emphasis remap='I'>status_return</emphasis>
10060
</term>
10061
<listitem>
10062
<para>
10063
Returns a value indicating what kind of data is returned.
10064
</para>
10065
</listitem>
10066
</varlistentry>
10067
</variablelist>
10068
</para>
10069
<para>
10070
<!-- .LP -->
10071
<!-- .eM -->
10072
The
10073
<function>XmbLookupString</function>
10074
and
10075
<function>XwcLookupString</function>
10076
functions return the string from the input method specified
10077
in the buffer_return argument.
10078
If no string is returned,
10079
the buffer_return argument is unchanged.
10080
</para>
10081
<para>
10082
<!-- .LP -->
10083
The KeySym into which the KeyCode from the event was mapped is returned
10084
in the keysym_return argument if it is non-NULL and the status_return
10085
argument indicates that a KeySym was returned.
10086
If both a string and a KeySym are returned,
10087
the KeySym value does not necessarily correspond to the string returned.
10088
</para>
10089
<para>
10090
<!-- .LP -->
10091
<function>XmbLookupString</function>
10092
returns the length of the string in bytes, and
10093
<function>XwcLookupString</function>
10094
returns the length of the string in characters.
10095
Both
10096
<function>XmbLookupString</function>
10097
and
10098
<function>XwcLookupString</function>
10099
return text in the encoding of the locale bound to the input method
10100
of the specified input context.
10101
</para>
10102
<para>
10103
<!-- .LP -->
10104
Each string returned by
10105
<function>XmbLookupString</function>
10106
and
10107
<function>XwcLookupString</function>
10108
begins in the initial state of the encoding of the locale
10109
(if the encoding of the locale is state-dependent).
10110
<!-- .NT -->
10111
<note><para>
10112
To insure proper input processing,
10113
it is essential that the client pass only
10114
<symbol>KeyPress</symbol>
10115
events to
10116
<function>XmbLookupString</function>
10117
and
10118
<function>XwcLookupString</function>.
10119
Their behavior when a client passes a
10120
<symbol>KeyRelease</symbol>
10121
event is undefined.
10122
</para></note>
10123
<!-- .NE -->
10124
</para>
10125
<para>
10126
<!-- .LP -->
10127
Clients should check the status_return argument before
10128
using the other returned values.
10129
These two functions both return a value to status_return
10130
that indicates what has been returned in the other arguments.
10131
The possible values returned are:
10132
</para>
10133
10134
<informaltable>
10135
<tgroup cols='2' align='center'>
10136
<colspec colname='c1'/>
10137
<colspec colname='c2'/>
10138
<tbody>
10139
<row>
10140
<entry><symbol>XBufferOverflow</symbol></entry>
10141
<entry>The input string to be returned is too large for the supplied buffer_return.
10142
The required size
10143
(<function>XmbLookupString</function>
10144
in bytes;
10145
<function>XwcLookupString</function>
10146
in characters) is returned as the value of the function,
10147
and the contents of buffer_return and keysym_return are not modified.
10148
The client should recall the function with the same event
10149
and a buffer of adequate size to obtain the string.</entry>
10150
</row>
10151
<row>
10152
<entry><symbol>XLookupNone</symbol></entry>
10153
<entry>No consistent input has been composed so far.
10154
The contents of buffer_return and keysym_return are not modified,
10155
and the function returns zero.</entry>
10156
</row>
10157
<row>
10158
<entry><symbol>XLookupChars</symbol></entry>
10159
<entry>Some input characters have been composed.
10160
They are placed in the buffer_return argument,
10161
and the string length is returned as the value of the function.
10162
The string is encoded in the locale bound to the input context.
10163
The content of the keysym_return argument is not modified.</entry>
10164
</row>
10165
<row>
10166
<entry><symbol>XLookupKeySym</symbol></entry>
10167
<entry>A KeySym has been returned instead of a string
10168
and is returned in keysym_return.
10169
The content of the buffer_return argument is not modified,
10170
and the function returns zero.</entry>
10171
</row>
10172
<row>
10173
<entry><symbol>XLookupBoth</symbol></entry>
10174
<entry>Both a KeySym and a string are returned;
10175
<symbol>XLookupChars</symbol>
10176
and
10177
<symbol>XLookupKeySym</symbol>
10178
occur simultaneously.</entry>
10179
</row>
10180
</tbody>
10181
</tgroup>
10182
</informaltable>
10183
10184
<para>
10185
<!-- .LP -->
10186
It does not make any difference if the input context passed as an argument to
10187
<function>XmbLookupString</function>
10188
and
10189
<function>XwcLookupString</function>
10190
is the one currently in possession of the focus or not.
10191
Input may have been composed within an input context before it lost the focus,
10192
and that input may be returned on subsequent calls to
10193
<function>XmbLookupString</function>
10194
or
10195
<function>XwcLookupString</function>
10196
even though it does not have any more keyboard focus.
10197
</para>
10198
</sect2>
10199
<sect2 id="Input_Method_Conventions">
10200
<title>Input Method Conventions</title>
10201
<!-- .XS -->
10202
<!-- (SN Input Method Conventions -->
10203
<!-- .XE -->
10204
<para>
10205
<!-- .LP -->
10206
The input method architecture is transparent to the client.
10207
However, clients should respect a number of conventions in order
10208
to work properly.
10209
Clients must also be aware of possible effects of synchronization
10210
between input method and library in the case of a remote input server.
10211
</para>
10212
<sect3 id="Client_Conventions">
10213
<title>Client Conventions</title>
10214
<!-- .XS -->
10215
<!-- (SN Client Conventions -->
10216
<!-- .XE -->
10217
<para>
10218
<!-- .LP -->
10219
A well-behaved client (or toolkit) should first query the input method style.
10220
If the client cannot satisfy the requirements of the supported styles
10221
(in terms of geometry management or callbacks),
10222
it should negotiate with the user continuation of the program
10223
or raise an exception or error of some sort.
10224
</para>
10225
</sect3>
10226
<sect3 id="Synchronization_Conventions">
10227
<title>Synchronization Conventions</title>
10228
<!-- .XS -->
10229
<!-- (SN Synchronization Conventions -->
10230
<!-- .XE -->
10231
<para>
10232
<!-- .LP -->
10233
A
10234
<symbol>KeyPress</symbol>
10235
event with a KeyCode of zero is used exclusively as a
10236
signal that an input method has composed input that can be returned by
10237
<function>XmbLookupString</function>
10238
or
10239
<function>XwcLookupString</function>.
10240
No other use is made of a
10241
<symbol>KeyPress</symbol>
10242
event with KeyCode of zero.
10243
</para>
10244
<para>
10245
<!-- .LP -->
10246
Such an event may be generated by either a front-end
10247
or a back-end input method in an implementation-dependent manner.
10248
Some possible ways to generate this event include:
10249
</para>
10250
<itemizedlist>
10251
<listitem>
10252
<para>
10253
A synthetic event sent by an input method server
10254
</para>
10255
</listitem>
10256
<listitem>
10257
<para>
10258
An artificial event created by a input method filter and pushed
10259
onto a client's event queue
10260
</para>
10261
</listitem>
10262
<listitem>
10263
<para>
10264
A
10265
<symbol>KeyPress</symbol>
10266
event whose KeyCode value is modified by an input method filter
10267
</para>
10268
</listitem>
10269
</itemizedlist>
10270
<para>
10271
<!-- .LP -->
10272
When callback support is specified by the client,
10273
input methods will not take action unless they explicitly
10274
called back the client and obtained no response
10275
(the callback is not specified or returned invalid data).
10276
</para>
10277
</sect3>
10278
</sect2>
10279
</sect1>
10280
<sect1 id="String_Constants">
10281
<title>String Constants</title>
10282
<!-- .XS -->
10283
<!-- (SN String Constants -->
10284
<!-- .XE -->
10285
<para>
10286
<!-- .LP -->
10287
The following symbols for string constants are defined in
10288
<X11/Xlib.h> .
10289
Although they are shown here with particular macro definitions,
10290
they may be implemented as macros, as global symbols, or as a
10291
mixture of the two. The string pointer value itself
10292
is not significant; clients must not assume that inequality of two
10293
values implies inequality of the actual string data.
10294
</para>
10295
10296
<literallayout class="monospaced">
10297
#define XNVaNestedList "XNVaNestedList"
10298
#define XNSeparatorofNestedList "separatorofNestedList"
10299
#define XNQueryInputStyle "queryInputStyle"
10300
#define XNClientWindow "clientWindow"
10301
#define XNInputStyle "inputStyle"
10302
#define XNFocusWindow "focusWindow"
10303
#define XNResourceName "resourceName"
10304
#define XNResourceClass "resourceClass"
10305
#define XNGeometryCallback "geometryCallback"
10306
#define XNDestroyCallback "destroyCallback"
10307
#define XNFilterEvents "filterEvents"
10308
#define XNPreeditStartCallback "preeditStartCallback"
10309
#define XNPreeditDoneCallback "preeditDoneCallback"
10310
#define XNPreeditDrawCallback "preeditDrawCallback"
10311
#define XNPreeditCaretCallback "preeditCaretCallback"
10312
#define XNPreeditStateNotifyCallback "preeditStateNotifyCallback"
10313
#define XNPreeditAttributes "preeditAttributes"
10314
#define XNStatusStartCallback "statusStartCallback"
10315
#define XNStatusDoneCallback "statusDoneCallback"
10316
#define XNStatusDrawCallback "statusDrawCallback"
10317
#define XNStatusAttributes "statusAttributes"
10318
#define XNArea "area"
10319
#define XNAreaNeeded "areaNeeded"
10320
#define XNSpotLocation "spotLocation"
10321
#define XNColormap "colorMap"
10322
#define XNStdColormap "stdColorMap"
10323
#define XNForeground "foreground"
10324
#define XNBackground "background"
10325
#define XNBackgroundPixmap "backgroundPixmap"
10326
#define XNFontSet "fontSet"
10327
#define XNLineSpace "lineSpace"
10328
#define XNCursor "cursor"
10329
#define XNQueryIMValuesList "queryIMValuesList"
10330
#define XNQueryICValuesList "queryICValuesList"
10331
#define XNStringConversionCallback "stringConversionCallback"
10332
#define XNStringConversion "stringConversion"
10333
#define XNResetState "resetState"
10334
#define XNHotKey "hotkey"
10335
#define XNHotKeyState "hotkeyState"
10336
#define XNPreeditState "preeditState"
10337
#define XNVisiblePosition "visiblePosition"
10338
#define XNR6PreeditCallbackBehavior "r6PreeditCallback"
10339
#define XNRequiredCharSet "requiredCharSet"
10340
#define XNQueryOrientation "queryOrientation"
10341
#define XNDirectionalDependentDrawing "directionalDependentDrawing"
10342
#define XNContextualDrawing "contextualDrawing"
10343
#define XNBaseFontName "baseFontName"
10344
#define XNMissingCharSet "missingCharSet"
10345
#define XNDefaultString "defaultString"
10346
#define XNOrientation "orientation"
10347
#define XNFontInfo "fontInfo"
10348
#define XNOMAutomatic "omAutomatic"
10349
10350
</literallayout>
10351
10352
</sect1>
10353
</chapter>
Loggerhead is a web-based interface for Breezy
Version: 2.0.1