« back to all changes in this revision
Viewing changes to specs/libX11/CH13
- browse files at revision 37
- compare with another revision
- download diff
- download tarball
- view history from revision 37
- Committer: Bazaar Package Importer
- Author(s): Timo Aaltonen
- Date: 2009-12-04 11:43:54 UTC
- mfrom: (1.1.10 upstream) (2.1.5 sid)
- Revision ID: james.westby@ubuntu.com-20091204114354-0lik4mbb1bv1a8nw
Tags: 2:1.3.2-1ubuntu1
* Merge from Debian unstable, remaining changes:
- Add 100_latin_locale_alias.diff (LP 379785)
- Add 100_latin_locale_alias.diff (LP 379785)
- files added:
- debian/libx11-6.symbols
- patches
- specs
- specs/XIM
- specs/i18n
- specs/libX11
- files removed:
- debian/patches/002_arm_abi_brain_damage.diff
- files modified:
- ChangeLog
added
removed
specs/libX11/CH13
1
.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
2
.\"
3
.\" Permission is hereby granted, free of charge, to any person obtaining
4
.\" a copy of this software and associated documentation files (the
5
.\" "Software"), to deal in the Software without restriction, including
6
.\" without limitation the rights to use, copy, modify, merge, publish,
7
.\" distribute, sublicense, and/or sell copies of the Software, and to
8
.\" permit persons to whom the Software is furnished to do so, subject to
9
.\" the following conditions:
10
.\"
11
.\" The above copyright notice and this permission notice shall be included
12
.\" in all copies or substantial portions of the Software.
13
.\"
14
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
15
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
17
.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
18
.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
19
.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
20
.\" OTHER DEALINGS IN THE SOFTWARE.
21
.\"
22
.\" Except as contained in this notice, the name of the X Consortium shall
23
.\" not be used in advertising or otherwise to promote the sale, use or
24
.\" other dealings in this Software without prior written authorization
25
.\" from the X Consortium.
26
.\"
27
.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
28
.\" Digital Equipment Corporation
29
.\"
30
.\" Portions Copyright \(co 1990, 1991 by
31
.\" Tektronix, Inc.
32
.\"
33
.\" Permission to use, copy, modify and distribute this documentation for
34
.\" any purpose and without fee is hereby granted, provided that the above
35
.\" copyright notice appears in all copies and that both that copyright notice
36
.\" and this permission notice appear in all copies, and that the names of
37
.\" Digital and Tektronix not be used in in advertising or publicity pertaining
38
.\" to this documentation without specific, written prior permission.
39
.\" Digital and Tektronix makes no representations about the suitability
40
.\" of this documentation for any purpose.
41
.\" It is provided ``as is'' without express or implied warranty.
42
.\"
43
\&
44
.sp 1
45
.ce 3
46
\s+1\fBChapter 13\fP\s-1
47
48
\s+1\fBLocales and Internationalized Text Functions\fP\s-1
49
.sp 2
50
.nr H1 13
51
.nr H2 0
52
.nr H3 0
53
.nr H4 0
54
.nr H5 0
55
.na
56
.LP
57
.XS
58
Chapter 13: Locales and Internationalized Text Functions
59
.XE
60
An internationalized application is one that is adaptable to the requirements
61
of different native languages, local customs, and character string encodings.
62
The process of adapting the operation to a particular native language,
63
local custom, or string encoding is called \fIlocalization\fP\^.
64
A goal of internationalization is to permit localization
65
without program source modifications or recompilation.
66
.LP
67
As one of the localization mechanisms,
68
Xlib provides an X Input Method
69
.Pn ( XIM )
70
functional interface for internationalized text input
71
and an X Output Method
72
.Pn ( XOM )
73
functional interface for internationalized text output.
74
.LP
75
Internationalization in X is based on the concept of a \fIlocale\fP.
76
A locale defines the localized behavior of a program at run time.
77
Locales affect Xlib in its:
78
.IP \(bu 5
79
Encoding and processing of input method text
80
.IP \(bu 5
81
Encoding of resource files and values
82
.IP \(bu 5
83
Encoding and imaging of text strings
84
.IP \(bu 5
85
Encoding and decoding for inter-client text communication
86
.LP
87
Characters from various languages are represented in a computer
88
using an encoding.
89
Different languages have different encodings,
90
and there are even different encodings for the same characters
91
in the same language.
92
.LP
93
This chapter defines support for localized text imaging and text input
94
and describes the locale mechanism that controls all locale-dependent
95
Xlib functions.
96
Sets of functions are provided for multibyte (char *) text as well as
97
wide character (wchar_t) text in the form supported
98
by the host C language environment.
99
The multibyte and wide character functions
100
are equivalent except for the form of the text argument.
101
.LP
102
The Xlib internationalization functions are not meant to provide
103
support for multilingual applications (mixing multiple languages
104
within a single piece of text), but they make it possible to
105
implement applications that work in limited fashion with more than
106
one language in independent contexts.
107
.LP
108
The remainder of this chapter discusses:
109
.IP \(bu 5
110
X locale management
111
.IP \(bu 5
112
Locale and modifier dependencies
113
.IP \(bu 5
114
Variable argument lists
115
.IP \(bu 5
116
Output methods
117
.IP \(bu 5
118
Input methods
119
.IP \(bu 5
120
String constants
121
.NH 2
122
X Locale Management
123
.XS
124
\*(SN X Locale Management
125
.XE
126
.LP
127
X supports one or more of the locales defined by the host environment.
128
On implementations that conform to the ANSI C library,
129
the locale announcement method is
130
.PN setlocale .
131
This function configures the locale operation of both
132
the host C library and Xlib.
133
The operation of Xlib is governed by the LC_CTYPE category;
134
this is called the \fIcurrent locale\fP.
135
An implementation is permitted to provide implementation-dependent
136
mechanisms for announcing the locale in addition to
137
.PN setlocale .
138
.LP
139
On implementations that do not conform to the ANSI C library,
140
the locale announcement method is Xlib implementation-dependent.
141
.LP
142
The mechanism by which the semantic operation of Xlib is defined
143
for a specific locale is implementation-dependent.
144
.LP
145
.sp
146
X is not required to support all the locales supported by the host.
147
To determine if the current locale is supported by X, use
148
.PN XSupportsLocale .
149
.IN "XSupportsLocale" "" "@DEF@"
150
.sM
151
.FD 0
152
Bool XSupportsLocale\^(\|)
153
.FN
154
.LP
155
.eM
156
The
157
.PN XSupportsLocale
158
function returns
159
.PN True
160
if Xlib functions are capable of operating under the current locale.
161
If it returns
162
.PN False ,
163
Xlib locale-dependent functions for which the
164
.PN XLocaleNotSupported
165
return status is defined will return
166
.PN XLocaleNotSupported .
167
Other Xlib locale-dependent routines will operate in the ``C'' locale.
168
.LP
169
The client is responsible for selecting its locale and X modifiers.
170
Clients should provide a means for the user to override the clients'
171
locale selection at client invocation.
172
Most single-display X clients operate in a single locale
173
for both X and the host processing environment.
174
They will configure the locale by calling three functions:
175
the host locale configuration function,
176
.PN XSupportsLocale ,
177
and
178
.PN XSetLocaleModifiers .
179
.LP
180
The semantics of certain categories of X internationalization capabilities
181
can be configured by setting modifiers.
182
Modifiers are named by implementation-dependent and locale-specific strings.
183
The only standard use for this capability at present
184
is selecting one of several styles of keyboard input method.
185
.LP
186
.sp
187
To configure Xlib locale modifiers for the current locale, use
188
.PN XSetLocaleModifiers .
189
.IN "XSetLocaleModifiers" "" "@DEF@"
190
.sM
191
.FD 0
192
char *XSetLocaleModifiers\^(\^\fImodifier_list\fP\^)
193
.br
194
char *\fImodifier_list\fP\^;
195
.FN
196
.IP \fImodifier_list\fP 1i
197
Specifies the modifiers.
198
.LP
199
.eM
200
The
201
.PN XSetLocaleModifiers
202
function sets the X modifiers for the current locale setting.
203
The modifier_list argument is a null-terminated string of the form
204
``{@\^\fIcategory\fP\^=\^\fIvalue\fP\^}'', that is,
205
having zero or more concatenated ``@\^\fIcategory\fP\^=\^\fIvalue\fP\^''
206
entries, where \fIcategory\fP is a category name
207
and \fIvalue\fP is the (possibly empty) setting for that category.
208
The values are encoded in the current locale.
209
Category names are restricted to the POSIX Portable Filename Character Set.
210
.LP
211
The local host X locale modifiers announcer (on POSIX-compliant systems,
212
the XMODIFIERS environment variable) is appended to the modifier_list to
213
provide default values on the local host.
214
If a given category appears more than once in the list,
215
the first setting in the list is used.
216
If a given category is not included in the full modifier list,
217
the category is set to an implementation-dependent default
218
for the current locale.
219
An empty value for a category explicitly specifies the
220
implementation-dependent default.
221
.LP
222
If the function is successful, it returns a pointer to a string.
223
The contents of the string are such that a subsequent call with that string
224
(in the same locale) will restore the modifiers to the same settings.
225
If modifier_list is a NULL pointer,
226
.PN XSetLocaleModifiers
227
also returns a pointer to such a string,
228
and the current locale modifiers are not changed.
229
.LP
230
If invalid values are given for one or more modifier categories supported by
231
the locale, a NULL pointer is returned, and none of the
232
current modifiers are changed.
233
.LP
234
At program startup,
235
the modifiers that are in effect are unspecified until
236
the first successful call to set them. Whenever the locale is changed, the
237
modifiers that are in effect become unspecified until the next successful call
238
to set them.
239
Clients should always call
240
.PN XSetLocaleModifiers
241
with a non-NULL modifier_list after setting the locale
242
before they call any locale-dependent Xlib routine.
243
.LP
244
The only standard modifier category currently defined is ``im'',
245
which identifies the desired input method.
246
The values for input method are not standardized.
247
A single locale may use multiple input methods,
248
switching input method under user control.
249
The modifier may specify the initial input method in effect
250
or an ordered list of input methods.
251
Multiple input methods may be specified in a single im value string
252
in an implementation-dependent manner.
253
.LP
254
The returned modifiers string is owned by Xlib and should not be modified or
255
freed by the client.
256
It may be freed by Xlib after the current locale or modifiers are changed.
257
Until freed, it will not be modified by Xlib.
258
.LP
259
The recommended procedure for clients initializing their locale and modifiers
260
is to obtain locale and modifier announcers separately from
261
one of the following prioritized sources:
262
.IP \(bu 5
263
A command line option
264
.IP \(bu 5
265
A resource
266
.IP \(bu 5
267
The empty string ("\^")
268
.LP
269
The first of these that is defined should be used.
270
Note that when a locale command line option or locale resource is defined,
271
the effect should be to set all categories to the specified locale,
272
overriding any category-specific settings in the local host environment.
273
.NH 2
274
Locale and Modifier Dependencies
275
.XS
276
\*(SN Locale and Modifier Dependencies
277
.XE
278
.LP
279
The internationalized Xlib functions operate in the current locale
280
configured by the host environment and X locale modifiers set by
281
.PN XSetLocaleModifiers
282
or in the locale and modifiers configured at the time
283
some object supplied to the function was created.
284
For each locale-dependent function,
285
the following table describes the locale (and modifiers) dependency:
286
.TS H
287
lw(1.25i) lw(2.5i) lw(2i).
288
_
289
.sp 6p
290
.B
291
Locale from Affects the Function In
292
.sp 6p
293
_
294
.sp 6p
295
.TH
296
.R
297
Locale Query/Configuration:
298
.sp 6p
299
T{
300
.PN setlocale
301
T} T{
302
.PN XSupportsLocale
303
T} T{
304
Locale queried
305
T}
306
T{
307
.PN XSetLocaleModifiers
308
T} T{
309
Locale modified
310
T}
311
.sp
312
Resources:
313
.sp 6p
314
T{
315
.PN setlocale
316
T} T{
317
.PN XrmGetFileDatabase
318
T} T{
319
Locale of
320
.PN XrmDatabase
321
T}
322
T{
323
.PN XrmGetStringDatabase
324
T}
325
T{
326
.PN XrmDatabase
327
T} T{
328
.PN XrmPutFileDatabase
329
T} T{
330
Locale of
331
.PN XrmDatabase
332
T}
333
T{
334
.PN XrmLocaleOfDatabase
335
T}
336
.sp
337
Setting Standard Properties:
338
.sp 6p
339
T{
340
.PN setlocale
341
T} T{
342
.PN XmbSetWMProperties
343
T} T{
344
Encoding of supplied/returned
345
T}
346
text (some WM_ property
347
text in environment locale)
348
.sp 6p
349
T{
350
.PN setlocale
351
T} T{
352
.PN XmbTextPropertyToTextList
353
T} T{
354
Encoding of supplied/returned text
355
T}
356
T{
357
.PN XwcTextPropertyToTextList
358
T}
359
T{
360
.PN XmbTextListToTextProperty
361
T}
362
T{
363
.PN XwcTextListToTextProperty
364
T}
365
.sp
366
Text Input:
367
.sp 6p
368
T{
369
.PN setlocale
370
T} T{
371
.PN XOpenIM
372
T} T{
373
XIM input method selection
374
T}
375
T{
376
.PN XRegisterIMInstantiateCallback
377
T} T{
378
XIM selection
379
T}
380
T{
381
.PN XUnregisterIMInstantiateCallback
382
T} T{
383
XIM selection
384
T}
385
T{
386
.PN XIM
387
T} T{
388
.PN XCreateIC
389
T} T{
390
XIC input method configuration
391
T}
392
T{
393
.PN XLocaleOfIM ,
394
and so on
395
T} T{
396
Queried locale
397
T}
398
T{
399
.PN XIC
400
T} T{
401
.PN XmbLookupString
402
T} T{
403
Keyboard layout
404
T}
405
T{
406
.PN XwcLookupString
407
T} T{
408
Encoding of returned text
409
T}
410
.sp
411
Text Drawing:
412
.sp 6p
413
T{
414
.PN setlocale
415
T} T{
416
.PN XOpenOM
417
T} T{
418
XOM output method selection
419
T}
420
T{
421
.PN XCreateFontSet
422
T} T{
423
Charsets of fonts in
424
.PN XFontSet
425
T}
426
T{
427
.PN XOM
428
T} T{
429
.PN XCreateOC
430
T} T{
431
XOC output method configuration
432
T}
433
T{
434
.PN XLocaleOfOM ,
435
and so on
436
T} T{
437
Queried locale
438
T}
439
T{
440
.PN XFontSet
441
T} T{
442
.PN XmbDrawText ,
443
T} T{
444
Locale of supplied text
445
T}
446
T{
447
.PN XwcDrawText ,
448
and so on
449
T} T{
450
Locale of supplied text
451
T}
452
T{
453
.PN XExtentsOfFontSet ,
454
and so on
455
T} T{
456
Locale-dependent metrics
457
T}
458
T{
459
.PN XmbTextExtents ,
460
T}
461
T{
462
.PN XwcTextExtents ,
463
and so on
464
T}
465
.sp
466
Xlib Errors:
467
.sp 6p
468
T{
469
.PN setlocale
470
T} T{
471
.PN XGetErrorDatabaseText
472
T} T{
473
Locale of error message
474
T}
475
T{
476
.PN XGetErrorText
477
T}
478
.sp 6p
479
_
480
.TE
481
.LP
482
Clients may assume that a locale-encoded text string returned
483
by an X function can be passed to a C library routine, or vice versa,
484
if the locale is the same at the two calls.
485
.LP
486
All text strings processed by internationalized Xlib functions are assumed
487
to begin in the initial state of the encoding of the locale, if the encoding
488
is state-dependent.
489
.LP
490
All Xlib functions behave as if they do not change the current locale
491
or X modifier setting.
492
(This means that if they do change locale or call
493
.PN XSetLocaleModifiers
494
with a non-NULL argument, they must save and restore the current state on
495
entry and exit.)
496
Also, Xlib functions on implementations that conform to the ANSI C library do
497
not alter the global state associated with the ANSI C functions
498
.PN mblen ,
499
.PN mbtowc ,
500
.PN wctomb ,
501
and
502
.PN strtok .
503
.NH 2
504
Variable Argument Lists
505
.XS
506
\*(SN Variable Argument Lists
507
.XE
508
.LP
509
Various functions in this chapter have arguments that conform
510
to the ANSI C variable argument list calling convention.
511
Each function denoted with an argument of the form ``...'' takes
512
a variable-length list of name and value pairs,
513
where each name is a string and each value is of type
514
.PN XPointer .
515
A name argument that is NULL identifies the end of the list.
516
.LP
517
A variable-length argument list may contain a nested list.
518
If the name
519
.PN XNVaNestedList
520
is specified in place of an argument name,
521
then the following value is interpreted as an
522
.PN XVaNestedList
523
value that specifies a list of values logically inserted into the
524
original list at the point of declaration.
525
A NULL identifies the end of a nested list.
526
.LP
527
.sp
528
To allocate a nested variable argument list dynamically, use
529
.PN XVaCreateNestedList .
530
.IN "XVaCreateNestedList" "" @DEF@"
531
.sM
532
.FD 0
533
typedef void * XVaNestedList;
534
535
XVaNestedList XVaCreateNestedList\^(\^\fIdummy\fP\^, ...)
536
.br
537
int \fIdummy\fP\^;
538
.FN
539
.IP \fIdummy\fP 1i
540
Specifies an unused argument (required by ANSI C).
541
.ds Al
542
.IP ... 1i
543
Specifies the variable length argument list\*(Al.
544
.LP
545
.eM
546
The
547
.PN XVaCreateNestedList
548
function allocates memory and copies its arguments into
549
a single list pointer,
550
which may be used as a value for arguments requiring a list value.
551
Any entries are copied as specified.
552
Data passed by reference is not copied;
553
the caller must ensure data remains valid for the lifetime
554
of the nested list.
555
The list should be freed using
556
.PN XFree
557
when it is no longer needed.
558
.NH 2
559
Output Methods
560
.XS
561
\*(SN Output Methods
562
.XE
563
.LP
564
This section provides discussions of the following X Output Method
565
(XOM) topics:
566
.IP \(bu 5
567
Output method overview
568
.IP \(bu 5
569
Output method functions
570
.IP \(bu 5
571
Output method values
572
.IP \(bu 5
573
Output context functions
574
.IP \(bu 5
575
Output context values
576
.IP \(bu 5
577
Creating and freeing a font set
578
.IP \(bu 5
579
Obtaining font set metrics
580
.IP \(bu 5
581
Drawing text using font sets
582
.NH 3
583
Output Method Overview
584
.XS
585
\*(SN Output Method Overview
586
.XE
587
.LP
588
Locale-dependent text may include one or more text components, each of
589
which may require different fonts and character set encodings.
590
In some languages, each component might have a different
591
drawing direction, and some components might contain
592
context-dependent characters that change shape based on
593
relationships with neighboring characters.
594
.LP
595
When drawing such locale-dependent text, some locale-specific
596
knowledge is required;
597
for example, what fonts are required to draw the text,
598
how the text can be separated into components, and which
599
fonts are selected to draw each component.
600
Further, when bidirectional text must be drawn,
601
the internal representation order of the text must be changed
602
into the visual representation order to be drawn.
603
.LP
604
An X Output Method provides a functional interface so that clients
605
do not have to deal directly with such locale-dependent details.
606
Output methods provide the following capabilities:
607
.IP \(bu 5
608
Creating a set of fonts required to draw locale-dependent text.
609
.IP \(bu 5
610
Drawing locale-dependent text with a font set without the caller
611
needing to be aware of locale dependencies.
612
.IP \(bu 5
613
Obtaining the escapement and extents in pixels of locale-dependent text.
614
.IP \(bu 5
615
Determining if bidirectional or context-dependent drawing is required
616
in a specific locale with a specific font set.
617
.LP
618
Two different abstractions are used in the representation of
619
the output method for clients.
620
.LP
621
The abstraction used to communicate with an output method
622
is an opaque data structure represented by the
623
.PN XOM
624
data type.
625
The abstraction for representing the state of a particular output thread
626
is called an \fIoutput context\fP.
627
The Xlib representation of an output context is an
628
.PN XOC ,
629
which is compatible with
630
.PN XFontSet
631
in terms of its functional interface, but is
632
a broader, more generalized abstraction.
633
.NH 3
634
Output Method Functions
635
.XS
636
\*(SN Output Method Functions
637
.XE
638
.LP
639
To open an output method, use
640
.PN XOpenOM .
641
.IN "XOpenOM" "" "@DEF@"
642
.sM
643
.FD 0
644
XOM XOpenOM\^(\^\fIdisplay\fP\^, \fIdb\fP\^, \fIres_name\fP\^, \fIres_class\fP\^)
645
.br
646
Display *\fIdisplay\fP\^;
647
.br
648
XrmDatabase \fIdb\fP\^;
649
.br
650
char *\fIres_name\fP\^;
651
.br
652
char *\fIres_class\fP\^;
653
.FN
654
.IP \fIdisplay\fP 1i
655
Specifies the connection to the X server.
656
.IP \fIdb\fP 1i
657
Specifies a pointer to the resource database.
658
.IP \fIres_name\fP 1i
659
Specifies the full resource name of the application.
660
.IP \fIres_class\fP 1i
661
Specifies the full class name of the application.
662
.LP
663
.eM
664
The
665
.PN XOpenOM
666
function opens an output method
667
matching the current locale and modifiers specification.
668
The current locale and modifiers are bound to the output method
669
when
670
.PN XOpenOM
671
is called.
672
The locale associated with an output method cannot be changed.
673
.LP
674
The specific output method to which this call will be routed
675
is identified on the basis of the current locale and modifiers.
676
.PN XOpenOM
677
will identify a default output method corresponding to the
678
current locale.
679
That default can be modified using
680
.PN XSetLocaleModifiers
681
to set the output method modifier.
682
.LP
683
The db argument is the resource database to be used by the output method
684
for looking up resources that are private to the output method.
685
It is not intended that this database be used to look
686
up values that can be set as OC values in an output context.
687
If db is NULL,
688
no database is passed to the output method.
689
.LP
690
The res_name and res_class arguments specify the resource name
691
and class of the application.
692
They are intended to be used as prefixes by the output method
693
when looking up resources that are common to all output contexts
694
that may be created for this output method.
695
The characters used for resource names and classes must be in the
696
X Portable Character Set.
697
The resources looked up are not fully specified
698
if res_name or res_class is NULL.
699
.LP
700
The res_name and res_class arguments are not assumed to exist beyond
701
the call to
702
.PN XOpenOM .
703
The specified resource database is assumed to exist for the lifetime
704
of the output method.
705
.LP
706
.PN XOpenOM
707
returns NULL if no output method could be opened.
708
.LP
709
.sp
710
To close an output method, use
711
.PN XCloseOM .
712
.IN "XCloseOM" "" "@DEF@"
713
.sM
714
.FD 0
715
Status XCloseOM\^(\^\fIom\fP\^)
716
.br
717
XOM \fIom\fP\^;
718
.FN
719
.IP \fIom\fP 1i
720
Specifies the output method.
721
.LP
722
.eM
723
The
724
.PN XCloseOM
725
function closes the specified output method.
726
.LP
727
.sp
728
To set output method attributes, use
729
.PN XSetOMValues .
730
.IN "XSetOMValues" "" "@DEF@"
731
.sM
732
.FD 0
733
char * XSetOMValues\^(\^\fIom\fP\^, ...)
734
.br
735
XOM \fIom\fP\^;
736
.FN
737
.IP \fIom\fP 1i
738
Specifies the output method.
739
.ds Al \ to set XOM values
740
.IP ... 1i
741
Specifies the variable-length argument list\*(Al.
742
.LP
743
.eM
744
The
745
.PN XSetOMValues
746
function presents a variable argument list programming interface
747
for setting properties or features of the specified output method.
748
This function returns NULL if it succeeds;
749
otherwise,
750
it returns the name of the first argument that could not be obtained.
751
.LP
752
No standard arguments are currently defined by Xlib.
753
.LP
754
.sp
755
To query an output method, use
756
.PN XGetOMValues .
757
.IN "XGetOMValues" "" "@DEF@"
758
.sM
759
.FD 0
760
char * XGetOMValues\^(\^\fIom\fP\^, ...)
761
.br
762
XOM \fIom\fP\^;
763
.FN
764
.IP \fIom\fP 1i
765
Specifies the output method.
766
.ds Al \ to get XOM values
767
.IP ... 1i
768
Specifies the variable-length argument list\*(Al.
769
.LP
770
.eM
771
The
772
.PN XGetOMValues
773
function presents a variable argument list programming interface
774
for querying properties or features of the specified output method.
775
This function returns NULL if it succeeds;
776
otherwise,
777
it returns the name of the first argument that could not be obtained.
778
.LP
779
To obtain the display associated with an output method, use
780
.PN XDisplayOfOM .
781
.IN "XDisplayOfOM" "" "@DEF@"
782
.sM
783
.FD 0
784
Display * XDisplayOfOM\^(\^\fIom\fP\^)
785
.br
786
XOM \fIom\fP\^;
787
.FN
788
.IP \fIom\fP 1i
789
Specifies the output method.
790
.LP
791
.eM
792
The
793
.PN XDisplayOfOM
794
function returns the display associated with the specified output method.
795
.LP
796
.sp
797
To get the locale associated with an output method, use
798
.PN XLocaleOfOM .
799
.IN "XLocaleOfOM" "" "@DEF@"
800
.sM
801
.FD 0
802
char * XLocaleOfOM\^(\^\fIom\fP\^)
803
.br
804
XOM \fIom\fP\^;
805
.FN
806
.IP \fIom\fP 1i
807
Specifies the output method.
808
.LP
809
.eM
810
The
811
.PN XLocaleOfOM
812
returns the locale associated with the specified output method.
813
.NH 3
814
X Output Method Values
815
.XS
816
\*(SN X Output Method Values
817
.XE
818
.LP
819
The following table describes how XOM values are interpreted by an
820
output method.
821
The first column lists the XOM values. The second column indicates
822
how each of the XOM values are treated by a particular output style.
823
.LP
824
.LP
825
The following key applies to this table.
826
.TS H
827
lw(1i) lw(4.75i).
828
_
829
.sp 6p
830
.B
831
Key Explanation
832
.sp 6p
833
_
834
.sp 6p
835
.TH
836
.R
837
G T{
838
This value may be read using
839
.PN XGetOMValues .
840
T}
841
.sp 6p
842
_
843
.TE
844
.LP
845
.TS H
846
lw(2.25i) c
847
lw(2.25i) c.
848
_
849
.sp 6p
850
.B
851
XOM Value Key
852
.sp 6p
853
_
854
.sp 6p
855
.TH
856
.R
857
T{
858
.PN XNRequiredCharSet
859
T} T{
860
G
861
T}
862
T{
863
.PN XNQueryOrientation
864
T} T{
865
G
866
T}
867
T{
868
.PN XNDirectionalDependentDrawing
869
T} T{
870
G
871
T}
872
T{
873
.PN XNContextualDrawing
874
T} T{
875
G
876
T}
877
.sp 6p
878
_
879
.TE
880
.LP
881
.NH 4
882
Required Char Set
883
.XS
884
\*(SN Required Char Set
885
.XE
886
.LP
887
The
888
.PN XNRequiredCharSet
889
argument returns the list of charsets that are required for loading the fonts
890
needed for the locale.
891
The value of the argument is a pointer to a structure of type
892
.PN XOMCharSetList .
893
.LP
894
The
895
.PN XOMCharSetList
896
structure is defined as follows:
897
.IN "XOMCharSetList" "" "@DEF@"
898
.sM
899
.LP
900
.Ds 0
901
.TA .5i 2.5i
902
.ta .5i 2.5i
903
typedef struct {
904
int charset_count;
905
char **charset_list;
906
} XOMCharSetList;
907
.De
908
.LP
909
.eM
910
The charset_list member is a list of one or more null-terminated
911
charset names, and the charset_count member is the number of
912
charset names.
913
.LP
914
The required charset list is owned by Xlib and should not be modified or
915
freed by the client.
916
It will be freed by a call to
917
.PN XCloseOM
918
with the associated
919
.PN XOM .
920
Until freed, its contents will not be modified by Xlib.
921
.LP
922
.NH 4
923
Query Orientation
924
.XS
925
\*(SN Query Orientation
926
.XE
927
.LP
928
The
929
.PN XNQueryOrientation
930
argument returns the global orientation of text when drawn.
931
Other than
932
.PN XOMOrientation_LTR_TTB ,
933
the set of orientations supported is locale-dependent.
934
The value of the argument is a pointer to a structure of type
935
.PN XOMOrientation .
936
Clients are responsible for freeing the
937
.PN XOMOrientation
938
structure by using
939
.PN XFree ;
940
this also frees the contents of the structure.
941
.LP
942
.sM
943
.Ds 0
944
.TA .5i 2.5i
945
.ta .5i 2.5i
946
typedef struct {
947
int num_orientation;
948
XOrientation *orientation; /* Input Text description */
949
} XOMOrientation;
950
951
typedef enum {
952
XOMOrientation_LTR_TTB,
953
XOMOrientation_RTL_TTB,
954
XOMOrientation_TTB_LTR,
955
XOMOrientation_TTB_RTL,
956
XOMOrientation_Context
957
} XOrientation;
958
.De
959
.LP
960
.eM
961
The possible value for XOrientation may be:
962
.IP \(bu 5
963
.PN XOMOrientation_LTR_TTB
964
left-to-right, top-to-bottom global orientation
965
.IP \(bu 5
966
.PN XOMOrientation_RTL_TTB
967
right-to-left, top-to-bottom global orientation
968
.IP \(bu 5
969
.PN XOMOrientation_TTB_LTR
970
top-to-bottom, left-to-right global orientation
971
.IP \(bu 5
972
.PN XOMOrientation_TTB_RTL
973
top-to-bottom, right-to-left global orientation
974
.IP \(bu 5
975
.PN XOMOrientation_Context
976
contextual global orientation
977
.LP
978
.NH 4
979
Directional Dependent Drawing
980
.XS
981
\*(SN Directional Dependent Drawing
982
.XE
983
.LP
984
The
985
.PN XNDirectionalDependentDrawing
986
argument indicates whether the text rendering functions
987
implement implicit handling of directional text. If this value
988
is
989
.PN True ,
990
the output method has knowledge of directional
991
dependencies and reorders text as necessary when
992
rendering text. If this value is
993
.PN False ,
994
the output method does not implement any directional text
995
handling, and all character directions are assumed to be left-to-right.
996
.LP
997
Regardless of the rendering order of characters,
998
the origins of all characters are on the primary draw direction side
999
of the drawing origin.
1000
.LP
1001
This OM value presents functionality identical to the
1002
.PN XDirectionalDependentDrawing
1003
function.
1004
.NH 4
1005
Context Dependent Drawing
1006
.XS
1007
\*(SN Context Dependent Drawing
1008
.XE
1009
.LP
1010
The
1011
.PN XNContextualDrawing
1012
argument indicates whether the text rendering functions
1013
implement implicit context-dependent drawing. If this value is
1014
.PN True ,
1015
the output method has knowledge of context dependencies and
1016
performs character shape editing, combining glyphs to present
1017
a single character as necessary. The actual shape editing is
1018
dependent on the locale implementation and the font set used.
1019
.LP
1020
This OM value presents functionality identical to the
1021
.PN XContextualDrawing
1022
function.
1023
.NH 3
1024
Output Context Functions
1025
.XS
1026
\*(SN Output Context Functions
1027
.XE
1028
.LP
1029
An output context is an abstraction that contains both the data
1030
required by an output method and the information required
1031
to display that data.
1032
There can be multiple output contexts for one output method.
1033
The programming interfaces for creating, reading, or modifying
1034
an output context use a variable argument list.
1035
The name elements of the argument lists are referred to as XOC values.
1036
It is intended that output methods be controlled by these XOC values.
1037
As new XOC values are created,
1038
they should be registered with the X Consortium.
1039
An
1040
.PN XOC
1041
can be used anywhere an
1042
.PN XFontSet
1043
can be used, and vice versa;
1044
.PN XFontSet
1045
is retained for compatibility with previous releases.
1046
The concepts of output methods and output contexts include broader,
1047
more generalized abstraction than font set,
1048
supporting complex and more intelligent text display, and dealing not only
1049
with multiple fonts but also with context dependencies.
1050
However,
1051
.PN XFontSet
1052
is widely used in several interfaces, so
1053
.PN XOC
1054
is defined as an upward compatible type of
1055
.PN XFontSet .
1056
.LP
1057
.sp
1058
To create an output context, use
1059
.PN XCreateOC .
1060
.IN "XCreateOC" "" "@DEF@"
1061
.sM
1062
.FD 0
1063
XOC XCreateOC\^(\^\fIom\fP\^, ...)
1064
.br
1065
XOM \fIom\fP\^;
1066
.FN
1067
.IP \fIom\fP 1i
1068
Specifies the output method.
1069
.ds Al \ to set XOC values
1070
.IP ... 1i
1071
Specifies the variable-length argument list\*(Al.
1072
.LP
1073
.eM
1074
The
1075
.PN XCreateOC
1076
function creates an output context within the specified output method.
1077
.LP
1078
The base font names argument is mandatory at creation time, and
1079
the output context will not be created unless it is provided.
1080
All other output context values can be set later.
1081
.LP
1082
.PN XCreateOC
1083
returns NULL if no output context could be created.
1084
NULL can be returned for any of the following reasons:
1085
.IP \(bu 5
1086
A required argument was not set.
1087
.IP \(bu 5
1088
A read-only argument was set.
1089
.IP \(bu 5
1090
An argument name is not recognized.
1091
.IP \(bu 5
1092
The output method encountered an output method implementation-dependent error.
1093
.LP
1094
.PN XCreateOC
1095
can generate a
1096
.PN BadAtom
1097
error.
1098
.LP
1099
.sp
1100
To destroy an output context, use
1101
.PN XDestroyOC .
1102
.IN "XDestroyOC" "" "@DEF@"
1103
.sM
1104
.FD 0
1105
void XDestroyOC\^(\^\fIoc\fP\^)
1106
.br
1107
XOC \fIoc\fP\^;
1108
.FN
1109
.IP \fIoc\fP 1i
1110
Specifies the output context.
1111
.LP
1112
.eM
1113
The
1114
.PN XDestroyOC
1115
function destroys the specified output context.
1116
.LP
1117
.sp
1118
To get the output method associated with an output context, use
1119
.PN XOMOfOC .
1120
.IN "XOMOfOC" "" "@DEF@"
1121
.sM
1122
.FD 0
1123
XOM XOMOfOC\^(\^\fIoc\fP\^)
1124
.br
1125
XOC \fIoc\fP\^;
1126
.FN
1127
.IP \fIoc\fP 1i
1128
Specifies the output context.
1129
.LP
1130
.eM
1131
The
1132
.PN XOMOfOC
1133
function returns the output method associated with the
1134
specified output context.
1135
.LP
1136
.sp
1137
Xlib provides two functions for setting and reading output context values,
1138
respectively,
1139
.PN XSetOCValues
1140
and
1141
.PN XGetOCValues .
1142
Both functions have a variable-length argument list.
1143
In that argument list, any XOC value's name must be denoted
1144
with a character string using the X Portable Character Set.
1145
.LP
1146
.sp
1147
To set XOC values, use
1148
.PN XSetOCValues .
1149
.IN "XSetOCValues" "" "@DEF@"
1150
.sM
1151
.FD 0
1152
char * XSetOCValues\^(\^\fIoc\fP\^, ...)
1153
.br
1154
XOC \fIoc\fP\^;
1155
.FN
1156
.IP \fIoc\fP 1i
1157
Specifies the output context.
1158
.ds Al \ to set XOC values
1159
.IP ... 1i
1160
Specifies the variable-length argument list\*(Al.
1161
.LP
1162
.eM
1163
The
1164
.PN XSetOCValues
1165
function returns NULL if no error occurred;
1166
otherwise,
1167
it returns the name of the first argument that could not be set.
1168
An argument might not be set for any of the following reasons:
1169
.IP \(bu 5
1170
The argument is read-only.
1171
.IP \(bu 5
1172
The argument name is not recognized.
1173
.IP \(bu 5
1174
An implementation-dependent error occurs.
1175
.LP
1176
Each value to be set must be an appropriate datum,
1177
matching the data type imposed by the semantics of the argument.
1178
.LP
1179
.PN XSetOCValues
1180
can generate a
1181
.PN BadAtom
1182
error.
1183
.LP
1184
.sp
1185
To obtain XOC values, use
1186
.PN XGetOCValues .
1187
.IN "XGetOCValues" "" "@DEF@"
1188
.sM
1189
.FD 0
1190
char * XGetOCValues\^(\^\fIoc\fP\^, ...)
1191
.br
1192
XOC \fIoc\fP\^;
1193
.FN
1194
.IP \fIoc\fP 1i
1195
Specifies the output context.
1196
.ds Al \ to get XOC values
1197
.IP ... 1i
1198
Specifies the variable-length argument list\*(Al.
1199
.LP
1200
.eM
1201
The
1202
.PN XGetOCValues
1203
function returns NULL if no error occurred; otherwise,
1204
it returns the name of the first argument that could not be obtained.
1205
An argument might not be obtained for any of the following reasons:
1206
.IP \(bu 5
1207
The argument name is not recognized.
1208
.IP \(bu 5
1209
An implementation-dependent error occurs.
1210
.LP
1211
Each argument value
1212
following a name must point to a location where the value is to be stored.
1213
.NH 3
1214
Output Context Values
1215
.XS
1216
\*(SN Output Context Values
1217
.XE
1218
.LP
1219
The following table describes how XOC values are interpreted
1220
by an output method.
1221
The first column lists the XOC values.
1222
The second column indicates the alternative interfaces that function
1223
identically and are provided for compatibility with previous releases.
1224
The third column indicates how each of the XOC values is treated.
1225
.LP
1226
The following keys apply to this table.
1227
.TS H
1228
lw(1i) lw(4.75i).
1229
_
1230
.sp 6p
1231
.B
1232
Key Explanation
1233
.sp 6p
1234
_
1235
.TH
1236
.R
1237
C T{
1238
This value must be set with
1239
.PN XCreateOC .
1240
T}
1241
D T{
1242
This value may be set using
1243
.PN XCreateOC .
1244
If it is not set,
1245
.br
1246
a default is provided.
1247
T}
1248
G T{
1249
This value may be read using
1250
.PN XGetOCValues .
1251
T}
1252
S T{
1253
This value must be set using
1254
.PN XSetOCValues .
1255
T}
1256
.sp 6p
1257
_
1258
.TE
1259
.LP
1260
.TS H
1261
l c c
1262
l c c.
1263
_
1264
.sp 6p
1265
.B
1266
XOC Value Alternative Interface Key
1267
.sp 6p
1268
_
1269
.sp 6p
1270
.TH
1271
.R
1272
T{
1273
BaseFontName
1274
T} T{
1275
.PN XCreateFontSet
1276
T} T{
1277
C-G
1278
T}
1279
T{
1280
MissingCharSet
1281
T} T{
1282
.PN XCreateFontSet
1283
T} T{
1284
G
1285
T}
1286
T{
1287
DefaultString
1288
T} T{
1289
.PN XCreateFontSet
1290
T} T{
1291
G
1292
T}
1293
T{
1294
Orientation
1295
T} T{
1296
\-
1297
T} T{
1298
D-S-G
1299
T}
1300
T{
1301
ResourceName
1302
T} T{
1303
\-
1304
T} T{
1305
S-G
1306
T}
1307
T{
1308
ResourceClass
1309
T} T{
1310
\-
1311
T} T{
1312
S-G
1313
T}
1314
T{
1315
FontInfo
1316
T} T{
1317
.PN XFontsOfFontSet
1318
T} T{
1319
G
1320
T}
1321
T{
1322
OMAutomatic
1323
T} T{
1324
\-
1325
T} T{
1326
G
1327
T}
1328
.sp 6p
1329
_
1330
.TE
1331
.LP
1332
.NH 4
1333
Base Font Name
1334
.XS
1335
\*(SN Base Font Name
1336
.XE
1337
.LP
1338
The
1339
.PN XNBaseFontName
1340
argument is a list of base font names that Xlib uses
1341
to load the fonts needed for the locale.
1342
The base font names are a comma-separated list. The string is null-terminated
1343
and is assumed to be in the Host Portable Character Encoding;
1344
otherwise, the result is implementation-dependent.
1345
White space immediately on either side of a separating comma is ignored.
1346
.LP
1347
Use of XLFD font names permits Xlib to obtain the fonts needed for a
1348
variety of locales from a single locale-independent base font name.
1349
The single base font name should name a family of fonts whose members
1350
are encoded in the various charsets needed by the locales of interest.
1351
.LP
1352
An XLFD base font name can explicitly name a charset needed for the locale.
1353
This allows the user to specify an exact font for use with a charset required
1354
by a locale, fully controlling the font selection.
1355
.LP
1356
If a base font name is not an XLFD name,
1357
Xlib will attempt to obtain an XLFD name from the font properties
1358
for the font.
1359
If Xlib is successful, the
1360
.PN XGetOCValues
1361
function will return this XLFD name instead of the client-supplied name.
1362
.LP
1363
This argument must be set at creation time
1364
and cannot be changed.
1365
If no fonts exist for any of the required charsets,
1366
or if the locale definition in Xlib requires that a font exist
1367
for a particular charset and a font is not found for that charset,
1368
.PN XCreateOC
1369
returns NULL.
1370
.LP
1371
When querying for the
1372
.PN XNBaseFontName
1373
XOC value,
1374
.PN XGetOCValues
1375
returns a null-terminated string identifying the base font names that
1376
Xlib used to load the fonts needed for the locale.
1377
This string is owned by Xlib and should not be modified or freed by
1378
the client.
1379
The string will be freed by a call to
1380
.PN XDestroyOC
1381
with the associated
1382
.PN XOC .
1383
Until freed, the string contents will not be modified by Xlib.
1384
.NH 4
1385
Missing CharSet
1386
.XS
1387
\*(SN Missing CharSet
1388
.XE
1389
.LP
1390
The
1391
.PN XNMissingCharSet
1392
argument returns the list of required charsets that are missing from the
1393
font set.
1394
The value of the argument is a pointer to a structure of type
1395
.PN XOMCharSetList .
1396
.LP
1397
If fonts exist for all of the charsets required by the current locale,
1398
charset_list is set to NULL and charset_count is set to zero.
1399
If no fonts exist for one or more of the required charsets,
1400
charset_list is set to a list of one or more null-terminated charset names
1401
for which no fonts exist, and charset_count is set to the number of
1402
missing charsets.
1403
The charsets are from the list of the required charsets for
1404
the encoding of the locale and do not include any charsets to which Xlib
1405
may be able to remap a required charset.
1406
.LP
1407
The missing charset list is owned by Xlib and should not be modified or
1408
freed by the client.
1409
It will be freed by a call to
1410
.PN XDestroyOC
1411
with the associated
1412
.PN XOC .
1413
Until freed, its contents will not be modified by Xlib.
1414
.NH 4
1415
Default String
1416
.XS
1417
\*(SN Default String
1418
.XE
1419
.LP
1420
When a drawing or measuring function is called with an
1421
.PN XOC
1422
that has missing charsets, some characters in the locale will not be
1423
drawable.
1424
The
1425
.PN XNDefaultString
1426
argument returns a pointer to a string that represents the glyphs
1427
that are drawn with this
1428
.PN XOC
1429
when the charsets of the available fonts do not include all glyphs
1430
required to draw a character.
1431
The string does not necessarily consist of valid characters
1432
in the current locale and is not necessarily drawn with
1433
the fonts loaded for the font set,
1434
but the client can draw or measure the default glyphs
1435
by including this string in a string being drawn or measured with the
1436
.PN XOC .
1437
.LP
1438
If the
1439
.PN XNDefaultString
1440
argument returned the empty string ("\^"),
1441
no glyphs are drawn and the escapement is zero.
1442
The returned string is null-terminated.
1443
It is owned by Xlib and should not be modified or freed by the client.
1444
It will be freed by a call to
1445
.PN XDestroyOC
1446
with the associated
1447
.PN XOC .
1448
Until freed, its contents will not be modified by Xlib.
1449
.NH 4
1450
Orientation
1451
.XS
1452
\*(SN Orientation
1453
.XE
1454
.LP
1455
The
1456
.PN XNOrientation
1457
argument specifies the current orientation of text when drawn. The value of
1458
this argument is one of the values returned by the
1459
.PN XGetOMValues
1460
function with the
1461
.PN XNQueryOrientation
1462
argument specified in the
1463
.PN XOrientation
1464
list.
1465
The value of the argument is of type
1466
.PN XOrientation .
1467
When
1468
.PN XNOrientation
1469
is queried, the value specifies the current orientation.
1470
When
1471
.PN XNOrientation
1472
is set, a value is used to set the current orientation.
1473
.LP
1474
When
1475
.PN XOMOrientation_Context
1476
is set, the text orientation of the
1477
text is determined according to an implementation-defined method
1478
(for example, ISO 6429 control sequences), and the initial text orientation for
1479
locale-dependent Xlib functions is assumed to
1480
be
1481
.PN XOMOrientation_LTR_TTB .
1482
.LP
1483
The
1484
.PN XNOrientation
1485
value does not change the prime drawing direction
1486
for Xlib drawing functions.
1487
.NH 4
1488
Resource Name and Class
1489
.XS
1490
\*(SN Resource Name and Class
1491
.XE
1492
.LP
1493
The
1494
.PN XNResourceName
1495
and
1496
.PN XNResourceClass
1497
arguments are strings that specify the full name and class
1498
used by the client to obtain resources for the display of the output context.
1499
These values should be used as prefixes for name and class
1500
when looking up resources that may vary according to the output context.
1501
If these values are not set,
1502
the resources will not be fully specified.
1503
.LP
1504
It is not intended that values that can be set as XOM values be
1505
set as resources.
1506
.LP
1507
When querying for the
1508
.PN XNResourceName
1509
or
1510
.PN XNResourceClass
1511
XOC value,
1512
.PN XGetOCValues
1513
returns a null-terminated string.
1514
This string is owned by Xlib and should not be modified or freed by
1515
the client.
1516
The string will be freed by a call to
1517
.PN XDestroyOC
1518
with the associated
1519
.PN XOC
1520
or when the associated value is changed via
1521
.PN XSetOCValues .
1522
Until freed, the string contents will not be modified by Xlib.
1523
.NH 4
1524
Font Info
1525
.XS
1526
\*(SN Font Info
1527
.XE
1528
.LP
1529
The
1530
.PN XNFontInfo
1531
argument specifies a list of one or more
1532
.PN XFontStruct
1533
structures
1534
and font names for the fonts used for drawing by the given output context.
1535
The value of the argument is a pointer to a structure of type
1536
.PN XOMFontInfo .
1537
.LP
1538
.sM
1539
.Ds 0
1540
.TA .5i 2.5i
1541
.ta .5i 2.5i
1542
typedef struct {
1543
int num_font;
1544
XFontStruct **font_struct_list;
1545
char **font_name_list;
1546
} XOMFontInfo;
1547
.De
1548
.LP
1549
.eM
1550
A list of pointers to the
1551
.PN XFontStruct
1552
structures is returned to font_struct_list.
1553
A list of pointers to null-terminated, fully-specified font name strings
1554
in the locale of the output context is returned to font_name_list.
1555
The font_name_list order corresponds to the font_struct_list order.
1556
The number of
1557
.PN XFontStruct
1558
structures and font names is returned to num_font.
1559
.LP
1560
Because it is not guaranteed that a given character will be imaged using a
1561
single font glyph,
1562
there is no provision for mapping a character or default string
1563
to the font properties, font ID, or direction hint for the font
1564
for the character.
1565
The client may access the
1566
.PN XFontStruct
1567
list to obtain these values for all the fonts currently in use.
1568
.LP
1569
Xlib does not guarantee that fonts are loaded from the server
1570
at the creation of an
1571
.PN XOC .
1572
Xlib may choose to cache font data, loading it only as needed to draw text
1573
or compute text dimensions.
1574
Therefore, existence of the per_char metrics in the
1575
.PN XFontStruct
1576
structures in the
1577
.PN XFontStructSet
1578
is undefined.
1579
Also, note that all properties in the
1580
.PN XFontStruct
1581
structures are in the STRING encoding.
1582
.LP
1583
The client must not free the
1584
.PN XOMFontInfo
1585
struct itself; it will be freed when the
1586
.PN XOC
1587
is closed.
1588
.NH 4
1589
OM Automatic
1590
.XS
1591
\*(SN OM Automatic
1592
.XE
1593
.LP
1594
The
1595
.PN XNOMAutomatic
1596
argument returns whether the associated output context was created by
1597
.PN XCreateFontSet
1598
or not. Because the
1599
.PN XFreeFontSet
1600
function not only destroys the output context but also closes the implicit
1601
output method associated with it,
1602
.PN XFreeFontSet
1603
should be used with any output context created by
1604
.PN XCreateFontSet .
1605
However, it is possible that a client does not know how the output context
1606
was created.
1607
Before a client destroys the output context,
1608
it can query whether
1609
.PN XNOMAutomatic
1610
is set to determine whether
1611
.PN XFreeFontSet
1612
or
1613
.PN XDestroyOC
1614
should be used to destroy the output context.
1615
.NH 3
1616
Creating and Freeing a Font Set
1617
.XS
1618
\*(SN Creating and Freeing a Font Set
1619
.XE
1620
.LP
1621
Xlib international text drawing is done using a set of one or more fonts,
1622
as needed for the locale of the text.
1623
Fonts are loaded according to a list of base font names
1624
supplied by the client and the charsets required by the locale.
1625
The
1626
.PN XFontSet
1627
is an opaque type representing the state of a particular output thread
1628
and is equivalent to the type
1629
.PN XOC .
1630
.LP
1631
.sp
1632
The
1633
.PN XCreateFontSet
1634
function is a convenience function for creating an output context using
1635
only default values. The returned
1636
.PN XFontSet
1637
has an implicitly created
1638
.PN XOM .
1639
This
1640
.PN XOM
1641
has an OM value
1642
.PN XNOMAutomatic
1643
automatically set to
1644
.PN True
1645
so that the output context self indicates whether it was created by
1646
.PN XCreateOC
1647
or
1648
.PN XCreateFontSet .
1649
.IN "XCreateFontSet" "" "@DEF@"
1650
.sM
1651
.FD 0
1652
XFontSet XCreateFontSet\^(\^\fIdisplay\fP\^, \fIbase_font_name_list\fP\^, \fImissing_charset_list_return\fP\^,
1653
.br
1654
\fImissing_charset_count_return\fP\^, \fIdef_string_return\fP\^)
1655
.br
1656
Display *\fIdisplay\fP\^;
1657
.br
1658
char *\fIbase_font_name_list\fP\^;
1659
.br
1660
char ***\fImissing_charset_list_return\fP\^;
1661
.br
1662
int *\fImissing_charset_count_return\fP\^;
1663
.br
1664
char **\fIdef_string_return\fP\^;
1665
.FN
1666
.IP \fIdisplay\fP 1i
1667
Specifies the connection to the X server.
1668
.IP \fIbase_font_name_list\fP 1i
1669
Specifies the base font names.
1670
.IP \fImissing_charset_list_return\fP 1i
1671
Returns the missing charsets.
1672
.IP \fImissing_charset_count_return\fP 1i
1673
Returns the number of missing charsets.
1674
.IP \fIdef_string_return\fP 1i
1675
Returns the string drawn for missing charsets.
1676
.LP
1677
.eM
1678
The
1679
.PN XCreateFontSet
1680
function creates a font set for the specified display.
1681
The font set is bound to the current locale when
1682
.PN XCreateFontSet
1683
is called.
1684
The font set may be used in subsequent calls to obtain font
1685
and character information and to image text in the locale of the font set.
1686
.LP
1687
The base_font_name_list argument is a list of base font names
1688
that Xlib uses to load the fonts needed for the locale.
1689
The base font names are a comma-separated list.
1690
The string is null-terminated
1691
and is assumed to be in the Host Portable Character Encoding;
1692
otherwise, the result is implementation-dependent.
1693
White space immediately on either side of a separating comma is ignored.
1694
.LP
1695
Use of XLFD font names permits Xlib to obtain the fonts needed for a
1696
variety of locales from a single locale-independent base font name.
1697
The single base font name should name a family of fonts whose members
1698
are encoded in the various charsets needed by the locales of interest.
1699
.LP
1700
An XLFD base font name can explicitly name a charset needed for the locale.
1701
This allows the user to specify an exact font for use with a charset required
1702
by a locale, fully controlling the font selection.
1703
.LP
1704
If a base font name is not an XLFD name,
1705
Xlib will attempt to obtain an XLFD name from the font properties
1706
for the font.
1707
If this action is successful in obtaining an XLFD name, the
1708
.PN XBaseFontNameListOfFontSet
1709
function will return this XLFD name instead of the client-supplied name.
1710
.LP
1711
Xlib uses the following algorithm to select the fonts
1712
that will be used to display text with the
1713
.PN XFontSet .
1714
.LP
1715
For each font charset required by the locale,
1716
the base font name list is searched for the first appearance of one
1717
of the following cases that names a set of fonts that exist at the server:
1718
.IP \(bu 5
1719
The first XLFD-conforming base font name that specifies the required
1720
charset or a superset of the required charset in its
1721
.PN CharSetRegistry
1722
and
1723
.PN CharSetEncoding
1724
fields.
1725
The implementation may use a base font name whose specified charset
1726
is a superset of the required charset, for example,
1727
an ISO8859-1 font for an ASCII charset.
1728
.IP \(bu 5
1729
The first set of one or more XLFD-conforming base font names
1730
that specify one or more charsets that can be remapped to support the
1731
required charset.
1732
The Xlib implementation may recognize various mappings
1733
from a required charset to one or more other charsets
1734
and use the fonts for those charsets.
1735
For example, JIS Roman is ASCII with tilde and backslash replaced
1736
by yen and overbar;
1737
Xlib may load an ISO8859-1 font to support this character set
1738
if a JIS Roman font is not available.
1739
.IP \(bu 5
1740
The first XLFD-conforming font name or the first non-XLFD font name
1741
for which an XLFD font name can be obtained, combined with the
1742
required charset (replacing the
1743
.PN CharSetRegistry
1744
and
1745
.PN CharSetEncoding
1746
fields in the XLFD font name).
1747
As in case 1,
1748
the implementation may use a charset that is a superset
1749
of the required charset.
1750
.IP \(bu 5
1751
The first font name that can be mapped in some implementation-dependent
1752
manner to one or more fonts that support imaging text in the charset.
1753
.LP
1754
For example, assume that a locale required the charsets:
1755
.LP
1756
.Ds 0
1757
ISO8859-1
1758
JISX0208.1983
1759
JISX0201.1976
1760
GB2312-1980.0
1761
.De
1762
.LP
1763
The user could supply a base_font_name_list that explicitly specifies the
1764
charsets, ensuring that specific fonts are used if they exist.
1765
For example:
1766
.LP
1767
.Ds 0
1768
"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240-JISX0208.1983-0,\\
1769
-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120-JISX0201.1976-0,\\
1770
-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240-GB2312-1980.0,\\
1771
-Adobe-Courier-Bold-R-Normal--25-180-75-75-M-150-ISO8859-1"
1772
.De
1773
.LP
1774
Alternatively, the user could supply a base_font_name_list
1775
that omits the charsets,
1776
letting Xlib select font charsets required for the locale.
1777
For example:
1778
.LP
1779
.Ds 0
1780
"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\
1781
-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120,\\
1782
-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\
1783
-Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150"
1784
.De
1785
.LP
1786
Alternatively, the user could simply supply a single base font name
1787
that allows Xlib to select from all available fonts
1788
that meet certain minimum XLFD property requirements.
1789
For example:
1790
.LP
1791
.Ds 0
1792
"-*-*-*-R-Normal--*-180-100-100-*-*"
1793
.De
1794
.LP
1795
If
1796
.PN XCreateFontSet
1797
is unable to create the font set,
1798
either because there is insufficient memory or because the current locale
1799
is not supported,
1800
.PN XCreateFontSet
1801
returns NULL, missing_charset_list_return is set to NULL,
1802
and missing_charset_count_return
1803
is set to zero.
1804
If fonts exist for all of the charsets required by the current locale,
1805
.PN XCreateFontSet
1806
returns a valid
1807
.PN XFontSet ,
1808
missing_charset_list_return is set to NULL,
1809
and missing_charset_count_return is set to zero.
1810
.LP
1811
If no font exists for one or more of the required charsets,
1812
.PN XCreateFontSet
1813
sets missing_charset_list_return to a
1814
list of one or more null-terminated charset names for which no font exists
1815
and sets missing_charset_count_return to the number of missing fonts.
1816
The charsets are from the list of the required charsets for
1817
the encoding of the locale and do not include any charsets to which Xlib
1818
may be able to remap a required charset.
1819
.LP
1820
If no font exists for any of the required charsets
1821
or if the locale definition in Xlib requires that a font exist
1822
for a particular charset and a font is not found for that charset,
1823
.PN XCreateFontSet
1824
returns NULL.
1825
Otherwise,
1826
.PN XCreateFontSet
1827
returns a valid
1828
.PN XFontSet
1829
to font_set.
1830
.LP
1831
When an Xmb/wc drawing or measuring function is called with an
1832
.PN XFontSet
1833
that has missing charsets, some characters in the locale will not be
1834
drawable.
1835
If def_string_return is non-NULL,
1836
.PN XCreateFontSet
1837
returns a pointer to a string that represents the glyphs
1838
that are drawn with this
1839
.PN XFontSet
1840
when the charsets of the available fonts do not include all font glyphs
1841
required to draw a codepoint.
1842
The string does not necessarily consist of valid characters
1843
in the current locale and is not necessarily drawn with
1844
the fonts loaded for the font set,
1845
but the client can draw and measure the default glyphs
1846
by including this string in a string being drawn or measured with the
1847
.PN XFontSet .
1848
.LP
1849
If the string returned to def_string_return is the empty string ("\^"),
1850
no glyphs are drawn, and the escapement is zero.
1851
The returned string is null-terminated.
1852
It is owned by Xlib and should not be modified or freed by the client.
1853
It will be freed by a call to
1854
.PN XFreeFontSet
1855
with the associated
1856
.PN XFontSet .
1857
Until freed, its contents will not be modified by Xlib.
1858
.LP
1859
The client is responsible for constructing an error message from the
1860
missing charset and default string information and may choose to continue
1861
operation in the case that some fonts did not exist.
1862
.LP
1863
The returned
1864
.PN XFontSet
1865
and missing charset list should be freed with
1866
.PN XFreeFontSet
1867
and
1868
.PN XFreeStringList ,
1869
respectively.
1870
The client-supplied base_font_name_list may be freed
1871
by the client after calling
1872
.PN XCreateFontSet .
1873
.LP
1874
.sp
1875
To obtain a list of
1876
.PN XFontStruct
1877
structures and full font names given an
1878
.PN XFontSet ,
1879
use
1880
.PN XFontsOfFontSet .
1881
.IN "XFontsOfFontSet" "" "@DEF@"
1882
.sM
1883
.FD 0
1884
int XFontsOfFontSet\^(\^\fIfont_set\fP\^, \fIfont_struct_list_return\fP\^, \fIfont_name_list_return\fP\^)
1885
.br
1886
XFontSet \fIfont_set\fP\^;
1887
.br
1888
XFontStruct ***\fIfont_struct_list_return\fP\^;
1889
.br
1890
char ***\fIfont_name_list_return\fP\^;
1891
.FN
1892
.IP \fIfont_set\fP 1i
1893
Specifies the font set.
1894
.IP \fIfont_struct_list_return\fP 1i
1895
Returns the list of font structs.
1896
.IP \fIfont_name_list_return\fP 1i
1897
Returns the list of font names.
1898
.LP
1899
.eM
1900
The
1901
.PN XFontsOfFontSet
1902
function returns a list of one or more
1903
.PN XFontStructs
1904
and font names for the fonts used by the Xmb and Xwc layers
1905
for the given font set.
1906
A list of pointers to the
1907
.PN XFontStruct
1908
structures is returned to font_struct_list_return.
1909
A list of pointers to null-terminated, fully specified font name strings
1910
in the locale of the font set is returned to font_name_list_return.
1911
The font_name_list order corresponds to the font_struct_list order.
1912
The number of
1913
.PN XFontStruct
1914
structures and font names is returned as the value of the function.
1915
.LP
1916
Because it is not guaranteed that a given character will be imaged using a
1917
single font glyph,
1918
there is no provision for mapping a character or default string
1919
to the font properties, font ID, or direction hint for the font
1920
for the character.
1921
The client may access the
1922
.PN XFontStruct
1923
list to obtain these values for all the fonts currently in use.
1924
.LP
1925
Xlib does not guarantee that fonts are loaded from the server
1926
at the creation of an
1927
.PN XFontSet .
1928
Xlib may choose to cache font data, loading it only as needed to draw text
1929
or compute text dimensions.
1930
Therefore, existence of the per_char metrics in the
1931
.PN XFontStruct
1932
structures in the
1933
.PN XFontStructSet
1934
is undefined.
1935
Also, note that all properties in the
1936
.PN XFontStruct
1937
structures are in the STRING encoding.
1938
.LP
1939
The
1940
.PN XFontStruct
1941
and font name lists are owned by Xlib
1942
and should not be modified or freed by the client.
1943
They will be freed by a call to
1944
.PN XFreeFontSet
1945
with the associated
1946
.PN XFontSet .
1947
Until freed, their contents will not be modified by Xlib.
1948
.LP
1949
.sp
1950
To obtain the base font name list and the selected font name list given an
1951
.PN XFontSet ,
1952
use
1953
.PN XBaseFontNameListOfFontSet .
1954
.IN "XBaseFontNameListOfFontSet" "" "@DEF@"
1955
.sM
1956
.FD 0
1957
char *XBaseFontNameListOfFontSet\^(\^\fIfont_set\fP\^)
1958
.br
1959
XFontSet \fIfont_set\fP\^;
1960
.FN
1961
.IP \fIfont_set\fP 1i
1962
Specifies the font set.
1963
.LP
1964
.eM
1965
The
1966
.PN XBaseFontNameListOfFontSet
1967
function returns the original base font name list supplied
1968
by the client when the
1969
.PN XFontSet
1970
was created.
1971
A null-terminated string containing a list of
1972
comma-separated font names is returned
1973
as the value of the function.
1974
White space may appear immediately on either side of separating commas.
1975
.LP
1976
If
1977
.PN XCreateFontSet
1978
obtained an XLFD name from the font properties for the font specified
1979
by a non-XLFD base name, the
1980
.PN XBaseFontNameListOfFontSet
1981
function will return the XLFD name instead of the non-XLFD base name.
1982
.LP
1983
The base font name list is owned by Xlib and should not be modified or
1984
freed by the client.
1985
It will be freed by a call to
1986
.PN XFreeFontSet
1987
with the associated
1988
.PN XFontSet .
1989
Until freed, its contents will not be modified by Xlib.
1990
.LP
1991
.sp
1992
To obtain the locale name given an
1993
.PN XFontSet ,
1994
use
1995
.PN XLocaleOfFontSet .
1996
.IN "XLocaleOfFontSet" "" "@DEF@"
1997
.sM
1998
.FD 0
1999
char *XLocaleOfFontSet\^(\^\fIfont_set\fP\^)
2000
.br
2001
XFontSet \fIfont_set\fP\^;
2002
.FN
2003
.IP \fIfont_set\fP 1i
2004
Specifies the font set.
2005
.LP
2006
.eM
2007
The
2008
.PN XLocaleOfFontSet
2009
function
2010
returns the name of the locale bound to the specified
2011
.PN XFontSet ,
2012
as a null-terminated string.
2013
.LP
2014
The returned locale name string is owned by Xlib
2015
and should not be modified or freed by the client.
2016
It may be freed by a call to
2017
.PN XFreeFontSet
2018
with the associated
2019
.PN XFontSet .
2020
Until freed, it will not be modified by Xlib.
2021
.LP
2022
.sp
2023
The
2024
.PN XFreeFontSet
2025
function is a convenience function for freeing an output context.
2026
.PN XFreeFontSet
2027
also frees its associated
2028
.PN XOM
2029
if the output context was created by
2030
.PN XCreateFontSet .
2031
.IN "XFreeFontSet" "" "@DEF@"
2032
.sM
2033
.FD 0
2034
void XFreeFontSet\^(\^\fIdisplay\fP\^, \fIfont_set\fP\^)
2035
.br
2036
Display *\fIdisplay\fP\^;
2037
.br
2038
XFontSet \fIfont_set\fP\^;
2039
.FN
2040
.IP \fIdisplay\fP 1i
2041
Specifies the connection to the X server.
2042
.IP \fIfont_set\fP 1i
2043
Specifies the font set.
2044
.LP
2045
.eM
2046
The
2047
.PN XFreeFontSet
2048
function frees the specified font set.
2049
The associated base font name list, font name list,
2050
.PN XFontStruct
2051
list, and
2052
.PN XFontSetExtents ,
2053
if any, are freed.
2054
.NH 3
2055
Obtaining Font Set Metrics
2056
.XS
2057
\*(SN Obtaining Font Set Metrics
2058
.XE
2059
.LP
2060
Metrics for the internationalized text drawing functions
2061
are defined in terms of a primary draw direction,
2062
which is the default direction in which the character origin advances
2063
for each succeeding character in the string.
2064
The Xlib interface is currently defined to support only a left-to-right
2065
primary draw direction.
2066
The drawing origin is the position passed to the drawing function
2067
when the text is drawn.
2068
The baseline is a line drawn through the drawing origin parallel
2069
to the primary draw direction.
2070
Character ink is the pixels painted in the foreground color
2071
and does not include interline or intercharacter spacing
2072
or image text background pixels.
2073
.LP
2074
The drawing functions are allowed to implement implicit text
2075
directionality control, reversing the order in which characters are
2076
rendered along the primary draw direction in response to locale-specific
2077
lexical analysis of the string.
2078
.LP
2079
Regardless of the character rendering order,
2080
the origins of all characters are on the primary draw direction side
2081
of the drawing origin.
2082
The screen location of a particular character image may be determined with
2083
.PN XmbTextPerCharExtents
2084
or
2085
.PN XwcTextPerCharExtents .
2086
.LP
2087
The drawing functions are allowed to implement context-dependent
2088
rendering, where the glyphs drawn for a string are not simply a
2089
concatenation of the glyphs that represent each individual character.
2090
A string of two characters drawn with
2091
.PN XmbDrawString
2092
may render differently than if the two characters
2093
were drawn with separate calls to
2094
.PN XmbDrawString .
2095
If the client appends or inserts a character
2096
in a previously drawn string,
2097
the client may need to redraw some adjacent characters
2098
to obtain proper rendering.
2099
.LP
2100
.sp
2101
To find out about direction-dependent rendering, use
2102
.PN XDirectionalDependentDrawing .
2103
.IN "XDirectionalDependentDrawing" "" "@DEF@"
2104
.sM
2105
.FD 0
2106
Bool XDirectionalDependentDrawing\^(\^\fIfont_set\fP\^)
2107
.br
2108
XFontSet \fIfont_set\fP\^;
2109
.FN
2110
.IP \fIfont_set\fP 1i
2111
Specifies the font set.
2112
.LP
2113
.eM
2114
The
2115
.PN XDirectionalDependentDrawing
2116
function returns
2117
.PN True
2118
if the drawing functions implement implicit text directionality;
2119
otherwise, it returns
2120
.PN False .
2121
.LP
2122
.sp
2123
To find out about context-dependent rendering, use
2124
.PN XContextualDrawing .
2125
.IN "XContextualDrawing" "" "@DEF@"
2126
.sM
2127
.FD 0
2128
Bool XContextualDrawing\^(\^\fIfont_set\fP\^)
2129
.br
2130
XFontSet \fIfont_set\fP\^;
2131
.FN
2132
.IP \fIfont_set\fP 1i
2133
Specifies the font set.
2134
.LP
2135
.eM
2136
The
2137
.PN XContextualDrawing
2138
function returns
2139
.PN True
2140
if text drawn with the font set might include context-dependent drawing;
2141
otherwise, it returns
2142
.PN False .
2143
.LP
2144
.sp
2145
To find out about context-dependent or direction-dependent rendering, use
2146
.PN XContextDependentDrawing .
2147
.IN "XContextDependentDrawing" "" "@DEF@"
2148
.sM
2149
.FD 0
2150
Bool XContextDependentDrawing\^(\^\fIfont_set\fP\^)
2151
.br
2152
XFontSet \fIfont_set\fP\^;
2153
.FN
2154
.IP \fIfont_set\fP 1i
2155
Specifies the font set.
2156
.LP
2157
.eM
2158
The
2159
.PN XContextDependentDrawing
2160
function returns
2161
.PN True
2162
if the drawing functions implement implicit text directionality or
2163
if text drawn with the font_set might include context-dependent drawing;
2164
otherwise, it returns
2165
.PN False .
2166
.LP
2167
The drawing functions do not interpret newline, tab, or other control
2168
characters.
2169
The behavior when nonprinting characters other than space are drawn
2170
is implementation-dependent.
2171
It is the client's responsibility to interpret control characters
2172
in a text stream.
2173
.LP
2174
The maximum character extents for the fonts that are used by the text
2175
drawing layers can be accessed by the
2176
.PN XFontSetExtents
2177
structure:
2178
.IN "XFontSetExtents" "" "@DEF@"
2179
.LP
2180
.Ds 0
2181
.TA .5i 3i
2182
.ta .5i 3i
2183
typedef struct {
2184
XRectangle max_ink_extent; /* over all drawable characters */
2185
XRectangle max_logical_extent; /* over all drawable characters */
2186
} XFontSetExtents;
2187
.De
2188
.LP
2189
The
2190
.PN XRectangle
2191
structures used to return font set metrics are the usual Xlib screen-oriented
2192
rectangles
2193
with x, y giving the upper left corner, and width and height always positive.
2194
.LP
2195
The max_ink_extent member gives the maximum extent, over all drawable characters, of
2196
the rectangles that bound the character glyph image drawn in the
2197
foreground color, relative to a constant origin.
2198
See
2199
.PN XmbTextExtents
2200
and
2201
.PN XwcTextExtents
2202
for detailed semantics.
2203
.LP
2204
The max_logical_extent member gives the maximum extent,
2205
over all drawable characters, of the rectangles
2206
that specify minimum spacing to other graphical features,
2207
relative to a constant origin.
2208
Other graphical features drawn by the client, for example,
2209
a border surrounding the text, should not intersect this rectangle.
2210
The max_logical_extent member should be used to compute minimum
2211
interline spacing and the minimum area that must be allowed
2212
in a text field to draw a given number of arbitrary characters.
2213
.LP
2214
Due to context-dependent rendering,
2215
appending a given character to a string may change
2216
the string's extent by an amount other than that character's
2217
individual extent.
2218
.LP
2219
The rectangles for a given character in a string can be obtained from
2220
.PN XmbPerCharExtents
2221
or
2222
.PN XwcPerCharExtents .
2223
.LP
2224
.sp
2225
To obtain the maximum extents structure given an
2226
.PN XFontSet ,
2227
use
2228
.PN XExtentsOfFontSet .
2229
.IN "XExtentsOfFontSet" "" "@DEF@"
2230
.sM
2231
.FD 0
2232
XFontSetExtents *XExtentsOfFontSet\^(\^\fIfont_set\fP\^)
2233
.br
2234
XFontSet \fIfont_set\fP\^;
2235
.FN
2236
.IP \fIfont_set\fP 1i
2237
Specifies the font set.
2238
.LP
2239
.eM
2240
The
2241
.PN XExtentsOfFontSet
2242
function returns an
2243
.PN XFontSetExtents
2244
structure for the fonts used by the Xmb and Xwc layers
2245
for the given font set.
2246
.LP
2247
The
2248
.PN XFontSetExtents
2249
structure is owned by Xlib and should not be modified
2250
or freed by the client.
2251
It will be freed by a call to
2252
.PN XFreeFontSet
2253
with the associated
2254
.PN XFontSet .
2255
Until freed, its contents will not be modified by Xlib.
2256
.LP
2257
.sp
2258
To obtain the escapement in pixels of the specified text as a value,
2259
use
2260
.PN XmbTextEscapement
2261
or
2262
.PN XwcTextEscapement .
2263
.IN "XmbTextEscapement" "" "@DEF@"
2264
.IN "XwcTextEscapement" "" "@DEF@"
2265
.sM
2266
.FD 0
2267
int XmbTextEscapement\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^)
2268
.br
2269
XFontSet \fIfont_set\fP\^;
2270
.br
2271
char *\fIstring\fP\^;
2272
.br
2273
int \fInum_bytes\fP\^;
2274
.FN
2275
.FD 0
2276
int XwcTextEscapement\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^)
2277
.br
2278
XFontSet \fIfont_set\fP\^;
2279
.br
2280
wchar_t *\fIstring\fP\^;
2281
.br
2282
int \fInum_wchars\fP\^;
2283
.FN
2284
.IP \fIfont_set\fP 1i
2285
Specifies the font set.
2286
.IP \fIstring\fP 1i
2287
Specifies the character string.
2288
.IP \fInum_bytes\fP 1i
2289
Specifies the number of bytes in the string argument.
2290
.IP \fInum_wchars\fP 1i
2291
Specifies the number of characters in the string argument.
2292
.LP
2293
.eM
2294
The
2295
.PN XmbTextEscapement
2296
and
2297
.PN XwcTextEscapement
2298
functions return the escapement in pixels of the specified string as a value,
2299
using the fonts loaded for the specified font set.
2300
The escapement is the distance in pixels in the primary draw
2301
direction from the drawing origin to the origin of the next character to
2302
be drawn, assuming that the rendering of the next character is not
2303
dependent on the supplied string.
2304
.LP
2305
Regardless of the character rendering order,
2306
the escapement is always positive.
2307
.LP
2308
.sp
2309
To obtain the overall_ink_return and overall_logical_return arguments,
2310
the overall bounding box of the string's image, and a logical bounding box,
2311
use
2312
.PN XmbTextExtents
2313
or
2314
.PN XwcTextExtents .
2315
.IN "XmbTextExtents" "" "@DEF@"
2316
.IN "XwcTextExtents" "" "@DEF@"
2317
.sM
2318
.FD 0
2319
int XmbTextExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^, \fIoverall_ink_return\fP\^, \fIoverall_logical_return\fP\^)
2320
.br
2321
XFontSet \fIfont_set\fP\^;
2322
.br
2323
char *\fIstring\fP\^;
2324
.br
2325
int \fInum_bytes\fP\^;
2326
.br
2327
XRectangle *\fIoverall_ink_return\fP\^;
2328
.br
2329
XRectangle *\fIoverall_logical_return\fP\^;
2330
.FN
2331
.FD 0
2332
int XwcTextExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^,
2333
\fIoverall_ink_return\fP\^, \fIoverall_logical_return\fP\^)
2334
.br
2335
XFontSet \fIfont_set\fP\^;
2336
.br
2337
wchar_t *\fIstring\fP\^;
2338
.br
2339
int \fInum_wchars\fP\^;
2340
.br
2341
XRectangle *\fIoverall_ink_return\fP\^;
2342
.br
2343
XRectangle *\fIoverall_logical_return\fP\^;
2344
.FN
2345
.IP \fIfont_set\fP 1i
2346
Specifies the font set.
2347
.IP \fIstring\fP 1i
2348
Specifies the character string.
2349
.IP \fInum_bytes\fP 1i
2350
Specifies the number of bytes in the string argument.
2351
.IP \fInum_wchars\fP 1i
2352
Specifies the number of characters in the string argument.
2353
.ds Ov dimensions
2354
.IP \fIoverall_ink_return\fP 1i
2355
Returns the overall ink \*(Ov.
2356
.IP \fIoverall_logical_return\fP 1i
2357
Returns the overall logical \*(Ov.
2358
.LP
2359
.eM
2360
The
2361
.PN XmbTextExtents
2362
and
2363
.PN XwcTextExtents
2364
functions set the components of the specified overall_ink_return and
2365
overall_logical_return
2366
arguments to the overall bounding box of the string's image
2367
and a logical bounding box for spacing purposes, respectively.
2368
They return the value returned by
2369
.PN XmbTextEscapement
2370
or
2371
.PN XwcTextEscapement .
2372
These metrics are relative to the drawing origin of the string,
2373
using the fonts loaded for the specified font set.
2374
.LP
2375
If the overall_ink_return argument is non-NULL,
2376
it is set to the bounding box of the string's character ink.
2377
The overall_ink_return for a nondescending, horizontally drawn
2378
Latin character is conventionally entirely above the baseline;
2379
that is, overall_ink_return.height <= \-overall_ink_return.y.
2380
The overall_ink_return for a nonkerned character
2381
is entirely at, and to the right of, the origin;
2382
that is, overall_ink_return.x >= 0.
2383
A character consisting of a single pixel at the origin would set
2384
overall_ink_return fields y = 0, x = 0, width = 1, and height = 1.
2385
.LP
2386
If the overall_logical_return argument is non-NULL,
2387
it is set to the bounding box that provides minimum spacing
2388
to other graphical features for the string.
2389
Other graphical features, for example, a border surrounding the text,
2390
should not intersect this rectangle.
2391
.LP
2392
When the
2393
.PN XFontSet
2394
has missing charsets,
2395
metrics for each unavailable character are taken
2396
from the default string returned by
2397
.PN XCreateFontSet
2398
so that the metrics represent the text as it will actually be drawn.
2399
The behavior for an invalid codepoint is undefined.
2400
.LP
2401
To determine the effective drawing origin for a character in a drawn string,
2402
the client should call
2403
.PN XmbTextPerCharExtents
2404
on the entire string, then on the character,
2405
and subtract the x values of the returned
2406
rectangles for the character.
2407
This is useful to redraw portions of a line of text
2408
or to justify words, but for context-dependent rendering,
2409
the client should not assume that it can redraw the character by itself
2410
and get the same rendering.
2411
.LP
2412
.sp
2413
To obtain per-character information for a text string,
2414
use
2415
.PN XmbTextPerCharExtents
2416
or
2417
.PN XwcTextPerCharExtents .
2418
.IN "XmbTextPerCharExtents" "" "@DEF@"
2419
.IN "XwcTextPerCharExtents" "" "@DEF@"
2420
.sM
2421
.FD 0
2422
Status XmbTextPerCharExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^, \fIink_array_return\fP\^,
2423
.br
2424
\fIlogical_array_return\fP\^, \fIarray_size\fP\^, \fInum_chars_return\fP\^, \fIoverall_ink_return\fP\^, \fIoverall_logical_return\fP\^)
2425
.br
2426
XFontSet \fIfont_set\fP\^;
2427
.br
2428
char *\fIstring\fP\^;
2429
.br
2430
int \fInum_bytes\fP\^;
2431
.br
2432
XRectangle *\fIink_array_return\fP\^;
2433
.br
2434
XRectangle *\fIlogical_array_return\fP\^;
2435
.br
2436
int \fIarray_size\fP\^;
2437
.br
2438
int *\fInum_chars_return\fP\^;
2439
.br
2440
XRectangle *\fIoverall_ink_return\fP\^;
2441
.br
2442
XRectangle *\fIoverall_logical_return\fP\^;
2443
.FN
2444
.FD 0
2445
Status XwcTextPerCharExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^, \fIink_array_return\fP\^,
2446
.br
2447
\fIlogical_array_return\fP\^, \fIarray_size\fP\^, \fInum_chars_return\fP\^, \fIoverall_ink_return\fP\^, \fIoverall_ink_return\fP\^)
2448
.br
2449
XFontSet \fIfont_set\fP\^;
2450
.br
2451
wchar_t *\fIstring\fP\^;
2452
.br
2453
int \fInum_wchars\fP\^;
2454
.br
2455
XRectangle *\fIink_array_return\fP\^;
2456
.br
2457
XRectangle *\fIlogical_array_return\fP;
2458
.br
2459
int \fIarray_size\fP\^;
2460
.br
2461
int *\fInum_chars_return\fP\^;
2462
.br
2463
XRectangle *\fIoverall_ink_return\fP\^;
2464
.br
2465
XRectangle *\fIoverall_logical_return\fP\^;
2466
.FN
2467
.IP \fIfont_set\fP 1i
2468
Specifies the font set.
2469
.IP \fIstring\fP 1i
2470
Specifies the character string.
2471
.IP \fInum_bytes\fP 1i
2472
Specifies the number of bytes in the string argument.
2473
.IP \fInum_wchars\fP 1i
2474
Specifies the number of characters in the string argument.
2475
.IP \fIink_array_return\fP 1i
2476
Returns the ink dimensions for each character.
2477
.IP \fIlogical_array_return\fP 1i
2478
Returns the logical dimensions for each character.
2479
.IP \fIarray_size\fP 1i
2480
Specifies the size of ink_array_return and logical_array_return.
2481
The caller must pass in arrays of this size.
2482
.IP \fInum_chars_return\fP 1i
2483
Returns the number of characters in the string argument.
2484
.ds Ov extents of the entire string
2485
.IP \fIoverall_ink_return\fP 1i
2486
Returns the overall ink \*(Ov.
2487
.IP \fIoverall_logical_return\fP 1i
2488
Returns the overall logical \*(Ov.
2489
.LP
2490
.eM
2491
The
2492
.PN XmbTextPerCharExtents
2493
and
2494
.PN XwcTextPerCharExtents
2495
functions return the text dimensions of each character of the specified text,
2496
using the fonts loaded for the specified font set.
2497
Each successive element of ink_array_return and logical_array_return
2498
is set to the successive character's drawn metrics,
2499
relative to the drawing origin of the string and one
2500
rectangle
2501
for each character in the supplied text string.
2502
The number of elements of ink_array_return and logical_array_return
2503
that have been set is returned to num_chars_return.
2504
.LP
2505
Each element of ink_array_return is set to the bounding box
2506
of the corresponding character's drawn foreground color.
2507
Each element of logical_array_return is set to the bounding box
2508
that provides minimum spacing to other graphical features
2509
for the corresponding character.
2510
Other graphical features should not intersect any of the
2511
logical_array_return rectangles.
2512
.LP
2513
Note that an
2514
.PN XRectangle
2515
represents the effective drawing dimensions of the character,
2516
regardless of the number of font glyphs that are used to draw
2517
the character or the direction in which the character is drawn.
2518
If multiple characters map to a single character glyph,
2519
the dimensions of all the
2520
.PN XRectangles
2521
of those characters are the same.
2522
.LP
2523
When the
2524
.PN XFontSet
2525
has missing charsets, metrics for each unavailable
2526
character are taken from the default string returned by
2527
.PN XCreateFontSet
2528
so that the metrics represent the text as it will actually be drawn.
2529
The behavior for an invalid codepoint is undefined.
2530
.LP
2531
If the array_size is too small for the number of characters in the
2532
supplied text, the functions return zero
2533
and num_chars_return is set to the number of rectangles required.
2534
Otherwise, the functions return a nonzero value.
2535
.LP
2536
If the overall_ink_return or overall_logical_return argument is non-NULL,
2537
.PN XmbTextPerCharExtents
2538
and
2539
.PN XwcTextPerCharExtents
2540
return the maximum extent of the string's metrics to overall_ink_return
2541
or overall_logical_return, as returned by
2542
.PN XmbTextExtents
2543
or
2544
.PN XwcTextExtents .
2545
.NH 3
2546
Drawing Text Using Font Sets
2547
.XS
2548
\*(SN Drawing Text Using Font Sets
2549
.XE
2550
.LP
2551
The functions defined in this section
2552
draw text at a specified location in a drawable.
2553
They are similar to the functions
2554
.PN XDrawText ,
2555
.PN XDrawString ,
2556
and
2557
.PN XDrawImageString
2558
except that they work with font sets instead of single fonts
2559
and interpret the text based on the locale of the font set
2560
instead of treating the bytes of the string as direct font indexes.
2561
See section 8.6 for details of the use of Graphics Contexts (GCs)
2562
and possible protocol errors.
2563
If a
2564
.PN BadFont
2565
error is generated,
2566
characters prior to the offending character may have been drawn.
2567
.LP
2568
The text is drawn using the fonts loaded for the specified font set;
2569
the font in the GC is ignored and may be modified by the functions.
2570
No validation that all fonts conform to some width rule is performed.
2571
.LP
2572
The text functions
2573
.PN XmbDrawText
2574
and
2575
.PN XwcDrawText
2576
use the following structures:
2577
.LP
2578
.IN "XmbTextItem" "" "@DEF@"
2579
.sM
2580
.Ds 0
2581
.TA .5i 2.5i
2582
.ta .5i 2.5i
2583
typedef struct {
2584
char *chars; /* pointer to string */
2585
int nchars; /* number of bytes */
2586
int delta; /* pixel delta between strings */
2587
XFontSet font_set; /* fonts, None means don't change */
2588
} XmbTextItem;
2589
.De
2590
.LP
2591
.IN "XwcTextItem" "" "@DEF@"
2592
.Ds 0
2593
.TA .5i 2.5i
2594
.ta .5i 2.5i
2595
typedef struct {
2596
wchar_t *chars; /* pointer to wide char string */
2597
int nchars; /* number of wide characters */
2598
int delta; /* pixel delta between strings */
2599
XFontSet font_set; /* fonts, None means don't change */
2600
} XwcTextItem;
2601
.De
2602
.LP
2603
.eM
2604
.sp
2605
To draw text using multiple font sets in a given drawable, use
2606
.PN XmbDrawText
2607
or
2608
.PN XwcDrawText .
2609
.IN "XmbDrawText" "" "@DEF@"
2610
.IN "XwcDrawText" "" "@DEF@"
2611
.sM
2612
.FD 0
2613
void XmbDrawText\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^)
2614
.br
2615
Display *\fIdisplay\fP\^;
2616
.br
2617
Drawable \fId\fP\^;
2618
.br
2619
GC \fIgc\fP\^;
2620
.br
2621
int \fIx\fP\^, \fIy\fP\^;
2622
.br
2623
XmbTextItem *\fIitems\fP\^;
2624
.br
2625
int \fInitems\fP\^;
2626
.FN
2627
.FD 0
2628
void XwcDrawText\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^)
2629
.br
2630
Display *\fIdisplay\fP\^;
2631
.br
2632
Drawable \fId\fP\^;
2633
.br
2634
GC \fIgc\fP\^;
2635
.br
2636
int \fIx\fP\^, \fIy\fP\^;
2637
.br
2638
XwcTextItem *\fIitems\fP\^;
2639
.br
2640
int \fInitems\fP\^;
2641
.FN
2642
.IP \fIdisplay\fP 1i
2643
Specifies the connection to the X server.
2644
.IP \fId\fP 1i
2645
Specifies the drawable.
2646
.IP \fIgc\fP 1i
2647
Specifies the GC.
2648
.ds Xy
2649
.IP \fIx\fP 1i
2650
.br
2651
.ns
2652
.IP \fIy\fP 1i
2653
Specify the x and y coordinates\*(Xy.
2654
.IP \fIitems\fP 1i
2655
Specifies an array of text items.
2656
.IP \fInitems\fP 1i
2657
Specifies the number of text items in the array.
2658
.LP
2659
.eM
2660
The
2661
.PN XmbDrawText
2662
and
2663
.PN XwcDrawText
2664
functions allow complex spacing and font set shifts between text strings.
2665
Each text item is processed in turn, with the origin of a text
2666
element advanced in the primary draw direction by the escapement of the
2667
previous text item.
2668
A text item delta specifies an additional escapement of the text item
2669
drawing origin in the primary draw direction.
2670
A font_set member other than
2671
.PN None
2672
in an item causes the font set to be used for this and subsequent text items
2673
in the text_items list.
2674
Leading text items with a font_set member set to
2675
.PN None
2676
will not be drawn.
2677
.LP
2678
.PN XmbDrawText
2679
and
2680
.PN XwcDrawText
2681
do not perform any context-dependent rendering between text segments.
2682
Clients may compute the drawing metrics by passing each text segment to
2683
.PN XmbTextExtents
2684
and
2685
.PN XwcTextExtents
2686
or
2687
.PN XmbTextPerCharExtents
2688
and
2689
.PN XwcTextPerCharExtents .
2690
When the
2691
.PN XFontSet
2692
has missing charsets, each unavailable character is drawn
2693
with the default string returned by
2694
.PN XCreateFontSet .
2695
The behavior for an invalid codepoint is undefined.
2696
.LP
2697
.sp
2698
To draw text using a single font set in a given drawable, use
2699
.PN XmbDrawString
2700
or
2701
.PN XwcDrawString .
2702
.IN "XmbDrawString" "" "@DEF@"
2703
.IN "XwcDrawString" "" "@DEF@"
2704
.sM
2705
.FD 0
2706
void XmbDrawString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^)
2707
.br
2708
Display *\fIdisplay\fP\^;
2709
.br
2710
Drawable \fId\fP\^;
2711
.br
2712
XFontSet \fIfont_set\fP\^;
2713
.br
2714
GC \fIgc\fP\^;
2715
.br
2716
int \fIx\fP\^, \fIy\fP\^;
2717
.br
2718
char *\fIstring\fP\^;
2719
.br
2720
int \fInum_bytes\fP\^;
2721
.FN
2722
.FD 0
2723
void XwcDrawString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^)
2724
.br
2725
Display *\fIdisplay\fP\^;
2726
.br
2727
Drawable \fId\fP\^;
2728
.br
2729
XFontSet \fIfont_set\fP\^;
2730
.br
2731
GC \fIgc\fP\^;
2732
.br
2733
int \fIx\fP\^, \fIy\fP\^;
2734
.br
2735
wchar_t *\fIstring\fP\^;
2736
.br
2737
int \fInum_wchars\fP\^;
2738
.FN
2739
.IP \fIdisplay\fP 1i
2740
Specifies the connection to the X server.
2741
.IP \fId\fP 1i
2742
Specifies the drawable.
2743
.IP \fIfont_set\fP 1i
2744
Specifies the font set.
2745
.IP \fIgc\fP 1i
2746
Specifies the GC.
2747
.ds Xy
2748
.IP \fIx\fP 1i
2749
.br
2750
.ns
2751
.IP \fIy\fP 1i
2752
Specify the x and y coordinates\*(Xy.
2753
.IP \fIstring\fP 1i
2754
Specifies the character string.
2755
.IP \fInum_bytes\fP 1i
2756
Specifies the number of bytes in the string argument.
2757
.IP \fInum_wchars\fP 1i
2758
Specifies the number of characters in the string argument.
2759
.LP
2760
.eM
2761
The
2762
.PN XmbDrawString
2763
and
2764
.PN XwcDrawString
2765
functions draw the specified text with the foreground pixel.
2766
When the
2767
.PN XFontSet
2768
has missing charsets, each unavailable character is drawn
2769
with the default string returned by
2770
.PN XCreateFontSet .
2771
The behavior for an invalid codepoint is undefined.
2772
.LP
2773
.sp
2774
To draw image text using a single font set in a given drawable, use
2775
.PN XmbDrawImageString
2776
or
2777
.PN XwcDrawImageString .
2778
.IN "XmbDrawImageString" "" "@DEF@"
2779
.IN "XwcDrawImageString" "" "@DEF@"
2780
.sM
2781
.FD 0
2782
void XmbDrawImageString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^)
2783
.br
2784
Display *\fIdisplay\fP\^;
2785
.br
2786
Drawable \fId\fP\^;
2787
.br
2788
XFontSet \fIfont_set\fP\^;
2789
.br
2790
GC \fIgc\fP\^;
2791
.br
2792
int \fIx\fP\^, \fIy\fP\^;
2793
.br
2794
char *\fIstring\fP\^;
2795
.br
2796
int \fInum_bytes\fP\^;
2797
.FN
2798
.FD 0
2799
void XwcDrawImageString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^)
2800
.br
2801
Display *\fIdisplay\fP\^;
2802
.br
2803
Drawable \fId\fP\^;
2804
.br
2805
XFontSet \fIfont_set\fP\^;
2806
.br
2807
GC \fIgc\fP\^;
2808
.br
2809
int \fIx\fP\^, \fIy\fP\^;
2810
.br
2811
wchar_t *\fIstring\fP\^;
2812
.br
2813
int \fInum_wchars\fP\^;
2814
.FN
2815
.IP \fIdisplay\fP 1i
2816
Specifies the connection to the X server.
2817
.IP \fId\fP 1i
2818
Specifies the drawable.
2819
.IP \fIfont_set\fP 1i
2820
Specifies the font set.
2821
.IP \fIgc\fP 1i
2822
Specifies the GC.
2823
.ds Xy
2824
.IP \fIx\fP 1i
2825
.br
2826
.ns
2827
.IP \fIy\fP 1i
2828
Specify the x and y coordinates\*(Xy.
2829
.IP \fIstring\fP 1i
2830
Specifies the character string.
2831
.IP \fInum_bytes\fP 1i
2832
Specifies the number of bytes in the string argument.
2833
.IP \fInum_wchars\fP 1i
2834
Specifies the number of characters in the string argument.
2835
.LP
2836
.eM
2837
The
2838
.PN XmbDrawImageString
2839
and
2840
.PN XwcDrawImageString
2841
functions fill a destination rectangle with the background pixel defined
2842
in the GC and then paint the text with the foreground pixel.
2843
The filled rectangle is the rectangle returned to overall_logical_return by
2844
.PN XmbTextExtents
2845
or
2846
.PN XwcTextExtents
2847
for the same text and
2848
.PN XFontSet .
2849
.LP
2850
When the
2851
.PN XFontSet
2852
has missing charsets, each unavailable character is drawn
2853
with the default string returned by
2854
.PN XCreateFontSet .
2855
The behavior for an invalid codepoint is undefined.
2856
.NH 2
2857
Input Methods
2858
.XS
2859
\*(SN Input Methods
2860
.XE
2861
.LP
2862
This section provides discussions of the following X Input Method
2863
(XIM) topics:
2864
.IP \(bu 5
2865
Input method overview
2866
.IP \(bu 5
2867
Input method management
2868
.IP \(bu 5
2869
Input method functions
2870
.IP \(bu 5
2871
Input method values
2872
.IP \(bu 5
2873
Input context functions
2874
.IP \(bu 5
2875
Input context values
2876
.IP \(bu 5
2877
Input method callback semantics
2878
.IP \(bu 5
2879
Event filtering
2880
.IP \(bu 5
2881
Getting keyboard input
2882
.IP \(bu 5
2883
Input method conventions
2884
.NH 3
2885
Input Method Overview
2886
.XS
2887
\*(SN Input Method Overview
2888
.XE
2889
.LP
2890
This section provides definitions for terms and concepts used
2891
for internationalized text input and a brief overview of the
2892
intended use of the mechanisms provided by Xlib.
2893
.LP
2894
A large number of languages in the world use alphabets
2895
consisting of a small set of symbols (letters) to form words.
2896
To enter text into a computer in an alphabetic language,
2897
a user usually has a keyboard on which there exist key symbols corresponding
2898
to the alphabet.
2899
Sometimes, a few characters of an alphabetic language are missing
2900
on the keyboard.
2901
Many computer users who speak a Latin-alphabet-based language
2902
only have an English-based keyboard.
2903
They need to hit a combination of keystrokes
2904
to enter a character that does not exist directly on the keyboard.
2905
A number of algorithms have been developed for entering such characters.
2906
These are known as European input methods, compose input methods,
2907
or dead-key input methods.
2908
.LP
2909
Japanese is an example of a language with a phonetic symbol set,
2910
where each symbol represents a specific sound.
2911
There are two phonetic symbol sets in Japanese: Katakana and Hiragana.
2912
In general,
2913
Katakana is used for words that are of foreign origin,
2914
and Hiragana is used for writing native Japanese words.
2915
Collectively, the two systems are called Kana.
2916
Each set consists of 48 characters.
2917
.LP
2918
Korean also has a phonetic symbol set, called Hangul.
2919
Each of the 24 basic phonetic symbols (14 consonants and 10 vowels)
2920
represents a specific sound.
2921
A syllable is composed of two or three parts:
2922
the initial consonants, the vowels, and the optional last consonants.
2923
With Hangul,
2924
syllables can be treated as the basic units on which text processing is done.
2925
For example,
2926
a delete operation may work on a phonetic symbol or a syllable.
2927
Korean code sets include several thousands of these syllables.
2928
A user types the phonetic symbols that make up the syllables of the words
2929
to be entered.
2930
The display may change as each phonetic symbol is entered.
2931
For example,
2932
when the second phonetic symbol of a syllable is entered,
2933
the first phonetic symbol may change its shape and size.
2934
Likewise, when the third phonetic symbol is entered,
2935
the first two phonetic symbols may change their shape and size.
2936
.LP
2937
Not all languages rely solely on alphabetic or phonetic systems.
2938
Some languages, including Japanese and Korean, employ an
2939
ideographic writing system.
2940
In an ideographic system, rather than taking a small set of
2941
symbols and combining them in different ways to create words,
2942
each word consists of one unique symbol (or, occasionally, several symbols).
2943
The number of symbols can be very large:
2944
approximately 50,000 have been identified in Hanzi,
2945
the Chinese ideographic system.
2946
.LP
2947
Two major aspects of ideographic systems impact their use with computers.
2948
First, the standard computer character sets in Japan, China, and Korea
2949
include roughly 8,000 characters,
2950
while sets in Taiwan have between 15,000 and 30,000 characters.
2951
This makes it necessary to use more than one byte to represent a character.
2952
Second, it obviously is impractical to have a keyboard that includes
2953
all of a given language's ideographic symbols.
2954
Therefore, a mechanism is required for entering characters
2955
so that a keyboard with a reasonable number of keys can be used.
2956
Those input methods are usually based on phonetics,
2957
but there also exist methods based on the graphical properties of
2958
characters.
2959
.LP
2960
In Japan, both Kana and the ideographic system Kanji are used.
2961
In Korea, Hangul and sometimes the ideographic system Hanja are used.
2962
Now consider entering ideographs in Japan, Korea, China, and Taiwan.
2963
.LP
2964
In Japan, either Kana or English characters are typed and then a region
2965
is selected (sometimes automatically) for conversion to Kanji.
2966
Several Kanji characters may have the same phonetic representation.
2967
If that is the case with the string entered,
2968
a menu of characters is presented and
2969
the user must choose the appropriate one.
2970
If no choice is necessary or a preference has been established,
2971
the input method does the substitution directly.
2972
When Latin characters are converted to Kana or Kanji,
2973
it is called a romaji conversion.
2974
.LP
2975
In Korea, it is usually acceptable to keep Korean text in Hangul form,
2976
but some people may choose to write Hanja-originated words in Hanja
2977
rather than in Hangul.
2978
To change Hangul to Hanja,
2979
the user selects a region for conversion
2980
and then follows the same basic method as that described for Japanese.
2981
.LP
2982
Probably because there are well-accepted phonetic writing systems
2983
for Japanese and Korean,
2984
computer input methods in these countries for entering ideographs
2985
are fairly standard.
2986
Keyboard keys have both English characters and phonetic symbols
2987
engraved on them, and the user can switch between the two sets.
2988
.LP
2989
The situation is different for Chinese.
2990
While there is a phonetic system called Pinyin promoted by authorities,
2991
there is no consensus for entering Chinese text.
2992
Some vendors use a phonetic decomposition (Pinyin or another),
2993
others use ideographic decomposition of Chinese words,
2994
with various implementations and keyboard layouts.
2995
There are about 16 known methods, none of which is a clear standard.
2996
.LP
2997
Also, there are actually two ideographic sets used:
2998
Traditional Chinese (the original written Chinese)
2999
and Simplified Chinese.
3000
Several years ago,
3001
the People's Republic of China launched a campaign to simplify
3002
some ideographic characters and eliminate redundancies altogether.
3003
Under the plan,
3004
characters would be streamlined every five years.
3005
Characters have been revised several times now,
3006
resulting in the smaller, simpler set that makes up Simplified Chinese.
3007
.NH 4
3008
Input Method Architecture
3009
.XS
3010
\*(SN Input Method Architecture
3011
.XE
3012
.LP
3013
As shown in the previous section,
3014
there are many different input methods in use today,
3015
each varying with language, culture, and history.
3016
A common feature of many input methods is that the user may type
3017
multiple keystrokes to compose a single character (or set
3018
of characters).
3019
The process of composing characters from keystrokes is called
3020
\fIpreediting\fP.
3021
It may require complex algorithms and large dictionaries
3022
involving substantial computer resources.
3023
.LP
3024
Input methods may require one or more areas in which to show the
3025
feedback of the actual keystrokes, to propose disambiguation to the
3026
user, to list dictionaries, and so on.
3027
The input method areas of concern are as follows:
3028
.IP \(bu 5
3029
The \fIstatus\fP area is a logical extension of the
3030
LEDs that exist on the physical keyboard.
3031
It is a window that is intended to present the internal state
3032
of the input method that is critical to the user.
3033
The status area may consist of text data and bitmaps or some combination.
3034
.IP \(bu 5
3035
The \fIpreedit\fP area displays the
3036
intermediate text for those languages that are composing prior to
3037
the client handling the data.
3038
.IP \(bu 5
3039
The \fIauxiliary\fP area is used for pop-up menus and customizing
3040
dialogs that may be required for an input method.
3041
There may be multiple auxiliary areas for an input method.
3042
Auxiliary areas are managed by the input method independent of the client.
3043
Auxiliary areas are assumed to be separate dialogs,
3044
which are maintained by the input method.
3045
.LP
3046
There are various user interaction styles used for preediting.
3047
The ones supported by Xlib are as follows:
3048
.IP \(bu 5
3049
For \fIon-the-spot\fP input methods,
3050
preediting data will be displayed directly in the application window.
3051
Application data is moved to allow preedit data to appear
3052
at the point of insertion.
3053
.IP \(bu 5
3054
\fIOver-the-spot\fP preediting means that the data is displayed in
3055
a preedit window that is placed over the point of insertion.
3056
.IP \(bu 5
3057
\fIOff-the-spot\fP preediting means that the preedit window is
3058
inside the application window but not at the point of insertion.
3059
Often, this type of window is placed at the bottom of the application window.
3060
.IP \(bu 5
3061
\fIRoot-window\fP preediting refers to input methods that use a preedit
3062
window that is the child of
3063
.PN RootWindow .
3064
.LP
3065
It would require a lot of computing resources if portable applications
3066
had to include input methods for all the languages in the world.
3067
To avoid this,
3068
a goal of the Xlib design is to allow an application
3069
to communicate with an input method placed in a separate process.
3070
Such a process is called an \fIinput server\fP.
3071
The server to which the application should connect is dependent on
3072
the environment when the application is started up,
3073
that is, the user language and the actual encoding to be used for it.
3074
The input method connection is said to be \fIlocale-dependent\fP.
3075
It is also user-dependent.
3076
For a given language, the user can choose, to some extent,
3077
the user interface style of input method (if choice is possible among
3078
several).
3079
.LP
3080
Using an input server implies communication overhead,
3081
but applications can be migrated without relinking.
3082
Input methods can be implemented either as a
3083
stub communicating to an input server or as a local library.
3084
.LP
3085
An input method may be based on a \fIfront-end\fP or a \fIback-end\fP
3086
architecture.
3087
In a front-end architecture,
3088
there are two separate connections to the X server:
3089
keystrokes go directly from the X server to the input method on
3090
one connection and other events to the regular client connection.
3091
The input method is then acting as a filter and sends composed strings
3092
to the client.
3093
A front-end architecture requires synchronization between the
3094
two connections to avoid lost key events or locking issues.
3095
.LP
3096
In a back-end architecture,
3097
a single X server connection is used.
3098
A dispatching mechanism must decide on this channel to delegate appropriate
3099
keystrokes to the input method.
3100
For instance,
3101
it may retain a Help keystroke for its own purpose.
3102
In the case where the input method is a separate process (that is, a server),
3103
there must be a special communication protocol between the back-end client
3104
and the input server.
3105
.LP
3106
A front-end architecture introduces synchronization issues
3107
and a filtering mechanism for noncharacter keystrokes
3108
(Function keys, Help, and so on).
3109
A back-end architecture sometimes implies more communication overhead
3110
and more process switching.
3111
If all three processes (X server, input server, client)
3112
are running on a single workstation,
3113
there are two process switches for each keystroke in a back-end
3114
architecture,
3115
but there is only one in a front-end architecture.
3116
.LP
3117
The abstraction used by a client to communicate with an input method
3118
is an opaque data structure represented by the
3119
.PN XIM
3120
data type.
3121
This data structure is returned by the
3122
.PN XOpenIM
3123
function, which opens an input method on a given display.
3124
Subsequent operations on this data structure encapsulate all communication
3125
between client and input method.
3126
There is no need for an X client to use any networking library
3127
or natural language package to use an input method.
3128
.LP
3129
A single input server may be used for one or more languages,
3130
supporting one or more encoding schemes.
3131
But the strings returned from an input method will always be encoded
3132
in the (single) locale associated with the
3133
.PN XIM
3134
object.
3135
.NH 4
3136
Input Contexts
3137
.XS
3138
\*(SN Input Contexts
3139
.XE
3140
.LP
3141
Xlib provides the ability to manage a multi-threaded state for text input.
3142
A client may be using multiple windows,
3143
each window with multiple text entry areas,
3144
and the user possibly switching among them at any time.
3145
The abstraction for representing the state of a particular input thread
3146
is called an \fIinput context\fP.
3147
The Xlib representation of an input context is an
3148
.PN XIC .
3149
.LP
3150
An input context is the abstraction retaining the state, properties,
3151
and semantics of communication between a client and an input method.
3152
An input context is a combination of an input method, a locale
3153
specifying the encoding of the character strings to be returned,
3154
a client window, internal state information,
3155
and various layout or appearance characteristics.
3156
The input context concept somewhat matches for input the graphics context
3157
abstraction defined for graphics output.
3158
.LP
3159
One input context belongs to exactly one input method.
3160
Different input contexts may be associated with the same input method,
3161
possibly with the same client window.
3162
An
3163
.PN XIC
3164
is created with the
3165
.PN XCreateIC
3166
function, providing an
3167
.PN XIM
3168
argument and affiliating the input context to the input method
3169
for its lifetime.
3170
When an input method is closed with
3171
.PN XCloseIM ,
3172
all of its affiliated input contexts should not be used any more
3173
(and should preferably be destroyed before closing the input method).
3174
.LP
3175
Considering the example of a client window with multiple text entry areas,
3176
the application programmer could, for example, choose to implement as follows:
3177
.IP \(bu 5
3178
As many input contexts are created as text entry areas, and the client
3179
will get the input accumulated on each context each time it looks up
3180
in that context.
3181
.IP \(bu 5
3182
A single context is created for a top-level window in the application.
3183
If such a window contains several text entry areas,
3184
each time the user moves to another text entry area,
3185
the client has to indicate changes in the context.
3186
.LP
3187
A range of choices can be made by application designers to use
3188
either a single or multiple input contexts,
3189
according to the needs of their application.
3190
.NH 4
3191
Getting Keyboard Input
3192
.XS
3193
\*(SN Getting Keyboard Input
3194
.XE
3195
.LP
3196
To obtain characters from an input method,
3197
a client must call the function
3198
.PN XmbLookupString
3199
or
3200
.PN XwcLookupString
3201
with an input context created from that input method.
3202
Both a locale and display are bound to an input method when it is opened,
3203
and an input context inherits this locale and display.
3204
Any strings returned by
3205
.PN XmbLookupString
3206
or
3207
.PN XwcLookupString
3208
will be encoded in that locale.
3209
.NH 4
3210
Focus Management
3211
.XS
3212
\*(SN Focus Management
3213
.XE
3214
.LP
3215
For each text entry area in which the
3216
.PN XmbLookupString
3217
or
3218
.PN XwcLookupString
3219
functions are used,
3220
there will be an associated input context.
3221
.LP
3222
When the application focus moves to a text entry area,
3223
the application must set the input context focus to the
3224
input context associated with that area.
3225
The input context focus is set by calling
3226
.PN XSetICFocus
3227
with the appropriate input context.
3228
.LP
3229
Also, when the application focus moves out of a text entry area, the
3230
application should unset the focus for the associated input context
3231
by calling
3232
.PN XUnsetICFocus .
3233
As an optimization, if
3234
.PN XSetICFocus
3235
is called successively on two different input contexts,
3236
setting the focus on the second
3237
will automatically unset the focus on the first.
3238
.LP
3239
To set and unset the input context focus correctly,
3240
it is necessary to track application-level focus changes.
3241
Such focus changes do not necessarily correspond to X server focus changes.
3242
.LP
3243
If a single input context
3244
is being used to do input for
3245
multiple text entry areas, it will also be necessary
3246
to set the focus window of the
3247
input context whenever the focus window changes
3248
(see section 13.5.6.3).
3249
.NH 4
3250
Geometry Management
3251
.XS
3252
\*(SN Geometry Management
3253
.XE
3254
.LP
3255
In most input method architectures
3256
(on-the-spot being the notable exception),
3257
the input method will perform the display of its own data.
3258
To provide better visual locality,
3259
it is often desirable to have the input method areas embedded within a client.
3260
To do this,
3261
the client may need to allocate space for an input method.
3262
Xlib provides support that allows the size and position of input method
3263
areas to be provided by a client.
3264
The input method areas that are supported for geometry management
3265
are the status area and the preedit area.
3266
.LP
3267
The fundamental concept on which geometry management for input method windows
3268
is based is the proper division of responsibilities between the
3269
client (or toolkit) and the input method.
3270
The division of responsibilities is as follows:
3271
.IP \(bu 5
3272
The client is responsible for the geometry of the input method window.
3273
.IP \(bu 5
3274
The input method is responsible for the contents of the input method window.
3275
.LP
3276
An input method is able to suggest a size to the client,
3277
but it cannot suggest a placement.
3278
Also the input method can only suggest a size.
3279
It does not determine the size,
3280
and it must accept the size it is given.
3281
.LP
3282
Before a client provides geometry management for an input method,
3283
it must determine if geometry management is needed.
3284
The input method indicates the need for geometry management
3285
by setting
3286
.PN XIMPreeditArea
3287
or
3288
.PN XIMStatusArea
3289
in its
3290
.PN XIMStyles
3291
value returned by
3292
.PN XGetIMValues .
3293
When a client has decided that it will provide geometry management
3294
for an input method,
3295
it indicates that decision by setting the
3296
.PN XNInputStyle
3297
value in the
3298
.PN XIC .
3299
.LP
3300
After a client has established with the input method
3301
that it will do geometry management,
3302
the client must negotiate the geometry with the input method.
3303
The geometry is negotiated by the following steps:
3304
.IP \(bu 5
3305
The client suggests an area to the input method by setting the
3306
.PN XNAreaNeeded
3307
value for that area.
3308
If the client has no constraints for the input method,
3309
it either will not suggest an area or will set the width and height to zero.
3310
Otherwise, it will set one of the values.
3311
.IP \(bu 5
3312
The client will get the XIC value
3313
.PN XNAreaNeeded .
3314
The input method will return its suggested size in this value.
3315
The input method should pay attention to any constraints suggested
3316
by the client.
3317
.IP \(bu 5
3318
The client sets the XIC value
3319
.PN XNArea
3320
to inform the input method of the geometry of its window.
3321
The client should try to honor the geometry requested by the input method.
3322
The input method must accept this geometry.
3323
.LP
3324
Clients doing geometry management must be aware that setting other
3325
XIC values may affect the geometry desired by an input method.
3326
For example,
3327
.PN XNFontSet
3328
and
3329
.PN XNLineSpacing
3330
may change the geometry desired by the input method.
3331
.LP
3332
The table of XIC values (see section 13.5.6)
3333
indicates the values that can cause the desired geometry to change
3334
when they are set.
3335
It is the responsibility of the client to renegotiate the geometry
3336
of the input method window when it is needed.
3337
.LP
3338
In addition,
3339
a geometry management callback is provided
3340
by which an input method can initiate a geometry change.
3341
.NH 4
3342
Event Filtering
3343
.XS
3344
\*(SN Event Filtering
3345
.XE
3346
.LP
3347
A filtering mechanism is provided to allow input methods
3348
to capture X events transparently to clients.
3349
It is expected that toolkits (or clients) using
3350
.PN XmbLookupString
3351
or
3352
.PN XwcLookupString
3353
will call this filter at some point in the event processing mechanism
3354
to make sure that events needed by an input method can be filtered
3355
by that input method.
3356
.LP
3357
If there were no filter,
3358
a client could receive and discard events that are necessary
3359
for the proper functioning of an input method.
3360
The following provides a few examples of such events:
3361
.IP \(bu 5
3362
Expose events on preedit window in local mode.
3363
.IP \(bu 5
3364
Events may be used by an input method to communicate with an input server.
3365
Such input server protocol-related events have to be intercepted
3366
if one does not want to disturb client code.
3367
.IP \(bu 5
3368
Key events can be sent to a filter before they are bound
3369
to translations such as those the X Toolkit Intrinsics library provides.
3370
.LP
3371
Clients are expected to get the XIC value
3372
.PN XNFilterEvents
3373
and augment the event mask for the client window with that event mask.
3374
This mask may be zero.
3375
.NH 4
3376
Callbacks
3377
.XS
3378
\*(SN Callbacks
3379
.XE
3380
.LP
3381
When an on-the-spot input method is implemented,
3382
only the client can insert or delete preedit data in place
3383
and possibly scroll existing text.
3384
This means that the echo of the keystrokes has to be achieved
3385
by the client itself, tightly coupled with the input method logic.
3386
.LP
3387
When the user enters a keystroke,
3388
the client calls
3389
.PN XmbLookupString
3390
or
3391
.PN XwcLookupString .
3392
At this point, in the on-the-spot case,
3393
the echo of the keystroke in the preedit has not yet been done.
3394
Before returning to the client logic that handles the input characters,
3395
the look-up function
3396
must call the echoing logic to insert the new keystroke.
3397
If the keystrokes entered so far make up a character,
3398
the keystrokes entered need to be deleted,
3399
and the composed character will be returned.
3400
Hence, what happens is that, while being called by client code,
3401
the input method logic has to call back to the client before it returns.
3402
The client code, that is, a callback procedure,
3403
is called from the input method logic.
3404
.LP
3405
There are a number of cases where the input method logic has to
3406
call back the client.
3407
Each of those cases is associated with a well-defined callback action.
3408
It is possible for the client to specify, for each input context,
3409
what callback is to be called for each action.
3410
.LP
3411
There are also callbacks provided for feedback of status information
3412
and a callback to initiate a geometry request for an input method.
3413
.NH 4
3414
Visible Position Feedback Masks
3415
.XS
3416
\*(SN Visible Position Feedback Masks
3417
.XE
3418
.LP
3419
In the on-the-spot input style, there is a problem when
3420
attempting to draw preedit strings that are longer than the
3421
available space. Once the display area is exceeded, it is not
3422
clear how best to display the preedit string.
3423
The visible position feedback masks of
3424
.PN XIMText
3425
help resolve this problem by allowing the input method to specify hints that
3426
indicate the essential portions of the preedit string.
3427
For example, such hints can help developers implement
3428
scrolling of a long preedit string within a short preedit display area.
3429
.NH 4
3430
Preedit String Management
3431
.XS
3432
\*(SN Preedit String Management
3433
.XE
3434
.LP
3435
As highlighted before, the input method architecture provides
3436
preediting, which supports a type of preprocessor input composition.
3437
In this case, composition consists of interpreting a sequence
3438
of key events and returning a committed string via
3439
.PN XmbLookupString
3440
or
3441
.PN XwcLookupString .
3442
This provides the basics for input methods.
3443
.LP
3444
In addition to preediting based on key events, a general framework
3445
is provided to give a client that desires it more advanced preediting based
3446
on the text within the client. This framework is called
3447
\fIstring conversion\fP and is provided using XIC values.
3448
The fundamental concept of string conversion
3449
is to allow the input method to manipulate the client's
3450
text independent of any user preediting operation.
3451
.LP
3452
The need for string conversion is based on
3453
language needs and input method capabilities.
3454
The following are some examples of string conversion:
3455
.IP \(bu 5
3456
Transliteration conversion provides language-specific conversions
3457
within the input method.
3458
In the case of Korean input, users wish to convert a Hangul string
3459
into a Hanja string while in preediting, after preediting,
3460
or in other situations (for example, on a selected string).
3461
The conversion is triggered when the user
3462
presses a Hangul-to-Hanja key sequence (which may be input method specific).
3463
Sometimes the user may want to invoke the conversion after finishing
3464
preediting or on a user-selected string.
3465
Thus, the string to be converted is in an application buffer, not in
3466
the preedit area of the input method. The string conversion services
3467
allow the client to request this transliteration conversion from the
3468
input method.
3469
There are many other transliteration conversions defined for
3470
various languages, for example, Kana-to-Kanji conversion in Japanese.
3471
.sp
3472
The key to remember is that transliteration conversions are triggered
3473
at the request of the user and returned to the client
3474
immediately without affecting the preedit area of the input method.
3475
.IP \(bu 5
3476
Reconversion of a previously committed string or
3477
a selected string is supported by many input methods as a
3478
convenience to the user.
3479
For example, a user tends to mistype the commit key while
3480
preediting. In that case, some input methods provide a special
3481
key sequence to request a ``reconvert'' operation on the
3482
committed string, similiar to the undo facility provided by most
3483
text editors.
3484
Another example is where the user is proofreading a document
3485
that has some misconversions from preediting and wants to correct
3486
the misconverted text. Such reconversion is again triggered
3487
by the user invoking some special action, but reconversions should
3488
not affect the state of the preedit area.
3489
.IP \(bu 5
3490
Context-sensitive conversion is required for some languages
3491
and input methods that need to retrieve text that surrounds the
3492
current spot location (cursor position) of the client's buffer.
3493
Such text is needed when the preediting operation depends on
3494
some surrounding characters (usually preceding the spot location).
3495
For example,
3496
in Thai language input, certain character sequences may be invalid and
3497
the input method may want to check whether characters constitute a
3498
valid word. Input methods that do such context-dependent
3499
checking need to retrieve the characters surrounding the current
3500
cursor position to obtain complete words.
3501
.sp
3502
Unlike other conversions, this conversion is not explicitly
3503
requested by the user.
3504
Input methods that provide such context-sensitive conversion
3505
continuously need to request context from the client, and any change
3506
in the context of the spot location may affect such conversions.
3507
The client's context would be needed if the user moves the cursor
3508
and starts editing again.
3509
.sp
3510
For this reason, an input method supporting this type of conversion
3511
should take notice of when the client calls
3512
.PN XmbResetIC
3513
or
3514
.PN XwcResetIC ,
3515
which is usually an indication of a context change.
3516
.LP
3517
Context-sensitive conversions just need a copy of the client's text,
3518
while other conversions replace the client's text with new text
3519
to achieve the reconversion or transliteration. Yet in all
3520
cases the result of a conversion, either immediately or via preediting,
3521
is returned by the
3522
.PN XmbLookupString
3523
and
3524
.PN XwcLookupString
3525
functions.
3526
.LP
3527
String conversion support is dependent on the availability of the
3528
.PN XNStringConversion
3529
or
3530
.PN XNStringConversionCallback
3531
XIC values.
3532
Because the input method may not support string conversions,
3533
clients have to query the availability of string conversion
3534
operations by checking the supported XIC values list by calling
3535
.PN XGetIMValues
3536
with the
3537
.PN XNQueryICValuesList
3538
IM value.
3539
.LP
3540
The difference between these two values is whether the
3541
conversion is invoked by the client or the input method.
3542
The
3543
.PN XNStringConversion
3544
XIC value is used by clients to request
3545
a string conversion from the input method. The client
3546
is responsible for determining which events are used
3547
to trigger the string conversion and whether the string to be
3548
converted should be copied or deleted. The type of conversion
3549
is determined by the input method; the client can only
3550
pass the string to be converted. The client is guaranteed that
3551
no
3552
.PN XNStringConversionCallback
3553
will be issued when this value is set; thus, the client need
3554
only set one of these values.
3555
.LP
3556
The
3557
.PN XNStringConversionCallback
3558
XIC value is used by the client to notify the input method that
3559
it will accept requests from the input method for string conversion.
3560
If this value is set,
3561
it is the input method's responsibility to determine which
3562
events are used to trigger the string conversion.
3563
When such events occur, the input method issues a call to the
3564
client-supplied procedure to retrieve the string to be converted. The client's
3565
callback procedure is notified whether to copy or delete the string and
3566
is provided with hints as to the amount of text needed.
3567
The
3568
.PN XIMStringConversionCallbackStruct
3569
specifies which text should be passed back to the input method.
3570
.LP
3571
Finally, the input method may call the client's
3572
.PN XNStringConversionCallback
3573
procedure multiple times if the string returned from the callback is
3574
not sufficient to perform a successful conversion. The arguments
3575
to the client's procedure allow the input method to define a
3576
position (in character units) relative to the client's cursor position
3577
and the size of the text needed. By varying the position and size of
3578
the desired text in subsequent callbacks, the input method can retrieve
3579
additional text.
3580
.LP
3581
.NH 3
3582
Input Method Management
3583
.XS
3584
\*(SN Input Method Management
3585
.XE
3586
.LP
3587
The interface to input methods might appear to be simply creating
3588
an input method
3589
.Pn ( XOpenIM )
3590
and freeing an input method
3591
.Pn ( XCloseIM ).
3592
However, input methods may
3593
require complex communication with input method servers (IM servers),
3594
for example:
3595
.IP \(bu 5
3596
If the X server, IM server, and X clients are started asynchronously,
3597
some clients may attempt to connect to the IM server before it is
3598
fully operational, and fail.
3599
Therefore, some mechanism is needed to allow clients to detect when an IM
3600
server has started.
3601
.LP
3602
It is up to clients to decide what should be done when an IM server is
3603
not available (for example, wait, or use some other IM server).
3604
.LP
3605
.IP \(bu 5
3606
Some input methods may allow the underlying IM server to be switched.
3607
Such customization may be desired without restarting the entire client.
3608
.LP
3609
To support management of input methods in these cases, the following
3610
functions are provided:
3611
.TS
3612
lw(2.4i) lw(3.3i).
3613
T{
3614
.PN XRegisterIMInstantiateCallback
3615
T} T{
3616
This function allows clients to register a callback procedure
3617
to be called when Xlib detects that an IM server is up and available.
3618
T}
3619
T{
3620
.PN XOpenIM
3621
T} T{
3622
A client calls this function as a result of the callback procedure
3623
being called.
3624
T}
3625
T{
3626
.PN XSetIMValue ,
3627
.PN XSetICValue
3628
T} T{
3629
These functions use the XIM and XIC values,
3630
.PN XNDestroyCallback ,
3631
to allow a client
3632
to register a callback procedure to be called when Xlib detects that
3633
an IM server that was associated with an opened
3634
input method is no longer available.
3635
.sp 4p
3636
In addition, this function can be used to switch IM servers for those input
3637
methods that support such functionality. The IM value for switching IM
3638
servers is implementation-dependent; see the description below about
3639
switching IM servers.
3640
T}
3641
T{
3642
.PN XUnregisterIMInstantiateCallback
3643
T} T{
3644
This function removes a callback procedure registered by the client.
3645
T}
3646
.TE
3647
.LP
3648
Input methods that support switching of IM servers may exhibit some
3649
side-effects:
3650
.IP \(bu 5
3651
The input method will ensure that any new IM server supports any of the
3652
input styles being used by input contexts already associated with the
3653
input method.
3654
However, the list of supported input styles may be different.
3655
.LP
3656
.IP \(bu 5
3657
Geometry management requests on previously created input contexts
3658
may be initiated by the new IM server.
3659
.LP
3660
.NH 4
3661
Hot Keys
3662
.XS
3663
\*(SN Hot Keys
3664
.XE
3665
.LP
3666
Some clients need to guarantee which keys can be used to escape from the
3667
input method, regardless of the input method state;
3668
for example, the client-specific Help key or the keys to move the
3669
input focus.
3670
The HotKey mechanism allows clients
3671
to specify a set of keys for this purpose. However, the input
3672
method might not allow clients to specify hot keys.
3673
Therefore, clients have to query support of hot keys by checking the
3674
supported XIC values list by calling
3675
.PN XGetIMValues
3676
with the
3677
.PN XNQueryICValuesList
3678
IM value.
3679
When the hot keys specified conflict with the key bindings of the
3680
input method, hot keys take precedence over the key bindings of the input
3681
method.
3682
.LP
3683
.NH 4
3684
Preedit State Operation
3685
.XS
3686
\*(SN Preedit State Operation
3687
.XE
3688
.LP
3689
An input method may have several internal states, depending on its
3690
implementation and the locale. However, one state that is
3691
independent of locale and implementation is whether the input method
3692
is currently performing a preediting operation.
3693
Xlib provides the ability for an application to manage the preedit state
3694
programmatically. Two methods are provided for
3695
retrieving the preedit state of an input context.
3696
One method is to query the state by calling
3697
.PN XGetICValues
3698
with the
3699
.PN XNPreeditState
3700
XIC value.
3701
Another method is to receive notification whenever
3702
the preedit state is changed. To receive such notification,
3703
an application needs to register a callback by calling
3704
.PN XSetICValues
3705
with the
3706
.PN XNPreeditStateNotifyCallback
3707
XIC value.
3708
In order to change the preedit state programmatically, an application
3709
needs to call
3710
.PN XSetICValues
3711
with
3712
.PN XNPreeditState.
3713
.LP
3714
Availability of the preedit state is input method dependent. The input
3715
method may not provide the ability to set the state or to
3716
retrieve the state programmatically. Therefore, clients have to
3717
query availability of preedit state operations by checking the
3718
supported XIC values list by calling
3719
.PN XGetIMValues
3720
with the
3721
.PN XNQueryICValuesList
3722
IM value.
3723
.NH 3
3724
Input Method Functions
3725
.XS
3726
\*(SN Input Method Functions
3727
.XE
3728
.LP
3729
To open a connection, use
3730
.PN XOpenIM .
3731
.IN "XOpenIM" "" "@DEF@"
3732
.sM
3733
.FD 0
3734
XIM XOpenIM\^(\^\fIdisplay\fP\^, \fIdb\fP\^, \fIres_name\fP\^, \fIres_class\fP\^)
3735
.br
3736
Display *\fIdisplay\fP\^;
3737
.br
3738
XrmDatabase \fIdb\fP\^;
3739
.br
3740
char *\fIres_name\fP\^;
3741
.br
3742
char *\fIres_class\fP\^;
3743
.FN
3744
.IP \fIdisplay\fP 1i
3745
Specifies the connection to the X server.
3746
.IP \fIdb\fP 1i
3747
Specifies a pointer to the resource database.
3748
.IP \fIres_name\fP 1i
3749
Specifies the full resource name of the application.
3750
.IP \fIres_class\fP 1i
3751
Specifies the full class name of the application.
3752
.LP
3753
.eM
3754
The
3755
.PN XOpenIM
3756
function opens an input method,
3757
matching the current locale and modifiers specification.
3758
Current locale and modifiers are bound to the input method at opening time.
3759
The locale associated with an input method cannot be changed dynamically.
3760
This implies that the strings returned by
3761
.PN XmbLookupString
3762
or
3763
.PN XwcLookupString ,
3764
for any input context affiliated with a given input method,
3765
will be encoded in the locale current at the time the input method is opened.
3766
.LP
3767
The specific input method to which this call will be routed
3768
is identified on the basis of the current locale.
3769
.PN XOpenIM
3770
will identify a default input method corresponding to the
3771
current locale.
3772
That default can be modified using
3773
.PN XSetLocaleModifiers
3774
for the input method modifier.
3775
.LP
3776
The db argument is the resource database to be used by the input method
3777
for looking up resources that are private to the input method.
3778
It is not intended that this database be used to look
3779
up values that can be set as IC values in an input context.
3780
If db is NULL,
3781
no database is passed to the input method.
3782
.LP
3783
The res_name and res_class arguments specify the resource name
3784
and class of the application.
3785
They are intended to be used as prefixes by the input method
3786
when looking up resources that are common to all input contexts
3787
that may be created for this input method.
3788
The characters used for resource names and classes must be in the
3789
X Portable Character Set.
3790
The resources looked up are not fully specified
3791
if res_name or res_class is NULL.
3792
.LP
3793
The res_name and res_class arguments are not assumed to exist beyond
3794
the call to
3795
.PN XOpenIM .
3796
The specified resource database is assumed to exist for the lifetime
3797
of the input method.
3798
.LP
3799
.PN XOpenIM
3800
returns NULL if no input method could be opened.
3801
.LP
3802
.sp
3803
To close a connection, use
3804
.PN XCloseIM .
3805
.IN "XCloseIM" "" "@DEF@"
3806
.sM
3807
.FD 0
3808
Status XCloseIM\^(\^\fIim\fP\^)
3809
.br
3810
XIM \fIim\fP\^;
3811
.FN
3812
.IP \fIim\fP 1i
3813
Specifies the input method.
3814
.LP
3815
.eM
3816
The
3817
.PN XCloseIM
3818
function closes the specified input method.
3819
.LP
3820
.sp
3821
To set input method attributes, use
3822
.PN XSetIMValues .
3823
.IN "XSetIMValues" "" "@DEF@"
3824
.sM
3825
.FD 0
3826
char * XSetIMValues\^(\^\fIim\fP\^, ...)
3827
.br
3828
XIM \fIim\fP\^;
3829
.FN
3830
.IP \fIim\fP 1i
3831
Specifies the input method.
3832
.ds Al \ to set XIM values
3833
.IP ... 1i
3834
Specifies the variable-length argument list\*(Al.
3835
.LP
3836
.eM
3837
The
3838
.PN XSetIMValues
3839
function presents a variable argument list programming interface
3840
for setting attributes of the specified input method.
3841
It returns NULL if it succeeds;
3842
otherwise,
3843
it returns the name of the first argument that could not be set.
3844
Xlib does not attempt to set arguments from the supplied list that
3845
follow the failed argument;
3846
all arguments in the list preceding the failed argument have been set
3847
correctly.
3848
.LP
3849
.sp
3850
To query an input method, use
3851
.PN XGetIMValues .
3852
.IN "XGetIMValues" "" "@DEF@"
3853
.sM
3854
.FD 0
3855
char * XGetIMValues\^(\^\fIim\fP\^, ...)
3856
.br
3857
XIM \fIim\fP\^;
3858
.FN
3859
.IP \fIim\fP 1i
3860
Specifies the input method.
3861
.ds Al \ to get XIM values
3862
.IP ... 1i
3863
Specifies the variable length argument list\*(Al.
3864
.LP
3865
.eM
3866
The
3867
.PN XGetIMValues
3868
function presents a variable argument list programming interface
3869
for querying properties or features of the specified input method.
3870
This function returns NULL if it succeeds;
3871
otherwise,
3872
it returns the name of the first argument that could not be obtained.
3873
.LP
3874
Each XIM value argument (following a name) must point to
3875
a location where the XIM value is to be stored.
3876
That is, if the XIM value is of type T,
3877
the argument must be of type T*.
3878
If T itself is a pointer type,
3879
then
3880
.PN XGetIMValues
3881
allocates memory to store the actual data,
3882
and the client is responsible for freeing this data by calling
3883
.PN XFree
3884
with the returned pointer.
3885
.LP
3886
.sp
3887
To obtain the display associated with an input method, use
3888
.PN XDisplayOfIM .
3889
.IN "XDisplayOfIM" "" "@DEF@"
3890
.sM
3891
.FD 0
3892
Display * XDisplayOfIM\^(\^\fIim\fP\^)
3893
.br
3894
XIM \fIim\fP\^;
3895
.FN
3896
.IP \fIim\fP 1i
3897
Specifies the input method.
3898
.LP
3899
.eM
3900
The
3901
.PN XDisplayOfIM
3902
function returns the display associated with the specified input method.
3903
.LP
3904
.sp
3905
To get the locale associated with an input method, use
3906
.PN XLocaleOfIM .
3907
.IN "XLocaleOfIM" "" "@DEF@"
3908
.sM
3909
.FD 0
3910
char * XLocaleOfIM\^(\^\fIim\fP\^)
3911
.br
3912
XIM \fIim\fP\^;
3913
.FN
3914
.IP \fIim\fP 1i
3915
Specifies the input method.
3916
.LP
3917
.eM
3918
The
3919
.PN XLocaleOfIM
3920
function returns the locale associated with the specified input method.
3921
.LP
3922
.sp
3923
To register an input method instantiate callback, use
3924
.PN XRegisterIMInstantiateCallback .
3925
.IN "XRegisterIMInstantiateCallback" "" "@DEF@"
3926
.sM
3927
.FD 0
3928
Bool XRegisterIMInstantiateCallback\^(\^\fIdisplay\fP\^, \fIdb\fP\^, \fIres_name\fP\^, \fIres_class\fP\^, \fIcallback\fP\^, \fIclient_data\fP\^)
3929
.br
3930
Display *\fIdisplay\fP\^;
3931
.br
3932
XrmDatabase \fIdb\fP\^;
3933
.br
3934
char *\fIres_name\fP\^;
3935
.br
3936
char *\fIres_class\fP\^;
3937
.br
3938
XIMProc \fIcallback\fP\^;
3939
.br
3940
XPointer *\fIclient_data\fP\^;
3941
.FN
3942
.IP \fIdisplay\fP 1i
3943
Specifies the connection to the X server.
3944
.IP \fIdb\fP 1i
3945
Specifies a pointer to the resource database.
3946
.IP \fIres_name\fP 1i
3947
Specifies the full resource name of the application.
3948
.IP \fIres_class\fP 1i
3949
Specifies the full class name of the application.
3950
.IP \fIcallback\fP 1i
3951
Specifies a pointer to the input method instantiate callback.
3952
.IP \fIclient_data\fP 1i
3953
Specifies the additional client data.
3954
.LP
3955
.eM
3956
The
3957
.PN XRegisterIMInstantiateCallback
3958
function registers a callback to be invoked whenever a new input method
3959
becomes available for the specified display that matches the current
3960
locale and modifiers.
3961
.LP
3962
The function returns
3963
.PN True
3964
if it succeeds; otherwise, it returns
3965
.PN False .
3966
.LP
3967
The generic prototype is as follows:
3968
.IN "IMInstantiateCallback" "" "@DEF@"
3969
.sM
3970
.FD 0
3971
void IMInstantiateCallback\^(\^\fIdisplay\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
3972
.br
3973
Display *\fIdisplay\fP\^;
3974
.br
3975
XPointer \fIclient_data\fP\^;
3976
.br
3977
XPointer \fIcall_data\fP\^;
3978
.FN
3979
.IP \fIdisplay\fP 1i
3980
Specifies the connection to the X server.
3981
.IP \fIclient_data\fP 1i
3982
Specifies the additional client data.
3983
.IP \fIcall_data\fP 1i
3984
Not used for this callback and always passed as NULL.
3985
.LP
3986
.eM
3987
To unregister an input method instantiation callback, use
3988
.PN XUnregisterIMInstantiateCallback .
3989
.IN "XUnregisterIMInstantiateCallback" "" "@DEF@"
3990
.sM
3991
.FD 0
3992
Bool XUnregisterIMInstantiateCallback\^(\^\fIdisplay\fP\^, \fIdb\fP\^, \fIres_name\fP\^, \fIres_class\fP\^, \fIcallback\fP\^, \fIclient_data\fP\^)
3993
.br
3994
Display *\fIdisplay\fP\^;
3995
.br
3996
XrmDatabase \fIdb\fP\^;
3997
.br
3998
char *\fIres_name\fP\^;
3999
.br
4000
char *\fIres_class\fP\^;
4001
.br
4002
XIMProc \fIcallback\fP\^;
4003
.br
4004
XPointer *\fIclient_data\fP\^;
4005
.FN
4006
.IP \fIdisplay\fP 1i
4007
Specifies the connection to the X server.
4008
.IP \fIdb\fP 1i
4009
Specifies a pointer to the resource database.
4010
.IP \fIres_name\fP 1i
4011
Specifies the full resource name of the application.
4012
.IP \fIres_class\fP 1i
4013
Specifies the full class name of the application.
4014
.IP \fIcallback\fP 1i
4015
Specifies a pointer to the input method instantiate callback.
4016
.IP \fIclient_data\fP 1i
4017
Specifies the additional client data.
4018
.LP
4019
.eM
4020
The
4021
.PN XUnregisterIMInstantiateCallback
4022
function removes an input method instantiation callback previously
4023
registered.
4024
The function returns
4025
.PN True
4026
if it succeeds; otherwise, it returns
4027
.PN False .
4028
.NH 3
4029
Input Method Values
4030
.XS
4031
\*(SN Input Method Values
4032
.XE
4033
.LP
4034
The following table describes how XIM values are interpreted
4035
by an input method.
4036
The first column lists the XIM values.
4037
The second column indicates how each of the XIM values
4038
are treated by that input style.
4039
.LP
4040
.LP
4041
The following keys apply to this table.
4042
.TS H
4043
lw(1i) lw(4.75i).
4044
_
4045
.sp 6p
4046
.B
4047
Key Explanation
4048
.sp 6p
4049
_
4050
.TH
4051
.R
4052
D T{
4053
This value may be set using
4054
.PN XSetIMValues .
4055
If it is not set,
4056
.br
4057
a default is provided.
4058
T}
4059
S T{
4060
This value may be set using
4061
.PN XSetIMValues .
4062
T}
4063
G T{
4064
This value may be read using
4065
.PN XGetIMValues .
4066
T}
4067
.sp 6p
4068
_
4069
.TE
4070
.LP
4071
.TS H
4072
lw(2.25i) c
4073
lw(2.25i) c.
4074
_
4075
.sp 6p
4076
.B
4077
XIM Value Key
4078
.sp 6p
4079
_
4080
.sp 6p
4081
.TH
4082
.R
4083
T{
4084
.PN XNQueryInputStyle
4085
T} T{
4086
G
4087
T}
4088
T{
4089
.PN XNResourceName
4090
T} T{
4091
D-S-G
4092
T}
4093
T{
4094
.PN XNResourceClass
4095
T} T{
4096
D-S-G
4097
T}
4098
T{
4099
.PN XNDestroyCallback
4100
T} T{
4101
D-S-G
4102
T}
4103
T{
4104
.PN XNQueryIMValuesList
4105
T} T{
4106
G
4107
T}
4108
T{
4109
.PN XNQueryICValuesList
4110
T} T{
4111
G
4112
T}
4113
T{
4114
.PN XNVisiblePosition
4115
T} T{
4116
G
4117
T}
4118
T{
4119
.PN XNR6PreeditCallbackBehavior
4120
T} T{
4121
D-S-G
4122
T}
4123
.sp 6p
4124
_
4125
.TE
4126
.LP
4127
.PN XNR6PreeditCallbackBehavior
4128
is obsolete and its use is not recommended (see section 13.5.4.6).
4129
.LP
4130
.NH 4
4131
Query Input Style
4132
.XS
4133
\*(SN Query Input Style
4134
.XE
4135
.LP
4136
A client should always query the input method to determine which input
4137
styles are supported.
4138
The client should then find an input style it is capable of supporting.
4139
.LP
4140
If the client cannot find an input style that it can support,
4141
it should negotiate with the user the continuation of the program
4142
(exit, choose another input method, and so on).
4143
.LP
4144
The argument value must be a pointer to a location
4145
where the returned value will be stored.
4146
The returned value is a pointer to a structure of type
4147
.PN XIMStyles .
4148
Clients are responsible for freeing the
4149
.PN XIMStyles
4150
structure.
4151
To do so, use
4152
.PN XFree .
4153
.LP
4154
The
4155
.PN XIMStyles
4156
structure is defined as follows:
4157
.LP
4158
.IN "XIMStyle" "" "@DEF@"
4159
.IN "XIMPreeditArea" "" "@DEF@"
4160
.IN "XIMPreeditCallbacks" "" "@DEF@"
4161
.IN "XIMPreeditPosition" "" "@DEF@"
4162
.IN "XIMPreeditNothing" "" "@DEF@"
4163
.IN "XIMPreeditNone" "" "@DEF@"
4164
.IN "XIMStatusArea" "" "@DEF@"
4165
.IN "XIMStatusCallbacks" "" "@DEF@"
4166
.IN "XIMStatusNothing" "" "@DEF@"
4167
.IN "XIMStatusNone" "" "@DEF@"
4168
.IN "XIMStyles" "" "@DEF@"
4169
.sM
4170
.Ds 0
4171
typedef unsigned long XIMStyle;
4172
.De
4173
.TS
4174
lw(.5i) lw(2i) lw(2.5i).
4175
T{
4176
#define
4177
T} T{
4178
.PN XIMPreeditArea
4179
T} T{
4180
0x0001L
4181
T}
4182
T{
4183
#define
4184
T} T{
4185
.PN XIMPreeditCallbacks
4186
T} T{
4187
0x0002L
4188
T}
4189
T{
4190
#define
4191
T} T{
4192
.PN XIMPreeditPosition
4193
T} T{
4194
0x0004L
4195
T}
4196
T{
4197
#define
4198
T} T{
4199
.PN XIMPreeditNothing
4200
T} T{
4201
0x0008L
4202
T}
4203
T{
4204
#define
4205
T} T{
4206
.PN XIMPreeditNone
4207
T} T{
4208
0x0010L
4209
T}
4210
.sp
4211
T{
4212
#define
4213
T} T{
4214
.PN XIMStatusArea
4215
T} T{
4216
0x0100L
4217
T}
4218
T{
4219
#define
4220
T} T{
4221
.PN XIMStatusCallbacks
4222
T} T{
4223
0x0200L
4224
T}
4225
T{
4226
#define
4227
T} T{
4228
.PN XIMStatusNothing
4229
T} T{
4230
0x0400L
4231
T}
4232
T{
4233
#define
4234
T} T{
4235
.PN XIMStatusNone
4236
T} T{
4237
0x0800L
4238
T}
4239
.TE
4240
.Ds 0
4241
.TA .5i 2.5i
4242
.ta .5i 2.5i
4243
typedef struct {
4244
unsigned short count_styles;
4245
XIMStyle * supported_styles;
4246
} XIMStyles;
4247
.De
4248
.LP
4249
.eM
4250
An
4251
.PN XIMStyles
4252
structure contains the number of input styles supported
4253
in its count_styles field.
4254
This is also the size of the supported_styles array.
4255
.LP
4256
The supported styles is a list of bitmask combinations,
4257
which indicate the combination of styles for each of the areas supported.
4258
These areas are described later.
4259
Each element in the list should select one of the bitmask values for
4260
each area.
4261
The list describes the complete set of combinations supported.
4262
Only these combinations are supported by the input method.
4263
.LP
4264
The preedit category defines what type of support is provided
4265
by the input method for preedit information.
4266
.IN "XIMPreeditArea" "" "@DEF@"
4267
.IN "XIMPreeditPosition" "" "@DEF@"
4268
.IN "XIMPreeditCallbacks" "" "@DEF@"
4269
.IN "XIMPreeditNothing" "" "@DEF@"
4270
.IN "XIMPreeditNone" "" "@DEF@"
4271
.TS
4272
lw(1.5i) lw(4.25i).
4273
T{
4274
.PN XIMPreeditArea
4275
T} T{
4276
If chosen,
4277
the input method would require the client to provide some area values
4278
for it to do its preediting.
4279
Refer to XIC values
4280
.PN XNArea
4281
and
4282
.PN XNAreaNeeded .
4283
T}
4284
T{
4285
.PN XIMPreeditPosition
4286
T} T{
4287
If chosen,
4288
the input method would require the client to provide positional values.
4289
Refer to XIC values
4290
.PN XNSpotLocation
4291
and
4292
.PN XNFocusWindow .
4293
T}
4294
T{
4295
.PN XIMPreeditCallbacks
4296
T} T{
4297
If chosen,
4298
the input method would require the client to define the set of preedit callbacks.
4299
Refer to XIC values
4300
.PN XNPreeditStartCallback ,
4301
.PN XNPreeditDoneCallback ,
4302
.PN XNPreeditDrawCallback ,
4303
and
4304
.PN XNPreeditCaretCallback .
4305
T}
4306
T{
4307
.PN XIMPreeditNothing
4308
T} T{
4309
If chosen, the input method can function without any preedit values.
4310
T}
4311
T{
4312
.PN XIMPreeditNone
4313
T} T{
4314
The input method does not provide any preedit feedback.
4315
Any preedit value is ignored.
4316
This style is mutually exclusive with the other preedit styles.
4317
T}
4318
.TE
4319
.LP
4320
The status category defines what type of support is provided
4321
by the input method for status information.
4322
.IN "XIMStatusArea" "" "@DEF@"
4323
.IN "XIMStatusCallbacks" "" "@DEF@"
4324
.IN "XIMStatusNothing" "" "@DEF@"
4325
.IN "XIMStatusNone" "" "@DEF@"
4326
.TS
4327
lw(1.5i) lw(4.25i).
4328
T{
4329
.PN XIMStatusArea
4330
T} T{
4331
The input method requires the client to provide
4332
some area values for it to do its status feedback.
4333
See
4334
.PN XNArea
4335
and
4336
.PN XNAreaNeeded .
4337
T}
4338
T{
4339
.PN XIMStatusCallbacks
4340
T} T{
4341
The input method requires the client to define the set of status callbacks,
4342
.PN XNStatusStartCallback ,
4343
.PN XNStatusDoneCallback ,
4344
and
4345
.PN XNStatusDrawCallback .
4346
T}
4347
T{
4348
.PN XIMStatusNothing
4349
T} T{
4350
The input method can function without any status values.
4351
T}
4352
T{
4353
.PN XIMStatusNone
4354
T} T{
4355
The input method does not provide any status feedback.
4356
If chosen, any status value is ignored.
4357
This style is mutually exclusive with the other status styles.
4358
T}
4359
.TE
4360
.NH 4
4361
Resource Name and Class
4362
.XS
4363
\*(SN Resource Name and Class
4364
.XE
4365
.LP
4366
The
4367
.PN XNResourceName
4368
and
4369
.PN XNResourceClass
4370
arguments are strings that specify the full name and class
4371
used by the input method.
4372
These values should be used as prefixes for the name and class
4373
when looking up resources that may vary according to the input method.
4374
If these values are not set,
4375
the resources will not be fully specified.
4376
.LP
4377
It is not intended that values that can be set as XIM values be
4378
set as resources.
4379
.LP
4380
.NH 4
4381
Destroy Callback
4382
.XS
4383
\*(SN Destroy Callback
4384
.XE
4385
.LP
4386
The
4387
.PN XNDestroyCallback
4388
argument is a pointer to a structure of type
4389
.PN XIMCallback .
4390
.PN XNDestroyCallback
4391
is triggered when an input method stops its service for any reason.
4392
After the callback is invoked, the input method is closed and the
4393
associated input context(s) are destroyed by Xlib.
4394
Therefore, the client should not call
4395
.PN XCloseIM
4396
or
4397
.PN XDestroyIC .
4398
.LP
4399
The generic prototype of this callback function is as follows:
4400
.IN "DestroyCallback" "" "@DEF@"
4401
.sM
4402
.FD 0
4403
void DestroyCallback\^(\^\fIim\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
4404
.br
4405
XIM \fIim\fP\^;
4406
.br
4407
XPointer \fIclient_data\fP\^;
4408
.br
4409
XPointer \fIcall_data\fP\^;
4410
.FN
4411
.IP \fIim\fP 1i
4412
Specifies the input method.
4413
.IP \fIclient_data\fP 1i
4414
Specifies the additional client data.
4415
.IP \fIcall_data\fP 1i
4416
Not used for this callback and always passed as NULL.
4417
.LP
4418
.eM
4419
A DestroyCallback is always called with a NULL call_data argument.
4420
.LP
4421
.NH 4
4422
Query IM/IC Values List
4423
.XS
4424
\*(SN Query IM/IC Values List
4425
.XE
4426
.LP
4427
.PN XNQueryIMValuesList
4428
and
4429
.PN XNQueryICValuesList
4430
are used to query about XIM and XIC values supported by the input method.
4431
.LP
4432
The argument value must be a pointer to a location where the returned
4433
value will be stored. The returned value is a pointer to a structure
4434
of type
4435
.PN XIMValuesList .
4436
Clients are responsible for freeing the
4437
.PN XIMValuesList
4438
structure.
4439
To do so, use
4440
.PN XFree .
4441
.LP
4442
The
4443
.PN XIMValuesList
4444
structure is defined as follows:
4445
.sM
4446
.Ds 0
4447
.TA .5i 2.5i
4448
.ta .5i 2.5i
4449
typedef struct {
4450
unsigned short count_values;
4451
char **supported_values;
4452
} XIMValuesList;
4453
.De
4454
.LP
4455
.eM
4456
.NH 4
4457
Visible Position
4458
.XS
4459
\*(SN Visible Position
4460
.XE
4461
.LP
4462
The
4463
.PN XNVisiblePosition
4464
argument indicates whether the visible position masks of
4465
.PN XIMFeedback
4466
in
4467
.PN XIMText
4468
are available.
4469
.LP
4470
The argument value must be a pointer to a location where the returned
4471
value will be stored. The returned value is of type
4472
.PN Bool .
4473
If the returned value is
4474
.PN True ,
4475
the input method uses the visible position masks of
4476
.PN XIMFeedback
4477
in
4478
.PN XIMText ;
4479
otherwise, the input method does not use the masks.
4480
.LP
4481
Because this XIM value is optional, a client should call
4482
.PN XGetIMValues
4483
with argument
4484
.PN XNQueryIMValues
4485
before using this argument.
4486
If the
4487
.PN XNVisiblePosition
4488
does not exist in the IM values list returned from
4489
.PN XNQueryIMValues ,
4490
the visible position masks of
4491
.PN XIMFeedback
4492
in
4493
.PN XIMText
4494
are not used to indicate the visible position.
4495
.LP
4496
.NH 4
4497
Preedit Callback Behavior
4498
.XS
4499
\*(SN Preedit Callback Behavior
4500
.XE
4501
.LP
4502
The
4503
.PN XNR6PreeditCallbackBehavior
4504
argument originally included in the X11R6 specification has been
4505
deprecated.\(dg
4506
.\" If XNR6PreeditCallbackBehavior is not deprecated, then its type
4507
.\" should be changed from *Bool to Bool.
4508
.FS \(dg
4509
During formulation of the X11R6 specification, the behavior of
4510
the R6 PreeditDrawCallbacks was going to differ significantly from
4511
that of the R5 callbacks.
4512
Late changes to the specification converged the R5 and R6 behaviors,
4513
eliminating the need for
4514
.PN XNR6PreeditCallbackBehavior .
4515
Unfortunately, this argument was not removed from the R6 specification
4516
before it was published.
4517
.FE
4518
.LP
4519
The
4520
.PN XNR6PreeditCallbackBehavior
4521
argument indicates whether the behavior of preedit callbacks regarding
4522
.PN XIMPreeditDrawCallbackStruct
4523
values follows Release 5 or Release 6 semantics.
4524
.LP
4525
The value is of type
4526
.PN Bool .
4527
When querying for
4528
.PN XNR6PreeditCallbackBehavior ,
4529
if the returned value is
4530
.PN True ,
4531
the input method uses the Release 6 behavior;
4532
otherwise, it uses the Release 5 behavior.
4533
The default value is
4534
.PN False .
4535
In order to use Release 6 semantics, the value of
4536
.PN XNR6PreeditCallbackBehavior
4537
must be set to
4538
.PN True .
4539
.LP
4540
Because this XIM value is optional, a client should call
4541
.PN XGetIMValues
4542
with argument
4543
.PN XNQueryIMValues
4544
before using this argument.
4545
If the
4546
.PN XNR6PreeditCallbackBehavior
4547
does not exist in the IM values list returned from
4548
.PN XNQueryIMValues ,
4549
the PreeditCallback behavior is Release 5 semantics.
4550
.LP
4551
.NH 3
4552
Input Context Functions
4553
.XS
4554
\*(SN Input Context Functions
4555
.XE
4556
.LP
4557
An input context is an abstraction that is used to contain both the data
4558
required (if any) by an input method and the information required
4559
to display that data.
4560
There may be multiple input contexts for one input method.
4561
The programming interfaces for creating, reading, or modifying
4562
an input context use a variable argument list.
4563
The name elements of the argument lists are referred to as XIC values.
4564
It is intended that input methods be controlled by these XIC values.
4565
As new XIC values are created,
4566
they should be registered with the X Consortium.
4567
.LP
4568
.sp
4569
To create an input context, use
4570
.PN XCreateIC .
4571
.IN "XCreateIC" "" "@DEF@"
4572
.sM
4573
.FD 0
4574
XIC XCreateIC\^(\^\fIim\fP\^, ...)
4575
.br
4576
XIM \fIim\fP\^;
4577
.FN
4578
.IP \fIim\fP 1i
4579
Specifies the input method.
4580
.ds Al \ to set XIC values
4581
.IP ... 1i
4582
Specifies the variable length argument list\*(Al.
4583
.LP
4584
.eM
4585
The
4586
.PN XCreateIC
4587
function creates a context within the specified input method.
4588
.LP
4589
Some of the arguments are mandatory at creation time, and
4590
the input context will not be created if those arguments are not provided.
4591
The mandatory arguments are the input style and the set of text callbacks
4592
(if the input style selected requires callbacks).
4593
All other input context values can be set later.
4594
.LP
4595
.PN XCreateIC
4596
returns a NULL value if no input context could be created.
4597
A NULL value could be returned for any of the following reasons:
4598
.IP \(bu 5
4599
A required argument was not set.
4600
.IP \(bu 5
4601
A read-only argument was set (for example,
4602
.PN XNFilterEvents ).
4603
.IP \(bu 5
4604
The argument name is not recognized.
4605
.IP \(bu 5
4606
The input method encountered an input method implementation-dependent error.
4607
.LP
4608
.PN XCreateIC
4609
can generate
4610
.PN BadAtom ,
4611
.PN BadColor ,
4612
.PN BadPixmap ,
4613
and
4614
.PN BadWindow
4615
errors.
4616
.LP
4617
.sp
4618
To destroy an input context, use
4619
.PN XDestroyIC .
4620
.IN "XDestroyIC" "" "@DEF@"
4621
.sM
4622
.FD 0
4623
void XDestroyIC\^(\^\fIic\fP\^)
4624
.br
4625
XIC \fIic\fP\^;
4626
.FN
4627
.IP \fIic\fP 1i
4628
Specifies the input context.
4629
.LP
4630
.eM
4631
.PN XDestroyIC
4632
destroys the specified input context.
4633
.LP
4634
.sp
4635
To communicate to and synchronize with input method
4636
for any changes in keyboard focus from the client side,
4637
use
4638
.PN XSetICFocus
4639
and
4640
.PN XUnsetICFocus .
4641
.IN "XSetICFocus" "" "@DEF@"
4642
.sM
4643
.FD 0
4644
void XSetICFocus\^(\^\fIic\fP\^)
4645
.br
4646
XIC \fIic\fP\^;
4647
.FN
4648
.IP \fIic\fP 1i
4649
Specifies the input context.
4650
.LP
4651
.eM
4652
The
4653
.PN XSetICFocus
4654
function allows a client to notify an input method that the focus window
4655
attached to the specified input context has received keyboard focus.
4656
The input method should take action to provide appropriate feedback.
4657
Complete feedback specification is a matter of user interface policy.
4658
.LP
4659
Calling
4660
.PN XSetICFocus
4661
does not affect the focus window value.
4662
.LP
4663
.sp
4664
.IN "XUnsetICFocus" "" "@DEF@"
4665
.sM
4666
.FD 0
4667
void XUnsetICFocus\^(\^\fIic\fP\^)
4668
.br
4669
XIC \fIic\fP\^;
4670
.FN
4671
.IP \fIic\fP 1i
4672
Specifies the input context.
4673
.LP
4674
.eM
4675
The
4676
.PN XUnsetICFocus
4677
function allows a client to notify an input method that the specified input context
4678
has lost the keyboard focus and that no more input is expected on the focus window
4679
attached to that input context.
4680
The input method should take action to provide appropriate feedback.
4681
Complete feedback specification is a matter of user interface policy.
4682
.LP
4683
Calling
4684
.PN XUnsetICFocus
4685
does not affect the focus window value;
4686
the client may still receive
4687
events from the input method that are directed to the focus window.
4688
.LP
4689
.sp
4690
To reset the state of an input context to its initial state, use
4691
.PN XmbResetIC
4692
or
4693
.PN XwcResetIC .
4694
.IN "XmbResetIC" "" "@DEF@"
4695
.IN "XwcResetIC" "" "@DE@"
4696
.sM
4697
.FD 0
4698
char * XmbResetIC\^(\^\fIic\fP\^)
4699
.br
4700
XIC \fIic\fP\^;
4701
.FN
4702
.FD 0
4703
wchar_t * XwcResetIC\^(\^\fIic\fP\^)
4704
.br
4705
XIC \fIic\fP\^;
4706
.FN
4707
.IP \fIic\fP 1i
4708
Specifies the input context.
4709
.LP
4710
.eM
4711
When
4712
.PN XNResetState
4713
is set to
4714
.PN XIMInitialState ,
4715
.PN XmbResetIC
4716
and
4717
.PN XwcResetIC
4718
reset an input context to its initial state;
4719
when
4720
.PN XNResetState
4721
is set to
4722
.PN XIMPreserveState ,
4723
the current input context state is preserved.
4724
In both cases, any input pending on that context is deleted.
4725
The input method is required to clear the preedit area, if any,
4726
and update the status accordingly.
4727
Calling
4728
.PN XmbResetIC
4729
or
4730
.PN XwcResetIC
4731
does not change the focus.
4732
.LP
4733
The return value of
4734
.PN XmbResetIC
4735
is its current preedit string as a multibyte string.
4736
If there is any preedit text drawn or visible to the user,
4737
then these procedures must return a non-NULL string.
4738
If there is no visible preedit text,
4739
then it is input method implementation-dependent
4740
whether these procedures return a non-NULL string or NULL.
4741
.LP
4742
The client should free the returned string by calling
4743
.PN XFree .
4744
.LP
4745
.sp
4746
To get the input method associated with an input context, use
4747
.PN XIMOfIC .
4748
.IN "XIMOfIC" "" "@DEF@"
4749
.sM
4750
.FD 0
4751
XIM XIMOfIC\^(\^\fIic\fP\^)
4752
.br
4753
XIC \fIic\fP\^;
4754
.FN
4755
.IP \fIic\fP 1i
4756
Specifies the input context.
4757
.LP
4758
.eM
4759
The
4760
.PN XIMOfIC
4761
function returns the input method associated with the specified input context.
4762
.LP
4763
.sp
4764
Xlib provides two functions for setting and reading XIC values, respectively,
4765
.PN XSetICValues
4766
and
4767
.PN XGetICValues .
4768
Both functions have a variable-length argument list.
4769
In that argument list, any XIC value's name must be denoted
4770
with a character string using the X Portable Character Set.
4771
.LP
4772
.sp
4773
To set XIC values, use
4774
.PN XSetICValues .
4775
.IN "XSetICValues" "" "@DEF@"
4776
.sM
4777
.FD 0
4778
char * XSetICValues\^(\^\fIic\fP\^, ...)
4779
.br
4780
XIC \fIic\fP\^;
4781
.FN
4782
.IP \fIic\fP 1i
4783
Specifies the input context.
4784
.ds Al \ to set XIC values
4785
.IP ... 1i
4786
Specifies the variable length argument list\*(Al.
4787
.LP
4788
.eM
4789
The
4790
.PN XSetICValues
4791
function returns NULL if no error occurred;
4792
otherwise,
4793
it returns the name of the first argument that could not be set.
4794
An argument might not be set for any of the following reasons:
4795
.IP \(bu 5
4796
The argument is read-only (for example,
4797
.PN XNFilterEvents ).
4798
.IP \(bu 5
4799
The argument name is not recognized.
4800
.IP \(bu 5
4801
An implementation-dependent error occurs.
4802
.LP
4803
Each value to be set must be an appropriate datum,
4804
matching the data type imposed by the semantics of the argument.
4805
.LP
4806
.PN XSetICValues
4807
can generate
4808
.PN BadAtom ,
4809
.PN BadColor ,
4810
.PN BadCursor ,
4811
.PN BadPixmap ,
4812
and
4813
.PN BadWindow
4814
errors.
4815
.LP
4816
.sp
4817
To obtain XIC values, use
4818
.PN XGetICValues .
4819
.IN "XGetICValues" "" "@DEF@"
4820
.sM
4821
.FD 0
4822
char * XGetICValues\^(\^\fIic\fP\^, ...)
4823
.br
4824
XIC \fIic\fP\^;
4825
.FN
4826
.IP \fIic\fP 1i
4827
Specifies the input context.
4828
.ds Al \ to get XIC values
4829
.IP ... 1i
4830
Specifies the variable length argument list\*(Al.
4831
.LP
4832
.eM
4833
The
4834
.PN XGetICValues
4835
function returns NULL if no error occurred; otherwise,
4836
it returns the name of the first argument that could not be obtained.
4837
An argument could not be obtained for any of the following reasons:
4838
.IP \(bu 5
4839
The argument name is not recognized.
4840
.IP \(bu 5
4841
The input method encountered an implementation-dependent error.
4842
.LP
4843
Each IC attribute value argument (following a name) must point to
4844
a location where the IC value is to be stored.
4845
That is, if the IC value is of type T,
4846
the argument must be of type T*.
4847
If T itself is a pointer type,
4848
then
4849
.PN XGetICValues
4850
allocates memory to store the actual data,
4851
and the client is responsible for freeing this data by calling
4852
.PN XFree
4853
with the returned pointer.
4854
The exception to this rule is for an IC value of type
4855
.PN XVaNestedList
4856
(for preedit and status attributes).
4857
In this case, the argument must also be of type
4858
.PN XVaNestedList .
4859
Then, the rule of changing type T to T* and freeing the allocated data
4860
applies to each element of the nested list.
4861
.NH 3
4862
Input Context Values
4863
.XS
4864
\*(SN Input Context Values
4865
.XE
4866
.LP
4867
The following tables describe how XIC values are interpreted
4868
by an input method depending on the input style chosen by the
4869
user.
4870
.LP
4871
The first column lists the XIC values.
4872
The second column indicates which values are involved in affecting,
4873
negotiating, and setting the geometry of the input method windows.
4874
The subentries under the third column indicate the different
4875
input styles that are supported.
4876
Each of these columns indicates how each of the XIC values
4877
are treated by that input style.
4878
.LP
4879
The following keys apply to these tables.
4880
.TS H
4881
lw(1i) lw(4.75i).
4882
_
4883
.sp 6p
4884
.B
4885
Key Explanation
4886
.sp 6p
4887
_
4888
.TH
4889
.R
4890
C T{
4891
This value must be set with
4892
.PN XCreateIC .
4893
T}
4894
D T{
4895
This value may be set using
4896
.PN XCreateIC .
4897
If it is not set,
4898
a default is provided.
4899
T}
4900
G T{
4901
This value may be read using
4902
.PN XGetICValues .
4903
T}
4904
GN T{
4905
This value may cause geometry negotiation when its value is set by means of
4906
.PN XCreateIC
4907
or
4908
.PN XSetICValues .
4909
T}
4910
GR T{
4911
This value will be the response of the input method when any
4912
GN value is changed.
4913
T}
4914
GS T{
4915
This value will cause the geometry of the input method window to be set.
4916
T}
4917
O T{
4918
This value must be set once and only once.
4919
It need not be set at create time.
4920
T}
4921
S T{
4922
This value may be set with
4923
.PN XSetICValues .
4924
T}
4925
Ignored T{
4926
This value is ignored by the input method for the given input style.
4927
T}
4928
.sp 6p
4929
_
4930
.TE
4931
.LP
4932
.TS H
4933
c c c s s s s
4934
l c c c c c c
4935
c c c c c c c
4936
l c c c c c c.
4937
_
4938
.sp 6p
4939
.B
4940
Input Style
4941
XIC Value Geometry Preedit Preedit Preedit Preedit Preedit
4942
Management Callback Position Area Nothing None
4943
.sp 6p
4944
_
4945
.sp 6p
4946
.TH
4947
.R
4948
Input Style C-G C-G C-G C-G C-G
4949
Client Window O-G O-G O-G O-G Ignored
4950
Focus Window GN D-S-G D-S-G D-S-G D-S-G Ignored
4951
Resource Name Ignored D-S-G D-S-G D-S-G Ignored
4952
Resource Class Ignored D-S-G D-S-G D-S-G Ignored
4953
Geometry Callback Ignored Ignored D-S-G Ignored Ignored
4954
Filter Events G G G G Ignored
4955
Destroy Callback D-S-G D-S-G D-S-G D-S-G D-S-G
4956
String Conversion Callback S-G S-G S-G S-G S-G
4957
String Conversion D-S-G D-S-G D-S-G D-S-G D-S-G
4958
Reset State D-S-G D-S-G D-S-G D-S-G Ignored
4959
HotKey S-G S-G S-G S-G Ignored
4960
HotKeyState D-S-G D-S-G D-S-G D-S-G Ignored
4961
.sp 6p
4962
\fBPreedit\fP
4963
Area GS Ignored D-S-G D-S-G Ignored Ignored
4964
Area Needed GN-GR Ignored Ignored S-G Ignored Ignored
4965
Spot Location Ignored D-S-G Ignored Ignored Ignored
4966
Colormap Ignored D-S-G D-S-G D-S-G Ignored
4967
Foreground Ignored D-S-G D-S-G D-S-G Ignored
4968
Background Ignored D-S-G D-S-G D-S-G Ignored
4969
Background Pixmap Ignored D-S-G D-S-G D-S-G Ignored
4970
Font Set GN Ignored D-S-G D-S-G D-S-G Ignored
4971
Line Spacing GN Ignored D-S-G D-S-G D-S-G Ignored
4972
Cursor Ignored D-S-G D-S-G D-S-G Ignored
4973
Preedit State D-S-G D-S-G D-S-G D-S-G Ignored
4974
Preedit State Notify Callback S-G S-G S-G S-G Ignored
4975
Preedit Callbacks C-S-G Ignored Ignored Ignored Ignored
4976
.sp 6p
4977
_
4978
.TE
4979
.LP
4980
.TS H
4981
c c c s s s
4982
l c c c c c
4983
c c c c c c
4984
l c c c c c.
4985
_
4986
.sp 6p
4987
.B
4988
Input Style
4989
XIC Value Geometry Status Status Status Status
4990
Management Callback Area Nothing None
4991
.sp 6p
4992
_
4993
.sp 6p
4994
.TH
4995
.R
4996
Input Style C-G C-G C-G C-G
4997
Client Window O-G O-G O-G Ignored
4998
Focus Window GN D-S-G D-S-G D-S-G Ignored
4999
Resource Name Ignored D-S-G D-S-G Ignored
5000
Resource Class Ignored D-S-G D-S-G Ignored
5001
Geometry Callback Ignored D-S-G Ignored Ignored
5002
Filter Events G G G G
5003
.sp 6p
5004
\fBStatus\fP
5005
Area GS Ignored D-S-G Ignored Ignored
5006
Area Needed GN-GR Ignored S-G Ignored Ignored
5007
Colormap Ignored D-S-G D-S-G Ignored
5008
Foreground Ignored D-S-G D-S-G Ignored
5009
Background Ignored D-S-G D-S-G Ignored
5010
Background Pixmap Ignored D-S-G D-S-G Ignored
5011
Font Set GN Ignored D-S-G D-S-G Ignored
5012
Line Spacing GN Ignored D-S-G D-S-G Ignored
5013
Cursor Ignored D-S-G D-S-G Ignored
5014
Status Callbacks C-S-G Ignored Ignored Ignored
5015
.sp 6p
5016
_
5017
.TE
5018
.NH 4
5019
Input Style
5020
.XS
5021
\*(SN Input Style
5022
.XE
5023
.LP
5024
The
5025
.PN XNInputStyle
5026
argument specifies the input style to be used.
5027
The value of this argument must be one of the values returned by the
5028
.PN XGetIMValues
5029
function with the
5030
.PN XNQueryInputStyle
5031
argument specified in the supported_styles list.
5032
.LP
5033
Note that this argument must be set at creation time
5034
and cannot be changed.
5035
.NH 4
5036
Client Window
5037
.XS
5038
\*(SN Client Window
5039
.XE
5040
.LP
5041
.IN "XNClientWindow" "" "@DEF@"
5042
The
5043
.PN XNClientWindow
5044
argument specifies to the input method the client window in
5045
which the input method
5046
can display data or create subwindows.
5047
Geometry values for input method areas are given with respect to the client
5048
window.
5049
Dynamic change of client window is not supported.
5050
This argument may be set only once and
5051
should be set before any input is done using this input context.
5052
If it is not set,
5053
the input method may not operate correctly.
5054
.LP
5055
If an attempt is made to set this value a second time with
5056
.PN XSetICValues ,
5057
the string
5058
.PN XNClientWindow
5059
will be returned by
5060
.PN XSetICValues ,
5061
and the client window will not be changed.
5062
.LP
5063
If the client window is not a valid window ID on the display
5064
attached to the input method,
5065
a
5066
.PN BadWindow
5067
error can be generated when this value is used by the input method.
5068
.NH 4
5069
Focus Window
5070
.XS
5071
\*(SN Focus Window
5072
.XE
5073
.LP
5074
.IN "XNFocusWindow" "" "@DEF@"
5075
The
5076
.PN XNFocusWindow
5077
argument specifies the focus window.
5078
The primary purpose of the
5079
.PN XNFocusWindow
5080
is to identify the window that will receive the key event when input
5081
is composed.
5082
In addition, the input method may possibly affect the focus window
5083
as follows:
5084
.IP \(bu 5
5085
Select events on it
5086
.IP \(bu 5
5087
Send events to it
5088
.IP \(bu 5
5089
Modify its properties
5090
.IP \(bu 5
5091
Grab the keyboard within that window
5092
.LP
5093
The associated value must be of type
5094
.PN Window .
5095
If the focus window is not a valid window ID on the display
5096
attached to the input method,
5097
a
5098
.PN BadWindow
5099
error can be generated when this value is used by the input method.
5100
.LP
5101
When this XIC value is left unspecified,
5102
the input method will use the client window as the default focus window.
5103
.NH 4
5104
Resource Name and Class
5105
.XS
5106
\*(SN Resource Name and Class
5107
.XE
5108
.LP
5109
.IN "XNResourceName" "" "@DEF@"
5110
.IN "XNResourceClass" "" "@DEF@"
5111
The
5112
.PN XNResourceName
5113
and
5114
.PN XNResourceClass
5115
arguments are strings that specify the full name and class
5116
used by the client to obtain resources for the client window.
5117
These values should be used as prefixes for name and class
5118
when looking up resources that may vary according to the input context.
5119
If these values are not set,
5120
the resources will not be fully specified.
5121
.LP
5122
It is not intended that values that can be set as XIC values be
5123
set as resources.
5124
.NH 4
5125
Geometry Callback
5126
.XS
5127
\*(SN Geometry Callback
5128
.XE
5129
.LP
5130
.IN "XNGeometryCallback" "" "@DEF@"
5131
The
5132
.PN XNGeometryCallback
5133
argument is a structure of type
5134
.PN XIMCallback
5135
(see section 13.5.6.13.12).
5136
.LP
5137
The
5138
.PN XNGeometryCallback
5139
argument specifies the geometry callback that a client can set.
5140
This callback is not required for correct operation of either
5141
an input method or a client.
5142
It can be set for a client whose user interface policy permits
5143
an input method to request the dynamic change of that input
5144
method's window.
5145
An input method that does dynamic change will need to filter any
5146
events that it uses to initiate the change.
5147
.NH 4
5148
Filter Events
5149
.XS
5150
\*(SN Filter Events
5151
.XE
5152
.LP
5153
.IN "XNFilterEvents" "" "@DEF@"
5154
The
5155
.PN XNFilterEvents
5156
argument returns the event mask that an input method needs
5157
to have selected for.
5158
The client is expected to augment its own event mask
5159
for the client window with this one.
5160
.LP
5161
This argument is read-only, is set by the input method at create time,
5162
and is never changed.
5163
.LP
5164
The type of this argument is
5165
.PN unsigned
5166
.PN long .
5167
Setting this value will cause an error.
5168
.NH 4
5169
Destroy Callback
5170
.XS
5171
\*(SN Destroy Callback
5172
.XE
5173
.LP
5174
The
5175
.PN XNDestroyCallback
5176
argument is a pointer to a structure of type
5177
.PN XIMCallback
5178
(see section 13.5.6.13.12). This callback is triggered when the input method
5179
stops its service for any reason; for example, when a connection to an IM
5180
server is broken. After the destroy callback is called,
5181
the input context is destroyed and the input method is closed.
5182
Therefore, the client should not call
5183
.PN XDestroyIC
5184
and
5185
.PN XCloseIM .
5186
.LP
5187
.NH 4
5188
String Conversion Callback
5189
.XS
5190
\*(SN String Conversion Callback
5191
.XE
5192
.LP
5193
The
5194
.PN XNStringConversionCallback
5195
argument is a structure of type
5196
.PN XIMCallback
5197
(see section 13.5.6.13.12).
5198
.LP
5199
The
5200
.PN XNStringConversionCallback
5201
argument specifies a string conversion callback. This callback
5202
is not required for correct operation of
5203
either the input method or the client. It can be set by a client
5204
to support string conversions that may be requested
5205
by the input method. An input method that does string conversions
5206
will filter any events that it uses to initiate the conversion.
5207
.LP
5208
Because this XIC value is optional, a client should call
5209
.PN XGetIMValues
5210
with argument
5211
.PN XNQueryICValuesList
5212
before using this argument.
5213
.LP
5214
.NH 4
5215
String Conversion
5216
.XS
5217
\*(SN String Conversion
5218
.XE
5219
.LP
5220
The
5221
.PN XNStringConversion
5222
argument is a structure of type
5223
.PN XIMStringConversionText .
5224
.LP
5225
The
5226
.PN XNStringConversion
5227
argument specifies the string to be converted by an input method.
5228
This argument is not required for correct operation of either
5229
the input method or the client.
5230
.LP
5231
String conversion facilitates the manipulation of text independent
5232
of preediting.
5233
It is essential for some input methods and clients to manipulate
5234
text by performing context-sensitive conversion,
5235
reconversion, or transliteration conversion on it.
5236
.LP
5237
Because this XIC value is optional, a client should call
5238
.PN XGetIMValues
5239
with argument
5240
.PN XNQueryICValuesList
5241
before using this argument.
5242
.LP
5243
The
5244
.PN XIMStringConversionText
5245
structure is defined as follows:
5246
.LP
5247
.sM
5248
.Ds 0
5249
5250
typedef struct _XIMStringConversionText {
5251
unsigned short length;
5252
XIMStringConversionFeedback *feedback;
5253
Bool encoding_is_wchar;
5254
union {
5255
char *mbs;
5256
wchar_t *wcs;
5257
} string;
5258
} XIMStringConversionText;
5259
5260
typedef unsigned long XIMStringConversionFeedback;
5261
.De
5262
.LP
5263
.eM
5264
The feedback member is reserved for future use. The text to be
5265
converted is defined by the string and length members. The length
5266
is indicated in characters. To prevent the library from freeing memory
5267
pointed to by an uninitialized pointer, the client should set the feedback
5268
element to NULL.
5269
.LP
5270
.NH 4
5271
Reset State
5272
.XS
5273
\*(SN Reset State
5274
.XE
5275
.LP
5276
The
5277
.PN XNResetState
5278
argument specifies the state the input context will return to after calling
5279
.PN XmbResetIC
5280
or
5281
.PN XwcResetIC .
5282
.LP
5283
The XIC state may be set to its initial state, as specified by the
5284
.PN XNPreeditState
5285
value when
5286
.PN XCreateIC
5287
was called, or it may be set to preserve the current state.
5288
.LP
5289
The valid masks for
5290
.PN XIMResetState
5291
are as follows:
5292
.LP
5293
.IN "XIMInitialState" "" "@DEF@"
5294
.IN "XINPreserveState" "" "@DEF@"
5295
.sM
5296
.LP
5297
.Ds 0
5298
typedef unsigned long XIMResetState;
5299
.De
5300
.TS
5301
lw(.5i) lw(2i) lw(2i).
5302
T{
5303
#define
5304
T} T{
5305
.PN XIMInitialState
5306
T} T{
5307
(1L)
5308
T}
5309
T{
5310
#define
5311
T} T{
5312
.PN XIMPreserveState
5313
T} T{
5314
(1L<<1)
5315
T}
5316
.TE
5317
.LP
5318
.eM
5319
If
5320
.PN XIMInitialState
5321
is set, then
5322
.PN XmbResetIC
5323
and
5324
.PN XwcResetIC
5325
will return to the initial
5326
.PN XNPreeditState
5327
state of the XIC.
5328
.LP
5329
If
5330
.PN XIMPreserveState
5331
is set, then
5332
.PN XmbResetIC
5333
and
5334
.PN XwcResetIC
5335
will preserve the current state of the XIC.
5336
.LP
5337
If
5338
.PN XNResetState
5339
is left unspecified, the default is
5340
.PN XIMInitialState .
5341
.LP
5342
.PN XIMResetState
5343
values other than those specified above will default to
5344
.PN XIMInitialState .
5345
.LP
5346
Because this XIC value is optional, a client should call
5347
.PN XGetIMValues
5348
with argument
5349
.PN XNQueryICValuesList
5350
before using this argument.
5351
.LP
5352
.NH 4
5353
Hot Keys
5354
.XS
5355
\*(SN Hot Keys
5356
.XE
5357
.LP
5358
The
5359
.PN XNHotKey
5360
argument specifies the hot key list to the XIC.
5361
The hot key list is a pointer to the structure of type
5362
.PN XIMHotKeyTriggers ,
5363
which specifies the key events that must be received
5364
without any interruption of the input method.
5365
For the hot key list set with this argument to be utilized, the client
5366
must also set
5367
.PN XNHotKeyState
5368
to
5369
.PN XIMHotKeyStateON .
5370
.LP
5371
Because this XIC value is optional, a client should call
5372
.PN XGetIMValues
5373
with argument
5374
.PN XNQueryICValuesList
5375
before using this functionality.
5376
.LP
5377
The value of the argument is a pointer to a structure of type
5378
.PN XIMHotKeyTriggers .
5379
.LP
5380
If an event for a key in the hot key list is found, then the process will
5381
receive the event and it will be processed inside the client.
5382
.LP
5383
.sM
5384
.Ds 0
5385
.TA .5i 2.5i
5386
.ta .5i 2.5i
5387
typedef struct {
5388
KeySym keysym;
5389
unsigned int modifier;
5390
unsigned int modifier_mask;
5391
} XIMHotKeyTrigger;
5392
5393
typedef struct {
5394
int num_hot_key;
5395
XIMHotKeyTrigger *key;
5396
} XIMHotKeyTriggers;
5397
.De
5398
.LP
5399
.eM
5400
.LP
5401
The combination of modifier and modifier_mask are used to represent one of
5402
three states for each modifier:
5403
either the modifier must be on, or the modifier must be off, or the modifier
5404
is a ``don't care'' \- it may be on or off.
5405
When a modifier_mask bit is set to 0, the state of the associated modifier
5406
is ignored when evaluating whether the key is hot or not.
5407
.TS H
5408
lw(1i) lw(1i) lw(3i).
5409
_
5410
.sp 6p
5411
.B
5412
Modifier Bit Mask Bit Meaning
5413
.sp 6p
5414
_
5415
.sp 6p
5416
.TH
5417
.R
5418
T{
5419
0
5420
T} T{
5421
1
5422
T} T{
5423
The modifier must be off.
5424
T}
5425
T{
5426
1
5427
T} T{
5428
1
5429
T} T{
5430
The modifier must be on.
5431
T}
5432
T{
5433
n/a
5434
T} T{
5435
0
5436
T} T{
5437
Do not care if the modifier is on or off.
5438
T}
5439
.sp 6p
5440
_
5441
.TE
5442
.NH 4
5443
Hot Key State
5444
.XS
5445
\*(SN Hot Key State
5446
.XE
5447
.LP
5448
The
5449
.PN XNHotKeyState
5450
argument specifies the hot key state of the input method.
5451
This is usually used to switch the input method between hot key
5452
operation and normal input processing.
5453
.LP
5454
The value of the argument is a pointer to a structure of type
5455
XIMHotKeyState .
5456
.LP
5457
.sM
5458
.Ds 0
5459
.TA .5i 2.5i
5460
.ta .5i 2.5i
5461
typedef unsigned long XIMHotKeyState;
5462
.De
5463
.TS
5464
lw(.5i) lw(3i) lw(2i).
5465
T{
5466
#define
5467
T} T{
5468
.PN XIMHotKeyStateON
5469
T} T{
5470
(0x0001L)
5471
T}
5472
T{
5473
#define
5474
T} T{
5475
.PN XIMHotKeyStateOFF
5476
T} T{
5477
(0x0002L)
5478
T}
5479
.TE
5480
.LP
5481
.eM
5482
.LP
5483
If not specified, the default is
5484
.PN XIMHotKeyStateOFF .
5485
.LP
5486
.NH 4
5487
Preedit and Status Attributes
5488
.XS
5489
\*(SN Preedit and Status Attributes
5490
.XE
5491
.LP
5492
.IN "XNPreeditAttributes" "" "@DEF@"
5493
.IN "XNStatusAttributes" "" "@DEF@"
5494
The
5495
.PN XNPreeditAttributes
5496
and
5497
.PN XNStatusAttributes
5498
arguments specify to an input method the attributes to be used for the
5499
preedit and status areas,
5500
if any.
5501
Those attributes are passed to
5502
.PN XSetICValues
5503
or
5504
.PN XGetICValues
5505
as a nested variable-length list.
5506
The names to be used in these lists are described in the following sections.
5507
.NH 5
5508
Area
5509
.XS
5510
\*(SN Area
5511
.XE
5512
.LP
5513
.IN "XNArea" "" "@DEF@"
5514
The value of the
5515
.PN XNArea
5516
argument must be a pointer to a structure of type
5517
.PN XRectangle.
5518
The interpretation of the
5519
.PN XNArea
5520
argument is dependent on the input method style that has been set.
5521
.LP
5522
If the input method style is
5523
.PN XIMPreeditPosition ,
5524
.PN XNArea
5525
specifies the clipping region within which preediting will take place.
5526
If the focus window has been set,
5527
the coordinates are assumed to be relative to the focus window.
5528
Otherwise, the coordinates are assumed to be relative to the client window.
5529
If neither has been set,
5530
the results are undefined.
5531
.LP
5532
If
5533
.PN XNArea
5534
is not specified, is set to NULL, or is invalid,
5535
the input method will default the clipping region
5536
to the geometry of the
5537
.PN XNFocusWindow .
5538
If the area specified is NULL or invalid,
5539
the results are undefined.
5540
.LP
5541
If the input style is
5542
.PN XIMPreeditArea
5543
or
5544
.PN XIMStatusArea ,
5545
.PN XNArea
5546
specifies the geometry provided by the client to the input method.
5547
The input method may use this area to display its data,
5548
either preedit or status depending on the area designated.
5549
The input method may create a window as a child of the client window
5550
with dimensions that fit the
5551
.PN XNArea .
5552
The coordinates are relative to the client window.
5553
If the client window has not been set yet,
5554
the input method should save these values
5555
and apply them when the client window is set.
5556
If
5557
.PN XNArea
5558
is not specified, is set to NULL, or is invalid,
5559
the results are undefined.
5560
.NH 5
5561
Area Needed
5562
.XS
5563
\*(SN Area Needed
5564
.XE
5565
.LP
5566
.IN "XNAreaNeeded" "" "@DEF@"
5567
When set, the
5568
.PN XNAreaNeeded
5569
argument specifies the geometry suggested by the client for this area
5570
(preedit or status).
5571
The value associated with the argument must be a pointer to a
5572
structure of type
5573
.PN XRectangle .
5574
Note that the x, y values are not used
5575
and that nonzero values for width or height are the constraints
5576
that the client wishes the input method to respect.
5577
.LP
5578
When read, the
5579
.PN XNAreaNeeded
5580
argument specifies the preferred geometry desired by the input method
5581
for the area.
5582
.LP
5583
This argument is only valid if the input style is
5584
.PN XIMPreeditArea
5585
or
5586
.PN XIMStatusArea .
5587
It is used for geometry negotiation between the client and the input method
5588
and has no other effect on the input method
5589
(see section 13.5.1.5).
5590
.NH 5
5591
Spot Location
5592
.XS
5593
\*(SN Spot Location
5594
.XE
5595
.LP
5596
.IN "XNSpotLocation" "" "@DEF@"
5597
The
5598
.PN XNSpotLocation
5599
argument specifies to the input method the coordinates of the spot
5600
to be used by an input method executing with
5601
.PN XNInputStyle
5602
set to
5603
.PN XIMPreeditPosition .
5604
When specified to any input method other than
5605
.PN XIMPreeditPosition ,
5606
this XIC value is ignored.
5607
.LP
5608
The x coordinate specifies the position where the next character
5609
would be inserted.
5610
The y coordinate is the position of the baseline used
5611
by the current text line in the focus window.
5612
The x and y coordinates are relative to the focus window, if it has been set;
5613
otherwise, they are relative to the client window.
5614
If neither the focus window nor the client window has been set,
5615
the results are undefined.
5616
.LP
5617
The value of the argument is a pointer to a structure of type
5618
.PN XPoint .
5619
.NH 5
5620
Colormap
5621
.XS
5622
\*(SN Colormap
5623
.XE
5624
.LP
5625
Two different arguments can be used to indicate what colormap the input method
5626
should use to allocate colors, a colormap ID, or a standard colormap name.
5627
.LP
5628
.IN "XNColormap" "" "@DEF@"
5629
The
5630
.PN XNColormap
5631
argument is used to specify a colormap ID.
5632
The argument value is of type
5633
.PN Colormap .
5634
An invalid argument may generate a
5635
.PN BadColor
5636
error when it is used by the input method.
5637
.LP
5638
.IN "XNStdColormap" "" "@DEF@"
5639
The
5640
.PN XNStdColormap
5641
argument is used to indicate the name of the standard colormap
5642
in which the input method should allocate colors.
5643
The argument value is an
5644
.PN Atom
5645
that should be a valid atom for calling
5646
.PN XGetRGBColormaps .
5647
An invalid argument may generate a
5648
.PN BadAtom
5649
error when it is used by the input method.
5650
.LP
5651
If the colormap is left unspecified,
5652
the client window colormap becomes the default.
5653
.NH 5
5654
Foreground and Background
5655
.XS
5656
\*(SN Foreground and Background
5657
.XE
5658
.LP
5659
.IN "XNForeground" "" "@DEF@"
5660
.IN "XNBackground" "" "@DEF@"
5661
The
5662
.PN XNForeground
5663
and
5664
.PN XNBackground
5665
arguments specify the foreground and background pixel, respectively.
5666
The argument value is of type
5667
.PN unsigned
5668
.PN long .
5669
It must be a valid pixel in the input method colormap.
5670
.LP
5671
If these values are left unspecified,
5672
the default is determined by the input method.
5673
.NH 5
5674
Background Pixmap
5675
.XS
5676
\*(SN Background Pixmap
5677
.XE
5678
.LP
5679
The
5680
.PN XNBackgroundPixmap
5681
argument specifies a background pixmap to be used as the background of the
5682
window.
5683
The value must be of type
5684
.PN Pixmap .
5685
An invalid argument may generate a
5686
.PN BadPixmap
5687
error when it is used by the input method.
5688
.LP
5689
If this value is left unspecified,
5690
the default is determined by the input method.
5691
.NH 5
5692
Font Set
5693
.XS
5694
\*(SN Font Set
5695
.XE
5696
.LP
5697
.IN "XNFontSet" "" "@DEF@"
5698
The
5699
.PN XNFontSet
5700
argument specifies to the input method what font set is to be used.
5701
The argument value is of type
5702
.PN XFontSet .
5703
.LP
5704
If this value is left unspecified,
5705
the default is determined by the input method.
5706
.NH 5
5707
Line Spacing
5708
.XS
5709
\*(SN Line Spacing
5710
.XE
5711
.LP
5712
The
5713
.PN XNLineSpace
5714
argument specifies to the input method what line spacing is to be used
5715
in the preedit window if more than one line is to be used.
5716
This argument is of type
5717
.PN int .
5718
.LP
5719
If this value is left unspecified,
5720
the default is determined by the input method.
5721
.NH 5
5722
Cursor
5723
.XS
5724
\*(SN Cursor
5725
.XE
5726
.LP
5727
.IN "XNCursor" "" "DEF@"
5728
The
5729
.PN XNCursor
5730
argument specifies to the input method what cursor is to be used
5731
in the specified window.
5732
This argument is of type
5733
.PN Cursor .
5734
.LP
5735
An invalid argument may generate a
5736
.PN BadCursor
5737
error when it is used by the input method.
5738
If this value is left unspecified,
5739
the default is determined by the input method.
5740
.NH 5
5741
Preedit State
5742
.XS
5743
\*(SN Preedit State
5744
.XE
5745
.LP
5746
The
5747
.PN XNPreeditState
5748
argument specifies the state of input preediting for the input method.
5749
Input preediting can be on or off.
5750
.LP
5751
The valid mask names for
5752
.PN XNPreeditState
5753
are as follows:
5754
.LP
5755
.IN "XIMPreeditUnknown" "" "@DEV@"
5756
.IN "XIMPreeditEnable" "" "@DEF@"
5757
.IN "XIMPreeditDisable" "" "@DEV@"
5758
.sM
5759
.LP
5760
.Ds 0
5761
typedef unsigned long XIMPreeditState;
5762
.De
5763
.TS
5764
lw(.5i) lw(2i) lw(2i).
5765
T{
5766
#define
5767
T} T{
5768
.PN XIMPreeditUnknown
5769
T} T{
5770
0L
5771
T}
5772
T{
5773
#define
5774
T} T{
5775
.PN XIMPreeditEnable
5776
T} T{
5777
1L
5778
T}
5779
T{
5780
#define
5781
T} T{
5782
.PN XIMPreeditDisable
5783
T} T{
5784
(1L<<1)
5785
T}
5786
.TE
5787
.LP
5788
.eM
5789
If a value of
5790
.PN XIMPreeditEnable
5791
is set, then input preediting is turned on by the input method.
5792
.LP
5793
If a value of
5794
.PN XIMPreeditDisable
5795
is set, then input preediting is turned off by the input method.
5796
.LP
5797
If
5798
.PN XNPreeditState
5799
is left unspecified, then the state will be implementation-dependent.
5800
.LP
5801
When
5802
.PN XNResetState
5803
is set to
5804
.PN XIMInitialState ,
5805
the
5806
.PN XNPreeditState
5807
value specified at the creation time will be reflected as the initial state for
5808
.PN XmbResetIC
5809
and
5810
.PN XwcResetIC .
5811
.LP
5812
Because this XIC value is optional, a client should call
5813
.PN XGetIMValues
5814
with argument
5815
.PN XNQueryICValuesList
5816
before using this argument.
5817
.NH 5
5818
Preedit State Notify Callback
5819
.XS
5820
\*(SN Preedit State Notify Callback
5821
.XE
5822
.LP
5823
The preedit state notify callback is triggered by the input method
5824
when the preediting state has changed.
5825
The value of the
5826
.PN XNPreeditStateNotifyCallback
5827
argument is a pointer to a structure of type
5828
.PN XIMCallback .
5829
The generic prototype is as follows:
5830
.IN "PreeditStateNotifyCallback" "" "@DEF@"
5831
.sM
5832
.FD 0
5833
void PreeditStateNotifyCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
5834
.br
5835
XIC \fIic\fP\^;
5836
.br
5837
XPointer \fIclient_data\fP\^;
5838
.br
5839
XIMPreeditStateNotifyCallbackStruct *\fIcall_data\fP\^;
5840
.FN
5841
.IP \fIic\fP 1i
5842
Specifies the input context.
5843
.IP \fIclient_data\fP 1i
5844
Specifies the additional client data.
5845
.IP \fIcall_data\fP 1i
5846
Specifies the current preedit state.
5847
.LP
5848
.eM
5849
The
5850
.PN XIMPreeditStateNotifyCallbackStruct
5851
structure is defined as follows:
5852
.LP
5853
.IN "XIMPreeditStateNotifyCallbackStruct" "" "@DEF@"
5854
.sM
5855
.Ds 0
5856
.TA .5i 2.5i
5857
.ta .5i 2.5i
5858
typedef struct _XIMPreeditStateNotifyCallbackStruct {
5859
XIMPreeditState state;
5860
} XIMPreeditStateNotifyCallbackStruct;
5861
.De
5862
.LP
5863
.eM
5864
.LP
5865
Because this XIC value is optional, a client should call
5866
.PN XGetIMValues
5867
with argument
5868
.PN XNQueryICValuesList
5869
before using this argument.
5870
.NH 5
5871
Preedit and Status Callbacks
5872
.XS
5873
\*(SN Preedit and Status Callbacks
5874
.XE
5875
.LP
5876
A client that wants to support the input style
5877
.PN XIMPreeditCallbacks
5878
must provide a set of preedit callbacks to the input method.
5879
The set of preedit callbacks is as follows:
5880
.IN "XNPreeditStartCallback" "" "@DEF@"
5881
.IN "XNPreeditDoneCallback" "" "@DEF@"
5882
.IN "XNPreeditDrawCallback" "" "@DEF@"
5883
.IN "XNPreeditCaretCallback" "" "@DEF@"
5884
.TS
5885
lw(1.75i) lw(4i).
5886
T{
5887
.PN XNPreeditStartCallback
5888
T} T{
5889
This is called when the input method starts preedit.
5890
T}
5891
T{
5892
.PN XNPreeditDoneCallback
5893
T} T{
5894
This is called when the input method stops preedit.
5895
T}
5896
T{
5897
.PN XNPreeditDrawCallback
5898
T} T{
5899
This is called when a number of preedit keystrokes should be echoed.
5900
T}
5901
T{
5902
.PN XNPreeditCaretCallback
5903
T} T{
5904
This is called to move the text insertion point within the preedit string.
5905
T}
5906
.TE
5907
.LP
5908
A client that wants to support the input style
5909
.PN XIMStatusCallbacks
5910
must provide a set of status callbacks to the input method.
5911
The set of status callbacks is as follows:
5912
.IN "XNStatusStartCallback" "" "@DEF@"
5913
.IN "XNStatusDoneCallback" "" "@DEF@"
5914
.IN "XNStatusDrawCallback" "" "@DEF@"
5915
.TS
5916
lw(1.75i) lw(4i).
5917
T{
5918
.PN XNStatusStartCallback
5919
T} T{
5920
This is called when the input method initializes the status area.
5921
T}
5922
T{
5923
.PN XNStatusDoneCallback
5924
T} T{
5925
This is called when the input method no longer needs the status area.
5926
T}
5927
T{
5928
.PN XNStatusDrawCallback
5929
T} T{
5930
This is called when updating of the status area is required.
5931
T}
5932
.TE
5933
.LP
5934
The value of any status or preedit argument is a pointer
5935
to a structure of type
5936
.PN XIMCallback .
5937
.IN "XIMProc" "" "@DEF@"
5938
.IN "XIMCallback" "" "@DEF@"
5939
.sM
5940
.LP
5941
.Ds 0
5942
.TA .5i 2.5i
5943
.ta .5i 2.5i
5944
typedef void (*XIMProc)();
5945
5946
typedef struct {
5947
XPointer client_data;
5948
XIMProc callback;
5949
} XIMCallback;
5950
.De
5951
.LP
5952
.eM
5953
Each callback has some particular semantics and will carry the data
5954
that expresses the environment necessary to the client
5955
into a specific data structure.
5956
This paragraph only describes the arguments to be used to set
5957
the callback.
5958
.LP
5959
Setting any of these values while doing preedit
5960
may cause unexpected results.
5961
.NH 3
5962
Input Method Callback Semantics
5963
.XS
5964
\*(SN Input Method Callback Semantics
5965
.XE
5966
.LP
5967
XIM callbacks are procedures defined by clients or text drawing packages
5968
that are to be called from the input method when selected events occur.
5969
Most clients will use a text editing package or a toolkit
5970
and, hence, will not need to define such callbacks.
5971
This section defines the callback semantics, when they are triggered,
5972
and what their arguments are.
5973
This information is mostly useful for X toolkit implementors.
5974
.LP
5975
Callbacks are mostly provided so that clients (or text editing
5976
packages) can implement on-the-spot preediting in their own window.
5977
In that case,
5978
the input method needs to communicate and synchronize with the client.
5979
The input method needs to communicate changes in the preedit window
5980
when it is under control of the client.
5981
Those callbacks allow the client to initialize the preedit area,
5982
display a new preedit string,
5983
move the text insertion point during preedit,
5984
terminate preedit, or update the status area.
5985
.LP
5986
All callback procedures follow the generic prototype:
5987
.IN "CallbackPrototype" "" "@DEF@"
5988
.sM
5989
.FD 0
5990
void CallbackPrototype\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
5991
.br
5992
XIC \fIic\fP\^;
5993
.br
5994
XPointer \fIclient_data\fP\^;
5995
.br
5996
SomeType \fIcall_data\fP\^;
5997
.FN
5998
.IP \fIic\fP 1i
5999
Specifies the input context.
6000
.IP \fIclient_data\fP 1i
6001
Specifies the additional client data.
6002
.IP \fIcall_data\fP 1i
6003
Specifies data specific to the callback.
6004
.LP
6005
.eM
6006
The call_data argument is a structure that expresses the arguments needed
6007
to achieve the semantics;
6008
that is,
6009
it is a specific data structure appropriate to the callback.
6010
In cases where no data is needed in the callback,
6011
this call_data argument is NULL.
6012
The client_data argument is a closure that has been initially specified
6013
by the client when specifying the callback and passed back.
6014
It may serve, for example, to inherit application context in the callback.
6015
.LP
6016
The following paragraphs describe the programming semantics
6017
and specific data structure associated with the different reasons.
6018
.NH 4
6019
Geometry Callback
6020
.XS
6021
\*(SN Geometry Callback
6022
.XE
6023
.LP
6024
The geometry callback is triggered by the input method
6025
to indicate that it wants the client to negotiate geometry.
6026
The generic prototype is as follows:
6027
.IN "GeometryCallback" "" "@DEF@"
6028
.sM
6029
.FD 0
6030
void GeometryCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
6031
.br
6032
XIC \fIic\fP\^;
6033
.br
6034
XPointer \fIclient_data\fP\^;
6035
.br
6036
XPointer \fIcall_data\fP\^;
6037
.FN
6038
.IP \fIic\fP 1i
6039
Specifies the input context.
6040
.IP \fIclient_data\fP 1i
6041
Specifies the additional client data.
6042
.IP \fIcall_data\fP 1i
6043
Not used for this callback and always passed as NULL.
6044
.LP
6045
.eM
6046
The callback is called with a NULL call_data argument.
6047
.NH 4
6048
Destroy Callback
6049
.XS
6050
\*(SN Destroy Callback
6051
.XE
6052
.LP
6053
The destroy callback is triggered by the input method
6054
when it stops service for any reason.
6055
After the callback is invoked, the input context will be freed by Xlib.
6056
The generic prototype is as follows:
6057
.IN "DestroyCallback" "" "@DEF@"
6058
.sM
6059
.FD 0
6060
void DestroyCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
6061
.br
6062
XIC \fIic\fP\^;
6063
.br
6064
XPointer \fIclient_data\fP\^;
6065
.br
6066
XPointer \fIcall_data\fP\^;
6067
.FN
6068
.IP \fIic\fP 1i
6069
Specifies the input context.
6070
.IP \fIclient_data\fP 1i
6071
Specifies the additional client data.
6072
.IP \fIcall_data\fP 1i
6073
Not used for this callback and always passed as NULL.
6074
.LP
6075
.eM
6076
The callback is called with a NULL call_data argument.
6077
.NH 4
6078
String Conversion Callback
6079
.XS
6080
\*(SN String Conversion Callback
6081
.XE
6082
.LP
6083
The string conversion callback is triggered by the input method
6084
to request the client to return the string to be converted. The
6085
returned string may be either a multibyte or wide character string,
6086
with an encoding matching the locale bound to the input context.
6087
The callback prototype is as follows:
6088
.IN "StringConversionCallback" "" "@DEF@"
6089
.sM
6090
.FD 0
6091
void StringConversionCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
6092
.br
6093
XIC \fIic\fP\^;
6094
.br
6095
XPointer \fIclient_data\fP\^;
6096
.br
6097
XIMStringConversionCallbackStruct *\fIcall_data\fP\^;
6098
.FN
6099
.IP \fIic\fP 1i
6100
Specifies the input method.
6101
.IP \fIclient_data\fP 1i
6102
Specifies the additional client data.
6103
.IP \fIcall_data\fP 1i
6104
Specifies the amount of the string to be converted.
6105
.LP
6106
.eM
6107
The callback is passed an
6108
.PN XIMStringConversionCallbackStruct
6109
structure in the call_data argument.
6110
The text member is an
6111
.PN XIMStringConversionText
6112
structure (see section 13.5.6.9) to be filled in by the client
6113
and describes the text to be sent to the input method.
6114
The data pointed to by the
6115
string and feedback elements of the
6116
.PN XIMStringConversionText
6117
structure will be freed using
6118
.PN XFree
6119
by the input method
6120
after the callback returns. So the client should not point to
6121
internal buffers that are critical to the client.
6122
Similarly, because the feedback element is currently reserved for future
6123
use, the client should set feedback to NULL to prevent the library from
6124
freeing memory at some random location due to an uninitialized pointer.
6125
.LP
6126
The
6127
.PN XIMStringConversionCallbackStruct
6128
structure is defined as follows:
6129
.LP
6130
.IN "XIMStringConversionCallbackStruct" "" "@DEF@"
6131
.sM
6132
.LP
6133
.Ds 0
6134
typedef struct _XIMStringConversionCallbackStruct {
6135
XIMStringConversionPosition position;
6136
XIMCaretDirection direction;
6137
short factor;
6138
XIMStringConversionOperation operation;
6139
XIMStringConversionText *text;
6140
} XIMStringConversionCallbackStruct;
6141
6142
typedef short XIMStringConversionPosition;
6143
6144
typedef unsigned short XIMStringConversionOperation;
6145
6146
.De
6147
.LP
6148
.TS
6149
lw(.5i) lw(3i) lw(2i).
6150
T{
6151
#define
6152
T} T{
6153
.PN XIMStringConversionSubstitution
6154
T} T{
6155
(0x0001)
6156
T}
6157
T{
6158
#define
6159
T} T{
6160
.PN XIMStringConversionRetrieval
6161
T} T{
6162
(0x0002)
6163
T}
6164
.TE
6165
.LP
6166
.eM
6167
.PN XIMStringConversionPosition
6168
specifies the starting position of the string to be returned
6169
in the
6170
.PN XIMStringConversionText
6171
structure. The value identifies a position, in units of characters,
6172
relative to the client's cursor position in the client's buffer.
6173
.LP
6174
The ending position of the text buffer is determined by
6175
the direction and factor members. Specifically, it is the character position
6176
relative to the starting point as defined by the
6177
.PN XIMCaretDirection .
6178
The factor member of
6179
.PN XIMStringConversionCallbackStruct
6180
specifies the number of
6181
.PN XIMCaretDirection
6182
positions to be applied. For example, if the direction specifies
6183
.PN XIMLineEnd
6184
and factor is 1, then all characters from the starting position to
6185
the end of the current display line are returned. If the direction
6186
specifies
6187
.PN XIMForwardChar
6188
or
6189
.PN XIMBackwardChar ,
6190
then the factor specifies a relative position, indicated in characters,
6191
from the starting position.
6192
.LP
6193
.PN XIMStringConversionOperation
6194
specifies whether the string to be converted should be
6195
deleted (substitution) or copied (retrieval) from the client's
6196
buffer. When the
6197
.PN XIMStringConversionOperation
6198
is
6199
.PN XIMStringConversionSubstitution ,
6200
the client must delete the string to be converted from its own buffer.
6201
When the
6202
.PN XIMStringConversionOperation
6203
is
6204
.PN XIMStringConversionRetrieval ,
6205
the client must not delete the string to be converted from its buffer.
6206
The substitute operation is typically used for reconversion and
6207
transliteration conversion,
6208
while the retrieval operation is typically used for context-sensitive
6209
conversion.
6210
.NH 4
6211
Preedit State Callbacks
6212
.XS
6213
\*(SN Preedit State Callbacks
6214
.XE
6215
.LP
6216
When the input method turns preediting on or off, a
6217
.PN PreeditStartCallback
6218
or
6219
.PN PreeditDoneCallback
6220
callback is triggered to let the toolkit do the setup
6221
or the cleanup for the preedit region.
6222
.IN "PreeditStartCallback" "" "@DEF@"
6223
.sM
6224
.FD 0
6225
int PreeditStartCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
6226
.br
6227
XIC \fIic\fP\^;
6228
.br
6229
XPointer \fIclient_data\fP\^;
6230
.br
6231
XPointer \fIcall_data\fP\^;
6232
.FN
6233
.IP \fIic\fP 1i
6234
Specifies the input context.
6235
.IP \fIclient_data\fP 1i
6236
Specifies the additional client data.
6237
.IP \fIcall_data\fP 1i
6238
Not used for this callback and always passed as NULL.
6239
.LP
6240
.eM
6241
When preedit starts on the specified input context,
6242
the callback is called with a NULL call_data argument.
6243
.PN PreeditStartCallback
6244
will return the maximum size of the preedit string.
6245
A positive number indicates the maximum number of bytes allowed
6246
in the preedit string,
6247
and a value of \-1 indicates there is no limit.
6248
.IN "PreeditDoneCallback" "" "@DEF@"
6249
.sM
6250
.FD 0
6251
void PreeditDoneCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
6252
.br
6253
XIC \fIic\fP\^;
6254
.br
6255
XPointer \fIclient_data\fP\^;
6256
.br
6257
XPointer \fIcall_data\fP\^;
6258
.FN
6259
.IP \fIic\fP 1i
6260
Specifies the input context.
6261
.IP \fIclient_data\fP 1i
6262
Specifies the additional client data.
6263
.IP \fIcall_data\fP 1i
6264
Not used for this callback and always passed as NULL.
6265
.LP
6266
.eM
6267
When preedit stops on the specified input context,
6268
the callback is called with a NULL call_data argument.
6269
The client can release the data allocated by
6270
.PN PreeditStartCallback .
6271
.LP
6272
.PN PreeditStartCallback
6273
should initialize appropriate data needed for
6274
displaying preedit information and for handling further
6275
.PN PreeditDrawCallback
6276
calls.
6277
Once
6278
.PN PreeditStartCallback
6279
is called, it will not be called again before
6280
.PN PreeditDoneCallback
6281
has been called.
6282
.NH 4
6283
Preedit Draw Callback
6284
.XS
6285
\*(SN Preedit Draw Callback
6286
.XE
6287
.LP
6288
This callback is triggered to draw and insert, delete or replace,
6289
preedit text in the preedit region.
6290
The preedit text may include unconverted input text such as Japanese Kana,
6291
converted text such as Japanese Kanji characters, or characters of both kinds.
6292
That string is either a multibyte or wide character string,
6293
whose encoding matches the locale bound to the input context.
6294
The callback prototype
6295
is as follows:
6296
.IN "PreeditDrawCallback" "" "@DEF@"
6297
.sM
6298
.FD 0
6299
void PreeditDrawCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
6300
.br
6301
XIC \fIic\fP\^;
6302
.br
6303
XPointer \fIclient_data\fP\^;
6304
.br
6305
XIMPreeditDrawCallbackStruct *\fIcall_data\fP\^;
6306
.FN
6307
.IP \fIic\fP 1i
6308
Specifies the input context.
6309
.IP \fIclient_data\fP 1i
6310
Specifies the additional client data.
6311
.IP \fIcall_data\fP 1i
6312
Specifies the preedit drawing information.
6313
.LP
6314
.eM
6315
The callback is passed an
6316
.PN XIMPreeditDrawCallbackStruct
6317
structure in the call_data argument.
6318
The text member of this structure contains the text to be drawn.
6319
After the string has been drawn,
6320
the caret should be moved to the specified location.
6321
.LP
6322
The
6323
.PN XIMPreeditDrawCallbackStruct
6324
structure is defined as follows:
6325
.LP
6326
.IN "XIMPreeditDrawCallbackStruct" "" "@DEF@"
6327
.sM
6328
.Ds 0
6329
.TA .5i 2.5i
6330
.ta .5i 2.5i
6331
typedef struct _XIMPreeditDrawCallbackStruct {
6332
int caret; /* Cursor offset within preedit string */
6333
int chg_first; /* Starting change position */
6334
int chg_length; /* Length of the change in character count */
6335
XIMText *text;
6336
} XIMPreeditDrawCallbackStruct;
6337
.De
6338
.LP
6339
.eM
6340
The client must keep updating a buffer of the preedit text
6341
and the callback arguments referring to indexes in that buffer.
6342
The call_data fields have specific meanings according to the operation,
6343
as follows:
6344
.IP \(bu 5
6345
To indicate text deletion,
6346
the call_data member specifies a NULL text field.
6347
The text to be deleted is then the current text in the buffer
6348
from position chg_first (starting at zero) on a character length
6349
of chg_length.
6350
.IP \(bu 5
6351
When text is non-NULL,
6352
it indicates insertion or replacement of text in the buffer.
6353
.IP
6354
The chg_length member
6355
identifies the number of characters in the current preedit buffer
6356
that are affected by this call.
6357
A positive chg_length indicates that chg_length number of characters, starting
6358
at chg_first, must be deleted or must be replaced by text, whose length is
6359
specified in the
6360
.PN XIMText
6361
structure.
6362
.IP
6363
A chg_length value of zero indicates that text must be inserted
6364
right at the position specified by chg_first.
6365
A value of zero for chg_first specifies the first character in the buffer.
6366
.IP
6367
chg_length and chg_first combine to identify the modification required to
6368
the preedit buffer; beginning at chg_first, replace chg_length number of
6369
characters with the text in the supplied
6370
.PN XIMText
6371
structure. For example, suppose the preedit buffer contains the string "ABCDE".
6372
.IP
6373
.DS I
6374
.ft C
6375
Text: A B C D E
6376
^ ^ ^ ^ ^ ^
6377
CharPos: 0 1 2 3 4 5
6378
.sp
6379
.ft P
6380
.DE
6381
The CharPos in the diagram shows the location of the character position
6382
relative to the character.
6383
.IP
6384
If the value of chg_first is 1 and the value of chg_length is 3, this
6385
says to replace 3 characters beginning at character position 1 with the
6386
string in the
6387
.PN XIMText
6388
structure.
6389
Hence, BCD would be replaced by the value in the structure.
6390
.IP
6391
Though chg_length and chg_first are both signed integers they will
6392
never have a negative value.
6393
.IP \(bu 5
6394
The caret member
6395
identifies the character position before which the cursor should
6396
be placed \- after modification to the preedit buffer has been completed.
6397
For example, if caret is zero, the cursor is at
6398
the beginning of the buffer. If the caret is one, the cursor is between
6399
the first and second character.
6400
.LP
6401
.IN "XIMText" "" @DEF@"
6402
.sM
6403
.Ds
6404
.TA .5i 1.5i 3i
6405
typedef struct _XIMText {
6406
unsigned short length;
6407
XIMFeedback * feedback;
6408
Bool encoding_is_wchar;
6409
union {
6410
char * multi_byte;
6411
wchar_t * wide_char;
6412
} string;
6413
} XIMText;
6414
.De
6415
.LP
6416
.eM
6417
The text string passed is actually a structure specifying as follows:
6418
.IP \(bu 5
6419
The length member is the text length in characters.
6420
.IP \(bu 5
6421
The encoding_is_wchar member is a value that indicates
6422
if the text string is encoded in wide character or multibyte format.
6423
The text string may be passed either as multibyte or as wide character;
6424
the input method controls in which form data is passed.
6425
The client's
6426
callback routine must be able to handle data passed in either form.
6427
.IP \(bu 5
6428
The string member is the text string.
6429
.IP \(bu 5
6430
The feedback member indicates rendering type for each character in the
6431
string member.
6432
If string is NULL (indicating that only highlighting of the existing
6433
preedit buffer should be updated), feedback points to length highlight
6434
elements that should be applied to the existing preedit buffer, beginning
6435
at chg_first.
6436
.LP
6437
The feedback member expresses the types of rendering feedback
6438
the callback should apply when drawing text.
6439
Rendering of the text to be drawn is specified either in generic ways
6440
(for example, primary, secondary) or in specific ways (reverse, underline).
6441
When generic indications are given,
6442
the client is free to choose the rendering style.
6443
It is necessary, however, that primary and secondary be mapped
6444
to two distinct rendering styles.
6445
.LP
6446
If an input method wants to control display of the preedit string, an
6447
input method can indicate the visibility hints using feedbacks in
6448
a specific way.
6449
The
6450
.PN XIMVisibleToForward ,
6451
.PN XIMVisibleToBackward ,
6452
and
6453
.PN XIMVisibleCenter
6454
masks are exclusively used for these visibility hints.
6455
The
6456
.PN XIMVisibleToForward
6457
mask
6458
indicates that the preedit text is preferably displayed in the
6459
primary draw direction from the
6460
caret position in the preedit area forward.
6461
The
6462
.PN XIMVisibleToBackward
6463
mask
6464
indicates that the preedit text is preferably displayed from
6465
the caret position in the preedit area backward, relative to the primary
6466
draw direction.
6467
The
6468
.PN XIMVisibleCenter
6469
mask
6470
indicates that the preedit text is preferably displayed with
6471
the caret position in the preedit area centered.
6472
.LP
6473
The insertion point of the preedit string could exist outside of
6474
the visible area when visibility hints are used.
6475
Only one of the
6476
masks
6477
is valid for the entire preedit string, and only one character
6478
can hold one of these feedbacks for a given input context at one time.
6479
This feedback may be OR'ed together with another highlight (such as
6480
.PN XIMReverse ).
6481
Only the most recently set feedback is valid, and any previous
6482
feedback is automatically canceled. This is a hint to the client, and
6483
the client is free to choose how to display the preedit string.
6484
.LP
6485
The feedback member also specifies how rendering of the text argument
6486
should be performed.
6487
If the feedback is NULL,
6488
the callback should apply the same feedback as is used for the surrounding
6489
characters in the preedit buffer; if chg_first is at a highlight boundary,
6490
the client can choose which of the two highlights to use.
6491
If feedback is not NULL, feedback specifies an array defining the
6492
rendering for each
6493
character of the string, and the length of the array is thus length.
6494
.LP
6495
If an input method wants to indicate that it is only updating the feedback of
6496
the preedit text without changing the content of it,
6497
the
6498
.PN XIMText
6499
structure will contain a NULL value for the string field,
6500
the number of characters affected (relative to chg_first)
6501
will be in the length field,
6502
and the feedback field will point to an array of
6503
.PN XIMFeedback .
6504
.LP
6505
Each element in the feedback array is a bitmask represented by a value of type
6506
.PN XIMFeedback .
6507
The valid mask names are as follows:
6508
.LP
6509
.IN "XIMReverse" "" "@DEF@"
6510
.IN "XIMUnderline" "" "@DEF@"
6511
.IN "XIMHighlight" "" "@DEF@"
6512
.IN "XIMPrimary" "" "@DEF@"
6513
.IN "XIMSecondary" "" "@DEF@"
6514
.IN "XIMTertiary" "" "@DEF@"
6515
.IN "XIMVisibleToForward" "" "@DEF@"
6516
.IN "XIMVisibleToBackward" "" "@DEF@"
6517
.IN "XIMVisibleCenter" "" "@DEF@"
6518
.sM
6519
.LP
6520
.Ds 0
6521
typedef unsigned long XIMFeedback;
6522
.De
6523
.TS
6524
lw(.5i) lw(2i) lw(2i).
6525
T{
6526
#define
6527
T} T{
6528
.PN XIMReverse
6529
T} T{
6530
1L
6531
T}
6532
T{
6533
#define
6534
T} T{
6535
.PN XIMUnderline
6536
T} T{
6537
(1L<<1)
6538
T}
6539
T{
6540
#define
6541
T} T{
6542
.PN XIMHighlight
6543
T} T{
6544
(1L<<2)
6545
T}
6546
T{
6547
#define
6548
T} T{
6549
.PN XIMPrimary
6550
T} T{
6551
(1L<<5)\(dg
6552
T}
6553
T{
6554
#define
6555
T} T{
6556
.PN XIMSecondary
6557
T} T{
6558
(1L<<6)\(dg
6559
T}
6560
T{
6561
#define
6562
T} T{
6563
.PN XIMTertiary
6564
T} T{
6565
(1L<<7)\(dg
6566
T}
6567
T{
6568
#define
6569
T} T{
6570
.PN XIMVisibleToForward
6571
T} T{
6572
(1L<<8)
6573
T}
6574
T{
6575
#define
6576
T} T{
6577
.PN XIMVisibleToBackward
6578
T} T{
6579
(1L<<9)
6580
T}
6581
T{
6582
#define
6583
T} T{
6584
.PN XIMVisibleCenter
6585
T} T{
6586
(1L<<10)
6587
T}
6588
.TE
6589
.LP
6590
.eM
6591
.LP
6592
Characters drawn with the
6593
.PN XIMReverse
6594
highlight should be drawn by swapping the foreground and background colors
6595
used to draw normal, unhighlighted characters.
6596
Characters drawn with the
6597
.PN XIMUnderline
6598
highlight should be underlined.
6599
Characters drawn with the
6600
.PN XIMHighlight ,
6601
.PN XIMPrimary ,
6602
.PN XIMSecondary ,
6603
and
6604
.PN XIMTertiary
6605
highlights should be drawn in some unique manner that must be different
6606
from
6607
.PN XIMReverse
6608
and
6609
.PN XIMUnderline .
6610
.FS \(dg
6611
The values for
6612
.PN XIMPrimary ,
6613
.PN XIMSecondary ,
6614
and
6615
.PN XIMTertiary
6616
were incorrectly defined in the R5 specification.
6617
The X Consortium's X11R5
6618
implementation correctly implemented the values for these highlights.
6619
The value of these highlights has been corrected in this specification
6620
to agree with the values in the Consortium's X11R5 and X11R6 implementations.
6621
.FE
6622
.NH 4
6623
Preedit Caret Callback
6624
.XS
6625
\*(SN Preedit Caret Callback
6626
.XE
6627
.LP
6628
An input method may have its own navigation keys to allow the user
6629
to move the text insertion point in the preedit area
6630
(for example, to move backward or forward).
6631
Consequently, input method needs to indicate to the client that it
6632
should move the text insertion point.
6633
It then calls the PreeditCaretCallback.
6634
.IN "PreeditCaretCallback" "" "@DEF@"
6635
.sM
6636
.FD 0
6637
void PreeditCaretCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
6638
.br
6639
XIC \fIic\fP\^;
6640
.br
6641
XPointer \fIclient_data\fP\^;
6642
.br
6643
XIMPreeditCaretCallbackStruct *\fIcall_data\fP\^;
6644
.FN
6645
.IP \fIic\fP 1i
6646
Specifies the input context.
6647
.IP \fIclient_data\fP 1i
6648
Specifies the additional client data.
6649
.IP \fIcall_data\fP 1i
6650
Specifies the preedit caret information.
6651
.LP
6652
.eM
6653
The input method will trigger PreeditCaretCallback
6654
to move the text insertion point during preedit.
6655
The call_data argument contains a pointer to an
6656
.PN XIMPreeditCaretCallbackStruct
6657
structure,
6658
which indicates where the caret should be moved.
6659
The callback must move the insertion point to its new location
6660
and return, in field position, the new offset value from the initial position.
6661
.LP
6662
The
6663
.PN XIMPreeditCaretCallbackStruct
6664
structure is defined as follows:
6665
.IN "XIMPreeditCaretCallbackStruct" "" "@DEF@"
6666
.LP
6667
.sM
6668
.Ds 0
6669
.TA .5i 2.5i
6670
.ta .5i 2.5i
6671
typedef struct _XIMPreeditCaretCallbackStruct {
6672
int position; /* Caret offset within preedit string */
6673
XIMCaretDirection direction; /* Caret moves direction */
6674
XIMCaretStyle style; /* Feedback of the caret */
6675
} XIMPreeditCaretCallbackStruct;
6676
.De
6677
.LP
6678
.eM
6679
The
6680
.PN XIMCaretStyle
6681
structure is defined as follows:
6682
.LP
6683
.IN "XIMCaretStyle" "" "@DEF@"
6684
.sM
6685
.Ds 0
6686
.TA .5i 2.5i
6687
.ta .5i 2.5i
6688
typedef enum {
6689
XIMIsInvisible, /* Disable caret feedback */
6690
XIMIsPrimary, /* UI defined caret feedback */
6691
XIMIsSecondary, /* UI defined caret feedback */
6692
} XIMCaretStyle;
6693
.De
6694
.LP
6695
.eM
6696
The
6697
.PN XIMCaretDirection
6698
structure is defined as follows:
6699
.IN "XIMCaretDirection" "" "@DEF@"
6700
.LP
6701
.sM
6702
.Ds 0
6703
.TA .5i 2.5i
6704
.ta .5i 2.5i
6705
typedef enum {
6706
XIMForwardChar, XIMBackwardChar,
6707
XIMForwardWord, XIMBackwardWord,
6708
XIMCaretUp, XIMCaretDown,
6709
XIMNextLine, XIMPreviousLine,
6710
XIMLineStart, XIMLineEnd,
6711
XIMAbsolutePosition,
6712
XIMDontChange,
6713
} XIMCaretDirection;
6714
.De
6715
.LP
6716
.eM
6717
These values are defined as follows:
6718
.IN "XIMForwardChar" "" "@DEF@"
6719
.IN "XIMBackwardChar" "" "@DEF@"
6720
.IN "XIMForwardWord" "" "@DEF@"
6721
.IN "XIMBackwardWord" "" "@DEF@"
6722
.IN "XIMCaretUp" "" "@DEF@"
6723
.IN "XIMCaretDown" "" "@DEF@"
6724
.TS
6725
lw(1.5i) lw(4.25i).
6726
T{
6727
.PN XIMForwardChar
6728
T} T{
6729
Move the caret forward one character position.
6730
T}
6731
T{
6732
.PN XIMBackwardChar
6733
T} T{
6734
Move the caret backward one character position.
6735
T}
6736
T{
6737
.PN XIMForwardWord
6738
T} T{
6739
Move the caret forward one word.
6740
T}
6741
T{
6742
.PN XIMBackwardWord
6743
T} T{
6744
Move the caret backward one word.
6745
T}
6746
T{
6747
.PN XIMCaretUp
6748
T} T{
6749
Move the caret up one line keeping the current horizontal offset.
6750
T}
6751
T{
6752
.PN XIMCaretDown
6753
T} T{
6754
Move the caret down one line keeping the current horizontal offset.
6755
T}
6756
T{
6757
.PN XIMPreviousLine
6758
T} T{
6759
Move the caret to the beginning of the previous line.
6760
T}
6761
T{
6762
.PN XIMNextLine
6763
T} T{
6764
Move the caret to the beginning of the next line.
6765
T}
6766
T{
6767
.PN XIMLineStart
6768
T} T{
6769
Move the caret to the beginning of the current display line
6770
that contains the caret.
6771
T}
6772
T{
6773
.PN XIMLineEnd
6774
T} T{
6775
Move the caret to the end of the current display line
6776
that contains the caret.
6777
T}
6778
T{
6779
.PN XIMAbsolutePosition
6780
T} T{
6781
The callback must move to the location specified by the position field
6782
of the callback data, indicated in characters, starting from the beginning
6783
of the preedit text.
6784
Hence, a value of zero means move back to the beginning of the preedit text.
6785
T}
6786
T{
6787
.PN XIMDontChange
6788
T} T{
6789
The caret position does not change.
6790
T}
6791
.TE
6792
.IN "XIMNextLine" "" "@DEF@"
6793
.IN "XIMPreviousLine" "" "@DEF@"
6794
.IN "XIMLineStart" "" "@DEF@"
6795
.IN "XIMLineEnd" "" "@DEF@"
6796
.IN "XIMAbsolutePosition" "" "@DEF@"
6797
.IN "XIMDontChange" "" "@DEF@"
6798
.NH 4
6799
Status Callbacks
6800
.XS
6801
\*(SN Status Callbacks
6802
.XE
6803
.LP
6804
An input method may communicate changes in the status of an input context
6805
(for example, created, destroyed, or focus changes) with three status
6806
callbacks: StatusStartCallback, StatusDoneCallback, and StatusDrawCallback.
6807
.LP
6808
.sp
6809
When the input context is created or gains focus,
6810
the input method calls the StatusStartCallback callback.
6811
.IN "StatusStartCallback" "" "@DEF@"
6812
.sM
6813
.FD 0
6814
void StatusStartCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
6815
.br
6816
XIC \fIic\fP\^;
6817
.br
6818
XPointer \fIclient_data\fP\^;
6819
.br
6820
XPointer \fIcall_data\fP\^;
6821
.FN
6822
.IP \fIic\fP 1i
6823
Specifies the input context.
6824
.IP \fIclient_data\fP 1i
6825
Specifies the additional client data.
6826
.IP \fIcall_data\fP 1i
6827
Not used for this callback and always passed as NULL.
6828
.LP
6829
.eM
6830
The callback should initialize appropriate data for displaying status
6831
and for responding to StatusDrawCallback calls.
6832
Once StatusStartCallback is called,
6833
it will not be called again before StatusDoneCallback has been called.
6834
.LP
6835
.sp
6836
When an input context
6837
is destroyed or when it loses focus, the input method calls StatusDoneCallback.
6838
.IN "StatusDoneCallback" "" "@DEF@"
6839
.sM
6840
.FD 0
6841
void StatusDoneCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
6842
.br
6843
XIC \fIic\fP\^;
6844
.br
6845
XPointer \fIclient_data\fP\^;
6846
.br
6847
XPointer \fIcall_data\fP\^;
6848
.FN
6849
.IP \fIic\fP 1i
6850
Specifies the input context.
6851
.IP \fIclient_data\fP 1i
6852
Specifies the additional client data.
6853
.IP \fIcall_data\fP 1i
6854
Not used for this callback and always passed as NULL.
6855
.LP
6856
.eM
6857
The callback may release any data allocated on
6858
.PN StatusStart .
6859
.LP
6860
.sp
6861
When an input context status has to be updated, the input method calls
6862
StatusDrawCallback.
6863
.IN "StatusDrawCallback" "" "@DEF@"
6864
.sM
6865
.FD 0
6866
void StatusDrawCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
6867
.br
6868
XIC \fIic\fP\^;
6869
.br
6870
XPointer \fIclient_data\fP\^;
6871
.br
6872
XIMStatusDrawCallbackStruct *\fIcall_data\fP\^;
6873
.FN
6874
.IP \fIic\fP 1i
6875
Specifies the input context.
6876
.IP \fIclient_data\fP 1i
6877
Specifies the additional client data.
6878
.IP \fIcall_data\fP 1i
6879
Specifies the status drawing information.
6880
.LP
6881
.eM
6882
The callback should update the status area by either drawing a string
6883
or imaging a bitmap in the status area.
6884
.LP
6885
The
6886
.PN XIMStatusDataType
6887
and
6888
.PN XIMStatusDrawCallbackStruct
6889
structures are defined as follows:
6890
.IN "XIMStatusDataType" "" "@DEF@"
6891
.IN "XIMStatusDrawCallbackStruct" "" "@DEF@"
6892
.LP
6893
.sM
6894
.Ds 0
6895
.TA .5i 1i 3i
6896
.ta .5i 1i 3i
6897
typedef enum {
6898
XIMTextType,
6899
XIMBitmapType,
6900
} XIMStatusDataType;
6901
6902
typedef struct _XIMStatusDrawCallbackStruct {
6903
XIMStatusDataType type;
6904
union {
6905
XIMText *text;
6906
Pixmap bitmap;
6907
} data;
6908
} XIMStatusDrawCallbackStruct;
6909
.De
6910
.LP
6911
.eM
6912
.LP
6913
The feedback styles
6914
.PN XIMVisibleToForward ,
6915
.PN XIMVisibleToBackward ,
6916
and
6917
.PN XIMVisibleToCenter
6918
are not relevant and will not appear in the
6919
.PN XIMFeedback
6920
element of the
6921
.PN XIMText
6922
structure.
6923
.LP
6924
.NH 3
6925
Event Filtering
6926
.XS
6927
\*(SN Event Filtering
6928
.XE
6929
.LP
6930
Xlib provides the ability for an input method
6931
to register a filter internal to Xlib.
6932
This filter is called by a client (or toolkit) by calling
6933
.PN XFilterEvent
6934
after calling
6935
.PN XNextEvent .
6936
Any client that uses the
6937
.PN XIM
6938
interface should call
6939
.PN XFilterEvent
6940
to allow input methods to process their events without knowledge
6941
of the client's dispatching mechanism.
6942
A client's user interface policy may determine the priority
6943
of event filters with respect to other event-handling mechanisms
6944
(for example, modal grabs).
6945
.LP
6946
Clients may not know how many filters there are, if any,
6947
and what they do.
6948
They may only know if an event has been filtered on return of
6949
.PN XFilterEvent .
6950
Clients should discard filtered events.
6951
.sp
6952
.LP
6953
To filter an event, use
6954
.PN XFilterEvent .
6955
.IN "XFilterEvent" "" "@DEF@"
6956
.sM
6957
.FD 0
6958
Bool XFilterEvent\^(\^\fIevent\fP\^, \fIw\fP\^)
6959
.br
6960
XEvent *\fIevent\fP\^;
6961
.br
6962
Window \fIw\fP\^;
6963
.FN
6964
.ds Ev event to filter
6965
.IP \fIevent\fP 1i
6966
Specifies the \*(Ev.
6967
.ds Wi for which the filter is to be applied
6968
.IP \fIw\fP 1i
6969
Specifies the window \*(Wi.
6970
.LP
6971
.eM
6972
If the window argument is
6973
.PN None ,
6974
.PN XFilterEvent
6975
applies the filter to the window specified in the
6976
.PN XEvent
6977
structure.
6978
The window argument is provided so that layers above Xlib
6979
that do event redirection can indicate to which window an event
6980
has been redirected.
6981
.LP
6982
If
6983
.PN XFilterEvent
6984
returns
6985
.PN True ,
6986
then some input method has filtered the event,
6987
and the client should discard the event.
6988
If
6989
.PN XFilterEvent
6990
returns
6991
.PN False ,
6992
then the client should continue processing the event.
6993
.LP
6994
If a grab has occurred in the client and
6995
.PN XFilterEvent
6996
returns
6997
.PN True ,
6998
the client should ungrab the keyboard.
6999
.NH 3
7000
Getting Keyboard Input
7001
.XS
7002
\*(SN Getting Keyboard Input
7003
.XE
7004
.LP
7005
To get composed input from an input method,
7006
use
7007
.PN XmbLookupString
7008
or
7009
.PN XwcLookupString .
7010
.IN "XmbLookupString" "" "@DEF@"
7011
.IN "XwcLookupString" "" "@DEF@"
7012
.sM
7013
.FD 0
7014
int XmbLookupString\^(\^\fIic\fP\^, \fIevent\fP\^, \fIbuffer_return\fP\^, \fIbytes_buffer\fP\^, \fIkeysym_return\fP\^, \fIstatus_return\fP\^)
7015
.br
7016
XIC \fIic\fP\^;
7017
.br
7018
XKeyPressedEvent *\fIevent\fP;
7019
.br
7020
char *\fIbuffer_return\fP\^;
7021
.br
7022
int \fIbytes_buffer\fP\^;
7023
.br
7024
KeySym *\fIkeysym_return\fP\^;
7025
.br
7026
Status *\fIstatus_return\fP\^;
7027
.FN
7028
.FD 0
7029
int XwcLookupString\^(\^\fIic\fP\^, \fIevent\fP\^, \fIbuffer_return\fP\^, \fIbytes_buffer\fP\^, \fIkeysym_return\fP\^, \fIstatus_return\fP\^)
7030
.br
7031
XIC \fIic\fP\^;
7032
.br
7033
XKeyPressedEvent *\fIevent\fP\^;
7034
.br
7035
wchar_t *\fIbuffer_return\fP\^;
7036
.br
7037
int \fIwchars_buffer\fP\^;
7038
.br
7039
KeySym *\fIkeysym_return\fP\^;
7040
.br
7041
Status *\fIstatus_return\fP\^;
7042
.FN
7043
.IP \fIic\fP 1i
7044
Specifies the input context.
7045
.ds Ev key event to be used
7046
.IP \fIevent\fP 1i
7047
Specifies the \*(Ev.
7048
.IP \fIbuffer_return\fP 1i
7049
Returns a multibyte string or wide character string (if any)
7050
from the input method.
7051
.IP \fIbytes_buffer\fP 1i
7052
.br
7053
.ns
7054
.IP \fIwchars_buffer\fP 1i
7055
Specifies space available in the return buffer.
7056
.IP \fIkeysym_return\fP 1i
7057
Returns the KeySym computed from the event if this argument is not NULL.
7058
.IP \fIstatus_return\fP 1i
7059
Returns a value indicating what kind of data is returned.
7060
.LP
7061
.eM
7062
The
7063
.PN XmbLookupString
7064
and
7065
.PN XwcLookupString
7066
functions return the string from the input method specified
7067
in the buffer_return argument.
7068
If no string is returned,
7069
the buffer_return argument is unchanged.
7070
.LP
7071
The KeySym into which the KeyCode from the event was mapped is returned
7072
in the keysym_return argument if it is non-NULL and the status_return
7073
argument indicates that a KeySym was returned.
7074
If both a string and a KeySym are returned,
7075
the KeySym value does not necessarily correspond to the string returned.
7076
.LP
7077
.PN XmbLookupString
7078
returns the length of the string in bytes, and
7079
.PN XwcLookupString
7080
returns the length of the string in characters.
7081
Both
7082
.PN XmbLookupString
7083
and
7084
.PN XwcLookupString
7085
return text in the encoding of the locale bound to the input method
7086
of the specified input context.
7087
.LP
7088
Each string returned by
7089
.PN XmbLookupString
7090
and
7091
.PN XwcLookupString
7092
begins in the initial state of the encoding of the locale
7093
(if the encoding of the locale is state-dependent).
7094
.NT
7095
To insure proper input processing,
7096
it is essential that the client pass only
7097
.PN KeyPress
7098
events to
7099
.PN XmbLookupString
7100
and
7101
.PN XwcLookupString .
7102
Their behavior when a client passes a
7103
.PN KeyRelease
7104
event is undefined.
7105
.NE
7106
.LP
7107
Clients should check the status_return argument before
7108
using the other returned values.
7109
These two functions both return a value to status_return
7110
that indicates what has been returned in the other arguments.
7111
The possible values returned are:
7112
.TS
7113
lw(1.5i) lw(4.3i).
7114
T{
7115
.PN XBufferOverflow
7116
T} T{
7117
The input string to be returned is too large for the supplied buffer_return.
7118
The required size
7119
.Pn ( XmbLookupString
7120
in bytes;
7121
.PN XwcLookupString
7122
in characters) is returned as the value of the function,
7123
and the contents of buffer_return and keysym_return are not modified.
7124
The client should recall the function with the same event
7125
and a buffer of adequate size to obtain the string.
7126
T}
7127
T{
7128
.PN XLookupNone
7129
T} T{
7130
No consistent input has been composed so far.
7131
The contents of buffer_return and keysym_return are not modified,
7132
and the function returns zero.
7133
T}
7134
T{
7135
.PN XLookupChars
7136
T} T{
7137
Some input characters have been composed.
7138
They are placed in the buffer_return argument,
7139
and the string length is returned as the value of the function.
7140
The string is encoded in the locale bound to the input context.
7141
The content of the keysym_return argument is not modified.
7142
T}
7143
T{
7144
.PN XLookupKeySym
7145
T} T{
7146
A KeySym has been returned instead of a string
7147
and is returned in keysym_return.
7148
The content of the buffer_return argument is not modified,
7149
and the function returns zero.
7150
T}
7151
T{
7152
.PN XLookupBoth
7153
T} T{
7154
Both a KeySym and a string are returned;
7155
.PN XLookupChars
7156
and
7157
.PN XLookupKeySym
7158
occur simultaneously.
7159
T}
7160
.TE
7161
.LP
7162
It does not make any difference if the input context passed as an argument to
7163
.PN XmbLookupString
7164
and
7165
.PN XwcLookupString
7166
is the one currently in possession of the focus or not.
7167
Input may have been composed within an input context before it lost the focus,
7168
and that input may be returned on subsequent calls to
7169
.PN XmbLookupString
7170
or
7171
.PN XwcLookupString
7172
even though it does not have any more keyboard focus.
7173
.NH 3
7174
Input Method Conventions
7175
.XS
7176
\*(SN Input Method Conventions
7177
.XE
7178
.LP
7179
The input method architecture is transparent to the client.
7180
However, clients should respect a number of conventions in order
7181
to work properly.
7182
Clients must also be aware of possible effects of synchronization
7183
between input method and library in the case of a remote input server.
7184
.NH 4
7185
Client Conventions
7186
.XS
7187
\*(SN Client Conventions
7188
.XE
7189
.LP
7190
A well-behaved client (or toolkit) should first query the input method style.
7191
If the client cannot satisfy the requirements of the supported styles
7192
(in terms of geometry management or callbacks),
7193
it should negotiate with the user continuation of the program
7194
or raise an exception or error of some sort.
7195
.NH 4
7196
Synchronization Conventions
7197
.XS
7198
\*(SN Synchronization Conventions
7199
.XE
7200
.LP
7201
A
7202
.PN KeyPress
7203
event with a KeyCode of zero is used exclusively as a
7204
signal that an input method has composed input that can be returned by
7205
.PN XmbLookupString
7206
or
7207
.PN XwcLookupString .
7208
No other use is made of a
7209
.PN KeyPress
7210
event with KeyCode of zero.
7211
.LP
7212
Such an event may be generated by either a front-end
7213
or a back-end input method in an implementation-dependent manner.
7214
Some possible ways to generate this event include:
7215
.IP \(bu 5
7216
A synthetic event sent by an input method server
7217
.IP \(bu 5
7218
An artificial event created by a input method filter and pushed
7219
onto a client's event queue
7220
.IP \(bu 5
7221
A
7222
.PN KeyPress
7223
event whose KeyCode value is modified by an input method filter
7224
.LP
7225
When callback support is specified by the client,
7226
input methods will not take action unless they explicitly
7227
called back the client and obtained no response
7228
(the callback is not specified or returned invalid data).
7229
.NH 2
7230
String Constants
7231
.XS
7232
\*(SN String Constants
7233
.XE
7234
.LP
7235
The following symbols for string constants are defined in
7236
.hN X11/Xlib.h .
7237
Although they are shown here with particular macro definitions,
7238
they may be implemented as macros, as global symbols, or as a
7239
mixture of the two. The string pointer value itself
7240
is not significant; clients must not assume that inequality of two
7241
values implies inequality of the actual string data.
7242
.IN "XNVaNestedList" "" "@DEF@"
7243
.IN "XNSeparatorofNestedList "" "@DEF@"
7244
.IN "XNQueryInputStyle" "" "@DEF@"
7245
.IN "XNClientWindow" "" "@DEF@"
7246
.IN "XNInputStyle" "" "@DEF@"
7247
.IN "XNFocusWindow" "" "@DEF@"
7248
.IN "XNResourceName" "" "@DEF@"
7249
.IN "XNResourceClass" "" "@DEF@"
7250
.IN "XNGeometryCallback" "" "@DEF@"
7251
.IN "XNDestroyCallback" "" "@DEF@"
7252
.IN "XNFilterEvents" "" "@DEF@"
7253
.IN "XNPreeditStartCallback" "" "@DEF@"
7254
.IN "XNPreeditDoneCallback" "" "@DEF@"
7255
.IN "XNPreeditDrawCallback" "" "@DEF@"
7256
.IN "XNPreeditCaretCallback" "" "@DEF@"
7257
.IN "XNPreeditStateNotifyCallback" "" "@DEF@"
7258
.IN "XNPreeditAttributes" "" "@DEF@"
7259
.IN "XNStatusStartCallback" "" "@DEF@"
7260
.IN "XNStatusDoneCallback" "" "@DEF@"
7261
.IN "XNStatusDrawCallback" "" "@DEF@"
7262
.IN "XNStatusAttributes" "" "@DEF@"
7263
.IN "XNArea" "" "@DEF@"
7264
.IN "XNAreaNeeded" "" "@DEF@"
7265
.IN "XNSpotLocation" "" "@DEF@"
7266
.IN "XNColormap" "" "@DEF@"
7267
.IN "XNStdColormap" "" "@DEF@"
7268
.IN "XNForeground" "" "@DEF@"
7269
.IN "XNBackground" "" "@DEF@"
7270
.IN "XNBackgroundPixmap" "" "@DEF@"
7271
.IN "XNFontSet" "" "@DEF@"
7272
.IN "XNLineSpace" "" "@DEF@"
7273
.IN "XNCursor" "" "@DEF@"
7274
.TS
7275
lw(.5i) lw(2.75i) lw(2.5i).
7276
T{
7277
#define
7278
T} T{
7279
.PN XNVaNestedList
7280
T} T{
7281
"XNVaNestedList"
7282
T}
7283
T{
7284
#define
7285
T} T{
7286
.PN XNSeparatorofNestedList
7287
T} T{
7288
"separatorofNestedList"
7289
T}
7290
T{
7291
#define
7292
T} T{
7293
.PN XNQueryInputStyle
7294
T} T{
7295
"queryInputStyle"
7296
T}
7297
T{
7298
#define
7299
T} T{
7300
.PN XNClientWindow
7301
T} T{
7302
"clientWindow"
7303
T}
7304
T{
7305
#define
7306
T} T{
7307
.PN XNInputStyle
7308
T} T{
7309
"inputStyle"
7310
T}
7311
T{
7312
#define
7313
T} T{
7314
.PN XNFocusWindow
7315
T} T{
7316
"focusWindow"
7317
T}
7318
T{
7319
#define
7320
T} T{
7321
.PN XNResourceName
7322
T} T{
7323
"resourceName"
7324
T}
7325
T{
7326
#define
7327
T} T{
7328
.PN XNResourceClass
7329
T} T{
7330
"resourceClass"
7331
T}
7332
T{
7333
#define
7334
T} T{
7335
.PN XNGeometryCallback
7336
T} T{
7337
"geometryCallback"
7338
T}
7339
T{
7340
#define
7341
T} T{
7342
.PN XNDestroyCallback
7343
T} T{
7344
"destroyCallback"
7345
T}
7346
T{
7347
#define
7348
T} T{
7349
.PN XNFilterEvents
7350
T} T{
7351
"filterEvents"
7352
T}
7353
T{
7354
#define
7355
T} T{
7356
.PN XNPreeditStartCallback
7357
T} T{
7358
"preeditStartCallback"
7359
T}
7360
T{
7361
#define
7362
T} T{
7363
.PN XNPreeditDoneCallback
7364
T} T{
7365
"preeditDoneCallback"
7366
T}
7367
T{
7368
#define
7369
T} T{
7370
.PN XNPreeditDrawCallback
7371
T} T{
7372
"preeditDrawCallback"
7373
T}
7374
T{
7375
#define
7376
T} T{
7377
.PN XNPreeditCaretCallback
7378
T} T{
7379
"preeditCaretCallback"
7380
T}
7381
T{
7382
#define
7383
T} T{
7384
.PN XNPreeditStateNotifyCallback
7385
T} T{
7386
"preeditStateNotifyCallback"
7387
T}
7388
T{
7389
#define
7390
T} T{
7391
.PN XNPreeditAttributes
7392
T} T{
7393
"preeditAttributes"
7394
T}
7395
.TE
7396
.sp -1
7397
.TS
7398
lw(.5i) lw(2.75i) lw(2.5i).
7399
T{
7400
#define
7401
T} T{
7402
.PN XNStatusStartCallback
7403
T} T{
7404
"statusStartCallback"
7405
T}
7406
T{
7407
#define
7408
T} T{
7409
.PN XNStatusDoneCallback
7410
T} T{
7411
"statusDoneCallback"
7412
T}
7413
T{
7414
#define
7415
T} T{
7416
.PN XNStatusDrawCallback
7417
T} T{
7418
"statusDrawCallback"
7419
T}
7420
T{
7421
#define
7422
T} T{
7423
.PN XNStatusAttributes
7424
T} T{
7425
"statusAttributes"
7426
T}
7427
T{
7428
#define
7429
T} T{
7430
.PN XNArea
7431
T} T{
7432
"area"
7433
T}
7434
T{
7435
#define
7436
T} T{
7437
.PN XNAreaNeeded
7438
T} T{
7439
"areaNeeded"
7440
T}
7441
T{
7442
#define
7443
T} T{
7444
.PN XNSpotLocation
7445
T} T{
7446
"spotLocation"
7447
T}
7448
T{
7449
#define
7450
T} T{
7451
.PN XNColormap
7452
T} T{
7453
"colorMap"
7454
T}
7455
T{
7456
#define
7457
T} T{
7458
.PN XNStdColormap
7459
T} T{
7460
"stdColorMap"
7461
T}
7462
T{
7463
#define
7464
T} T{
7465
.PN XNForeground
7466
T} T{
7467
"foreground"
7468
T}
7469
T{
7470
#define
7471
T} T{
7472
.PN XNBackground
7473
T} T{
7474
"background"
7475
T}
7476
T{
7477
#define
7478
T} T{
7479
.PN XNBackgroundPixmap
7480
T} T{
7481
"backgroundPixmap"
7482
T}
7483
T{
7484
#define
7485
T} T{
7486
.PN XNFontSet
7487
T} T{
7488
"fontSet"
7489
T}
7490
T{
7491
#define
7492
T} T{
7493
.PN XNLineSpace
7494
T} T{
7495
"lineSpace"
7496
T}
7497
T{
7498
#define
7499
T} T{
7500
.PN XNCursor
7501
T} T{
7502
"cursor"
7503
T}
7504
.TE
7505
.sp -1
7506
.TS
7507
lw(.5i) lw(2.75i) lw(2.5i).
7508
T{
7509
#define
7510
T} T{
7511
.PN XNQueryIMValuesList
7512
T} T{
7513
"queryIMValuesList"
7514
T}
7515
T{
7516
#define
7517
T} T{
7518
.PN XNQueryICValuesList
7519
T} T{
7520
"queryICValuesList"
7521
T}
7522
T{
7523
#define
7524
T} T{
7525
.PN XNStringConversionCallback
7526
T} T{
7527
"stringConversionCallback"
7528
T}
7529
T{
7530
#define
7531
T} T{
7532
.PN XNStringConversion
7533
T} T{
7534
"stringConversion"
7535
T}
7536
T{
7537
#define
7538
T} T{
7539
.PN XNResetState
7540
T} T{
7541
"resetState"
7542
T}
7543
T{
7544
#define
7545
T} T{
7546
.PN XNHotKey
7547
T} T{
7548
"hotkey"
7549
T}
7550
T{
7551
#define
7552
T} T{
7553
.PN XNHotKeyState
7554
T} T{
7555
"hotkeyState"
7556
T}
7557
T{
7558
#define
7559
T} T{
7560
.PN XNPreeditState
7561
T} T{
7562
"preeditState"
7563
T}
7564
T{
7565
#define
7566
T} T{
7567
.PN XNVisiblePosition
7568
T} T{
7569
"visiblePosition"
7570
T}
7571
T{
7572
#define
7573
T} T{
7574
.PN XNR6PreeditCallbackBehavior
7575
T} T{
7576
"r6PreeditCallback"
7577
T}
7578
.TE
7579
.sp -1
7580
.IN "XNQueryIMValuesList" "" "@DEF@"
7581
.IN "XNQueryICValuesList" "" "@DEF@"
7582
.IN "XNStringConversionCallback" "" "@DEF@"
7583
.IN "XNStringConversion" "" "@DEF@"
7584
.IN "XNResetState" "" "@DEF@"
7585
.IN "XNHotKey" "" "@DEF@"
7586
.IN "XNHotKeyState" "" "@DEF@"
7587
.IN "XNPreeditState" "" "@DEF@"
7588
.IN "XNVisiblePosition" "" "@DEF@"
7589
.IN "XNR6PreeditCallbackBehavior" "" "@DEF@"
7590
.TS
7591
lw(.5i) lw(2.75i) lw(2.5i).
7592
T{
7593
#define
7594
T} T{
7595
.PN XNRequiredCharSet
7596
T} T{
7597
"requiredCharSet"
7598
T}
7599
T{
7600
#define
7601
T} T{
7602
.PN XNQueryOrientation
7603
T} T{
7604
"queryOrientation"
7605
T}
7606
T{
7607
#define
7608
T} T{
7609
.PN XNDirectionalDependentDrawing
7610
T} T{
7611
"directionalDependentDrawing"
7612
T}
7613
T{
7614
#define
7615
T} T{
7616
.PN XNContextualDrawing
7617
T} T{
7618
"contextualDrawing"
7619
T}
7620
T{
7621
#define
7622
T} T{
7623
.PN XNBaseFontName
7624
T} T{
7625
"baseFontName"
7626
T}
7627
T{
7628
#define
7629
T} T{
7630
.PN XNMissingCharSet
7631
T} T{
7632
"missingCharSet"
7633
T}
7634
T{
7635
#define
7636
T} T{
7637
.PN XNDefaultString
7638
T} T{
7639
"defaultString"
7640
T}
7641
T{
7642
#define
7643
T} T{
7644
.PN XNOrientation
7645
T} T{
7646
"orientation"
7647
T}
7648
T{
7649
#define
7650
T} T{
7651
.PN XNFontInfo
7652
T} T{
7653
"fontInfo"
7654
T}
7655
T{
7656
#define
7657
T} T{
7658
.PN XNOMAutomatic
7659
T} T{
7660
"omAutomatic"
7661
T}
7662
.TE
7663
.IN "XNRequiredCharSet" "" "@DEF@"
7664
.IN "XNQueryOrientation" "" "@DEF@"
7665
.IN "XNDirectionalDependentDrawing" "" "@DEF@"
7666
.IN "XNContextualDrawing" "" "@DEF@"
7667
.IN "XNBaseFontName" "" "@DEF@"
7668
.IN "XNMissingCharSet" "" "@DEF@"
7669
.IN "XNDefaultString" "" "@DEF@"
7670
.IN "XNOrientation" "" "@DEF@"
7671
.IN "XNFontInfo" "" "@DEF@"
7672
.IN "XNOMAutomatic" "" "@DEF@"
7673
.bp
Loggerhead is a web-based interface for Breezy
Version: 2.0.1