⟦608fa79fa⟧

TextFile

\&
.sp 1
.ce 3
\s+1\fBChapter 13\fP\s-1

\s+1\fBLocales and Internationalized Text Functions\fP\s-1
.sp 2
.nr H1 13
.nr H2 0
.nr H3 0
.nr H4 0
.nr H5 0
.na
.LP
.XS
Chapter 13: Locales and Internationalized Text Functions
.XE
An internationalized application is one which is adaptable to the requirements
of different native languages, local customs, and character string encodings.
The process of adapting the operation to a particular native language,
local custom, or string encoding is called localizaton.
A goal of internationalization is to permit localization
without program source modifications or recompilation.
.LP
Internationalization in X is based on the concept of a \fIlocale\fP.
A locale defines the ``localized'' behavior of a program at run-time.
Locales affect Xlib in its:
.IP \(bu 5
Encoding and processing of input method text
.IP \(bu 5
Encoding of resource files and values
.IP \(bu 5
Encoding and imaging of text strings
.IP \(bu 5
Encoding and decoding for inter-client text communication
.LP
Characters from various languages are represented in a computer
using an encoding.
Different languages have different encodings,
and there are even different encodings for the same characters
in the same language.
.LP
This chapter defines support for localized text imaging and text input,
and the locale mechanism which controls all locale-dependent Xlib functions.
Sets of functions are provided for multibyte (char *) text as well as
wide character (wchar_t) text in the form supported
by the host C language environment.
The multibyte and wide character functions
are equivalent except for the form of the text argument.
.LP
The Xlib internationalization functions are not meant to provide
support for multilingual applications (mixing multiple languages
within a single piece of text), but they make it possible to
implement applications that work in limited fashion with more than
one language in independent contexts.
.NH 2
X Locale Management
.XS
\*(SN X Locale Management
.XE
.LP
X supports a one or more of the locales defined by the host environment.
On implementations that conform to the ANSI C library,
the locale announcement method is
.PN setlocale .
This function configures the locale operation of both
the host C library and Xlib.
The operation of Xlib is governed by the LC_CTYPE category;
this is called the \fIcurrent locale\fP.
An implementation is permitted to provide implementation-dependent
mechanisms for announcing the locale in addition to
.PN setlocale .
.LP
On implementations that do not conform to the ANSI C library,
the locale announcement method is Xlib implementation-dependent.
.LP
The mechanism by which the semantic operation of Xlib is defined
for a specific locale is implementation-dependent.
.LP
.sp
X is not required to support all the locales supported by the host.
To determine if the current locale is supported by X,
use
.PN XSupportsLocale .
.IN "XSupportsLocale" "" "@DEF@"
.\" Start marker code here
.FD 0
Bool XSupportsLocale\^(\|)
.FN
.\" End marker code here
.LP
The
.PN XSupportsLocale
function returns
.PN True
if Xlib functions are capable of operating under the current locale.
If it returns
.PN False ,
Xlib locale-dependent functions for which the
.PN XLocaleNotSupported
return status is defined will return
.PN XLocaleNotSupported .
Other Xlib locale-dependent routines will operate in the ``C'' locale.
.LP
The client is responsible for selecting its locale and X modifiers.
Clients should provide a means for the user to override the clients'
locale selection at client invocation.
Most single-display X clients operate in a single locale
for both X and the host processing environment.
They will configure the locale by calling three functions:
the host locale configuration function,
.PN XSupportsLocale ,
and
.PN XSetLocaleModifiers .
.LP
The semantics of certain categories of X internationalization capabilities
can be configured by setting modifiers.
Modifiers are named by implementation-dependent and locale-specific strings.
The only standard use for this capability at present
is selecting one of several styles of keyboard input method.
.LP
.sp
To configure Xlib locale modifiers for the current locale, use
.PN XSetLocaleModifiers .
.IN "XSetLocaleModifiers" "" "@DEF@"
.\" Start marker code here
.FD 0
char *XSetLocaleModifiers\^(\^\fImodifier_list\fP\^)
.br
char *\fImodifier_list\fP\^;
.FN
.IP \fImodifier_list\fP 1i
Specifies the modifiers.
.\" End marker code here
.LP
.PN XSetLocaleModifiers
sets the X modifiers for the current locale setting.
The modifier_list argument is a null-terminated string of the form
``{@\^\fIcategory\fP\^=\^\fIvalue\fP\^}'', that is,
having zero or more concatenated ``@\^\fIcategory\fP\^=\^\fIvalue\fP\^''
entries where \fIcategory\fP is a category name
and \fIvalue\fP is the (possibly empty) setting for that category.
The values are encoded in the current locale.
Category names are restricted to the POSIX Portable Filename Character Set.
.LP
The local host X locale modifiers announcer (on POSIX-compliant systems,
the XMODIFIERS environment variable) is appended to the modifier_list to
provide default values on the local host.
If a given category appears more than once in the list,
the first setting in the list is used.
If a given category is not included in the full modifier list,
the category is set to an implementation-dependent default for the current locale.
An empty value for a category explicitly specifies the
implementation-dependent default.
.LP
If the function is successful, it returns a pointer to a string. The contents
of the string are such that a subsequent call with that string (in the same
locale) will restore the modifiers to the same settings. If modifier_list is
a NULL pointer,
.PN XSetLocaleModifiers
also returns a pointer to such a string,
and the current locale modifiers are not changed.
.LP
If invalid values are given for one or more modifier categories supported by
the locale, a NULL pointer is returned, and none of the
current modifiers are changed.
.LP
At program startup the modifiers that are in effect are unspecified until
the first successful call to set them. Whenever the locale is changed, the
modifiers that are in effect become unspecified until the next successful call
to set them.
Clients should always call
.PN XSetLocaleModifiers
with a non-NULL modifier_list after setting the locale,
before they call any locale-dependent Xlib routine.
.LP
The only standard modifier category currently defined is ``im'',
which identifies the desired input method.
The values for input method are not standardized.
A single locale may use multiple input methods,
switching input method under user control.
The modifier may specify the initial input method in effect,
or an ordered list of input methods.
Multiple input methods may be specified in a single im value string
in an implementation-dependent manner.
.LP
The returned modifiers string is owned by Xlib and should not be modified or
freed by the client.
It may be freed by Xlib after the current locale or modifiers is changed.
Until freed, it will not be modified by Xlib.
.LP
The recommended procedure for clients initializing their locale and modifiers
is to obtain locale and modifier announcers separately from
one of the following prioritized sources:
.IP \(bu 5
A command line option
.IP \(bu 5
A resource
.IP \(bu 5
The empty string ("")
.LP
The first of these that is defined should be used.
Note that when a locale command line option or locale resource is defined,
the effect should be to set all categories to the specified locale,
overriding any category-specific settings in the local host environment.
.NH 2
Locale and Modifier Dependencies
.XS
\*(SN Locale and Modifier Dependencies
.XE
.LP
The internationalized Xlib functions operate in the current locale
configured by the host environment and X locale modifiers set by
.PN XSetLocaleModifiers ,
or in the locale and modifiers configured at the time
some object supplied to the function was created.
For each locale-dependent function,
the following table describes the locale (and modifiers) dependency:
.TS H
lw(1.25i) lw(2.5i) lw(2i).
_
.sp 6p
.B
locale from... Affects the function... in the...
.sp 6p
_
.sp 6p
.TH
.R
Locale Query/Configuration:
.sp 6p
T{
.PN setlocale
T} T{
.PN XSupportsLocale
T} T{
locale queried
T}
T{
.PN XSetLocaleModifiers
T} T{
locale modified
T}
.sp
Resources:
.sp 6p
T{
.PN setlocale
T} T{
.PN XrmGetFileDatabase
T} T{
locale of
.PN XrmDatabase
T}
T{
.PN XrmGetStringDatabase
T}
T{
.PN XrmDatabase
T} T{
.PN XrmPutFileDatabase
T} T{
locale of
.PN XrmDatabase
T}
T{
.PN XrmLocaleOfDatabase
T}
.sp
Setting Standard Properties:
.sp 6p
T{
.PN setlocale
T} T{
.PN XmbSetWMProperties
T} T{
encoding of supplied/returned
T}
text (some WM_ property
text in environment locale)
.sp 6p
T{
.PN setlocale
T} T{
.PN XmbTextPropertyToTextList
T} T{
encoding of supplied/returned text
T}
T{
.PN XwcTextPropertyToTextList
T}
T{
.PN XmbTextListToTextProperty
T}
T{
.PN XwcTextListToTextProperty
T}
.sp
Text Input:
.sp 6p
T{
.PN setlocale
T} T{
.PN XOpenIM
T} T{
XIM input method selection
T}
T{
.PN XIM
T} T{
.PN XCreateIC
T} T{
XIC input method configuration
T}
T{
.PN XLocaleOfIM ,
etc.
T} T{
queried locale
T}
T{
.PN XIC
T} T{
.PN XmbLookupText
T} T{
keyboard layout,
T}
T{
.PN XwcLookupText
T} T{
encoding of returned text
T}
.sp
Text Drawing:
.sp 6p
T{
.PN setlocale
T} T{
.PN XCreateFontSet
T} T{
charsets of fonts in
.PN XFontSet
T}
T{
.PN XFontSet
T} T{
.PN XmbDrawText ,
T} T{
locale of supplied text,
T}
T{
.PN XwcDrawText ,
etc.
T} T{
locale of supplied text,
T}
T{
.PN XExtentsOfFontSet ,
etc.
T} T{
locale-dependent metrics
T}
T{
.PN XmbTextExtents ,
T}
T{
.PN XwcTextExtents ,
etc.
T}
.sp
Xlib Errors:
.sp 6p
T{
.PN setlocale
T} T{
.PN XGetErrorDatabaseText
T} T{
locale of error message
T}
T{
.PN XGetErrorText
T}
.sp 6p
_
.TE
.LP
Clients may assume that a locale-encoded text string returned
by an X routine can be passed to a C-library routine, or vice-versa,
if the locale is the same at the two calls.
.LP
All text strings processed by internationalized Xlib functions are assumed
to begin in the initial state of the encoding of the locale, if the encoding
is state-dependent.
.LP
All Xlib routines behave as if they do not change the current locale
or X modifier setting.
(This means that if they do change locale or call
.PN XSetLocaleModifiers
with a non-NULL argument, they must save and restore the current state on
entry and exit.)
Also, Xlib functions on implementations that conform to the ANSI C library do
not alter the global state associated with the ANSI C functions
.PN mblen ,
.PN mbtowc ,
.PN wctomb ,
and
.PN strtok .
.NH 2
Creating and Freeing a Font Set
.XS
\*(SN Creating and Freeing a Font Set
.XE
.LP
Xlib international text drawing is done using a set of one or more fonts,
as needed for the locale of the text.
Fonts are loaded according to a list of base font names
supplied by the client, and the charsets required by the locale.
The
.PN XFontSet
is an opaque type.
.LP
.sp
To create an international text drawing font set, use
.PN XCreateFontSet .
.IN "XCreateFontSet" "" "@DEF@"
.\" Start marker code here
.FD 0
XFontSet XCreateFontSet\^(\^\fIdisplay\fP\^, \fIbase_font_name_list\fP\^, \fImissing_charset_list_return\fP\^,
.br
\fImissing_charset_count_return\fP\^, \fIdef_string_return\fP\^)
.br
Display *\fIdisplay\fP\^;
.br
char *\fIbase_font_name_list\fP\^;
.br
char ***\fImissing_charset_list_return\fP\^;
.br
int *\fImissing_charset_count_return\fP\^;
.br
char **\fIdef_string_return\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIbase_font_name_list\fP 1i
Specifies the base font names.
.IP \fImissing_charset_list_return\fP 1i
Returns the missing charsets.
.IP \fImissing_charset_count_return\fP 1i
Returns the number of missing charsets.
.IP \fIdef_string_return\fP 1i
Returns the string drawn for missing charsets.
.\" End marker code here
.LP
The
.PN XCreateFontSet
function creates a font set for the specified display.
The font set is bound to the current locale when
.PN XCreateFontSet
is called.
The font_set may be used in subsequent calls to obtain font
and character information, and to image text in the locale of the font_set.
.LP
The base_font_name_list argument is a list of base font names which Xlib uses
to load the fonts needed for the locale.
The base font names are a comma-separated list. The string is null-terminated,
and is assumed to be in the Host Portable Character Encoding;
otherwise, the result is implementation dependent.
Whitespace immediately on either side of a separating comma is ignored.
.LP
Use of XLFD font names permits Xlib to obtain the fonts needed for a
variety of locales from a single locale-independent base font name.
The single base font name should name a family of fonts whose members
are encoded in the various charsets needed by the locales of interest.
.LP
An XLFD base font name can explicitly name a charset needed for the locale.
This allows the user to specify an exact font for use with a charset required
by a locale, fully controlling the font selection.
.LP
If a base font name is not an XLFD name,
Xlib will attempt to obtain an XLFD name from the font properties
for the font.
If this action is successful in obtaining an XLFD name, the
.PN XBaseFontNameListOfFontSet
function will return this XLFD name instead of the client-supplied name.
.LP
The following algorithm is used to select the fonts that will be used to
display text with the
.PN XFontSet :
.LP
For each font charset required by the locale,
the base font name list is searched for the first one
of the following cases that names a set of fonts that exist at the server:
.IP 1. 5
The first XLFD-conforming base font name that specifies the required
charset or a superset of the required charset in its
.PN CharSetRegistry
and
.PN CharSetEncoding
fields.
The implementation may use a base font name whose specified charset
is a superset of the required charset, for example,
an ISO8859-1 font for an ASCII charset.
.IP 2. 5
The first set of one or more XLFD-conforming base font names
that specify one or more charsets that can be remapped to support the
required charset.
The Xlib implementation may recognize various mappings
from a required charset to one or more other charsets,
and use the fonts for those charsets.
For example, JIS Roman is ASCII with tilde and backslash replaced
by yen and overbar;
Xlib may load an ISO8859-1 font to support this character set,
if a JIS Roman font is not available.
.IP 3. 5
The first XLFD-conforming font name, or the first non-XLFD font name
for which an XLFD font name can be obtained, combined with the
required charset (replacing the
.PN CharSetRegistry
and
.PN CharSetEncoding
fields in the XLFD font name).
As in case 1,
the implementation may use a charset which is a superset
of the required charset.
.IP 4. 5
The first font name that can be mapped in some implementation-dependent
manner to one or more fonts that support imaging text in the charset.
.LP
For example, assume a locale required the charsets:
.LP
.Ds 0
ISO8859-1
JISX0208.1983
JISX0201.1976
GB2312-1980.0
.De
.LP
The user could supply a base_font_name_list which explicitly specifies the
charsets, insuring that specific fonts get used if they exist:
.LP
.Ds 0
"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240-JISX0208.1983-0,\\
-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120-JISX0201.1976-0,\\
-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240-GB2312-1980.0,\\
-Adobe-Courier-Bold-R-Normal--25-180-75-75-M-150-ISO8859-1"
.De
.LP
Or he could supply a base_font_name_list which omits the charsets,
letting Xlib select font charsets required for the locale:
.LP
.Ds 0
"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\
-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120,\\
-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\
-Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150"
.De
.LP
Or he could simply supply a single base font name which allows Xlib
to select from all available fonts which meet certain minimum XLFD
property requirements:
.LP
.Ds 0
"-*-*-*-R-Normal--*-180-100-100-*-*"
.De
.LP
If
.PN XCreateFontSet
is unable to create the font set,
either because there is insufficient memory or because the current locale
is not supported,
.PN XCreateFontSet
returns NULL, missing_charset_list_return is set to NULL,
and missing_charset_count_return
is set to zero.
If fonts exist for all of the charsets required by the current locale,
.PN XCreateFontSet
returns a valid
.PN XFontSet ,
missing_charset_list_return is set to NULL,
and missing_charset_count_return is set to zero.
.LP
If no font exists for one or more of the required charsets,
.PN XCreateFontSet
sets missing_charset_list_return to a
list of one or more null-terminated charset names for which no font exists,
and sets missing_charset_count_return to the number of missing fonts.
The charsets are from the list of the required charsets for
the encoding of the locale, and do not include any charsets to which Xlib
may be able to remap a required charset.
.LP
If no font exists for any of the required charsets,
or if the locale definition in Xlib requires that a font exist
for a particular charset and a font is not found for that charset,
.PN XCreateFontSet
returns NULL.
Otherwise,
.PN XCreateFontSet
returns a valid
.PN XFontSet
to font_set.
.LP
When an Xmb/wc drawing or measuring function is called with an
.PN XFontSet
that has missing charsets, some characters in the locale will not be
drawable.
If def_string_return is non-NULL,
.PN XCreateFontSet
returns a pointer to a string which represents the glyph(s)
which are drawn with this
.PN XFontSet
when the charsets of the available fonts do not include all font glyph(s)
required to draw a codepoint.
The string does not necessarily consist of valid characters
in the current locale and is not necessarily drawn with
the fonts loaded for the font set,
but the client can draw and measure the ``default glyphs''
by including this string in a string being drawn or measured with the
.PN XFontSet .
.LP
If the string returned to def_string_return is the empty string (""),
no glyphs are drawn, and the escapement is zero.
The returned string is null-terminated.
It is owned by Xlib and should not be modified or freed by the client.
It will be freed by a call to
.PN XFreeFontSet
with the associated
.PN XFontSet .
Until freed, its contents will not be modified by Xlib.
.LP
The client is responsible for constructing an error message from the
missing charset and default string information, and may choose to continue
operation in the case that some fonts did not exist.
.LP
The returned
.PN XFontSet
and missing charset list should be freed with
.PN XFreeFontSet
and
.PN XFreeStringList ,
respectively.
The client-supplied base_font_name_list may be freed
by the client after calling
.PN XCreateFontSet .
.LP
.sp
To obtains a list of
.PN XFontStruct
structures and full font names given an
.PN XFontSet ,
use
.PN XFontsOfFontSet .
.IN "XFontsOfFontSet" "" "@DEF@"
.\" Start marker code here
.FD 0
int XFontsOfFontSet\^(\^\fIfont_set\fP\^, \fIfont_struct_list_return\fP\^, \fIfont_name_list_return\fP\^)
.br
XFontSet \fIfont_set\fP\^;
.br
XFontStruct ***\fIfont_struct_list_return\fP\^;
.br
char ***\fIfont_name_list_return\fP\^;
.FN
.\" $Header: fontset.a,v 1.2 88/05/09 14:28:06 mento Exp $
.IP \fIfont_set\fP 1i
Specifies the font set.
.IP \fIfont_struct_list_return\fP 1i
Returns the list of font structs.
.IP \fIfont_name_list_return\fP 1i
Returns the list of font names.
.\" End marker code here
.LP
The
.PN XFontsOfFontSet
function returns a list of one or more
.PN XFontStructs
and font names for the fonts used by the Xmb and Xwc layers,
for the given font set.
A list of pointers to the
.PN XFontStruct
structures is returned to font_struct_list_return.
A list of pointers to null-terminated fully specified font name strings
in the locale of the font set is returned to font_name_list_return.
The font_name_list order corresponds to the font_struct_list order.
The number of
.PN XFontStruct
structures and font names is returned as the value of the function.
.LP
Because it is not guaranteed that a given character will be imaged using a
single font glyph,
there is no provision for mapping a character or default string
to the font properties, font ID, or direction hint for the font
for the character.
The client may access the
.PN XFontStruct
list to obtain these values for all the fonts currently in use.
.LP
It is not required that fonts be loaded from the server at the creation of an
.PN XFontSet .
Xlib may choose to cache font data, loading it only as needed to draw text
or compute text dimensions.
Therefore, existence of the per_char metrics in the
.PN XFontStruct
structures in the
.PN XFontStructSet
is undefined.
Also, note that all properties in the
.PN XFontStruct
structures are in the STRING encoding.
.LP
The
.PN XFontStruct
and font name lists are owned by Xlib
and should not be modified or freed by the client.
They will be freed by a call to
.PN XFreeFontSet
with the associated
.PN XFontSet .
Until freed, its contents will not be modified by Xlib.
.LP
.sp
To obtain the base font name list and the selected font name list given an
.PN XFontSet ,
use
.PN XBaseFontNameListOfFontSet .
.IN "XBaseFontNameListOfFontSet" "" "@DEF@"
.\" Start marker code here
.FD 0
char *XBaseFontNameListOfFontSet\^(\^\fIfont_set\fP\^)
.br
XFontSet \fIfont_set\fP\^;
.FN
.\" $Header: fontset.a,v 1.2 88/05/09 14:28:06 mento Exp $
.IP \fIfont_set\fP 1i
Specifies the font set.
.\" End marker code here
.LP
The
.PN XBaseFontNameListOfFontSet
function returns the original base font name list supplied
by the client when the
.PN XFontSet
was created.
A null-terminated string containing a list of
comma-separated font names is returned
as the value of the function.
Whitespace may appear immediately on either side of separating commas.
.LP
If
.PN XCreateFontSet
obtained an XLFD name from the font properties for the font specified
by a non-XLFD base name, the
.PN XBaseFontNameListOfFontSet
function will return the XLFD name instead of the non-XLFD base name.
.LP
The base font name list is owned by Xlib and should not be modified or
freed by the client.
It will be freed by a call to
.PN XFreeFontSet
with the associated
.PN XFontSet .
Until freed, its contents will not be modified by Xlib.
.LP
.sp
To obtain the locale name given an
.PN XFontSet ,
use
.PN XLocaleOfFontSet .
.IN "XLocaleOfFontSet" "" "@DEF@"
.\" Start marker code here
.FD 0
char *XLocaleOfFontSet\^(\^\fIfont_set\fP\^)
.br
XFontSet \fIfont_set\fP\^;
.FN
.\" $Header: fontset.a,v 1.2 88/05/09 14:28:06 mento Exp $
.IP \fIfont_set\fP 1i
Specifies the font set.
.\" End marker code here
.LP
The
.PN XLocaleOfFontSet
function
returns the name of the locale bound to the specified
.PN XFontSet ,
as a null-terminated string.
.LP
The returned locale name string is owned by Xlib
and should not be modified or freed by the client.
It may be freed by a call to
.PN XFreeFontSet
with the associated
.PN XFontSet .
Until freed, it will not be modified by Xlib.
.LP
.sp
To free a font set, use
.PN XFreeFontSet .
.IN "XFreeFontSet" "" "@DEF@"
.\" Start marker code here
.FD 0
void XFreeFontSet\^(\^\fIdisplay\fP\^, \fIfont_set\fP\^)
.br
Display *\fIdisplay\fP\^;
.br
XFontSet \fIfont_set\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: fontset.a,v 1.2 88/05/09 14:28:06 mento Exp $
.IP \fIfont_set\fP 1i
Specifies the font set.
.\" End marker code here
.LP
The
.PN XFreeFontSet
function frees the specified font set.
The associated base font name list, font name list,
.PN XFontStruct
list, and
.PN XFontSetExtents ,
if any, are freed.
.NH 2
Obtaining Font Set Metrics
.XS
\*(SN Obtaining Font Set Metrics
.XE
.LP
Metrics for the internationalized text drawing functions
are defined in terms of a primary draw direction,
which is the default direction in which the character origin advances
for each succeeding character in the string.
The Xlib interface is currently defined to support only a left-to-right
primary draw direction.
The drawing origin is the position passed to the drawing function
when the text is drawn.
The baseline is a line drawn through the drawing origin parallel
to the primary draw direction.
Character ink is the pixels painted in the foreground color
and does not include interline or intercharacter spacing
or image text background pixels.
.LP
The drawing functions are allowed to implement implicit text
directionality control, reversing the order in which characters are
rendered along the primary draw direction in response to locale-specific
lexical analysis of the string.
.LP
Regardless of the character rendering order,
the origins of all characters are on the primary draw direction side
of the drawing origin.
The screen location of a particular character image may be determined with
.PN XmbTextPerCharExtents
or
.PN XwcTextPerCharExtents .
.LP
The drawing functions are allowed to implement context-dependent
rendering, where the glyphs drawn for a string are not simply a
concatenation of the glyphs that represent each individual character.
A string of two characters drawn with
.PN XmbDrawString
may render differently than if the two characters
were drawn with separate calls to
.PN XmbDrawString.
If the client appends or inserts a character
in a previously drawn string,
the client may need to redraw some adjacent characters
in order to obtain proper rendering.
.LP
.sp
To find out about context-dependent rendering, use
.PN XContextDependentDrawing .
.IN "XContextDependentDrawing" "" "@DEF@"
.\" Start marker code here
.FD 0
Bool XContextDependentDrawing\^(\^\fIfont_set\fP\^)
.br
XFontSet \fIfont_set\fP\^;
.FN
.\" $Header: fontset.a,v 1.2 88/05/09 14:28:06 mento Exp $
.IP \fIfont_set\fP 1i
Specifies the font set.
.\" End marker code here
.LP
The
.PN XContextDependentDrawing
function returns
.PN True
if text drawn with the font_set might include context-dependent drawing.
.LP
The drawing functions do not interpret newline, tab, or other control
characters.
The behavior when non-printing characters other than space are drawn
is implementation-dependent.
It is the client's responsibility to interpret control characters
in a text stream.
.LP
The maximum character extents for the fonts that are used by the text
drawing layers may be accessed by the
.PN XFontSetExtents
structure:
.IN "XFontSetExtents" "" "@DEF@"
.LP
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct {
XRectangle max_ink_extent; /* over all drawable characters */
XRectangle max_logical_extent; /* over all drawable characters */
} XFontSetExtents;
.De
.LP
The
.PN XRectangles
used to return font set metrics are the usual Xlib screen-oriented
.PN XRectangles ,
with x, y giving the upper left corner, and width and height always positive.
.LP
The max_ink_extent member gives the maximum extent, over all drawable characters, of
the rectangles which bound the character glyph image drawn in the
foreground color, relative to a constant origin.
See
.PN XmbTextExtents
and
.PN XwcTextExtents
for detailed semantics.
.LP
The max_logical_extent member gives the maximum extent,
over all drawable characters, of the rectangles
which specify minimum spacing to other graphical features,
relative to a constant origin.
Other graphical features drawn by the client, for example,
a border surrounding the text, should not intersect this rectangle.
The max_logical_extent member should be used to compute minimum
inter-line spacing and the minimum area which must be allowed
in a text field to draw a given number of arbitrary characters.
.LP
Due to context-dependent rendering,
appending a given character to a string may increase
the string's extent by an amount which exceeds the font's max extent:
.LP
.Ds 0
max possible added extent = (max_extent * <total # chars>) \- prev_string_extent
.De
.LP
The rectangles for a given character in a string can be obtained from
.PN XmbPerCharExtents
or
.PN XwcPerCharExtents .
.LP
.sp
To obtain the maximum extents structure given an
.PN XFontSet ,
use
.PN XExtentsOfFontSet .
.IN "XExtentsOfFontSet" "" "@DEF@"
.\" Start marker code here
.FD 0
XFontSetExtents *XExtentsOfFontSet\^(\^\fIfont_set\fP\^)
.br
XFontSet \fIfont_set\fP\^;
.FN
.\" $Header: fontset.a,v 1.2 88/05/09 14:28:06 mento Exp $
.IP \fIfont_set\fP 1i
Specifies the font set.
.\" End marker code here
.LP
The
.PN XExtentsOfFontSet
function returns an
.PN XFontSetExtents
structure for the fonts used by the Xmb and Xwc layers,
for the given font set.
.LP
The
.PN XFontSetExtents
structure is owned by Xlib and should not be modified
or freed by the client.
It will be freed by a call to
.PN XFreeFontSet
with the associated
.PN XFontSet .
Until freed, its contents will not be modified by Xlib.
.LP
.sp
To obtain the escapement in pixels of the specified text as a value,
use
.PN XmbTextEscapement
or
.PN XwcTextEscapement .
.IN "XmbTextEscapement" "" "@DEF@"
.IN "XwcTextEscapement" "" "@DEF@"
.\" Start marker code here
.FD 0
int XmbTextEscapement\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^)
.br
XFontSet \fIfont_set\fP\^;
.br
char *\fIstring\fP\^;
.br
int \fInum_bytes\fP\^;
.FN
.FD 0
int XwcTextEscapement\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^)
.br
XFontSet \fIfont_set\fP\^;
.br
wchar_t *\fIstring\fP\^;
.br
int \fInum_wchars\fP\^;
.FN
.\" $Header: fontset.a,v 1.2 88/05/09 14:28:06 mento Exp $
.IP \fIfont_set\fP 1i
Specifies the font set.
.\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
.IP \fIstring\fP 1i
Specifies the character string.
.IP \fInum_bytes\fP 1i
Specifies the number of bytes in the string argument.
.IP \fInum_wchars\fP 1i
Specifies the number of characters in the string argument.
.\" End marker code here
.LP
The
.PN XmbTextEscapement
and
.PN XwcTextEscapement
functions return the escapement in pixels of the specified string as a value,
using the fonts loaded for the specified font set.
The escapement is the distance in pixels in the primary draw
direction from the drawing origin to the origin of the next character to
be drawn, assuming that the rendering of the next character is not
dependent on the supplied string.
.LP
Regardless of the character rendering order,
the escapement is always positive.
.LP
.sp
To obtain the overall_ink_return and overall_logical_return arguments,
the overall bounding box of the string's image, and a logical bounding box,
use
.PN XmbTextExtents
or
.PN XwcTextExtents .
.IN "XmbTextExtents" "" "@DEF@"
.IN "XwcTextExtents" "" "@DEF@"
.\" Start marker code here
.FD 0
int XmbTextExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^, \fIoverall_return\fP\^)
.br
XFontSet \fIfont_set\fP\^;
.br
char *\fIstring\fP\^;
.br
int \fInum_bytes\fP\^;
.br
XRectangle *\fIoverall_ink_return\fP\^;
.br
XRectangle *\fIoverall_logical_return\fP\^;
.FN
.FD 0
int XwcTextExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^, \fIoverall_return\fP\^)
.br
XFontSet \fIfont_set\fP\^;
.br
wchar_t *\fIstring\fP\^;
.br
int \fInum_wchars\fP\^;
.br
XRectangle *\fIoverall_ink_return\fP\^;
.br
XRectangle *\fIoverall_logical_return\fP\^;
.FN
.\" $Header: fontset.a,v 1.2 88/05/09 14:28:06 mento Exp $
.IP \fIfont_set\fP 1i
Specifies the font set.
.\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
.IP \fIstring\fP 1i
Specifies the character string.
.IP \fInum_bytes\fP 1i
Specifies the number of bytes in the string argument.
.IP \fInum_wchars\fP 1i
Specifies the number of characters in the string argument.
.ds Ov dimensions
.IP \fIoverall_ink_return\fP 1i
Returns the overall ink \*(Ov.
.IP \fIoverall_logical_return\fP 1i
Returns the overall logical \*(Ov.
.\" End marker code here
.LP
The
.PN XmbTextExtents
and
.PN XwcTextExtents
functions set the components of the specified overall_ink_return and
overall_logical_return
arguments to the overall bounding box of the string's image,
and a logical bounding box for spacing purposes, respectively.
They return the value returned by
.PN XmbTextEscapement
or
.PN XwcTextEscapement .
These metrics are relative to the drawing origin of the string,
using the fonts loaded for the specified font set.
.LP
If the overall_ink_return argument is non-NULL,
it is set to the bounding box of the string's character ink.
Note that the overall_ink_return for a non-descending horizontally drawn
Latin character is conventionally entirely above the baseline, that is,
overall_ink_return.height <= -overall_ink_return.y.
The overall_ink_return for a nonkerned character
is entirely at and to the right of the origin, that is,
overall_ink_return.x >= 0.
A character consisting of a single pixel at the origin
would set overall_ink_return fields y = 0, x = 0, width = 1, height = 1.
.LP
If the overall_logical_return argument is non-NULL,
it is set to the bounding box which provides minimum spacing
to other graphical features for the string.
Other graphical features, for example, a border surrounding the text,
should not intersect this rectangle.
.LP
When the
.PN XFontSet
has missing charsets,
metrics for each unavailable character are taken
from the default string returned by
.PN XCreateFontSet
so that the metrics represent the text as it will actually be drawn.
The behavior for an invalid codepoint is undefined.
.LP
To determine the effective drawing origin for a character in a drawn string,
the client should call
.PN XmbTextPerCharExtents
on the entire string, then on the character,
and subtract the x values of the returned
.PN XRectangles
for the character.
This is useful to redraw portions of a line of text
or to justify words, but for context-dependent rendering
the client should not assume that it can redraw the character by itself
and get the same rendering.
.LP
.sp
To obtain per-character information for a text string,
use
.PN XmbTextPerCharExtents
or
.PN XwcTextPerCharExtents .
.IN "XmbTextPerCharExtents" "" "@DEF@"
.IN "XwcTextPerCharExtents" "" "@DEF@"
.\" Start marker code here
.FD 0
Status XmbTextPerCharExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^, \fIink_array_return\fP\^,
.br
\fIlogical_array_return\fP\^, \fIarray_size\fP\^, \fInum_chars_return\fP\^, \fIoverall_return\fP\^)
.br
XFontSet \fIfont_set\fP\^;
.br
char *\fIstring\fP\^;
.br
int \fInum_bytes\fP\^;
.br
XRectangle *\fIink_array_return\fP\^;
.br
XRectangle *\fIlogical_array_return\fP\^;
.br
int \fIarray_size\fP\^;
.br
int *\fInum_chars_return\fP\^;
.br
XRectangle *\fIoverall_ink_return\fP\^;
.br
XRectangle *\fIoverall_logical_return\fP\^;
.FN
.FD 0
Status XwcTextPerCharExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^, \fIink_array_return\fP\^,
.br
\fIlogical_array_return\fP\^, \fIarray_size\fP\^, \fInum_chars_return\fP\^, \fIoverall_return\fP\^)
.br
XFontSet \fIfont_set\fP\^;
.br
wchar_t *\fIstring\fP\^;
.br
int \fInum_wchars\fP\^;
.br
XRectangle *\fIink_array_return\fP\^;
.br
XRectangle *\fIlogical_array_return\fP;
.br
int \fIarray_size\fP\^;
.br
int *\fInum_chars_return\fP\^;
.br
XRectangle *\fIoverall_ink_return\fP\^;
.br
XRectangle *\fIoverall_logical_return\fP\^;
.FN
.\" $Header: fontset.a,v 1.2 88/05/09 14:28:06 mento Exp $
.IP \fIfont_set\fP 1i
Specifies the font set.
.\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
.IP \fIstring\fP 1i
Specifies the character string.
.IP \fInum_bytes\fP 1i
Specifies the number of bytes in the string argument.
.IP \fInum_wchars\fP 1i
Specifies the number of characters in the string argument.
.IP \fIink_array_return\fP 1i
Returns the ink dimensions for each character.
.IP \fIlogical_array_return\fP 1i
Returns the logical dimensions for each character.
.IP \fIarray_size\fP 1i
Specifies the size of ink_array_return and logical_array_return.
Note that the caller must pass in arrays of this size.
.IP \fInum_chars_return\fP 1i
Returns the number characters in the string argument.
.ds Ov extents of the entire string
.IP \fIoverall_ink_return\fP 1i
Returns the overall ink \*(Ov.
.IP \fIoverall_logical_return\fP 1i
Returns the overall logical \*(Ov.
.\" End marker code here
.LP
The
.PN XmbTextPerCharExtents
and
.PN XwcTextPerCharExtents
return the text dimensions of each character of the specified text,
using the fonts loaded for the specified font set.
Each successive element of ink_array_return and logical_array_return
is set to the successive character's drawn metrics,
relative to the drawing origin of the string, one
.PN XRectangle
for each character in the supplied text string.
The number of elements of ink_array_return and logical_array_return
that have been set is returned to num_chars_return.
.LP
Each element of ink_array_return is set to the bounding box
of the corresponding character's drawn foreground color.
Each element of logical_array_return is set to the bounding box
which provides minimum spacing to other graphical features
for the corresponding character.
Other graphical features should not intersect any of the
logical_array_return rectangles.
.LP
Note that an
.PN XRectangle
represents the effective drawing dimensions of the character,
regardless of the number of font glyphs that are used to draw
the character, or the direction in which the character is drawn.
If multiple characters map to a single character glyph,
the dimensions of all the
.PN XRectangles
of those characters are the same.
.LP
When the
.PN XFontSet
has missing charsets, metrics for each unavailable
character are taken from the default string returned by
.PN XCreateFontSet ,
so that the metrics represent the text as it will actually be drawn.
The behavior for an invalid codepoint is undefined.
.LP
If the array_size is too small for the number of characters in the
supplied text, the functions return zero
and num_chars_return is set to the number of rectangles required.
Otherwise, the routines return a non-zero value.
.LP
If the overall_ink_return or overall_logical_return argument is non-NULL,
.PN XmbTextPerCharExtents
and
.PN XwcTextPerCharExtents
return the maximum extent of the string's metrics to overall_ink_return
or overall_logical_return, as returned by
.PN XmbTextExtents
or
.PN XwcTextExtents .
.NH 2
Drawing Text Using Font Sets
.XS
\*(SN Drawing Text Using Font Sets
.XE
.LP
The routines defined in this section
draw text at a specified location in a drawable.
They are similar to the functions
.PN XDrawText ,
.PN XDrawString ,
and
.PN XDrawImageString
except that they work with font sets instead of single fonts,
and interpret the text based on the locale of the font set
instead of treating the bytes of the string as direct font indexes.
See section 8.6 for details of the use of GCs and possible protocol errors.
If a
.PN BadFont
error is generated,
characters prior to the offending character may have been drawn.
.LP
The text is drawn using the fonts loaded for the specified font set;
the font in the GC is ignored, and may be modified by the routines.
No validation that all fonts conform to some width rule is performed.
.LP
The text functions
.PN XmbDrawText
and
.PN XwcDrawText
use the following structures.
.IN "XmbTextItem" "" "@DEF@"
.\" Start marker code here
.Ds 0
.TA .5i 2.5i
.ta .5i 2.5i
typedef struct {
char *chars; /* pointer to string */
int nchars; /* number of characters */
int delta; /* pixel delta between strings */
XFontSet font_set; /* fonts, None means don't change */
} XmbTextItem;
.De
.LP
.IN "XwcTextItem" "" "@DEF@"
.Ds 0
.TA .5i 2.5i
.ta .5i 2.5i
typedef struct {
wchar_t *chars; /* pointer to wide char string */
int nchars; /* number of wide characters */
int delta; /* pixel delta between strings */
XFontSet font_set; /* fonts, None means don't change */
} XwcTextItem;
.De
.\" End marker code here
.LP
.sp
To draw text using multiple font sets in a given drawable, use
.PN XmbDrawText
or
.PN XwcDrawText .
.IN "XmbDrawText" "" "@DEF@"
.IN "XwcDrawText" "" "@DEF@"
.\" Start marker code here
.FD 0
void XmbDrawText\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^)
.br
Display *\fIdisplay\fP\;
.br
Drawable \fId\fP\^;
.br
GC \fIgc\fP\^;
.br
int \fIx\fP\^, \fIy\fP\^;
.br
XmbTextItem *\fIitems\fP\^;
.br
int \fInitems\fP\^;
.FN
.FD 0
void XwcDrawText\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^)
.br
Display *\fIdisplay\fP\^;
.br
Drawable \fId\fP\^;
.br
GC \fIgc\fP\^;
.br
int \fIx\fP\^, \fIy\fP\^;
.br
XwcTextItem *\fIitems\fP\^;
.br
int \fInitems\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
.IP \fId\fP 1i
Specifies the drawable.
.\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
.IP \fIgc\fP 1i
Specifies the GC.
.ds Xy
.\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
.IP \fIx\fP 1i
.br
.ns
.IP \fIy\fP 1i
Specify the x and y coordinates\*(Xy.
.\" $Header: items.a,v 1.1 88/02/26 10:28:21 mento Exp $
.IP \fIitems\fP 1i
Specifies an array of text items.
.\" $Header: nitems.a,v 1.1 88/02/26 10:29:33 mento Exp $
.IP \fInitems\fP 1i
Specifies the number of text items in the array.
.\" End marker code here
.LP
.PN XmbDrawText
and
.PN XwcDrawText
allow complex spacing and font set shifts between text strings.
Each text item is processed in turn, with the origin of a text
element advanced in the primary draw direction by the escapement of the
previous text item.
A text item delta specifies an additional escapement of the text item
drawing origin in the primary draw direction.
A font_set member other than
.PN None
in an item causes the font set to be used for this and subsequent text items
in the text_items list.
Leading text items with font_set member set to
.PN None
will not be drawn.
.LP
.PN XmbDrawText
and
.PN XwcDrawText
do not perform any context-dependent rendering between text segments.
Clients may compute the drawing metrics by passing each text segment to
.PN XmbTextExtents
and XwcTextExtents
or
.PN XmbTextPerCharExtents
and
.PN XwcTextPerCharExtents .
When the
.PN XFontSet
has missing charsets, each unavailable character is drawn
with the default string returned by
.PN XCreateFontSet .
The behavior for an invalid codepoint is undefined.
.LP
.sp
To draw text using a single font set in a given drawable, use
.PN XmbDrawString
or
.PN XwcDrawString .
.IN "XmbDrawString" "" "@DEF@"
.IN "XwcDrawString" "" "@DEF@"
.\" Start marker code here
.FD 0
void XmbDrawString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^)
.br
Display *\fIdisplay\fP\^;
.br
Drawable \fId\fP\^;
.br
XFontSet \fIfont_set\fP\^;
.br
GC \fIgc\fP\^;
.br
int \fIx\fP\^, \fIy\fP\^;
.br
char *\fIstring\fP\^;
.br
int \fInum_bytes\fP\^;
.FN
.FD 0
void XwcDrawString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^)
.br
Display *\fIdisplay\fP\^;
.br
Drawable \fId\fP\^;
.br
XFontSet \fIfont_set\fP\^;
.br
GC \fIgc\fP\^;
.br
int \fIx\fP\^, \fIy\fP\^;
.br
wchar_t *\fIstring\fP\^;
.br
int \fInum_wchars\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
.IP \fId\fP 1i
Specifies the drawable.
.\" $Header: fontset.a,v 1.2 88/05/09 14:28:06 mento Exp $
.IP \fIfont_set\fP 1i
Specifies the font set.
.\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
.IP \fIgc\fP 1i
Specifies the GC.
.ds Xy
.\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
.IP \fIx\fP 1i
.br
.ns
.IP \fIy\fP 1i
Specify the x and y coordinates\*(Xy.
.\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
.IP \fIstring\fP 1i
Specifies the character string.
.IP \fInum_bytes\fP 1i
Specifies the number of bytes in the string argument.
.IP \fInum_wchars\fP 1i
Specifies the number of characters in the string argument.
.\" End marker code here
.LP
.PN XmbDrawString
and
.PN XwcDrawString
draw the specified text with the foreground pixel.
When the
.PN XFontSet
has missing charsets, each unavailable character is drawn
with the default string returned by
.PN XCreateFontSet .
The behavior for an invalid codepoint is undefined.
.LP
.sp
To draw image text using a single font set in a given drawable, use
.PN XmbDrawImageString
or
.PN XwcDrawImageString .
.IN "XmbDrawImageString" "" "@DEF@"
.IN "XwcDrawImageString" "" "@DEF@"
.\" Start marker code here
.FD 0
void XmbDrawImageString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^)
.br
Display *\fIdisplay\fP\^;
.br
Drawable \fId\fP\^;
.br
XFontSet \fIfont_set\fP\^;
.br
GC \fIgc\fP\^;
.br
int \fIx\fP\^, \fIy\fP\^;
.br
char *\fIstring\fP\^;
.br
int \fInum_bytes\fP\^;
.FN
.FD 0
void XwcDrawImageString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^)
.br
Display *\fIdisplay\fP\^;
.br
Drawable \fId\fP\^;
.br
XFontSet \fIfont_set\fP\^;
.br
GC \fIgc\fP\^;
.br
int \fIx\fP\^, \fIy\fP\^;
.br
wchar_t *\fIstring\fP\^;
.br
int \fInum_wchars\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: d.a,v 1.1 88/02/26 10:04:25 mento Exp $
.IP \fId\fP 1i
Specifies the drawable.
.\" $Header: fontset.a,v 1.2 88/05/09 14:28:06 mento Exp $
.IP \fIfont_set\fP 1i
Specifies the font set.
.\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
.IP \fIgc\fP 1i
Specifies the GC.
.ds Xy
.\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
.IP \fIx\fP 1i
.br
.ns
.IP \fIy\fP 1i
Specify the x and y coordinates\*(Xy.
.\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
.IP \fIstring\fP 1i
Specifies the character string.
.IP \fInum_bytes\fP 1i
Specifies the number of bytes in the string argument.
.IP \fInum_wchars\fP 1i
Specifies the number of characters in the string argument.
.\" End marker code here
.LP
.PN XmbDrawImageString
and
.PN XwcDrawImageString
fill a destination rectangle with the background pixel defined in the GC
and then paint the text with the foreground pixel.
The filled rectangle is the rectangle returned to overall_logical_return by
.PN XmbTextExtents
or
.PN XwcTextExtents
for the same text and
.PN XFontSet .
.LP
When the
.PN XFontSet
has missing charsets, each unavailable character is drawn
with the default string returned by
.PN XCreateFontSet .
The behavior for an invalid codepoint is undefined.
.NH 2
Input Method Overview
.XS
\*(SN Input Method Overview
.XE
.LP
This section provides definitions for terms and concepts used
for internationalized text input and a brief overview of the
intended use of the mechanisms provided by Xlib.
.LP
A large number of languages in the world use alphabets
consisting of a small set of symbols (letters) to form words.
To enter text into a computer in an alphabetic language,
a user usually has a keyboard on which there exists key symbols corresponding
to the alphabet.
Sometimes, a few characters of an alphabetic language are missing
on the keyboard.
Many computer users, who speak a Latin alphabet based language
only have a English-based keyboard.
They need to hit a combination of keystrokes in order
to enter a character that does not exist directly on the keyboard.
A number of algorithms have been developed for entering such characters,
known as European input methods, the compose input method,
or the dead-keys input method.
.LP
Japanese is an example of a language with a phonetic symbol set,
where each symbol represents a specific sound.
There are two phonetic symbol sets in Japanese: Katakana and Hiragana.
In general,
Katakana is used for words that are of foreign origin,
and hiragana for writing native Japanese words.
Collectively, the two systems are called Kana.
Each set consists of 48 characters.
.LP
Korean also has a phonetic symbol set, called Hangul.
Each of the 24 basic phonetic symbols (14 consonants and 10 vowels)
represents a specific sound.
A syllable is composed of two or three parts:
the initial consonants, the vowels, and the optional last consonants.
With Hangul,
syllables can be treated as the basic units on which text processing is done.
For example,
a delete operation may work on a phonetic symbol or a syllable.
Korean code sets include several thousands of these syllables.
A user types the phonetic symbols that make up the syllables of the words
to be entered.
The display may change as each phonetic symbol is entered.
For example,
when the second phonetic symbol of a syllable is entered,
the first phonetic symbol may change its shape and size.
Likewise, when the third phonetic symbol is entered,
the first two phonetic symbols may change their shape and size.
.LP
Not all languages rely solely on alphabetic or phonetic systems.
Some languages, including Japanese and Korean, employ an
ideographic writing system.
In an ideographic system, rather than taking a small set of
symbols and combining them in different ways to create words,
each word consists of one unique symbol (or, occasionally, several symbols).
The number of symbols may be very large:
approximately 50,000 have been identified in Hanzi,
the Chinese ideographic system.
.LP
There are two major aspects of ideographic systems for their computer
usage.
First, the standard computer character sets in Japan, China, and Korea
include roughly 8,000 characters,
while sets in Taiwan have between 15,000 and 30,000 characters,
which make it necessary to use more than one byte to represent a character.
Second, it obviously is impractical to have a keyboard that includes
all of a given language's ideographic symbols.
Therefore a mechanism is required for entering characters
so that a keyboard with a reasonable number of keys can be used.
Those input methods are usually based on phonetics,
but there also exist methods based on the graphical properties of
characters.
.LP
In Japan, both Kana and Kanji are used.
In Korea, Hangul and sometimes Hanja are used.
Now consider entering ideographs in Japan, Korea, China, and Taiwan.
.LP
In Japan, either Kana or English characters are typed and then a region
is selected (sometimes automatically) for conversion to Kanji.
Several Kanji characters may have the same phonetic representation.
If that is the case with the string entered,
a menu of characters is presented and
the user must choose the appropriate one.
If no choice is necessary or a preference has been established,
the input method does the substitution directly.
When Latin characters are converted to Kana or Kanji,
it is called a romaji conversion.
.LP
In Korea, it is usually acceptable to keep Korean text in Hangul form,
but some people may choose to write Hanja-originated words in Hanja
rather than in Hangul.
To change Hangul to Hanja,
a region is selected for conversion
and then the same basic method as described for Japanese is followed.
.LP
Probably because there are well-accepted phonetic writing systems
for Japanese and Korean,
computer input methods in these countries for entering ideographs
are fairly standard.
Keyboard keys have both English characters and phonetic symbols
engraved on them, and the user can switch between the two sets.
.LP
The situation is different for Chinese.
While there is a phonetic system called Pinyin promoted by authorities,
there is no consensus for entering Chinese text.
Some vendors use a phonetic decomposition (Pinyin or another),
others use ideographic decomposition of Chinese words,
with various implementations and keyboard layouts.
There are about 16 known methods, none of which is a clear standard.
.LP
Also, there are actually two ideographic sets used:
Traditional Chinese (the original written Chinese)
and Simplified Chinese.
Several years ago,
the People's Republic Of China launched a campaign to simplify
some ideographic characters and eliminate redundancies altogether.
Under the plan,
characters would be streamlined every five years.
Characters have been revised several times now,
resulting in the smaller, simpler set that makes up Simplified Chinese.
.NH 3
Input Method Architecture
.XS
\*(SN Input Method Architecture
.XE
.LP
As shown in the previous section,
there are many different input methods in use today,
each varying with language, culture, and history.
A common feature of many input methods is that the user may type
multiple keystrokes in order to compose a single character (or set
of characters).
The process of composing characters from keystrokes is called
\fIpreediting\fP.
It may require complex algorithms and large dictionaries
involving substantial computer resources.
.LP
Input methods may require one or more areas in which to show the
feedback of the actual keystrokes, to propose disambiguation to the
user, to list dictionaries, and so on.
The input method areas of concern are as follows.
.IP \(bu 5
The \fIStatus\fP area is intended to be a logical extension of the
LEDs that exist on the physical keyboard.
It is a window which is intended to present the internal state
of the input method that is critical to the user.
The status area may consist of text data and bitmaps or some combination.
.IP \(bu 5
The \fIPreedit\fP area is intended to display the
intermediate text for those languages that are composing prior to
the client handling the data.
.IP \(bu 5
The \fIAuxiliary\fP area is used for pop-up menus and customizing
dialogs that may be required for an input method.
There may be multiple Auxiliary areas for any input method.
Auxiliary areas are managed by the input method independent of the client.
Auxiliary areas are assumed to be a separate dialog which is maintained
by the input method.
.LP
There are various user interaction styles used for preediting.
The ones supported by Xlib are as follows.
.IP \(bu 5
For \fIon-the-spot\fP input methods,
preediting data will be displayed directly in the application window.
Application data is moved to allow preedit data to be displayed
at the point of insertion.
.IP \(bu 5
\fIOver-the-spot\fP preediting means that the data is displayed in
a preedit window that is placed over the point of insertion.
.IP \(bu 5
\fIOff-the-spot\fP preediting means that the preedit window is
inside the application window but not at the point of insertion.
Often, this type of window is placed at the bottom of the application window.
.IP \(bu 5
\fIRoot-window\fP preediting refers to input methods that use a preedit
window that is the child of
.PN RootWindow .
.LP
It would require a lot of computing resources if portable applications
had to include input methods for all the languages in the world.
To avoid this,
a goal of the Xlib design is to allow an application
to communicate with an input method placed in a separate process.
Such a process is called an \fIinput server\fR.
The server to which the application should connect is dependent on
the environment when the application is started up:
what is the user language, the actual encoding to be used for it.
The input method connection is said to be \fIlocale dependent\fR.
It is also user dependent:
for a given language, the user can choose to some extent
the user interface style of input method (if choice is possible among
several).
.LP
Using an input server implies communication overhead,
but applications can be migrated without relinking.
Input methods can be implemented either as a
stub communicating to an input server or as a local library.
.LP
An input method may be based on a \fIfront-end\fR or a \fIback-end\fR
architecture.
In front-end, there are two separate connections to the X server:
keystrokes go directly from X server to the input method on
one connection, other events to the regular client connection.
The input method is then acting as a filter, and sends composed strings
to the client.
Front-end requires synchronization between the two connections
to avoid lost key events or locking issues.
.LP
In back-end,
a single X server connection is used.
A dispatching mechanism must decide on this channel to delegate appropriate
keystrokes to the input method.
For instance,
it may retain a Help keystroke for its own purpose.
In the case where the input method is a separate process (that is, a server),
there must be a special communication protocol between the back-end client
and the input server.
.LP
Front-end introduces synchronization issues and filtering mechanism
for non-character keystrokes (Functions, Help, and so on).
Back-end sometimes implies more communication overhead and more process
switching.
If all three processes are running on a single workstation
(X server, input server, client),
there are two process switches for each keystroke in back-end,
but there is only one in frontend.
.LP
The abstraction used by a client to communicate with an input method
is an opaque data structure represented by the
.PN XIM
data type.
This data structure is returned by the
.PN XOpenIM
function, which opens an input method on a given display.
Subsequent operations on this data structure encapsulate all communication
between client and input method.
There is no need for an X client to use any networking library
or natural language package in order to use an input method.
.LP
A single input server may be used for one or more languages,
supporting one or more encoding schemes.
But the strings returned from an input method will always be encoded
in the (single) locale associated with
.PN XIM
object.
.NH 3
Input Contexts
.XS
\*(SN Input Contexts
.XE
.LP
Xlib provides the ability to manage a multithreaded state for text input.
A client may be using multiple windows,
each window with multiple text entry areas,
and the user possibly switching among them at any time.
The abstraction for representing state of a particular input thread
is called an \fIinput context\fR.
The Xlib representation of an input context is an
.PN XIC .
.LP
An input context is the abstraction retaining the state, properties,
and semantics of communication between a client and an input method.
An input context is a combination of an input method, a locale
specifying the encoding of the character strings to be returned,
a client window, internal state information
and various layout or appearance characteristics.
The input context concept somewhat matches for input the graphics context
abstraction defined for graphics output.
.LP
One input context belongs to exactly one input method.
Different input contexts may be associated with the same input method,
possibly with the same client window.
An
.PN XIC
is created with the
.PN XCreateIC
function, providing an
.PN XIM
argument,
affiliating the input context to the input method for its lifetime.
When an input method is closed with
.PN XCloseIM ,
all of its affiliated input contexts should not be used any more
(and should preferably be destroyed before closing the input method).
.LP
Considering the example of a client window with multiple text entry areas,
the application programmer could for example choose to implement:
.IP \(bu 5
As many input contexts are created as text entry areas and the client
will get the input accumulated on each context each time it will
lookup that context.
.IP \(bu 5
A single context is created for a top level window in the application.
If such window contains several text entry areas,
each time the user moves to another text entry area,
the client has to indicate changes in the context.
.LP
A range of choices can be made by application designers to use
either a single or multiple input contexts,
according to the needs of their application.
.NH 3
Getting Keyboard Input
.XS
\*(SN Getting Keyboard Input
.XE
.LP
In order to obtain characters from an input method a client must call
the function
.PN XmbLookupString
or
.PN XwcLookupString
with an input context created from that input method.
Both a locale and display are bound to an input method when it is opened,
and an input context inherits this locale and display.
Any strings returned by
.PN XmbLookupString
or
.PN XwcLookupString
will be encoded in that locale.
.NH 3
Focus Management
.XS
\*(SN Focus Management
.XE
.LP
For each text entry area in which the
.PN XmbLookupString
or
.PN XwcLookupString
routines are used there will be an associated input context.
.LP
When the application focus moves to a text entry area,
the application must set the input context focus to the
input context associated with that area.
The input context focus is set by calling
.PN XSetICFocus
with the appropriate input context.
.LP
Also, when the application focus moves out of a text entry area, the
application should unset the focus for the associated input context
by calling
.PN XUnsetICFocus .
As an optimization, if
.PN XSetICFocus
is called successively on two different input contexts,
setting the focus on the second
will automatically unset the focus on the first.
.LP
Note that in order to set and unset the input context focus correctly,
it will be necessary to track application-level focus changes.
Such focus changes do not necessarily correspond to X server focus changes.
.LP
If a single input context
is being used to do input for
multiple text entry areas, it will also be necessary
to set the focus window of the
input context whenever the focus window changes
(see
.PN XNFocusWindow
under
.PN XSetICValues ).
.NH 3
Geometry Management
.XS
\*(SN Geometry Management
.XE
.LP
In most input method architectures
(on-the-spot being the notable exception),
the input method will perform the display of its own data.
In order to provide better visual locality,
it is often desirable to have the input method areas embedded within a client.
In order to do this the client may need to allocate space for an input method.
Xlib provides support that allows the size and position of input method
areas to be provided by a client.
The input method areas that are supported for geometry management
are the Status area and the Preedit area.
.LP
The fundamental concept on which geometry management for input method windows
is based is the proper division of responsibilities between the
client (or toolkit) and the input method.
The division of responsibilities is as follows:
.IP \(bu 5
The client is responsible for the geometry of the input method window.
.IP \(bu 5
The input method is responsible for the contents of the input method window.
.LP
An input method is able to suggest a size to the client,
but it cannot suggest a placement.
Also the input method can only suggest a size.
It does not determine the size,
and it must accept the size it is given.
.LP
Before a client provides geometry management for an input method,
it must determine if geometry management is needed.
The input method indicates the need for geometry management
by setting
.PN XIMPreeditArea
or
.PN XIMStatusArea
in its
.PN XIMStyles
value returned by
.PN XGetIMValues .
When a client has decided that it will provide geometry management
for an input method,
it indicates that decision by setting the
.PN XNInputStyle
value in the
.PN XIC .
.LP
After a client has established with the input method
that it will will do geometry management,
the client must negotiate the geometry with the input method.
The geometry is negotiated by the following steps.
.IP \(bu 5
The client suggests an area to the input method by setting the
.PN XNAreaNeeded
value for that area.
If the client has no constraints
for the input method it either
will not suggest an area or
will set the width and height to zero. Otherwise it will set one of
the values.
.IP \(bu 5
The client will get the XIC value
.PN XNAreaNeeded .
The input method will return its suggested size in this value.
The input method should pay attention to any constraints suggested by the client.
.IP \(bu 5
The client sets the XIC value
.PN XNArea
to inform the input method of the geometry of its window.
The client should try to honor the geometry requested by the input method.
The input method must accept this geometry.
.LP
Clients doing geometry management must be aware that setting other
IC values may affect the geometry desired by an input method.
For example,
.PN XNFontSet
and
.PN XNLineSpacing
may change the geometry desired by the the input method.
.LP
The table of XIC values (see section 13.10)
indicates the values that can cause the desired geometry to change
when they are set.
It is the responsibility of the client to renegotiate the geometry
of the input method window when it is needed.
.LP
In addition,
a geometry management callback is provided
by which an input method can initiate a geometry change.
.NH 3
Event Filtering
.XS
\*(SN Event Filtering
.XE
.LP
A filtering mechanism is provided to allow input methods
to capture X events transparently to clients.
It is expected that toolkits (or clients) using
.PN XmbLookupString
or
.PN XwcLookupString
will call this filter at some point in the event processing mechanism
to make sure that events needed by an input method can be filtered
by that input method.
.LP
If there were no filter,
a client could receive and discard events that are necessary
for the proper functioning of an input method.
The following provides a few examples of such events:
.IP \(bu 5
Expose events on preedit window in local mode.
.IP \(bu 5
Events may be used by an input method to communicate with an input server.
Such input server protocol related events have to be intercepted
if one does not want to disturb client code.
.IP \(bu 5
Key events can be sent to a filter before they are bound
to translations such as Xt provides.
.LP
Clients are expected to get the XIC value
.PN XNFilterEvents
and augment the event mask for the client window with that event mask.
This mask may be zero.
.NH 3
Callbacks
.XS
\*(SN Callbacks
.XE
.LP
When an on-the-spot input method is implemented,
only the client can insert or delete preedit data in place
and possibly scroll existing text.
This means the echo of the keystrokes has to be achieved
by the client itself, tightly coupled with the input method logic.
.LP
When a keystroke is entered,
the client calls
.PN XmbLookupString
or
.PN XwcLookupString .
At this point, in the on-the-spot case,
the echo of the keystroke in the preedit has not yet been done.
Before returning to the client logic that handles the input characters,
the lookup function
must call the echoing logic for inserting the new keystroke.
If the keystrokes entered so far make up a character,
the keystrokes entered need to be deleted,
and the composed character will be returned.
Hence, what happens is that, while being called by client code,
input method logic has to call back to the client before it returns.
The client code, that is, a callback routine,
is called from the input method logic.
.LP
There are a number of cases where the input method logic has to
call back the client.
Each of those cases is associated with a well-defined callback action.
It is possible for the client to specify, for each input context,
what callback is to be called for each action.
.LP
There are also callbacks provided for feedback of status information
and a callback to initiate a geometry request for an input method.
.NH 2
Variable Argument Lists
.XS
\*(SN Variable Argument Lists
.XE
.LP
Several input method functions have arguments which conform to ANSI C variable
argument list calling convention.
Each function denoted with a ``...'' argument takes
a variable length list of name and value pairs where each name is a
string and each value is of type
.PN XPointer .
The end of the list is identified by a name argument containing NULL.
.LP
A variable length argument list may contain a nested list.
If the name
.PN XVaNestedList
is specified in place of an argument name,
then the following value is interpreted as a
.PN XVaNestedList
value which specifies a list of values logically inserted into the
original list at the point of declaration.
The end of a nested list is identified with a NULL.
.LP
.sp
To allocate a nested variable argument list dynamically, use
.PN XVaCreateNestedList .
.IN "XVaCreateNestedList" "" @DEF@"
.\" Start marker code here
.FD 0
typedef void * XVaNestedList;

XVaNestedList XVaCreateNestedList\^(\^\fIdummy\fP\^, ...)
.br
int \fIdummy\fP\^;
.FN
.IP \fIdummy\fP 1i
Unused argument (required by ANSI C).
.ds Al
.IP ... 1i
Specifies the variable length argument list\*(Al.
.\" End marker code here
.LP
The
.PN XVaCreateNestedList
function allocates memory and copies its arguments into
a single list pointer which may be used as value for arguments
requiring a list value.
Any entries are copied as specified.
Data passed by reference is not copied;
the caller must ensure data remains valid for the lifetime
of the nested list.
The list should be freed using
.PN XFree
when it is no longer needed.
.NH 2
Input Method Functions
.XS
\*(SN Input Method Functions
.XE
.LP
To open a connection, use
.PN XOpenIM .
.IN "XOpenIM" "" "@DEF@"
.\" Start marker code here
.FD 0
XIM XOpenIM\^(\^\fIdisplay\fP\^, \fIdb\fP\^, \fIres_name\fP\^, \fIres_class\fP\^)
.br
Display *\fIdisplay\fP\^;
.br
XrmDataBase \fIdb\fP\^;
.br
char *\fIres_name\fP\^;
.br
char *\fIres_class\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIdb\fP 1i
Specifies a pointer to the resource database.
.IP \fIres_name\fP 1i
Specifies the full resource name of the application.
.IP \fIres_class\fP 1i
Specifies the full class name of the application.
.\" End marker code here
.LP
The
.PN XOpenIM
function opens an input method,
matching the current locale and modifiers specification.
Current locale and modifiers are bound to the input method at opening time.
The locale associated with an input method cannot be changed dynamically.
This implies the strings returned by
.PN XmbLookupString
or
.PN XwcLookupString ,
for any input context affiliated with a given input method,
will be encoded in the locale current at the time input method is opened.
.LP
The specific input method to which this call will be routed
is identified on the basis of the current locale.
.PN XOpenIM
will identify a default input method corresponding to the
current locale.
That default can be modified using
.PN XSetLocaleModifiers
for the input method modifier.
.LP
The db argument is the resource database to be used by the input method
for looking up resources that are private to the input method.
It is not intended that this database be used to look
up values that can be set as IC values in an input context.
If db is NULL,
no data base is passed to the input method.
.LP
The res_name and res_class arguments specify the resource name
and class of the application.
They are intended to be used as prefixes by the input method
when looking up resources that are common to all input contexts
that may be created for this input method.
The characters used for resource names and classes must be in the
X portable character set.
The resources looked up are not fully specified
if res_name or res_class is NULL.
.LP
The res_name and res_class arguments are not assumed to exist beyond
the call to
.PN XOpenIM .
The specified resource database is assumed to exist for the lifetime
of the input method.
.LP
.PN XOpenIM
returns NULL if no input method could be opened.
.LP
.sp
To close a connection, use
.PN XCloseIM .
.IN "XCloseIM" "" "@DEF@"
.\" Start marker code here
.FD 0
Status XCloseIM\^(\^\fIim\fP\^)
.br
XIM \fIim\fP\^;
.FN
.IP \fIim\fP 1i
Specifies the input method.
.\" End marker code here
.LP
The
.PN XCloseIM
function closes the specified input method.
.LP
.sp
To query an input method, use
.PN XGetIMValues .
.IN "XGetIMValues" "" "@DEF@"
.\" Start marker code here
.FD 0
char * XGetIMValues\^(\^\fIim\fP\^, ...)
.br
XIM \fIim\fP\^;
.FN
.IP \fIim\fP 1i
Specifies the input method.
.ds Al \ to get XIM values
.IP ... 1i
Specifies the variable length argument list\*(Al.
.\" End marker code here
.LP
The
.PN XGetIMValues
function presents a variable argument list programming interface
for querying properties or features of the specified input method.
This function returns NULL if it succeeds;
otherwise,
it returns the name of the first argument that could not be obtained.
.LP
Only one standard argument is defined by Xlib:
.PN XNQueryInputStyle ,
which must be used to query about input styles supported by the input method.
.LP
A client should always query the input method to determine which styles
are supported.
The client should then find an input style it is capable of supporting.
.LP
If the client cannot find an input style that it can support
it should negotiate with the user the continuation of the program
(exit, choose another input method, and so on).
.LP
The argument value must be a pointer to a location
where the returned value will be stored.
The returned value is a pointer to a structure of type
.PN XIMStyles .
Clients are responsible for freeing the
.PN XIMStyles
data structure.
To do so, use
.PN XFree .
.LP
The
.PN XIMStyles
structure is defined as follows.
.IN "XIMStyle" "" "@DEF@"
.IN "XIMPreeditArea" "" "@DEF@"
.IN "XIMPreeditCallbacks" "" "@DEF@"
.IN "XIMPreeditPosition" "" "@DEF@"
.IN "XIMPreeditNothing" "" "@DEF@"
.IN "XIMPreeditNone" "" "@DEF@"
.IN "XIMStatusArea" "" "@DEF@"
.IN "XIMStatusCallbacks" "" "@DEF@"
.IN "XIMStatusNothing" "" "@DEF@"
.IN "XIMStatusNone" "" "@DEF@"
.IN "XIMStyles" "" "@DEF@"
.\" Start marker code here
.Ds 0
typedef unsigned long XIMStyle;
.De
.TS
lw(.5i) lw(2i) lw(2.5i).
T{
#define
T} T{
.PN XIMPreeditArea
T} T{
0x0001L
T}
T{
#define
T} T{
.PN XIMPreeditCallbacks
T} T{
0x0002L
T}
T{
#define
T} T{
.PN XIMPreeditPosition
T} T{
0x0004L
T}
T{
#define
T} T{
.PN XIMPreeditNothing
T} T{
0x0008L
T}
T{
#define
T} T{
.PN XIMPreeditNone
T} T{
0x0010L
T}
.sp
T{
#define
T} T{
.PN XIMStatusArea
T} T{
0x0100L
T}
T{
#define
T} T{
.PN XIMStatusCallbacks
T} T{
0x0200L
T}
T{
#define
T} T{
.PN XIMStatusNothing
T} T{
0x0400L
T}
T{
#define
T} T{
.PN XIMStatusNone
T} T{
0x0800L
T}
.TE
.Ds 0
.TA .5i 2.5i
.ta .5i 2.5i
typedef struct {
unsigned short count_styles;
XIMStyle * supported_styles;
} XIMStyles;
.De
.\" End marker code here
.LP
An
.PN XIMStyles
structure contains in its field count_styles,
the number of input styles supported.
This is also the size of the array in the field supported_styles.
.LP
The supported styles is a list of bit mask combinations,
which indicate the combination of styles for each of the areas supported.
These areas are described below.
Each element in the list should select one of the bit mask values for
each area.
The list describes the complete set of combinations supported.
Only these combinations are supported by the input method.
.LP
The Preedit category defines what type of support is provided
by the input method for preedit information:
.IN "XIMPreeditArea" "" "@DEF@"
.IN "XIMPreeditPosition" "" "@DEF@"
.IN "XIMPreeditCallbacks" "" "@DEF@"
.IN "XIMPreeditNothing" "" "@DEF@"
.IN "XIMPreeditNone" "" "@DEF@"
.TS
lw(1.5i) lw(4.25i).
T{
.PN XIMPreeditArea
T} T{
If chosen,
the input method would require the client to provide some area values
for it to do its preediting.
Refer to XIC values
.PN XNArea
and
.PN XNAreaNeeded .
T}
T{
.PN XIMPreeditPosition
T} T{
If chosen,
the input method would require the client to provide positional values.
Refer to XIC values
.PN XNSpotLocation
and
.PN XNFocusWindow .
T}
T{
.PN XIMPreeditCallbacks
T} T{
If chosen,
the input method would require the client to define the set of preedit callbacks.
Refer to XIC values
.PN XNPreeditStartCallback ,
.PN XNPreeditDoneCallback ,
.PN XNPreeditDrawCallback ,
and
.PN XNPreeditCaretCallback .
T}
T{
.PN XIMPreeditNothing
T} T{
If chosen, the input method can function without any Preedit values.
T}
T{
.PN XIMPreeditNone
T} T{
The input method does not provide any Preedit feedback.
Any Preedit value is ignored.
This style is mutually exclusive with the other Preedit styles.
T}
.TE
.LP
The Status category defines what type of support is provided
by the input method for status information:
.IN "XIMStatusArea" "" "@DEF@"
.IN "XIMStatusCallbacks" "" "@DEF@"
.IN "XIMStatusNothing" "" "@DEF@"
.IN "XIMStatusNone" "" "@DEF@"
.TS
lw(1.5i) lw(4.25i).
T{
.PN XIMStatusArea
T} T{
The input method requires the client to provide
some area values for it to do its Status feedback.
See
.PN XNArea
and
.PN XNAreaNeeded .
T}
T{
.PN XIMStatusCallbacks
T} T{
The input method requires the client to define the set of status callbacks;
.PN XNStatusStartCallback ,
.PN XNStatusDoneCallback ,
and
.PN XNStatusDrawCallback .
T}
T{
.PN XIMStatusNothing
T} T{
The input method can function without any Status values.
T}
T{
.PN XIMStatusNone
T} T{
The input method does not provide any Status feedback.
If chosen, any Status value is ignored.
This style is mutually exclusive with the other Status styles.
T}
.TE
.LP
.sp
To obtain the display associated with an input method, use
.PN XDisplayOfIM .
.IN "XDisplayOfIM" "" "@DEF@"
.\" Start marker code here
.FD 0
Display * XDisplayOfIM\^(\^\fIim\fP\^)
.br
XIM \fIim\fP\^;
.FN
.IP \fIim\fP 1i
Specifies the input method.
.\" End marker code here
.LP
The
.PN XDisplayOfIM
function returns the display associated with the specified input method.
.LP
.sp
To get the locale associated with an input method, use
.PN XLocaleOfIM .
.IN "XLocaleOfIM" "" "@DEF@"
.\" Start marker code here
.FD 0
char * XLocaleOfIM\^(\^\fIim\fP\^)
.br
XIM \fIim\fP\^;
.FN
.IP \fIim\fP 1i
Specifies the input method.
.\" End marker code here
.LP
The
.PN XLocaleOfIM
returns the locale associated with the specified input method.
.NH 2
Input Context Functions
.XS
\*(SN Input Context Functions
.XE
.LP
An input context is an abstraction that is used to contain both the data
required (if any) by an input method and the information required
to display that data.
There may be multiple input contexts for one input method.
The programming interfaces for creating, reading, or modifying
an input context use a variable argument list.
The name elements of the argument lists are referred to as XIC values.
It is intended that input methods be controlled by these XIC values.
As new XIC values are created they should be registered
with the X Consortium.
.LP
.sp
To create an input context use
.PN XCreateIC .
.IN "XCreateIC" "" "@DEF@"
.\" Start marker code here
.FD 0
XIC XCreateIC\^(\^\fIim\fP\^, ...)
.br
XIM \fIim\fP\^;
.FN
.IP \fIim\fP 1i
Specifies the input method.
.ds Al \ to set XIC values
.IP ... 1i
Specifies the variable length argument list\*(Al.
.\" End marker code here
.LP
The
.PN XCreateIC
function creates a context within the specified input method.
.LP
Some of the arguments are mandatory at creation time, and
the input context will not be created if they are not provided.
Those arguments are the input style and the set of text callbacks
(if the input style selected requires callbacks).
All other input context values can be set later.
.LP
.PN XCreateIC
returns a NULL value if no input context could be created.
A NULL value could be returned for any of the following reasons:
.IP \(bu 5
A required argument was not set.
.IP \(bu 5
A read-only argument was set (for example,
.PN XNFilterEvents ).
.IP \(bu 5
The argument name is not recognized.
.IP \(bu 5
The input method encountered an input method implementation dependent error.
.LP
.PN XCreateIC
can generate
.PN BadAtom ,
.PN BadColor ,
.PN BadPixmap ,
and
.PN BadWindow
errors.
.LP
.sp
To destroy an input context, use
.PN XDestroyIC .
.IN "XDestroyIC" "" "@DEF@"
.\" Start marker code here
.FD 0
void XDestroyIC\^(\^\fIic\fP\^)
.br
XIC \fIic\fP\^;
.FN
.IP \fIic\fP 1i
Specifies the input context.
.\" End marker code here
.LP
.PN XDestroyIC
destroys the specified input context.
.LP
.sp
To communicate to and synchronize with input method
for any changes in keyboard focus from the client side,
use
.PN XSetICFocus
and
.PN XUnsetICFocus .
.IN "XSetICFocus" "" "@DEF@"
.\" Start marker code here
.FD 0
void XSetICFocus\^(\^\fIic\fP\^)
.br
XIC \fIic\fP\^;
.FN
.IP \fIic\fP 1i
Specifies the input context.
.\" End marker code here
.LP
The
.PN XSetICFocus
function allows a client to notify an input method that the focus window
attached to the specified input context has received keyboard focus.
The input method should take action to provide appropriate feedback.
Complete feedback specification is a matter of user interface policy.
.LP
.sp
.IN "XUnsetICFocus" "" "@DEF@"
.\" Start marker code here
.FD 0
void XUnsetICFocus\^(\^\fIic\fP\^)
.br
XIC \fIic\fP\^;
.FN
.IP \fIic\fP 1i
Specifies the input context.
.\" End marker code here
.LP
The
.PN XUnsetICFocus
function allows a client to notify an input method that the specified input context
has lost the keyboard focus and that no more input is expected on the focus window
attached to that input context.
The input method should take action to provide appropriate feedback.
Complete feedback specification is a matter of user interface policy.
.LP
.sp
To reset the state of an input context to initial state, use
.PN XmbResetIC
or
.PN XwcResetIC .
.IN "XmbResetIC" "" "@DEF@"
.IN "XwcResetIC" "" "@DE@"
.\" Start marker code here
.FD 0
char * XmbResetIC\^(\^\fIic\fP\^)
.br
XIC \fIic\fP\^;
.FN
.FD 0
wchar_t * XwcResetIC\^(\^\fIic\fP\^)
.br
XIC \fIic\fP\^;
.FN
.IP \fIic\fP 1i
Specifies the input context.
.\" End marker code here
.LP
The
.PN XmbResetIC
and
.PN XwcResetIC
functions reset input context to initial state.
Any input pending on that context is deleted.
Input method is required to clear preedit area, if any,
and update status accordingly.
Calling
.PN XmbResetIC
or
.PN XwcResetIC
does not change the focus.
.LP
The return value of
.PN XmbResetIC
is its current preedit string as a multibyte string.
The return value of
.PN XwcResetIC
is its current preedit string as a wide character string.
It is input method implementation dependent whether
these routines return a non-NULL string or NULL.
.LP
The client should free the returned string by calling
.PN XFree .
.LP
.sp
To get the input method associated with an input context, use
.PN XIMOfIC .
.IN "XIMOfIC" "" "@DEF@"
.\" Start marker code here
.FD 0
XIM XIMOfIC\^(\^\fIic\fP\^)
.br
XIC \fIic\fP\^;
.FN
.IP \fIic\fP 1i
Specifies the input context.
.\" End marker code here
.LP
The
.PN XIMOfIC
function returns the input method associated with the specified input context.
.LP
.sp
Xlib provides two functions for setting and reading XIC values, respectively:
.PN XSetICValues
and
.PN XGetICValues .
Both functions have a variable length argument list.
In that argument list, any XIC value's name must be denoted
with a character string using the X Portable Character Set.
.LP
.sp
To set XIC values, use
.PN XSetICValues .
.IN "XSetICValues" "" "@DEF@"
.\" Start marker code here
.FD 0
char * XSetICValues\^(\^\fIic\fP\^, ...)
.br
XIC \fIic\fP\^;
.FN
.IP \fIic\fP 1i
Specifies the input context.
.ds Al \ to set XIC values
.IP ... 1i
Specifies the variable length argument list\*(Al.
.\" End marker code here
.LP
The
.PN XSetICValues
function returns NULL if no error occurred;
otherwise,
it returns the name of the first argument that could not be set.
An argument could be not set for any of the following reasons:
.IP \(bu 5
A read-only argument was set (for example,
.PN XNFilterEvents ).
.IP \(bu 5
The argument name is not recognized.
.IP \(bu 5
The input method encountered an input method implementation dependent error.
.LP
Each value to be set must be an appropriate datum,
matching the data type imposed by the semantics of the argument.
.LP
.PN XSetICValues
can generate
.PN BadAtom ,
.PN BadColor ,
.PN BadCursor ,
.PN BadPixmap ,
and
.PN BadWindow
errors.
.LP
.sp
To obtain XIC values, use
.PN XGetICValues .
.IN "XGetICValues" "" "@DEF@"
.\" Start marker code here
.FD 0
char * XGetICValues\^(\^\fIic\fP\^, ...)
.br
XIC \fIic\fP\^;
.FN
.IP \fIic\fP 1i
Specifies the input context.
.ds Al \ to get XIC values
.IP ... 1i
Specifies the variable length argument list\*(Al.
.\" End marker code here
.LP
The
.PN XGetICValues
function returns NULL if no error occurred; otherwise,
it returns the name of the first argument that could not be obtained.
An argument could be not obtained for any of the following reasons:
.IP \(bu 5
The argument name is not recognized.
.IP \(bu 5
The input method encountered an implementation dependent error.
.LP
Each argument value
(following a name) must point to a location where the value is to be stored.
.PN XGetICValues
allocates memory to store the values, and client is responsible for
freeing each value by calling
.PN XFree .
.NH 2
XIC Value Arguments
.XS
\*(SN XIC Value Arguments
.XE
.LP
The following tables describe how XIC values are interpreted
by an input method depending on the input style chosen by the
user.
.LP
The first column lists the XIC values.
The second column indicates which values are involved in affecting,
negotiating, and setting the geometry of the input method windows.
The subentries under the third column indicate the different
input styles that are supported.
Each of these columns indicates how each of the XIC values
are treated by that input style.
.LP
The following \fBKeys\fR apply to these tables.
.TS H
lw(1i) lw(4.75i).
.sp 6p
.B
Keys Explanation
.sp 6p
.TH
.R
C T{
This value must be set with
.PN XCreateIC .
T}
D T{
This value may be set using
.PN XCreateIC .
If it is not set,
a default is provided.
T}
G T{
This value may be read using
.PN XGetICValues .
T}
GN T{
This value may cause geometry negotiation when its value is set by means of
.PN XCreateIC
or
.PN XSetICValues .
T}
GR T{
This value will be the response of the input method when any
GN value is changed.
T}
GS T{
This value will cause the geometry of the input method window to be set.
T}
O T{
This value must be set once and only once.
It need not be set at create time.
T}
S T{
This value may be set with
.PN XSetICValues .
T}
ignored T{
This value is ignored by the input method for the given input style.
T}
.TE
.LP
.TS H
c c c s s s s
l c c c c c c
c c c c c c c
l c c c c c c.
_
.sp 6p
.B
Input Style
XIC Value Geometry Preedit Preedit Preedit Preedit Preedit
Management Callback Position Area Nothing None
.sp 6p
_
.sp 6p
.TH
.R
Input Style C-G C-G C-G C-G C-G
Client Window O-G O-G O-G ignored ignored
Focus Window GN D-S-G D-S-G D-S-G D-S-G ignored
Resource Name ignored D-S-G D-S-G D-S-G ignored
Resource Class ignored D-S-G D-S-G D-S-G ignored
Geometry Callback ignored ignored D-S-G ignored ignored
FilterEvents G G G G ignored
.sp 6p
\fBPreedit\fP
Area GS ignored D-S-G D-S-G ignored ignored
AreaNeeded GN-GR ignored ignored S-G ignored ignored
SpotLocation ignored C-S-G ignored ignored ignored
Colormap ignored D-S-G D-S-G D-S-G ignored
Foreground ignored D-S-G D-S-G D-S-G ignored
Background ignored D-S-G D-S-G D-S-G ignored
Background Pixmap ignored D-S-G D-S-G D-S-G ignored
FontSet GN ignored C-S-G C-S-G D-S-G ignored
LineSpacing GN ignored D-S-G D-S-G D-S-G ignored
Cursor ignored D-S-G D-S-G D-S-G ignored
Preedit Callbacks C-S-G ignored ignored ignored ignored
.sp 6p
_
.TE
.TS H
c c c s s s
l c c c c c
c c c c c c
l c c c c c.
_
.sp 6p
.B
Input Style
XIC Value Geometry Status Status Status Status
Management Callback Area Nothing None
.sp 6p
_
.sp 6p
.TH
.R
Input Style C-G C-G C-G C-G
Client Window O-G O-G O-G ignored
Focus Window GN D-S-G D-S-G D-S-G ignored
Resource Name ignored D-S-G D-S-G ignored
Resource Class ignored D-S-G D-S-G ignored
Geometry Callback ignored D-S-G ignored ignored
FilterEvents G G G G
.sp 6p
\fBStatus\fR
Area GS ignored D-S-G ignored ignored
AreaNeeded GN-GR ignored S-G ignored ignored
Colormap ignored D-S-G D-S-G ignored
Foreground ignored D-S-G D-S-G ignored
Background ignored D-S-G D-S-G ignored
Background Pixmap ignored D-S-G D-S-G ignored
FontSet GN ignored C-S-G D-S-G ignored
LineSpacing GN ignored D-S-G D-S-G ignored
Cursor ignored D-S-G D-S-G ignored
Status Callbacks C-S-G ignored ignored ignored
.sp 6p
_
.TE
.NH 3
Input Style
.XS
\*(SN Input Style
.XE
.LP
The
.PN XNInputStyle
argument specifies the input style to be used.
The value of this argument must be one of the values returned by the
.PN XGetIMValues
function with the
.PN XNQueryInputStyle
argument specified in the supported_styles list.
.LP
Note that this argument must be set at creation time
and cannot be changed.
.NH 3
Client Window
.XS
\*(SN Client Window
.XE
.LP
.IN "XNClientWindow" "" "@DEF@"
The
.PN XNClientWindow
argument specifies to the input method the client window in
which the input method
can display data or create subwindows.
Geometry values for input method areas are given with respect to the client
window.
Dynamic change of client window is not supported.
Note that this argument may be set only once and
should be set before any input is done using this input context.
If it is not set the input method may not operate correctly.
.LP
If an attempt is made to set this value a second time with
.PN XSetICValues ,
the string
.PN XNClientWindow
will be returned by
.PN XSetICValues ,
and the client window will not be changed.
.LP
If the client window is not a valid window ID on the display
attached to the input method,
a
.PN BadWindow
error can be generated when this value is used by the input method.
.NH 3
Focus Window
.XS
\*(SN Focus Window
.XE
.LP
.IN "XNFocusWindow" "" "@DEF@"
The
.PN XNFocusWindow
argument specifies the focus window.
The primary purpose of the
.PN XNFocusWindow
is to identify the window that will receive the key event when input
is composed.
In addition, the input method may possibly affect the focus window
as follows:
.IP \(bu 5
Select events on it
.IP \(bu 5
Send events to it
.IP \(bu 5
Modify its properties
.IP \(bu 5
Grab keyboard within that window
.LP
The value associated to the argument must be of type
.PN Window .
If the focus window is not a valid window ID on the display
attached to the input method,
a
.PN BadWindow
error can be generated when this value is used by the input method.
.LP
When this XIC value is left unspecified,
the input method will default focus window to client window.
.NH 3
Resource Name and Class
.XS
\*(SN Resource Name and Class
.XE
.LP
.IN "XNResourceName" "" "@DEF@"
.IN "XNResourceClass" "" "@DEF@"
The
.PN XNResourceName
and
.PN XNResourceClass
arguments are strings that specify the full name and class
used by the client to obtain resources for the client window.
These values should be used as prefixes for name and class
when looking up resources that may vary according to the input context.
If these values are not set,
the resources will not be fully specified.
.LP
It is not intended that values which can be set as XIC values be
set as resources.
.NH 3
Geometry Callback
.XS
\*(SN Geometry Callback
.XE
.LP
.IN "XNGeometryCallback" "" "@DEF@"
The
.PN XNGeometryCallback
argument is a structure of type
.PN XIMCallback
(see section 13.10.7.10).
.LP
The
.PN XNGeometryCallback
argument specifies the geometry callback which a client can set.
This callback is not required for correct operation of either
an input method or a client.
It can be set for a client whose user interface policy permits
an input method to request the dynamic change of that input
methods window.
An input method that does dynamic change will need to filter any
events that it uses to initiate the change.
.NH 3
Filter Events
.XS
\*(SN Filter Events
.XE
.LP
.IN "XNFilterEvents" "" "@DEF@"
The
.PN XNFilterEvents
argument returns the event mask that an input methods needs
to have selected for.
The client is expected to augment its own event mask
for the client window with this one.
.LP
Note that this argument is read-only,
is set by the input method at create time,
and is never changed.
.LP
Note also that the type of this argument is "unsigned long".
Setting this value will cause an error.
.NH 3
Preedit and Status Attributes
.XS
\*(SN Preedit and Status Attribute
.XE
.LP
.IN "XNPreeditAttributes" "" "@DEF@"
.IN "XNStatusAttributes" "" "@DEF@"
The
.PN XNPreeditAttributes
and
.PN XNStatusAttributes
arguments specify to input method the attributes to be used for the
Preedit and Status areas,
if any.
Those attributes are passed to
.PN XSetICValues
or
.PN XGetICValues
as a nested variable length list.
The names to be used in these lists are as described in the following sections.
.NH 4
Area
.XS
\*(SN Area
.XE
.LP
.IN "XNArea" "" "@DEF@"
The value of the
.PN XNArea
argument must be a pointer to a structure of type
.PN XRectangle.
The interpretation of the
.PN XNArea
argument is dependent on the input method style that has been set.
.LP
If the input method style is
.PN XIMPreeditPosition ,
.PN XNArea
specifies the clipping region within which preediting will take place.
If the focus window has been set,
the coordinates are assumed to be relative to the focus window.
Otherwise, the coordinates are assumed to be relative to the client window.
If neither has been set,
the results are undefined.
If
.PN XNArea
is not specified,
the input method will default the clipping region
to the geometry of the
.PN XNFocusWindow .
If the area specified is NULL or invalid,
the results are undefined.
.LP
If the input style is
.PN XIMPreeditArea
or
.PN XIMStatusArea ,
.PN XNArea
specifies the geometry provided by the client to the input method.
The input method may use this area to display its data,
either Preedit or Status depending on the area designated.
The input method may create a window as a child of the client window
with dimensions that fit the
.PN XNArea .
The coordinates are relative to the client window.
If the client window has not been set yet,
the input method should save these values
and apply them when the client window is set.
If
.PN XNArea
is not specified, is set to NULL or is invalid,
the results are undefined.
.NH 4
Area Needed
.XS
\*(SN Area Needed
.XE
.LP
.IN "XNAreaNeeded" "" "@DEF@"
When set, the
.PN XNAreaNeeded
argument specifies the geometry suggested by the client for this area
(Preedit or Status).
The value associated with the argument must be a pointer to a
structure of type
.PN XRectangle .
Note that the x, y values are not used
and that non-zero values for width or height are the constraints
that the client wishes the input method to respect.
.LP
When read, the
.PN XNAreaNeeded
argument specifies the preferred geometry desired by the input method
for the area.
.LP
This argument is only valid if the input style is
.PN XIMPreeditArea
or
.PN XIMStatusArea .
It is used for geometry negotiation between the client and the input method
and has no other effect upon the input method
(see section 13.6.5).
.NH 4
Spot Location
.XS
\*(SN Spot Location
.XE
.LP
.IN "XNSpotLocation" "" "@DEF@"
The
.PN XNSpotLocation
argument specifies to the input method the coordinates of the ``spot''
to be used by an input method executing with
.PN XNInputStyle
set to
.PN XIMPreeditPosition .
When specified to any input method other than
.PN XIMPreeditPosition ,
this XIC value is ignored.
.LP
The x coordinate specifies the position where the next character
would be inserted.
The y coordinate is the position of the baseline used by current text line
in the focus window.
The x and y coordinates are relative to the focus window, if it has been set;
otherwise, they are relative to the client window.
If neither the focus window nor the client window has been set,
the results are undefined.
.LP
Note that the value of the argument is a pointer to a structure of type
.PN XPoint .
.NH 4
Colormap
.XS
\*(SN Colormap
.XE
.LP
Two different arguments can be used to indicate what colormap the input method
should use to allocate colors:
a colormap ID,
or a standard colormap name.
.LP
.IN "XNColormap" "" "@DEF@"
The
\fBXNColormap\fR
argument is used to specify a colormap ID.
The argument value is of type
.PN Colormap .
An invalid argument may generate a
.PN BadColor error
when it is used by the input method.
.LP
.IN "XNStdColormap" "" "@DEF@"
The
.PN XNStdColormap
argument is used to indicate the name of the standard colormap
in which input method should to allocate colors.
The argument value is an
.PN Atom
that should be a valid atom for calling
.PN XGetRGBColormaps .
An invalid argument may generate a
.PN BadAtom
error when it is used by the input method.
.LP
If colormap is left unspecified, it is defaulted to client window colormap.
.NH 4
Foreground and Background
.XS
\*(SN Foreground and Background
.XE
.LP
.IN "XNForeground" "" "@DEF@"
.IN "XNBackground" "" "@DEF@"
The
.PN XNForeground
and
.PN XNBackground
arguments specify the foreground and background pixel, respectively.
The argument value is of type "unsigned long".
It must be a valid pixel in the input method colormap.
.LP
If these values are left unspecified,
the default is determined by the input method.
.NH 4
Background Pixmap
.XS
\*(SN Background Pixmap
.XE
.LP
The
.PN XNBackgroundPixmap
argument specifies a background pixmap to be used as the background of the
window.
The value must be of type
.PN Pixmap .
An invalid argument may generate a
.PN BadPixmap
error when it is used by the input method.
.LP
If this value is left unspecified,
the default is determined by the input method.
.NH 4
FontSet
.XS
\*(SN FontSet
.XE
.LP
.IN "XNFontSet" "" "@DEF@"
The
.PN XNFontSet
argument specifies to the input method what fontset is to be used.
The argument value is of type
.PN XFontSet .
.LP
If this value is left unspecified,
the default is determined by the input method.
.NH 4
Line Spacing
.XS
\*(SN Line Spacing
.XE
.LP
The
.PN XNLineSpace
argument specifies to the input method what line spacing is to be used
in preedit window if more than one line is to be used.
This argument is of type "int".
.LP
If this value is left unspecified,
the default is determined by the input method.
.NH 4
Cursor
.XS
\*(SN Cursor
.XE
.LP
.IN "XNCursor" "" "DEF@"
The
.PN XNCursor
argument specifies to the input method what cursor is to be used
in the specified window.
This argument is of type
.PN Cursor .
.LP
An invalid argument may generate a
.PN BadCursor
error when it is used by the input method.
If this value is left unspecified,
the default is determined by the input method.
.NH 4
Preedit and Status Callbacks
.XS
\*(SN Preedit and Status Callbacks
.XE
.LP
A client that wishes to support the input style
.PN XIMPreeditCallbacks
must provide a set of preedit callbacks to the input method.
The set of preedit callbacks are as follows:
.IN "XNPreeditStartCallback" "" "@DEF@"
.IN "XNPreeditDoneCallback" "" "@DEF@"
.IN "XNPreeditDrawCallback" "" "@DEF@"
.IN "XNPreeditCaretCallback" "" "@DEF@"
.TS
lw(1.75i) lw(4i).
T{
.PN XNPreeditStartCallback
T} T{
This is called when the input method starts preedit.
T}
T{
.PN XNPreeditDoneCallback
T} T{
This is called when the input method stops preedit.
T}
T{
.PN XNPreeditDrawCallback
T} T{
This is called when a number preedit keystrokes should be echoed.
T}
T{
.PN XNPreeditCaretCallback
T} T{
This is called to move text insertion point within preedit string
T}
.TE
.LP
A client that wishes to support the input style
.PN XIMStatusCallbacks
must provide a set of status callbacks to the input method.
The set of status callbacks are as follows:
.IN "XNStatusStartCallback" "" "@DEF@"
.IN "XNStatusDoneCallback" "" "@DEF@"
.IN "XNStatusDrawCallback" "" "@DEF@"
.TS
lw(1.75i) lw(4i).
T{
.PN XNStatusStartCallback
T} T{
This is called when the input method initializes status area.
T}
T{
.PN XNStatusDoneCallback
T} T{
This is called when the input method no longer needs status area.
T}
T{
.PN XNStatusDrawCallback
T} T{
This is called when updating the status area is required.
T}
.TE
.LP
The value of any status or preedit argument is a pointer
to a structure of type
.PN XIMCallback .
.IN "XIMProc" "" "@DEF@"
.IN "XIMCallback" "" "@DEF@"
.\" Start marker code here
.LP
.Ds 0
.TA .5i 2.5i
.ta .5i 2.5i
typedef void (*XIMProc)();

typedef struct {
XPointer client_data;
XIMProc callback;
} XIMCallback;
.De
.\" End marker code here
.LP
Each callback has some particular semantics and will carry the data
that expresses the environment necessary to the client
into a specific data structure.
This paragraph only describes the arguments to be used to set
the callback.
For a complete description of the semantics,
see section 13.11.
.LP
Note that setting any of these values while doing preedit
may cause unexpected results.
.NH 2
Callback Semantics
.XS
\*(SN Callback Semantics
.XE
.LP
Callbacks are functions defined by clients or text drawing packages
that are to be called from the input method when selected events occur.
Most clients will use a text editing package or a toolkit
and, hence, will not need to define such callbacks.
This section defines the callback semantics, when they are triggered,
and what their arguments are.
Note that this information is mostly useful for X toolkit implementors.
.LP
Callbacks are mostly provided so that clients (or text editing
packages) can implement on-the-spot preediting in their own window.
In that case,
the input method needs to communicate and synchronize with the client.
Input method needs to communicate changes in the preedit window
when it is under control of the client.
Those callbacks allow the client to initialize the preedit area,
display a new preedit string, move the text insertion point inside preedit,
terminate preedit, or update the status area.
.LP
All callback functions follow the generic prototype:
.IN "CallbackPrototype" "" "@DEF@"
.\" Start marker code here
.FD 0
void CallbackPrototype\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
.br
XIC \fIic\fP\^;
.br
XPointer \fIclient_data\fP\^;
.br
SomeType \fIcall_data\fP\^;
.FN
.IP \fIic\fP 1i
Specifies the input context.
.IP \fIclient_data\fP 1i
Specifies the additional client data.
.IP \fIcall_data\fP 1i
Specifies data specific to the callback.
.\" End marker code here
.LP
The call_data argument is a structure that expresses the arguments needed
to achieve the semantics;
that is,
it is a a specific data structure appropriate to the callback.
In cases where no data is needed in the callback,
this call_data argument is NULL.
The client_data argument is a closure that has been initially specified
by the client when specifying the callback and passed back.
It may serve, for example, to inherit application context in the callback.
.LP
The following paragraphs describe the programming semantics
and specific data structure associated with the different reasons.
.NH 3
Geometry Callback
.XS
\*(SN Geometry Callback
.XE
.LP
The geometry callback is triggered by the input method
to indicate that it wants the client to negotiate geometry.
The generic prototype is as follows:
.IN "GeometryCallback" "" "@DEF@"
.\" Start marker code here
.FD 0
void GeometryCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
.br
XIC \fIic\fP\^;
.br
XPointer \fIclient_data\fP\^;
.br
XPointer \fIcall_data\fP\^;
.FN
.IP \fIic\fP 1i
Specifies the input context.
.IP \fIclient_data\fP 1i
Specifies the additional client data.
.IP \fIcall_data\fP 1i
Not used for this callback, always passed as NULL.
.\" End marker code here
.LP
Note that a GeometryCallback
is called with a NULL call_data argument.
.NH 3
Preedit State Callbacks
.XS
\*(SN Preedit State Callbacks
.XE
.LP
When the input method turns input conversion on or off,
a PreeditStartCallback or PreeditDoneCallback
callback is triggered in order to let the toolkit do the setup
or the cleanup for the preedit region.
.IN "PreeditStartCallback" "" "@DEF@"
.\" Start marker code here
.FD 0
int PreeditStartCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
.br
XIC \fIic\fP\^;
.br
XPointer \fIclient_data\fP\^;
.br
XPointer \fIcall_data\fP\^;
.FN
.IP \fIic\fP 1i
Specifies the input context.
.IP \fIclient_data\fP 1i
Specifies the additional client data.
.IP \fIcall_data\fP 1i
Not used for this callback, always passed as NULL.
.\" End marker code here
.LP
When preedit starts on the specified input context,
the callback is called with a NULL call_data argument.
PreeditStartCallback will return the maximum size of the preedit string.
Note that a positive number indicates the maximum number of bytes allowed
in the preedit string,
and a value of \-1 indicates there is no limit.
.IN "PreeditDoneCallback" "" "@DEF@"
.\" Start marker code here
.FD 0
void PreeditDoneCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
.br
XIC \fIic\fP\^;
.br
XPointer \fIclient_data\fP\^;
.br
XPointer \fIcall_data\fP\^;
.FN
.IP \fIic\fP 1i
Specifies the input context.
.IP \fIclient_data\fP 1i
Specifies the additional client data.
.IP \fIcall_data\fP 1i
Not used for this callback, always passed as NULL.
.\" End marker code here
.LP
When preedit stops on the specified input context,
the callback is called with a NULL call_data argument.
The client can release the data allocated by
PreeditStartCallback.
.LP
PreeditStartCallback should initialize appropriate data needed for
displaying preedit information and for handling further
PreeditDrawCallback calls.
Once PreeditStartCallback
is called, it will not be called again before
PreeditDoneCallback has been called.
.NH 3
PreeditDraw Callback
.XS
\*(SN PreeditDraw Callback
.XE
.LP
This callback is triggered to draw and insert, delete or replace,
preedit text in the preedit region.
The preedit text may include unconverted input text such as Japanese kana,
converted text such as Japanese Kanji characters, or characters of both kinds.
That string is either a multibyte or wide character string,
whose encoding matches the locale bound to the input context.
The callback prototype
is as follows:
.IN "PreeditDrawCallback" "" "@DEF@"
.\" Start marker code here
.FD 0
void PreeditDrawCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
.br
XIC \fIic\fP\^;
.br
XPointer \fIclient_data\fP\^;
.br
XIMPreeditDrawCallbackStruct *\fIcall_data\fP\^;
.FN
.IP \fIic\fP 1i
Specifies the input context.
.IP \fIclient_data\fP 1i
Specifies the additional client data.
.IP \fIcall_data\fP 1i
Specifies the preedit drawing information.
.\" End marker code here
.LP
The callback is passed a
.PN XIMPreeditDrawCallbackStruct
structure in the call_data argument.
The text member of this structure contains the text to be drawn.
After the string has been drawn,
the caret should be moved to the specified location.
.LP
The
.PN XIMPreeditDrawCallbackStruct
structure is defined as follows:
.LP
.IN "XIMPreeditDrawCallbackStruct" "" "@DEF@"
.\" Start marker code here
.Ds 0
.TA .5i 2.5i
.ta .5i 2.5i
typedef struct _XIMPreeditDrawCallbackStruct {
int caret; /* Cursor offset within preedit string */
int chg_first; /* Starting change position */
int chg_length; /* Length of the change in character count */
XIMText *text;
} XIMPreeditDrawCallbackStruct;
.De
.\" End marker code here
.LP
The client must keep updating a buffer of the preedit text,
the callback arguments referring to indexes in that buffer.
The call_data fields have specific meanings according to the operation:
.IP \(bu 5
To indicate text deletion,
the call_data specifies a NULL text field.
The text to be deleted is then the current text in buffer
from position chg_first (starting at zero) on a (character) length
of chg_length.
.IP \(bu 5
When text is non-NULL,
it indicates insertion or replacement of text in the buffer.
.IP
A positive chg_length indicates that the characters starting
from chg_first to ch_first+chg_length must be deleted
and must be replaced by text, whose length is specified in the
.PN XIMText
structure.
.IP
A chg_length value of zero indicates that text must be inserted
right at the position specified by chg_first.
A value of zero for chg_first specifies the first character in the buffer.
.IP \(bu 5
The caret member is an index in the the preedit text buffer
that specifies the character after which the cursor should move
after text has been drawn or deleted.
.LP
.IN "XIMText" "" @DEF@"
.\" Start marker code here
.Ds
.TA .5i 1.5i 3i
typedef struct _XIMText {
unsigned short length;
XIMFeedback * feedback;
Bool encoding_is_wchar;
union {
char * multi_byte;
wchar_t * wide_char;
} string;
} XIMText;
.De
.\" End marker code here
.LP
The text string passed is actually a structure specifying:
.IP \(bu 5
The length member is the text length in characters.
.IP \(bu 5
The encoding_is_wchar member ia a value that indicates
if the text string is encoded in wide character or multibyte format.
This value should be set by the client when it sets the callback.
.IP \(bu 5
The string member is the text string.
.IP \(bu 5
The feedback member indicates rendering type.
.LP
The feedback member express the types of rendering feedback
the callback should apply when drawing text.
Rendering of the text to be drawn is specified either in generic ways
(for example, primary, secondary) or in specific ways (reverse, underline).
When generic indications are given,
the client is free to choose the rendering style.
It is necessary however that primary and secondary are mapped
to two distinct rendering styles.
.LP
The feedback member also specifies how the rendering of the text argument
should be achieved.
If feedback is NULL,
then rendering is assumed to be the same as rendering of other characters
in the text entry.
Otherwise, it specifies an array defining the rendering of each
character of the string (hence the length of the array is length).
.LP
If an input method wishes to indicate that it is only updating the feedback of
the preedit text without changing the content of it,
the
.PN XIMText
structure should contain a NULL value for the string field,
the number of characters affected in the length field,
and the feedback field should point to an array of
.PN XIMFeedback .
.LP
Each element in the array is a bit mask represented by a value of type
.PN XIMFeedback .
The valid masks names are as follows:
.LP
.IN "XIMReverse" "" "@DEF@"
.IN "XIMUnderline" "" "@DEF@"
.IN "XIMHighlight" "" "@DEF@"
.IN "XIMPrimary" "" "@DEF@"
.IN "XIMSecondary" "" "@DEF@"
.IN "XIMTertiary" "" "@DEF@"
.\" Start marker code here
.LP
.Ds 0
typedef unsigned long XIMFeedback;
.De
.TS
lw(.5i) lw(2i) lw(2i).
T{
#define
T} T{
.PN XIMReverse
T} T{
1
T}
T{
#define
T} T{
.PN XIMUnderline
T} T{
(1L<<1)
T}
T{
#define
T} T{
.PN XIMHighlight
T} T{
(1L<<2)
T}
T{
#define
T} T{
.PN XIMPrimary
T} T{
(1L<<3)
T}
T{
#define
T} T{
.PN XIMSecondary
T} T{
(1L<<4)
T}
T{
#define
T} T{
.PN XIMTertiary
T} T{
(1L<<5)
T}
.TE
.\" End marker code here
.NH 3
PreeditCaretCallback
.XS
\*(SN PreeditCaretCallback
.XE
.LP
An input method may have its own ``navigation keys'' to allow the user
to move the text insertion point in the preedit area
(for example, to move backward or forward).
Consequently, input method needs to indicate to the client that it
should move the text insertion point.
It then calls the PreeditCaretCallback.
.IN "PreeditCaretCallback" "" "@DEF@"
.\" Start marker code here
.FD 0
void PreeditCaretCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
.br
XIC \fIic\fP\^;
.br
XPointer \fIclient_data\fP\^;
.br
XIMPreeditCaretCallbackStruct *\fIcall_data\fP\^;
.FN
.IP \fIic\fP 1i
Specifies the input context.
.IP \fIclient_data\fP 1i
Specifies the additional client data.
.IP \fIcall_data\fP 1i
Specifies the preedit caret information.
.\" End marker code here
.LP
The input method will trigger PreeditCaretCallback
to move the text insertion point during preedit.
The call_data argument contains a pointer to an
.PN XIMPreeditCaretCallbackStruct
structure,
which indicates where the caret should be moved.
The callback must move the insertion point to its new location
and return, in field position, the new offset value from initial position.
.LP
The
.PN XIMPreeditCaretCallbackStruct
structure is defined as follows:
.IN "XIMPreeditCaretCallbackStruct" "" "@DEF@"
.LP
.\" Start marker code here
.Ds 0
.TA .5i 2.5i
.ta .5i 2.5i
typedef struct _XIMPreeditCaretCallbackStruct {
int position; /* Caret offset within preedit string */
XIMCaretDirection direction; /* Caret moves direction */
XIMCaretStyle style; /* Feedback of the caret */
} XIMPreeditCaretCallbackStruct;
.De
.\" End marker code here
.LP
The
.PN XIMCaretStyle
structure is defined as follows:
.LP
.IN "XIMCaretStyle" "" "@DEF@"
.\" Start marker code here
.Ds 0
.TA .5i 2.5i
.ta .5i 2.5i
typedef enum {
XIMIsInvisible, /* Disable caret feedback */
XIMIsPrimary, /* UI defined caret feedback */
XIMIsSecondary, /* UI defined caret feedback */
} XIMCaretStyle;
.De
.\" End marker code here
.LP
The
.PN XIMCaretDirection
structure is defined as follows:
.IN "XIMCaretDirection" "" "@DEF@"
.LP
.\" Start marker code here
.Ds 0
.TA .5i 2.5i
.ta .5i 2.5i
typedef enum {
XIMForwardChar, XIMBackwardChar,
XIMForwardWord, XIMBackwardWord,
XIMCaretUp, XIMCaretDown,
XIMNextLine, XIMPreviousLine,
XIMLineStart, XIMLineEnd,
XIMAbsolutePosition,
XIMDontChange,
} XIMCaretDirection;
.De
.\" End marker code here
.LP
The meaning of these values are defined as follows:
.IN "XIMForwardChar" "" "@DEF@"
.IN "XIMBackwardChar" "" "@DEF@"
.IN "XIMForwardWord" "" "@DEF@"
.IN "XIMBackwardWord" "" "@DEF@"
.IN "XIMCaretUp" "" "@DEF@"
.IN "XIMCaretDown" "" "@DEF@"
.TS
lw(1.5i) lw(4.25i).
T{
.PN XIMForwardChar
T} T{
Move caret forward one character position.
T}
T{
.PN XIMBackwardChar
T} T{
Move caret backward one character position.
T}
T{
.PN XIMForwardWord
T} T{
Move caret forward one word position.
T}
T{
.PN XIMBackwardWord
T} T{
Move caret backward one word position.
T}
T{
.PN XIMCaretUp
T} T{
Move caret up one line keeping current offset.
T}
T{
.PN XIMCaretDown
T} T{
Move caret down one line keeping current offset.
T}
T{
.PN XIMPreviousLine
T} T{
Move caret up one line.
T}
T{
.PN XIMNextLine
T} T{
Move caret down one line.
T}
T{
.PN XIMLineStart
T} T{
Move caret to the beginning of the current display line
that contains the caret.
T}
T{
.PN XIMLineEnd
T} T{
Move caret to the end of the current display line
that contains the caret.
T}
T{
.PN XIMAbsolutePosition
T} T{
The callback must move to the location specified by the position field
of the callback data, indicated in characters, starting from the beginning
of the preedit text.
Hence, a value of zero means move back to beginning of the preedit text.
T}
T{
.PN XIMDontChange
T} T{
The caret position does not change.
T}
.TE
.IN "XIMNextLine" "" "@DEF@"
.IN "XIMPreviousLine" "" "@DEF@"
.IN "XIMLineStart" "" "@DEF@"
.IN "XIMLineEnd" "" "@DEF@"
.IN "XIMAbsolutePosition" "" "@DEF@"
.IN "XIMDontChange" "" "@DEF@"
.NH 3
Status Callbacks
.XS
\*(SN Status Callbacks
.XE
.LP
An input method may communicate changes in the status of an input context
(for example, created, destroyed, or focus changes) with three status
callbacks: StatusStartCallback, StatusDoneCallback, and StatusDrawCallback.
.LP
.sp
When the input context is created or gains focus,
the input method calls the StatusStartCallback callback.
.IN "StatusStartCallback" "" "@DEF@"
.\" Start marker code here
.FD 0
void StatusStartCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
.br
XIC \fIic\fP\^;
.br
XPointer \fIclient_data\fP\^;
.br
XPointer \fIcall_data\fP\^;
.FN
.IP \fIic\fP 1i
Specifies the input context.
.IP \fIclient_data\fP 1i
Specifies the additional client data.
.IP \fIcall_data\fP 1i
Not used for this callback, always passed as NULL.
.\" End marker code here
.LP
The callback should initialize appropriate data for displaying status
and be prepared to further StatusDrawCallback calls.
Once StatusStartCallback is called,
it will not be called again before StatusDoneCallback has been called.
.LP
.sp
When an input context
is destroyed or when it loses focus, the input method calls StatusDoneCallback.
.IN "StatusDoneCallback" "" "@DEF@"
.\" Start marker code here
.FD 0
void StatusDoneCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
.br
XIC \fIic\fP\^;
.br
XPointer \fIclient_data\fP\^;
.br
XPointer \fIcall_data\fP\^;
.FN
.IP \fIic\fP 1i
Specifies the input context.
.IP \fIclient_data\fP 1i
Specifies the additional client data.
.IP \fIcall_data\fP 1i
Not used for this callback, always passed as NULL.
.\" End marker code here
.LP
The callback may release any data allocated on
.PN StatusStart .
.LP
.sp
When an input context status has to be updated, the input method calls
.PN StatusDrawCallback .
.IN "StatusDrawCallback" "" "@DEF@"
.\" Start marker code here
.FD 0
void StatusDrawCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
.br
XIC \fIic\fP\^;
.br
XPointer \fIclient_data\fP\^;
.br
XIMStatusDrawCallbackStruct *\fIcall_data\fP\^;
.FN
.IP \fIic\fP 1i
Specifies the input context.
.IP \fIclient_data\fP 1i
Specifies the additional client data.
.IP \fIcall_data\fP 1i
Specifies the status drawing information.
.\" End marker code here
.LP
The callback should update the status area by either drawing a string,
or imaging a bitmap in the status area.
.LP
The
.PN XIMStatusDataType
and
.PN XIMStatusDrawCallbackStruct
structures are defined as follows:
.IN "XIMStatusDataType" "" "@DEF@"
.IN "XIMStatusDrawCallbackStruct" "" "@DEF@"
.LP
.\" Start marker code here
.Ds 0
.TA .5i 1i 3i
.ta .5i 1i 3i
typedef enum {
XIMTextType,
XIMBitmapType,
} XIMStatusDataType;

typedef struct _XIMStatusDrawCallbackStruct {
XIMStatusDataType type;
union {
XIMText *text;
Pixmap bitmap;
} data;
} XIMStatusDrawCallbackStruct;
.De
.\" End marker code here
.NH 2
Event Filtering
.XS
\*(SN Event Filtering
.XE
.LP
Xlib provides the ability for an input method
to register a filter internal to Xlib.
This filter is called by a client (or toolkit) by calling
.PN XFilterEvent
after calling
.PN XNextEvent .
Any client that uses the
.PN XIM
interface should call
.PN XFilterEvent
to allow input methods to process their events without knowledge
of the client's dispatching mechanism.
A client's user interface policy may determine the priority
of event filters with respect to other event handling mechanisms
(for example, modal grabs).
.LP
Clients may not know how many filters there are, if any,
and what they do.
They may only know if an event has been filtered on return of
.PN XFilterEvent .
Clients should discard filtered events.
.IN "XFilterEvent" "" "@DEF@"
.\" Start marker code here
.FD 0
Bool XFilterEvent\^(\^\fIevent\fP\^, \fIw\fP\^)
.br
XEvent *\fIevent\fP\^;
.br
Window \fIw\fP\^;
.FN
.ds Ev event to filter
.IP \fIevent\fP 1i
Specifies the \*(Ev.
.ds Wi for which the filter is to be applied
.\" $Header: w_gen.a,v 1.4 88/08/04 11:21:56 mento Exp $
.IP \fIw\fP 1i
Specifies the window \*(Wi.
.\" End marker code here
.LP
If the window argument is
.PN None ,
.PN XFilterEvent
applies the filter to the window specified in the
.PN XEvent
structure.
The window argument is provided so that layers above Xlib
that do event redirection can indicate to which window an event
has been redirected.
.LP
If
.PN XFilterEvent
returns
.PN True ,
then some input method has filtered the event,
and the client should discard the event.
If
.PN XFilterEvent
returns
.PN False ,
then the client should continue processing the event.
.LP
If a grab has occurred in the client, and
.PN XFilterEvent
returns
.PN True ,
the client should ungrab the keyboard.
.NH 2
Getting Keyboard Input
.XS
\*(SN Getting Keyboard Input
.XE
.LP
To get composed input from an input method,
use
.PN XmbLookupString
or
.PN XwcLookupString .
.IN "XmbLookupString" "" "@DEF@"
.IN "XwcLookupString" "" "@DEF@"
.\" Start marker code here
.FD 0
int XmbLookupString\^(\^\fIic\fP\^, \fIevent\fP\^, \fIbuffer_return\fP\^, \fIbytes_buffer\fP\^, \fIkeysym_return\fP\^, \fIstatus_return\fP\^)
.br
XIC \fIic\fP\^;
.br
XKeyPressedEvent *\fIevent\fP;
.br
char *\fIbuffer_return\fP\^;
.br
int \fIbytes_buffer\fP\^;
.br
KeySym *\fIkeysym_return\fP\^;
.br
Status *\fIstatus_return\fP\^;
.FN
.FD 0
int XwcLookupString\^(\^\fIic\fP\^, \fIevent\fP\^, \fIbuffer_return\fP\^, \fIbytes_buffer\fP\^, \fIkeysym_return\fP\^, \fIstatus_return\fP\^)
.br
XIC \fIic\fP\^;
.br
XKeyPressedEvent *\fIevent\fP\^;
.br
wchar_t *\fIbuffer_return\fP\^;
.br
int \fIwchars_buffer\fP\^;
.br
KeySym *\fIkeysym_return\fP\^;
.br
Status *\fIstatus_return\fP\^;
.FN
.IP \fIic\fP 1i
Specifies the input context.
.ds Ev key event to be used
.IP \fIevent\fP 1i
Specifies the \*(Ev.
.IP \fIbuffer_return\fP 1i
Returns a multibyte string or wide character string (if any)
from the input method.
.IP \fIbytes_buffer\fP 1i
.br
.ns
.IP \fIwchars_buffer\fP 1i
Specifies space available in return buffer.
.IP \fIkeysym_return\fP 1i
Returns the KeySym computed from the event if this argument is not NULL.
.IP \fIstatus_return\fP 1i
Returns a value indicating what kind of data is returned.
.\" End marker code here
.LP
The
.PN XmbLookupString
and
.PN XwcLookupString
functions return the string from the input method specified
in the buffer_return argument.
If no string is returned,
the buffer_return argument is unchanged.
.LP
The KeySym into which the KeyCode from the event was mapped is returned
in the keysym_return argument if it is non-NULL and the status_return
argument indicates that a KeySym was returned.
If both a string and a KeySym are returned,
the KeySym value does not necessarily correspond to the string returned.
.LP
Note that
.PN XmbLookupString
returns the length of the string in bytes and that
.PN XwcLookupString
returns the length of the string in characters.
.LP
.PN XmbLookupString
and
.PN XwcLookupString
return text in the encoding of the locale bound to the input method
of the specified input context.
.LP
Note that each string returned by
.PN XmbLookupString
and
.PN XwcLookupString
begins in the initial state of the encoding of the locale
(if the encoding of the locale is state-dependent).
.NT
In order to insure proper input processing,
it is essential that the client pass only
.PN KeyPress
events to
.PN XmbLookupString
and
.PN XwcLookupString .
Their behavior when a client passes a
.PN KeyRelease
event is undefined.
.NE
.LP
Clients should check the status_return argument before
using the other returned values.
These two functions both return a value to status_return
that indicates what has been returned in the other arguments.
The possible values returned are:
.TS
lw(1.5i) lw(4.3i).
T{
.PN XBufferOverflow
T} T{
The input string to be returned is too large for the supplied buffer_return.
The required size
.Pn ( XmbLookupString
in bytes;
.PN XwcLookupString
in characters) is returned as the value of the function,
and the contents of buffer_return and keysym_return are not modified.
The client should recall the function with the same event
and a buffer of adequate size in order to obtain the string.
T}
T{
.PN XLookupNone
T} T{
No consistent input has been composed so far.
The contents of buffer_return and keysym_return are not modified,
and the function returns zero.
T}
T{
.PN XLookupChars
T} T{
Some input characters have been composed.
They are placed in the buffer_return argument,
and the string length is returned as the value of the function.
The string is encoded in the locale bound to the input context.
The contents of the keysym_return argument is not modified.
T}
T{
.PN XLookupKeySym
T} T{
A KeySym has been returned instead of a string
and is returned in keysym_return.
The contents of the buffer_return argument is not modified,
and the function returns zero.
T}
T{
.PN XLookupBoth
T} T{
Both a KeySym and a string are returned;
.PN XLookupChars
and
.PN XLookupKeySym
occur simultaneously.
T}
.TE
.LP
It does not make any difference if the input context passed as an argument to
.PN XmbLookupString
and
.PN XwcLookupString
is the one currently in possession of the focus or not.
Input may have been composed within an input context before it lost the focus,
and that input may be returned on subsequent calls to
.PN XmbLookupString
or
.PN XwcLookupString ,
even though it does not have any more keyboard focus.
.NH 2
Input Method Conventions
.XS
\*(SN Input Method Conventions
.XE
.LP
The input method architecture is transparent to the client.
However, clients should respect a number of conventions in order
to work properly.
Clients must also be aware of possible effects of synchronization
between input method and library in the case of a remote input server.
.NH 3
Client Conventions
.XS
\*(SN Client Conventions
.XE
.LP
A well-behaved client (or toolkit) should first query the input method style.
If the client cannot satisfy the requirements of the supported styles
(in terms of geometry management or callbacks),
it should negotiate with the user continuation of the program
or raise an exception or error of some sort.
.NH 3
Synchronization Conventions
.XS
\*(SN Synchronization Conventions
.XE
.LP
A
.PN KeyPress
event with a KeyCode of zero is used exclusively as a
signal that an input method has composed input which can be
return by
.PN XmbLookupString
or
.PN XwcLookupString .
No other use is made of a
.PN KeyPress
event with KeyCode of zero.
.LP
Such an event may be generated by either a front-end
or a back-end input method in an implementation dependent manner.
Some possible ways to generate this event include:
.IP \(bu 5
A synthetic event sent by an input method server
.IP \(bu 5
An artificial event created by a input method filter and pushed
onto a client's event queue
.IP \(bu 5
A
.PN KeyPress
event whose KeyCode value is modified by an input method filter
.LP
When callback support is specified by client,
input methods will not take action unless they explicitly
called back the client and obtained no response
(the callback is not specified or returned invalid data).
.NH 2
String Constants
.XS
\*(SN String Constants
.XE
.LP
The following symbols for string constants are defined in
.Pn < X11/Xlib.h >.
Although they are shown here with particular macro definitions,
they may be implemented as macros, as global symbols, or as a
mixture of the two. The string pointer value itself
is not significant; clients must not assume that inequality of two
values implies inequality of the actual string data.
.IN "XNVaNestedList" "" "@DEF@"
.IN "XNQueryInputStyle" "" "@DEF@"
.IN "XNClientWindow" "" "@DEF@"
.IN "XNInputStyle" "" "@DEF@"
.IN "XNFocusWindow" "" "@DEF@"
.IN "XNResourceName" "" "@DEF@"
.IN "XNResourceClass" "" "@DEF@"
.IN "XNGeometryCallback" "" "@DEF@"
.IN "XNFilterEvents" "" "@DEF@"
.IN "XNPreeditStartCallback" "" "@DEF@"
.IN "XNPreeditDoneCallback" "" "@DEF@"
.IN "XNPreeditDrawCallback" "" "@DEF@"
.IN "XNPreeditCaretCallback" "" "@DEF@"
.IN "XNPreeditAttributes" "" "@DEF@"
.TS
lw(.5i) lw(2i) lw(2i).
T{
#define
T} T{
.PN XNVaNestedList
T} T{
"XNVaNestedList"
T}
T{
#define
T} T{
.PN XNQueryInputStyle
T} T{
"queryInputStyle"
T}
T{
#define
T} T{
.PN XNClientWindow
T} T{
"clientWindow"
T}
T{
#define
T} T{
.PN XNInputStyle
T} T{
"inputStyle"
T}
T{
#define
T} T{
.PN XNFocusWindow
T} T{
"focusWindow"
T}
T{
#define
T} T{
.PN XNResourceName
T} T{
"resourceName"
T}
T{
#define
T} T{
.PN XNResourceClass
T} T{
"resourceClass"
T}
T{
#define
T} T{
.PN XNGeometryCallback
T} T{
"geometryCallback"
T}
T{
#define
T} T{
.PN XNFilterEvents
T} T{
"filterEvents"
T}
T{
#define
T} T{
.PN XNPreeditStartCallback
T} T{
"preeditStartCallback"
T}
T{
#define
T} T{
.PN XNPreeditDoneCallback
T} T{
"preeditDoneCallback"
T}
T{
#define
T} T{
.PN XNPreeditDrawCallback
T} T{
"preeditDrawCallback"
T}
T{
#define
T} T{
.PN XNPreeditCaretCallback
T} T{
"preeditCaretCallback"
T}
T{
#define
T} T{
.PN XNPreeditAttributes
T} T{
"preeditAttributes"
T}
.TE
.sp -1
.TS
lw(.5i) lw(2i) lw(2i).
T{
#define
T} T{
.PN XNStatusStartCallback
T} T{
"statusStartCallback"
T}
T{
#define
T} T{
.PN XNStatusDoneCallback
T} T{
"statusDoneCallback"
T}
T{
#define
T} T{
.PN XNStatusDrawCallback
T} T{
"statusDrawCallback"
T}
T{
#define
T} T{
.PN XNStatusAttributes
T} T{
"statusAttributes"
T}
T{
#define
T} T{
.PN XNArea
T} T{
"area"
T}
T{
#define
T} T{
.PN XNAreaNeeded
T} T{
"areaNeeded"
T}
T{
#define
T} T{
.PN XNSpotLocation
T} T{
"spotLocation"
T}
T{
#define
T} T{
.PN XNColormap
T} T{
"colorMap"
T}
T{
#define
T} T{
.PN XNStdColormap
T} T{
"stdColorMap"
T}
T{
#define
T} T{
.PN XNForeground
T} T{
"foreground"
T}
T{
#define
T} T{
.PN XNBackground
T} T{
"background"
T}
T{
#define
T} T{
.PN XNBackgroundPixmap
T} T{
"backgroundPixmap"
T}
T{
#define
T} T{
.PN XNFontSet
T} T{
"fontSet"
T}
T{
#define
T} T{
.PN XNLineSpace
T} T{
"lineSpace"
T}
T{
#define
T} T{
.PN XNCursor
T} T{
"cursor"
T}
.TE
.IN "XNStatusStartCallback" "" "@DEF@"
.IN "XNStatusDoneCallback" "" "@DEF@"
.IN "XNStatusDrawCallback" "" "@DEF@"
.IN "XNStatusAttributes" "" "@DEF@"
.IN "XNArea" "" "@DEF@"
.IN "XNAreaNeeded" "" "@DEF@"
.IN "XNSpotLocation" "" "@DEF@"
.IN "XNColormap" "" "@DEF@"
.IN "XNStdColormap" "" "@DEF@"
.IN "XNForeground" "" "@DEF@"
.IN "XNBackground" "" "@DEF@"
.IN "XNFontSet" "" "@DEF@"
.IN "XNLineSpace" "" "@DEF@"
.IN "XNCursor" "" "@DEF@"
.bp

DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦608fa79fa⟧ TextFile

Derivation

TextFile