<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<chapter id="locales_and_internationalized_text_functions">
<title>Locales and Internationalized Text Functions</title>
<para>
An internationalized application is one that 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 localization. A goal of
internationalization is to permit localization without program source modifications or recompila-
tion.
</para>
<para>
As one of the localization mechanisms, Xlib provides an X Input Method (<acronym>XIM</acronym>) functional inter-
face for internationalized text input and an X Output Method (<acronym>XOM</acronym>) functional interface for
internationalized text output.
</para>
<para>
Internationalization in X is based on the concept of a locale. A locale defines the localized
behavior of a program at run time. Locales affect Xlib in its:
</para>
<itemizedlist>
<listitem><para>Encoding and processing of input method text</para></listitem>
<listitem><para>Encoding of resource files and values</para></listitem>
<listitem><para>Encoding and imaging of text strings</para></listitem>
<listitem><para>Encoding and decoding for inter-client text communication</para></listitem>
</itemizedlist>
<para>
•
Encoding and decoding for inter-client text communication
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 charac-
ters in the same language.
</para>
<para>
This chapter defines support for localized text imaging and text input and describes the locale
mechanism that 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.
</para>
<para>
The Xlib internationalization functions are not meant to provide support for multilingual applica-
tions (mixing multiple languages within a single piece of text), but they make it possible to imple-
ment applications that work in limited fashion with more than one language in independent con-
texts.
</para>
<para>
The remainder of this chapter discusses:
</para>
<itemizedlist>
<listitem><para>X locale management</para></listitem>
<listitem><para>Locale and modifier dependencies</para></listitem>
<listitem><para>Variable argument lists</para></listitem>
<listitem><para>Output methods</para></listitem>
<listitem><para>Input methods</para></listitem>
<listitem><para>String constants</para></listitem>
</itemizedlist>
<sect1 id="X_Locale_Management">
<title>X Locale Management</title>
<!-- .XS -->
<!-- (SN X Locale Management -->
<!-- .XE -->
<para>
<!-- .LP -->
X supports 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
<function>setlocale</function>.
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 <emphasis remap='I'>current locale</emphasis>.
An implementation is permitted to provide implementation-dependent
mechanisms for announcing the locale in addition to
<function>setlocale</function>.
</para>
<para>
<!-- .LP -->
On implementations that do not conform to the ANSI C library,
the locale announcement method is Xlib implementation-dependent.
</para>
<para>
<!-- .LP -->
The mechanism by which the semantic operation of Xlib is defined
for a specific locale is implementation-dependent.
</para>
<para>
<!-- .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
<function>XSupportsLocale</function>.
</para>
<para>Bool XSupportsLocale()</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XSupportsLocale</function>
function returns
<symbol>True</symbol>
if Xlib functions are capable of operating under the current locale.
If it returns
<symbol>False</symbol>,
Xlib locale-dependent functions for which the
<symbol>XLocaleNotSupported</symbol>
return status is defined will return
<symbol>XLocaleNotSupported</symbol>.
Other Xlib locale-dependent routines will operate in the ``C'' locale.
</para>
<para>
<!-- .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,
<function>XSupportsLocale</function>,
and
<function>XSetLocaleModifiers</function>.
</para>
<para>
<!-- .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.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To configure Xlib locale modifiers for the current locale, use
<function>XSetLocaleModifiers</function>.
<indexterm significance="preferred"><primary>XSetLocaleModifiers</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>char *<function>XSetLocaleModifiers</function></funcdef>
<paramdef>char<parameter> *modifier_list</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>modifier_list</emphasis>
</term>
<listitem>
<para>
Specifies the modifiers.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XSetLocaleModifiers</function>
function sets the X modifiers for the current locale setting.
The modifier_list argument is a null-terminated string of the form
``{@<emphasis remap='I'>category</emphasis>=<emphasis remap='I'>value</emphasis>}'', that is,
having zero or more concatenated ``@<emphasis remap='I'>category</emphasis>=<emphasis remap='I'>value</emphasis>''
entries, where <emphasis remap='I'>category</emphasis> is a category name
and <emphasis remap='I'>value</emphasis> is the (possibly empty) setting for that category.
The values are encoded in the current locale.
Category names are restricted to the <acronym>POSIX</acronym> Portable Filename Character Set.
</para>
<para>
<!-- .LP -->
The local host X locale modifiers announcer (on <acronym>POSIX</acronym>-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.
</para>
<para>
<!-- .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,
<function>XSetLocaleModifiers</function>
also returns a pointer to such a string,
and the current locale modifiers are not changed.
</para>
<para>
<!-- .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.
</para>
<para>
<!-- .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
<function>XSetLocaleModifiers</function>
with a non-NULL modifier_list after setting the locale
before they call any locale-dependent Xlib routine.
</para>
<para>
<!-- .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.
</para>
<para>
<!-- .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 are changed.
Until freed, it will not be modified by Xlib.
</para>
<para>
<!-- .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:
</para>
<itemizedlist>
<listitem>
<para>
A command line option
</para>
</listitem>
<listitem>
<para>
A resource
</para>
</listitem>
<listitem>
<para>
The empty string ("")
</para>
</listitem>
</itemizedlist>
<para>
<!-- .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.
</para>
</sect1>
<sect1 id="Locale_and_Modifier_Dependencies">
<title>Locale and Modifier Dependencies</title>
<!-- .XS -->
<!-- (SN Locale and Modifier Dependencies -->
<!-- .XE -->
<para>
<!-- .LP -->
The internationalized Xlib functions operate in the current locale
configured by the host environment and X locale modifiers set by
<function>XSetLocaleModifiers</function>
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:
</para>
<informaltable>
<tgroup cols='3' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<colspec colname='c3'/>
<thead>
<row>
<entry>Locale from</entry>
<entry>Affects the Function</entry>
<entry>In</entry>
</row>
</thead>
<tbody>
<row>
<entry></entry>
<entry>Locale Query/Configuration:</entry>
</row>
<row>
<entry><function>setlocale</function></entry>
<entry><function>XSupportsLocale</function></entry>
<entry>Locale queried</entry>
</row>
<row>
<entry></entry>
<entry><function>XSetLocaleModifiers</function></entry>
<entry>Locale modified</entry>
</row>
<row>
<entry></entry>
</row>
<row>
<entry></entry>
<entry>Resources:</entry>
</row>
<row>
<entry><function>setlocale</function></entry>
<entry><function>XrmGetFileDatabase</function></entry>
<entry>Locale of <type>XrmDatabase</type></entry>
</row>
<row>
<entry></entry>
<entry><function>XrmGetStringDatabase</function></entry>
</row>
<row>
<entry><type>XrmDatabase</type></entry>
<entry><function>XrmPutFileDatabase</function></entry>
<entry>Locale of <type>XrmDatabase</type></entry>
</row>
<row>
<entry></entry>
<entry><function>XrmLocaleOfDatabase</function></entry>
</row>
<row>
<entry></entry>
</row>
<row>
<entry></entry>
<entry>Setting Standard Properties:</entry>
</row>
<row>
<entry><function>setlocale</function></entry>
<entry><function>XmbSetWMProperties</function></entry>
<entry>Encoding of supplied/returned
text (some WM_ property
text in environment locale)</entry>
</row>
<row>
<entry><function>setlocale</function></entry>
<entry><function>XmbTextPropertyToTextList</function></entry>
<entry>Encoding of supplied/returned text</entry>
</row>
<row>
<entry></entry>
<entry><function>XwcTextPropertyToTextList</function></entry>
</row>
<row>
<entry></entry>
<entry><function>XmbTextListToTextProperty</function></entry>
</row>
<row>
<entry></entry>
<entry><function>XwcTextListToTextProperty</function></entry>
</row>
<row>
<entry></entry>
</row>
<row>
<entry></entry>
<entry>Text Input:</entry>
</row>
<row>
<entry><function>setlocale</function></entry>
<entry><function>XOpenIM</function></entry>
<entry><acronym>XIM</acronym> input method selection</entry>
</row>
<row>
<entry></entry>
<entry><function>XRegisterIMInstantiateCallback</function></entry>
<entry><acronym>XIM</acronym> selection</entry>
</row>
<row>
<entry></entry>
<entry><function>XUnregisterIMInstantiateCallback</function></entry>
<entry><acronym>XIM</acronym> selection</entry>
</row>
<row>
<entry><type>XIM</type></entry>
<entry><function>XCreateIC</function></entry>
<entry><acronym>XIC</acronym> input method configuration</entry>
</row>
<row>
<entry></entry>
<entry><function>XLocaleOfIM</function>, and so on</entry>
<entry>Queried locale</entry>
</row>
<row>
<entry><type>XIC</type></entry>
<entry><function>XmbLookupString</function></entry>
<entry>Keyboard layout</entry>
</row>
<row>
<entry></entry>
<entry><function>XwcLookupString</function></entry>
<entry>Encoding of returned text</entry>
</row>
<row>
<entry></entry>
</row>
<row>
<entry></entry>
<entry>Text Drawing:</entry>
</row>
<row>
<entry><function>setlocale</function></entry>
<entry><function>XOpenOM</function></entry>
<entry><acronym>XOM</acronym> output method selection</entry>
</row>
<row>
<entry></entry>
<entry><function>XCreateFontSet</function></entry>
<entry>Charsets of fonts in XFontSet</entry>
</row>
<row>
<entry><type>XOM</type></entry>
<entry><function>XCreateOC</function></entry>
<entry><acronym>XOC</acronym> output method configuration</entry>
</row>
<row>
<entry></entry>
<entry><function>XLocaleOfOM</function>, and so on</entry>
<entry>Queried locale</entry>
</row>
<row>
<entry><type>XFontSet</type></entry>
<entry><function>XmbDrawText</function>,</entry>
<entry>Locale of supplied text</entry>
</row>
<row>
<entry></entry>
<entry><function>XwcDrawText</function>, and so on</entry>
<entry>Locale of supplied text</entry>
</row>
<row>
<entry></entry>
<entry><function>XExtentsOfFontSet</function>, and so on</entry>
<entry>Locale-dependent metrics</entry>
</row>
<row>
<entry></entry>
<entry><function>XmbTextExtents</function>,</entry>
</row>
<row>
<entry></entry>
<entry><function>XwcTextExtents</function>, and so on</entry>
</row>
<row>
<entry></entry>
</row>
<row>
<entry></entry>
<entry>Xlib Errors:</entry>
</row>
<row>
<entry><function>setlocale</function></entry>
<entry><function>XGetErrorDatabaseText</function></entry>
<entry>Locale of error message</entry>
</row>
<row>
<entry></entry>
<entry><function>XGetErrorText</function></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
<!-- .LP -->
Clients may assume that a locale-encoded text string returned
by an X function can be passed to a C library routine, or vice versa,
if the locale is the same at the two calls.
</para>
<para>
<!-- .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.
</para>
<para>
<!-- .LP -->
All Xlib functions behave as if they do not change the current locale
or X modifier setting.
(This means that if they do change locale or call
<function>XSetLocaleModifiers</function>
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
<function>mblen</function>,
<function>mbtowc</function>,
<function>wctomb</function>,
and
<function>strtok</function>.
</para>
</sect1>
<sect1 id="Variable_Argument_Lists">
<title>Variable Argument Lists</title>
<!-- .XS -->
<!-- (SN Variable Argument Lists -->
<!-- .XE -->
<para>
<!-- .LP -->
Various functions in this chapter have arguments that conform
to the ANSI C variable argument list calling convention.
Each function denoted with an argument of the form ``...'' takes
a variable-length list of name and value pairs,
where each name is a string and each value is of type
<type>XPointer</type>.
A name argument that is NULL identifies the end of the list.
</para>
<para>
<!-- .LP -->
A variable-length argument list may contain a nested list.
If the name
<symbol>XNVaNestedList</symbol>
is specified in place of an argument name,
then the following value is interpreted as an
<type>XVaNestedList</type>
value that specifies a list of values logically inserted into the
original list at the point of declaration.
A NULL identifies the end of a nested list.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To allocate a nested variable argument list dynamically, use
<function>XVaCreateNestedList</function>.
<indexterm significance="preferred"><primary>XVaCreateNestedList</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>XVaNestedList <function>XVaCreateNestedList</function></funcdef>
<paramdef>int<parameter> dummy</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>dummy</emphasis>
</term>
<listitem>
<para>
Specifies an unused argument (required by ANSI C).
<!-- .ds Al -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
...
</term>
<listitem>
<para>
Specifies the variable length argument list(Al.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XVaCreateNestedList</function>
function allocates memory and copies its arguments into
a single list pointer,
which may be used as a 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
<function>XFree</function>
when it is no longer needed.
</para>
</sect1>
<sect1 id="Output_Methods">
<title>Output Methods</title>
<!-- .XS -->
<!-- (SN Output Methods -->
<!-- .XE -->
<para>
<!-- .LP -->
This section provides discussions of the following X Output Method
(<acronym>XOM</acronym>) topics:
</para>
<itemizedlist>
<listitem>
<para>
Output method overview
</para>
</listitem>
<listitem>
<para>
Output method functions
</para>
</listitem>
<listitem>
<para>
Output method values
</para>
</listitem>
<listitem>
<para>
Output context functions
</para>
</listitem>
<listitem>
<para>
Output context values
</para>
</listitem>
<listitem>
<para>
Creating and freeing a font set
</para>
</listitem>
<listitem>
<para>
Obtaining font set metrics
</para>
</listitem>
<listitem>
<para>
Drawing text using font sets
</para>
</listitem>
</itemizedlist>
<sect2 id="Output_Method_Overview">
<title>Output Method Overview</title>
<!-- .XS -->
<!-- (SN Output Method Overview -->
<!-- .XE -->
<para>
<!-- .LP -->
Locale-dependent text may include one or more text components, each of
which may require different fonts and character set encodings.
In some languages, each component might have a different
drawing direction, and some components might contain
context-dependent characters that change shape based on
relationships with neighboring characters.
</para>
<para>
<!-- .LP -->
When drawing such locale-dependent text, some locale-specific
knowledge is required;
for example, what fonts are required to draw the text,
how the text can be separated into components, and which
fonts are selected to draw each component.
Further, when bidirectional text must be drawn,
the internal representation order of the text must be changed
into the visual representation order to be drawn.
</para>
<para>
<!-- .LP -->
An X Output Method provides a functional interface so that clients
do not have to deal directly with such locale-dependent details.
Output methods provide the following capabilities:
</para>
<itemizedlist>
<listitem>
<para>
Creating a set of fonts required to draw locale-dependent text.
</para>
</listitem>
<listitem>
<para>
Drawing locale-dependent text with a font set without the caller
needing to be aware of locale dependencies.
</para>
</listitem>
<listitem>
<para>
Obtaining the escapement and extents in pixels of locale-dependent text.
</para>
</listitem>
<listitem>
<para>
Determining if bidirectional or context-dependent drawing is required
in a specific locale with a specific font set.
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
Two different abstractions are used in the representation of
the output method for clients.
</para>
<para>
<!-- .LP -->
The abstraction used to communicate with an output method
is an opaque data structure represented by the
<type>XOM</type>
data type.
The abstraction for representing the state of a particular output thread
is called an <emphasis remap='I'>output context</emphasis>.
The Xlib representation of an output context is an
<type>XOC</type>,
which is compatible with
<type>XFontSet</type>
in terms of its functional interface, but is
a broader, more generalized abstraction.
</para>
</sect2>
<sect2 id="Output_Method_Functions">
<title>Output Method Functions</title>
<!-- .XS -->
<!-- (SN Output Method Functions -->
<!-- .XE -->
<para>
<!-- .LP -->
To open an output method, use
<function>XOpenOM</function>.
<indexterm significance="preferred"><primary>XOpenOM</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>XOM <function>XOpenOM</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>XrmDatabase<parameter> db</parameter></paramdef>
<paramdef>char<parameter> *res_name</parameter></paramdef>
<paramdef>char<parameter> *res_class</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>db</emphasis>
</term>
<listitem>
<para>
Specifies a pointer to the resource database.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>res_name</emphasis>
</term>
<listitem>
<para>
Specifies the full resource name of the application.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>res_class</emphasis>
</term>
<listitem>
<para>
Specifies the full class name of the application.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XOpenOM</function>
function opens an output method
matching the current locale and modifiers specification.
The current locale and modifiers are bound to the output method
when
<function>XOpenOM</function>
is called.
The locale associated with an output method cannot be changed.
</para>
<para>
<!-- .LP -->
The specific output method to which this call will be routed
is identified on the basis of the current locale and modifiers.
<function>XOpenOM</function>
will identify a default output method corresponding to the
current locale.
That default can be modified using
<function>XSetLocaleModifiers</function>
to set the output method modifier.
</para>
<para>
<!-- .LP -->
The db argument is the resource database to be used by the output method
for looking up resources that are private to the output method.
It is not intended that this database be used to look
up values that can be set as OC values in an output context.
If db is NULL,
no database is passed to the output method.
</para>
<para>
<!-- .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 output method
when looking up resources that are common to all output contexts
that may be created for this output 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.
</para>
<para>
<!-- .LP -->
The res_name and res_class arguments are not assumed to exist beyond
the call to
<function>XOpenOM</function>.
The specified resource database is assumed to exist for the lifetime
of the output method.
</para>
<para>
<!-- .LP -->
<function>XOpenOM</function>
returns NULL if no output method could be opened.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To close an output method, use
<function>XCloseOM</function>.
<indexterm significance="preferred"><primary>XCloseOM</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>Status <function>XCloseOM</function></funcdef>
<paramdef>XOM<parameter> om</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>om</emphasis>
</term>
<listitem>
<para>
Specifies the output method.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XCloseOM</function>
function closes the specified output method.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To set output method attributes, use
<function>XSetOMValues</function>.
<indexterm significance="preferred"><primary>XSetOMValues</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>char *<function>XSetOMValues</function></funcdef>
<paramdef>XOM<parameter> om</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>om</emphasis>
</term>
<listitem>
<para>
Specifies the output method.
<!-- .ds Al \ to set <acronym>XOM</acronym> values -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
...
</term>
<listitem>
<para>
Specifies the variable-length argument list(Al.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XSetOMValues</function>
function presents a variable argument list programming interface
for setting properties or features of the specified output method.
This function returns NULL if it succeeds;
otherwise,
it returns the name of the first argument that could not be obtained.
</para>
<para>
<!-- .LP -->
No standard arguments are currently defined by Xlib.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To query an output method, use
<function>XGetOMValues</function>.
<indexterm significance="preferred"><primary>XGetOMValues</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>char *<function>XGetOMValues</function></funcdef>
<paramdef>XOM<parameter> om</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>om</emphasis>
</term>
<listitem>
<para>
Specifies the output method.
<!-- .ds Al \ to get XOM values -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
...
</term>
<listitem>
<para>
Specifies the variable-length argument list(Al.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XGetOMValues</function>
function presents a variable argument list programming interface
for querying properties or features of the specified output method.
This function returns NULL if it succeeds;
otherwise,
it returns the name of the first argument that could not be obtained.
</para>
<para>
<!-- .LP -->
To obtain the display associated with an output method, use
<function>XDisplayOfOM</function>.
<indexterm significance="preferred"><primary>XDisplayOfOM</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>Display *<function>XDisplayOfOM</function></funcdef>
<paramdef>XOM<parameter> om</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>om</emphasis>
</term>
<listitem>
<para>
Specifies the output method.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XDisplayOfOM</function>
function returns the display associated with the specified output method.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To get the locale associated with an output method, use
<function>XLocaleOfOM</function>.
<indexterm significance="preferred"><primary>XLocaleOfOM</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>char *<function>XLocaleOfOM</function></funcdef>
<paramdef>XOM<parameter> om</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>om</emphasis>
</term>
<listitem>
<para>
Specifies the output method.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XLocaleOfOM</function>
returns the locale associated with the specified output method.
</para>
</sect2>
<sect2 id="X_Output_Method_Values">
<title>X Output Method Values</title>
<!-- .XS -->
<!-- (SN X Output Method Values -->
<!-- .XE -->
<para>
<!-- .LP -->
The following table describes how <acronym>XOM</acronym> values are interpreted by an
output method.
The first column lists the <acronym>XOM</acronym> values. The second column indicates
how each of the <acronym>XOM</acronym> values are treated by a particular output style.
</para>
<para>
<!-- .LP -->
</para>
<para>
<!-- .LP -->
The following key applies to this table.
</para>
<informaltable>
<tgroup cols='2' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<thead>
<row>
<entry>Key</entry>
<entry>Explanation</entry>
</row>
</thead>
<tbody>
<row>
<entry>G</entry>
<entry>This value may be read using <function>XGetOMValues</function>.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<informaltable>
<tgroup cols='2' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<thead>
<row>
<entry><acronym>XOM</acronym> Value</entry>
<entry>Key</entry>
</row>
</thead>
<tbody>
<row>
<entry><symbol>XNRequiredCharSet</symbol></entry>
<entry>G</entry>
</row>
<row>
<entry><symbol>XNQueryOrientation</symbol></entry>
<entry>G</entry>
</row>
<row>
<entry><symbol>XNDirectionalDependentDrawing</symbol></entry>
<entry>G</entry>
</row>
<row>
<entry><symbol>XNContextualDrawing</symbol></entry>
<entry>G</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
<!-- .LP -->
</para>
<sect3 id="Required_Char_Set">
<title>Required Char Set</title>
<!-- .XS -->
<!-- (SN Required Char Set -->
<!-- .XE -->
<para>
<!-- .LP -->
The
<symbol>XNRequiredCharSet</symbol>
argument returns the list of charsets that are required for loading the fonts
needed for the locale.
The value of the argument is a pointer to a structure of type
<structname>XOMCharSetList</structname>.
</para>
<para>
<!-- .LP -->
The
<structname>XOMCharSetList</structname>
structure is defined as follows:
<indexterm significance="preferred"><primary>XOMCharSetList</primary></indexterm>
<!-- .sM -->
</para>
<!-- .LP -->
<literallayout class="monospaced">
<!-- .TA .5i 2.5i -->
<!-- .ta .5i 2.5i -->
typedef struct {
int charset_count;
char **charset_list;
} XOMCharSetList;
</literallayout>
<para>
<!-- .LP -->
<!-- .eM -->
The charset_list member is a list of one or more null-terminated
charset names, and the charset_count member is the number of
charset names.
</para>
<para>
<!-- .LP -->
The required charset list is owned by Xlib and should not be modified or
freed by the client.
It will be freed by a call to
<function>XCloseOM</function>
with the associated
<type>XOM</type>.
Until freed, its contents will not be modified by Xlib.
</para>
<para>
<!-- .LP -->
</para>
</sect3>
<sect3 id="Query_Orientation">
<title>Query Orientation</title>
<!-- .XS -->
<!-- (SN Query Orientation -->
<!-- .XE -->
<para>
<!-- .LP -->
The
<symbol>XNQueryOrientation</symbol>
argument returns the global orientation of text when drawn.
Other than
<constant>XOMOrientation_LTR_TTB</constant>,
the set of orientations supported is locale-dependent.
The value of the argument is a pointer to a structure of type
<structname>XOMOrientation</structname>.
Clients are responsible for freeing the
<structname>XOMOrientation</structname>
structure by using
<function>XFree</function>;
this also frees the contents of the structure.
</para>
<!-- .LP -->
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 2.5i -->
<!-- .ta .5i 2.5i -->
typedef struct {
int num_orientation;
XOrientation *orientation; /* Input Text description */
} XOMOrientation;
typedef enum {
XOMOrientation_LTR_TTB,
XOMOrientation_RTL_TTB,
XOMOrientation_TTB_LTR,
XOMOrientation_TTB_RTL,
XOMOrientation_Context
} XOrientation;
</literallayout>
<para>
<!-- .LP -->
<!-- .eM -->
The possible value for XOrientation may be:
</para>
<itemizedlist>
<listitem>
<para>
<constant>XOMOrientation_LTR_TTB</constant>
left-to-right, top-to-bottom global orientation
</para>
</listitem>
<listitem>
<para>
<constant>XOMOrientation_RTL_TTB</constant>
right-to-left, top-to-bottom global orientation
</para>
</listitem>
<listitem>
<para>
<constant>XOMOrientation_TTB_LTR</constant>
top-to-bottom, left-to-right global orientation
</para>
</listitem>
<listitem>
<para>
<constant>XOMOrientation_TTB_RTL</constant>
top-to-bottom, right-to-left global orientation
</para>
</listitem>
<listitem>
<para>
<constant>XOMOrientation_Context</constant>
contextual global orientation
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
</para>
</sect3>
<sect3 id="Directional_Dependent_Drawing">
<title>Directional Dependent Drawing</title>
<!-- .XS -->
<!-- (SN Directional Dependent Drawing -->
<!-- .XE -->
<para>
<!-- .LP -->
The
<symbol>XNDirectionalDependentDrawing</symbol>
argument indicates whether the text rendering functions
implement implicit handling of directional text. If this value
is
<symbol>True</symbol>,
the output method has knowledge of directional
dependencies and reorders text as necessary when
rendering text. If this value is
<symbol>False</symbol>,
the output method does not implement any directional text
handling, and all character directions are assumed to be left-to-right.
</para>
<para>
<!-- .LP -->
Regardless of the rendering order of characters,
the origins of all characters are on the primary draw direction side
of the drawing origin.
</para>
<para>
<!-- .LP -->
This OM value presents functionality identical to the
<function>XDirectionalDependentDrawing</function>
function.
</para>
</sect3>
<sect3 id="Context_Dependent_Drawing">
<title>Context Dependent Drawing</title>
<!-- .XS -->
<!-- (SN Context Dependent Drawing -->
<!-- .XE -->
<para>
<!-- .LP -->
The
<symbol>XNContextualDrawing</symbol>
argument indicates whether the text rendering functions
implement implicit context-dependent drawing. If this value is
<symbol>True</symbol>,
the output method has knowledge of context dependencies and
performs character shape editing, combining glyphs to present
a single character as necessary. The actual shape editing is
dependent on the locale implementation and the font set used.
</para>
<para>
<!-- .LP -->
This OM value presents functionality identical to the
<function>XContextualDrawing</function>
function.
</para>
</sect3>
</sect2>
<sect2 id="Output_Context_Functions">
<title>Output Context Functions</title>
<!-- .XS -->
<!-- (SN Output Context Functions -->
<!-- .XE -->
<para>
<!-- .LP -->
An output context is an abstraction that contains both the data
required by an output method and the information required
to display that data.
There can be multiple output contexts for one output method.
The programming interfaces for creating, reading, or modifying
an output context use a variable argument list.
The name elements of the argument lists are referred to as <acronym>XOC</acronym> values.
It is intended that output methods be controlled by these <acronym>XOC</acronym> values.
As new <acronym>XOC</acronym> values are created,
they should be registered with the X Consortium.
An
<type>XOC</type>
can be used anywhere an
<type>XFontSet</type>
can be used, and vice versa;
<type>XFontSet</type>
is retained for compatibility with previous releases.
The concepts of output methods and output contexts include broader,
more generalized abstraction than font set,
supporting complex and more intelligent text display, and dealing not only
with multiple fonts but also with context dependencies.
However,
<type>XFontSet</type>
is widely used in several interfaces, so
<type>XOC</type>
is defined as an upward compatible type of
<type>XFontSet</type>.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To create an output context, use
<function>XCreateOC</function>.
<indexterm significance="preferred"><primary>XCreateOC</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>XOC <function>XCreateOC</function></funcdef>
<paramdef>XOM<parameter> om</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>om</emphasis>
</term>
<listitem>
<para>
Specifies the output method.
<!-- .ds Al \ to set <acronym>XOC</acronym> values -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
...
</term>
<listitem>
<para>
Specifies the variable-length argument list(Al.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XCreateOC</function>
function creates an output context within the specified output method.
</para>
<para>
<!-- .LP -->
The base font names argument is mandatory at creation time, and
the output context will not be created unless it is provided.
All other output context values can be set later.
</para>
<para>
<!-- .LP -->
<function>XCreateOC</function>
returns NULL if no output context could be created.
NULL can be returned for any of the following reasons:
</para>
<itemizedlist>
<listitem>
<para>
A required argument was not set.
</para>
</listitem>
<listitem>
<para>
A read-only argument was set.
</para>
</listitem>
<listitem>
<para>
An argument name is not recognized.
</para>
</listitem>
<listitem>
<para>
The output method encountered an output method implementation-dependent error.
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
<function>XCreateOC</function>
can generate a
<errorname>BadAtom</errorname>
error.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To destroy an output context, use
<function>XDestroyOC</function>.
<indexterm significance="preferred"><primary>XDestroyOC</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function>XDestroyOC</function></funcdef>
<paramdef>XOC<parameter> oc</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>oc</emphasis>
</term>
<listitem>
<para>
Specifies the output context.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XDestroyOC</function>
function destroys the specified output context.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To get the output method associated with an output context, use
<function>XOMOfOC</function>.
<indexterm significance="preferred"><primary>XOMOfOC</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>XOM <function>XOMOfOC</function></funcdef>
<paramdef>XOC<parameter> oc</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>oc</emphasis>
</term>
<listitem>
<para>
Specifies the output context.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XOMOfOC</function>
function returns the output method associated with the
specified output context.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
Xlib provides two functions for setting and reading output context values,
respectively,
<function>XSetOCValues</function>
and
<function>XGetOCValues</function>.
Both functions have a variable-length argument list.
In that argument list, any <acronym>XOC</acronym> value's name must be denoted
with a character string using the X Portable Character Set.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To set <acronym>XOC</acronym> values, use
<function>XSetOCValues</function>.
<indexterm significance="preferred"><primary>XSetOCValues</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>char *<function>XSetOCValues</function></funcdef>
<paramdef>XOC<parameter> oc</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>oc</emphasis>
</term>
<listitem>
<para>
Specifies the output context.
<!-- .ds Al \ to set <acronym>XOC</acronym> values -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
...
</term>
<listitem>
<para>
Specifies the variable-length argument list(Al.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XSetOCValues</function>
function returns NULL if no error occurred;
otherwise,
it returns the name of the first argument that could not be set.
An argument might not be set for any of the following reasons:
</para>
<itemizedlist>
<listitem>
<para>
The argument is read-only.
</para>
</listitem>
<listitem>
<para>
The argument name is not recognized.
</para>
</listitem>
<listitem>
<para>
An implementation-dependent error occurs.
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
Each value to be set must be an appropriate datum,
matching the data type imposed by the semantics of the argument.
</para>
<para>
<!-- .LP -->
<function>XSetOCValues</function>
can generate a
<errorname>BadAtom</errorname>
error.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To obtain <acronym>XOC</acronym> values, use
<function>XGetOCValues</function>.
<indexterm significance="preferred"><primary>XGetOCValues</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>char *<function>XGetOCValues</function></funcdef>
<paramdef>XOC<parameter> oc</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>oc</emphasis>
</term>
<listitem>
<para>
Specifies the output context.
<!-- .ds Al \ to get XOC values -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
...
</term>
<listitem>
<para>
Specifies the variable-length argument list(Al.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XGetOCValues</function>
function returns NULL if no error occurred; otherwise,
it returns the name of the first argument that could not be obtained.
An argument might not be obtained for any of the following reasons:
</para>
<itemizedlist>
<listitem>
<para>
The argument name is not recognized.
</para>
</listitem>
<listitem>
<para>
An implementation-dependent error occurs.
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
Each argument value
following a name must point to a location where the value is to be stored.
</para>
</sect2>
<sect2 id="Output_Context_Values">
<title>Output Context Values</title>
<!-- .XS -->
<!-- (SN Output Context Values -->
<!-- .XE -->
<para>
<!-- .LP -->
The following table describes how <acronym>XOC</acronym> values are interpreted
by an output method.
The first column lists the <acronym>XOC</acronym> values.
The second column indicates the alternative interfaces that function
identically and are provided for compatibility with previous releases.
The third column indicates how each of the <acronym>XOC</acronym> values is treated.
</para>
<!-- .LP -->
<para>
The following keys apply to this table.
</para>
<informaltable>
<tgroup cols='2' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<thead>
<row>
<entry>Key</entry>
<entry>Explanation</entry>
</row>
</thead>
<tbody>
<row>
<entry>C</entry>
<entry>This value must be set with <function>XCreateOC</function>.</entry>
</row>
<row>
<entry>D</entry>
<entry>This value may be set using <function>XCreateOC</function>.
If it is not set,a default is provided.</entry>
</row>
<row>
<entry>G</entry>
<entry>This value may be read using <function>XGetOCValues</function>.</entry>
</row>
<row>
<entry>S</entry>
<entry>This value must be set using <function>XSetOCValues</function>.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<!-- .LP -->
<informaltable>
<tgroup cols='3' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<colspec colname='c3'/>
<thead>
<row>
<entry><acronym>XOC</acronym> Value</entry>
<entry>Alternative Interface</entry>
<entry>Key</entry>
</row>
</thead>
<tbody>
<row>
<entry>BaseFontName</entry>
<entry><function>XCreateFontSet</function></entry>
<entry>C-G</entry>
</row>
<row>
<entry>MissingCharSet</entry>
<entry><function>XCreateFontSet</function></entry>
<entry>G</entry>
</row>
<row>
<entry>DefaultString</entry>
<entry><function>XCreateFontSet</function></entry>
<entry>G</entry>
</row>
<row>
<entry>Orientation</entry>
<entry>-</entry>
<entry>D-S-G</entry>
</row>
<row>
<entry>ResourceName</entry>
<entry>-</entry>
<entry>S-G</entry>
</row>
<row>
<entry>ResourceClass</entry>
<entry>-</entry>
<entry>S-G</entry>
</row>
<row>
<entry>FontInfo</entry>
<entry><function>XFontsOfFontSet</function></entry>
<entry>G</entry>
</row>
<row>
<entry>OMAutomatic</entry>
<entry>-</entry>
<entry>G</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
<!-- .LP -->
</para>
<sect3 id="Base_Font_Name">
<title>Base Font Name</title>
<!-- .XS -->
<!-- (SN Base Font Name -->
<!-- .XE -->
<para>
<!-- .LP -->
The
<symbol>XNBaseFontName</symbol>
argument is a list of base font names that 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.
White space immediately on either side of a separating comma is ignored.
</para>
<para>
<!-- .LP -->
Use of <acronym>XLFD</acronym> 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.
</para>
<para>
<!-- .LP -->
An <acronym>XLFD</acronym> 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.
</para>
<para>
<!-- .LP -->
If a base font name is not an <acronym>XLFD</acronym> name,
Xlib will attempt to obtain an <acronym>XLFD</acronym> name from the font properties
for the font.
If Xlib is successful, the
<function>XGetOCValues</function>
function will return this <acronym>XLFD</acronym> name instead of the client-supplied name.
</para>
<para>
<!-- .LP -->
This argument must be set at creation time
and cannot be changed.
If no fonts exist 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,
<function>XCreateOC</function>
returns NULL.
</para>
<para>
<!-- .LP -->
When querying for the
<symbol>XNBaseFontName</symbol>
<acronym>XOC</acronym> value,
<function>XGetOCValues</function>
returns a null-terminated string identifying the base font names that
Xlib used to load the fonts needed for the locale.
This string is owned by Xlib and should not be modified or freed by
the client.
The string will be freed by a call to
<function>XDestroyOC</function>
with the associated
<type>XOC</type>.
Until freed, the string contents will not be modified by Xlib.
</para>
</sect3>
<sect3 id="Missing_CharSet">
<title>Missing CharSet</title>
<!-- .XS -->
<!-- (SN Missing CharSet -->
<!-- .XE -->
<para>
<!-- .LP -->
The
<symbol>XNMissingCharSet</symbol>
argument returns the list of required charsets that are missing from the
font set.
The value of the argument is a pointer to a structure of type
<structname>XOMCharSetList</structname>.
</para>
<para>
<!-- .LP -->
If fonts exist for all of the charsets required by the current locale,
charset_list is set to NULL and charset_count is set to zero.
If no fonts exist for one or more of the required charsets,
charset_list is set to a list of one or more null-terminated charset names
for which no fonts exist, and charset_count is set to the number of
missing charsets.
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.
</para>
<para>
<!-- .LP -->
The missing charset list is owned by Xlib and should not be modified or
freed by the client.
It will be freed by a call to
<function>XDestroyOC</function>
with the associated
<type>XOC</type>.
Until freed, its contents will not be modified by Xlib.
</para>
</sect3>
<sect3 id="Default_String">
<title>Default String</title>
<!-- .XS -->
<!-- (SN Default String -->
<!-- .XE -->
<para>
<!-- .LP -->
When a drawing or measuring function is called with an
<type>XOC</type>
that has missing charsets, some characters in the locale will not be
drawable.
The
<symbol>XNDefaultString</symbol>
argument returns a pointer to a string that represents the glyphs
that are drawn with this
<type>XOC</type>
when the charsets of the available fonts do not include all glyphs
required to draw a character.
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 or measure the default glyphs
by including this string in a string being drawn or measured with the
<type>XOC</type>.
</para>
<para>
<!-- .LP -->
If the
<symbol>XNDefaultString</symbol>
argument returned 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
<function>XDestroyOC</function>
with the associated
<type>XOC</type>.
Until freed, its contents will not be modified by Xlib.
</para>
</sect3>
<sect3 id="Orientation">
<title>Orientation</title>
<!-- .XS -->
<!-- (SN Orientation -->
<!-- .XE -->
<para>
<!-- .LP -->
The
<symbol>XNOrientation</symbol>
argument specifies the current orientation of text when drawn. The value of
this argument is one of the values returned by the
<function>XGetOMValues</function>
function with the
<symbol>XNQueryOrientation</symbol>
argument specified in the
<type>XOrientation</type>
list.
The value of the argument is of type
<type>XOrientation</type>.
When
<symbol>XNOrientation</symbol>
is queried, the value specifies the current orientation.
When
<symbol>XNOrientation</symbol>
is set, a value is used to set the current orientation.
</para>
<para>
<!-- .LP -->
When
<constant>XOMOrientation_Context</constant>
is set, the text orientation of the
text is determined according to an implementation-defined method
(for example, ISO 6429 control sequences), and the initial text orientation for
locale-dependent Xlib functions is assumed to
be
<constant>XOMOrientation_LTR_TTB</constant>.
</para>
<para>
<!-- .LP -->
The
<symbol>XNOrientation</symbol>
value does not change the prime drawing direction
for Xlib drawing functions.
</para>
</sect3>
<sect3 id="Resource_Name_and_Class">
<title>Resource Name and Class</title>
<!-- .XS -->
<!-- (SN Resource Name and Class -->
<!-- .XE -->
<para>
<!-- .LP -->
The
<symbol>XNResourceName</symbol>
and
<symbol>XNResourceClass</symbol>
arguments are strings that specify the full name and class
used by the client to obtain resources for the display of the output context.
These values should be used as prefixes for name and class
when looking up resources that may vary according to the output context.
If these values are not set,
the resources will not be fully specified.
</para>
<para>
<!-- .LP -->
It is not intended that values that can be set as <acronym>XOM</acronym> values be
set as resources.
</para>
<para>
<!-- .LP -->
When querying for the
<symbol>XNResourceName</symbol>
or
<symbol>XNResourceClass</symbol>
<acronym>XOC</acronym> value,
<function>XGetOCValues</function>
returns a null-terminated string.
This string is owned by Xlib and should not be modified or freed by
the client.
The string will be freed by a call to
<function>XDestroyOC</function>
with the associated
<type>XOC</type>
or when the associated value is changed via
<function>XSetOCValues</function>.
Until freed, the string contents will not be modified by Xlib.
</para>
</sect3>
<sect3 id="Font_Info">
<title>Font Info</title>
<!-- .XS -->
<!-- (SN Font Info -->
<!-- .XE -->
<para>
<!-- .LP -->
The
<symbol>XNFontInfo</symbol>
argument specifies a list of one or more
<structname>XFontStruct</structname>
structures
and font names for the fonts used for drawing by the given output context.
The value of the argument is a pointer to a structure of type
<structname>XOMFontInfo</structname>.
</para>
<para>
<!-- .LP -->
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 2.5i -->
<!-- .ta .5i 2.5i -->
typedef struct {
int num_font;
XFontStruct **font_struct_list;
char **font_name_list;
} XOMFontInfo;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
A list of pointers to the
<structname>XFontStruct</structname>
structures is returned to font_struct_list.
A list of pointers to null-terminated, fully-specified font name strings
in the locale of the output context is returned to font_name_list.
The font_name_list order corresponds to the font_struct_list order.
The number of
<structname>XFontStruct</structname>
structures and font names is returned to num_font.
</para>
<para>
<!-- .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
<structname>XFontStruct</structname>
list to obtain these values for all the fonts currently in use.
</para>
<para>
<!-- .LP -->
Xlib does not guarantee that fonts are loaded from the server
at the creation of an
<type>XOC</type>.
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
<structname>XFontStruct</structname>
structures in the
<structname>XFontStructSet</structname>
is undefined.
Also, note that all properties in the
<structname>XFontStruct</structname>
structures are in the STRING encoding.
</para>
<para>
<!-- .LP -->
The client must not free the
<structname>XOMFontInfo</structname>
struct itself; it will be freed when the
<type>XOC</type>
is closed.
</para>
</sect3>
<sect3 id="OM_Automatic">
<title>OM Automatic</title>
<!-- .XS -->
<!-- (SN OM Automatic -->
<!-- .XE -->
<para>
<!-- .LP -->
The
<symbol>XNOMAutomatic</symbol>
argument returns whether the associated output context was created by
<function>XCreateFontSet</function>
or not. Because the
<function>XFreeFontSet</function>
function not only destroys the output context but also closes the implicit
output method associated with it,
<function>XFreeFontSet</function>
should be used with any output context created by
<function>XCreateFontSet</function>.
However, it is possible that a client does not know how the output context
was created.
Before a client destroys the output context,
it can query whether
<symbol>XNOMAutomatic</symbol>
is set to determine whether
<function>XFreeFontSet</function>
or
<function>XDestroyOC</function>
should be used to destroy the output context.
</para>
</sect3>
</sect2>
<sect2 id="Creating_and_Freeing_a_Font_Set">
<title>Creating and Freeing a Font Set</title>
<!-- .XS -->
<!-- (SN Creating and Freeing a Font Set -->
<!-- .XE -->
<para>
<!-- .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
<type>XFontSet</type>
is an opaque type representing the state of a particular output thread
and is equivalent to the type
<type>XOC</type>.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
The
<function>XCreateFontSet</function>
function is a convenience function for creating an output context using
only default values. The returned
<type>XFontSet</type>
has an implicitly created
<type>XOM</type>.
This
<type>XOM</type>
has an OM value
<symbol>XNOMAutomatic</symbol>
automatically set to
<symbol>True</symbol>
so that the output context self indicates whether it was created by
<function>XCreateOC</function>
or
<function>XCreateFontSet</function>.
<indexterm significance="preferred"><primary>XCreateFontSet</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>XFontSet <function>XCreateFontSet</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>char<parameter> *base_font_name_list</parameter></paramdef>
<paramdef>char<parameter> ***missing_charset_list_return</parameter></paramdef>
<paramdef>int<parameter> *missing_charset_count_return</parameter></paramdef>
<paramdef>char<parameter> **def_string_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>base_font_name_list</emphasis>
</term>
<listitem>
<para>
Specifies the base font names.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>missing_charset_list_return</emphasis>
</term>
<listitem>
<para>
Returns the missing charsets.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>missing_charset_count_return</emphasis>
</term>
<listitem>
<para>
Returns the number of missing charsets.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>def_string_return</emphasis>
</term>
<listitem>
<para>
Returns the string drawn for missing charsets.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XCreateFontSet</function>
function creates a font set for the specified display.
The font set is bound to the current locale when
<function>XCreateFontSet</function>
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.
</para>
<para>
<!-- .LP -->
The base_font_name_list argument is a list of base font names
that 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.
White space immediately on either side of a separating comma is ignored.
</para>
<para>
<!-- .LP -->
Use of <acronym>XLFD</acronym> 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.
</para>
<para>
<!-- .LP -->
An <acronym>XLFD</acronym> 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.
</para>
<para>
<!-- .LP -->
If a base font name is not an <acronym>XLFD</acronym> name,
Xlib will attempt to obtain an <acronym>XLFD</acronym> name from the font properties
for the font.
If this action is successful in obtaining an <acronym>XLFD</acronym> name, the
<function>XBaseFontNameListOfFontSet</function>
function will return this <acronym>XLFD</acronym> name instead of the client-supplied name.
</para>
<para>
<!-- .LP -->
Xlib uses the following algorithm to select the fonts
that will be used to display text with the
<type>XFontSet</type>.
</para>
<para>
<!-- .LP -->
For each font charset required by the locale,
the base font name list is searched for the first appearance of one
of the following cases that names a set of fonts that exist at the server:
</para>
<itemizedlist>
<listitem>
<para>
The first <acronym>XLFD</acronym>-conforming base font name that specifies the required
charset or a superset of the required charset in its
<structfield>CharSetRegistry</structfield>
and
<structfield>CharSetEncoding</structfield>
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.
</para>
</listitem>
<listitem>
<para>
The first set of one or more <acronym>XLFD</acronym>-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.
</para>
</listitem>
<listitem>
<para>
The first <acronym>XLFD</acronym>-conforming font name or the first non-<acronym>XLFD</acronym> font name
for which an <acronym>XLFD</acronym> font name can be obtained, combined with the
required charset (replacing the
<structfield>CharSetRegistry</structfield>
and
<structfield>CharSetEncoding</structfield>
fields in the <acronym>XLFD</acronym> font name).
As in case 1,
the implementation may use a charset that is a superset
of the required charset.
</para>
</listitem>
<listitem>
<para>
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.
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
For example, assume that a locale required the charsets:
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
ISO8859-1
JISX0208.1983
JISX0201.1976
GB2312-1980.0
</literallayout>
</para>
<para>
<!-- .LP -->
The user could supply a base_font_name_list that explicitly specifies the
charsets, ensuring that specific fonts are used if they exist.
For example:
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
"-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"
</literallayout>
</para>
<para>
<!-- .LP -->
Alternatively, the user could supply a base_font_name_list
that omits the charsets,
letting Xlib select font charsets required for the locale.
For example:
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
"-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"
</literallayout>
</para>
<para>
<!-- .LP -->
Alternatively, the user could simply supply a single base font name
that allows Xlib to select from all available fonts
that meet certain minimum <acronym>XLFD</acronym> property requirements.
For example:
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
"-*-*-*-R-Normal--*-180-100-100-*-*"
</literallayout>
</para>
<para>
<!-- .LP -->
If
<function>XCreateFontSet</function>
is unable to create the font set,
either because there is insufficient memory or because the current locale
is not supported,
<function>XCreateFontSet</function>
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,
<function>XCreateFontSet</function>
returns a valid
<type>XFontSet</type>,
missing_charset_list_return is set to NULL,
and missing_charset_count_return is set to zero.
</para>
<para>
<!-- .LP -->
If no font exists for one or more of the required charsets,
<function>XCreateFontSet</function>
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.
</para>
<para>
<!-- .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,
<function>XCreateFontSet</function>
returns NULL.
Otherwise,
<function>XCreateFontSet</function>
returns a valid
<type>XFontSet</type>
to font_set.
</para>
<para>
<!-- .LP -->
When an Xmb/wc drawing or measuring function is called with an
<type>XFontSet</type>
that has missing charsets, some characters in the locale will not be
drawable.
If def_string_return is non-NULL,
<function>XCreateFontSet</function>
returns a pointer to a string that represents the glyphs
that are drawn with this
<type>XFontSet</type>
when the charsets of the available fonts do not include all font glyphs
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
<type>XFontSet</type>.
</para>
<para>
<!-- .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
<function>XFreeFontSet</function>
with the associated
<type>XFontSet</type>.
Until freed, its contents will not be modified by Xlib.
</para>
<para>
<!-- .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.
</para>
<para>
<!-- .LP -->
The returned
<type>XFontSet</type>
and missing charset list should be freed with
<function>XFreeFontSet</function>
and
<function>XFreeStringList</function>,
respectively.
The client-supplied base_font_name_list may be freed
by the client after calling
<function>XCreateFontSet</function>.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To obtain a list of
<structname>XFontStruct</structname>
structures and full font names given an
<type>XFontSet</type>,
use
<function>XFontsOfFontSet</function>.
<indexterm significance="preferred"><primary>XFontsOfFontSet</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XFontsOfFontSet</function></funcdef>
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
<paramdef>XFontStruct<parameter> ***font_struct_list_return</parameter></paramdef>
<paramdef>char<parameter> ***font_name_list_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>font_set</emphasis>
</term>
<listitem>
<para>
Specifies the font set.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>font_struct_list_return</emphasis>
</term>
<listitem>
<para>
Returns the list of font structs.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>font_name_list_return</emphasis>
</term>
<listitem>
<para>
Returns the list of font names.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XFontsOfFontSet</function>
function returns a list of one or more
<structname>XFontStruct</structname>s
and font names for the fonts used by the Xmb and Xwc layers
for the given font set.
A list of pointers to the
<structname>XFontStruct</structname>
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
<structname>XFontStruct</structname>
structures and font names is returned as the value of the function.
</para>
<para>
<!-- .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
<structname>XFontStruct</structname>
list to obtain these values for all the fonts currently in use.
</para>
<para>
<!-- .LP -->
Xlib does not guarantee that fonts are loaded from the server
at the creation of an
<type>XFontSet</type>.
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
<structname>XFontStruct</structname>
structures in the
<structname>XFontStructSet</structname>
is undefined.
Also, note that all properties in the
<structname>XFontStruct</structname>
structures are in the STRING encoding.
</para>
<para>
<!-- .LP -->
The
<structname>XFontStruct</structname>
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
<function>XFreeFontSet</function>
with the associated
<type>XFontSet</type>.
Until freed, their contents will not be modified by Xlib.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To obtain the base font name list and the selected font name list given an
<type>XFontSet</type>,
use
<function>XBaseFontNameListOfFontSet</function>.
<indexterm significance="preferred"><primary>XBaseFontNameListOfFontSet</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>char *<function>XBaseFontNameListOfFontSet</function></funcdef>
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>font_set</emphasis>
</term>
<listitem>
<para>
Specifies the font set.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XBaseFontNameListOfFontSet</function>
function returns the original base font name list supplied
by the client when the
<type>XFontSet</type>
was created.
A null-terminated string containing a list of
comma-separated font names is returned
as the value of the function.
White space may appear immediately on either side of separating commas.
</para>
<para>
<!-- .LP -->
If
<function>XCreateFontSet</function>
obtained an <acronym>XLFD</acronym> name from the font properties for the font specified
by a non-<acronym>XLFD</acronym> base name, the
<function>XBaseFontNameListOfFontSet</function>
function will return the <acronym>XLFD</acronym> name instead of the non-<acronym>XLFD</acronym> base name.
</para>
<para>
<!-- .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
<function>XFreeFontSet</function>
with the associated
<type>XFontSet</type>.
Until freed, its contents will not be modified by Xlib.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To obtain the locale name given an
<type>XFontSet</type>,
use
<function>XLocaleOfFontSet</function>.
<indexterm significance="preferred"><primary>XLocaleOfFontSet</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>char *<function>XLocaleOfFontSet</function></funcdef>
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>font_set</emphasis>
</term>
<listitem>
<para>
Specifies the font set.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XLocaleOfFontSet</function>
function
returns the name of the locale bound to the specified
<type>XFontSet</type>,
as a null-terminated string.
</para>
<para>
<!-- .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
<function>XFreeFontSet</function>
with the associated
<type>XFontSet</type>.
Until freed, it will not be modified by Xlib.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
The
<function>XFreeFontSet</function>
function is a convenience function for freeing an output context.
<function>XFreeFontSet</function>
also frees its associated
<type>XOM</type>
if the output context was created by
<function>XCreateFontSet</function>.
<indexterm significance="preferred"><primary>XFreeFontSet</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function>XFreeFontSet</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>font_set</emphasis>
</term>
<listitem>
<para>
Specifies the font set.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XFreeFontSet</function>
function frees the specified font set.
The associated base font name list, font name list,
<structname>XFontStruct</structname>
list, and
<structname>XFontSetExtents</structname>,
if any, are freed.
</para>
</sect2>
<sect2 id="Obtaining_Font_Set_Metrics">
<title>Obtaining Font Set Metrics</title>
<!-- .XS -->
<!-- (SN Obtaining Font Set Metrics -->
<!-- .XE -->
<para>
<!-- .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.
</para>
<para>
<!-- .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.
</para>
<para>
<!-- .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
<function>XmbTextPerCharExtents</function>
or
<function>XwcTextPerCharExtents</function>.
</para>
<para>
<!-- .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
<function>XmbDrawString</function>
may render differently than if the two characters
were drawn with separate calls to
<function>XmbDrawString</function>.
If the client appends or inserts a character
in a previously drawn string,
the client may need to redraw some adjacent characters
to obtain proper rendering.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To find out about direction-dependent rendering, use
<function>XDirectionalDependentDrawing</function>.
<indexterm significance="preferred"><primary>XDirectionalDependentDrawing</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>Bool <function>XDirectionalDependentDrawing</function></funcdef>
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>font_set</emphasis>
</term>
<listitem>
<para>
Specifies the font set.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XDirectionalDependentDrawing</function>
function returns
<symbol>True</symbol>
if the drawing functions implement implicit text directionality;
otherwise, it returns
<symbol>False</symbol>.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To find out about context-dependent rendering, use
<function>XContextualDrawing</function>.
<indexterm significance="preferred"><primary>XContextualDrawing</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>Bool <function>XContextualDrawing</function></funcdef>
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>font_set</emphasis>
</term>
<listitem>
<para>
Specifies the font set.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XContextualDrawing</function>
function returns
<symbol>True</symbol>
if text drawn with the font set might include context-dependent drawing;
otherwise, it returns
<symbol>False</symbol>.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To find out about context-dependent or direction-dependent rendering, use
<function>XContextDependentDrawing</function>.
<indexterm significance="preferred"><primary>XContextDependentDrawing</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>Bool <function>XContextDependentDrawing</function></funcdef>
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>font_set</emphasis>
</term>
<listitem>
<para>
Specifies the font set.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XContextDependentDrawing</function>
function returns
<symbol>True</symbol>
if the drawing functions implement implicit text directionality or
if text drawn with the font_set might include context-dependent drawing;
otherwise, it returns
<symbol>False</symbol>.
</para>
<para>
<!-- .LP -->
The drawing functions do not interpret newline, tab, or other control
characters.
The behavior when nonprinting characters other than space are drawn
is implementation-dependent.
It is the client's responsibility to interpret control characters
in a text stream.
</para>
<para>
<!-- .LP -->
The maximum character extents for the fonts that are used by the text
drawing layers can be accessed by the
<structname>XFontSetExtents</structname>
structure:
<indexterm significance="preferred"><primary>XFontSetExtents</primary></indexterm>
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
<!-- .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;
</literallayout>
</para>
<para>
<!-- .LP -->
The
<structname>XRectangle</structname>
structures used to return font set metrics are the usual Xlib screen-oriented
rectangles
with x, y giving the upper left corner, and width and height always positive.
</para>
<para>
<!-- .LP -->
The max_ink_extent member gives the maximum extent, over all drawable characters, of
the rectangles that bound the character glyph image drawn in the
foreground color, relative to a constant origin.
See
<function>XmbTextExtents</function>
and
<function>XwcTextExtents</function>
for detailed semantics.
</para>
<para>
<!-- .LP -->
The max_logical_extent member gives the maximum extent,
over all drawable characters, of the rectangles
that 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
interline spacing and the minimum area that must be allowed
in a text field to draw a given number of arbitrary characters.
</para>
<para>
<!-- .LP -->
Due to context-dependent rendering,
appending a given character to a string may change
the string's extent by an amount other than that character's
individual extent.
</para>
<para>
<!-- .LP -->
The rectangles for a given character in a string can be obtained from
<function>XmbTextPerCharExtents</function>
or
<function>XwcTextPerCharExtents</function>.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To obtain the maximum extents structure given an
<type>XFontSet</type>,
use
<function>XExtentsOfFontSet</function>.
<indexterm significance="preferred"><primary>XExtentsOfFontSet</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>XFontSetExtents *<function>XExtentsOfFontSet</function></funcdef>
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>font_set</emphasis>
</term>
<listitem>
<para>
Specifies the font set.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XExtentsOfFontSet</function>
function returns an
<structname>XFontSetExtents</structname>
structure for the fonts used by the Xmb and Xwc layers
for the given font set.
</para>
<para>
<!-- .LP -->
The
<structname>XFontSetExtents</structname>
structure is owned by Xlib and should not be modified
or freed by the client.
It will be freed by a call to
<function>XFreeFontSet</function>
with the associated
<type>XFontSet</type>.
Until freed, its contents will not be modified by Xlib.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To obtain the escapement in pixels of the specified text as a value,
use
<function>XmbTextEscapement</function>
or
<function>XwcTextEscapement</function>.
<indexterm significance="preferred"><primary>XmbTextEscapement</primary></indexterm>
<indexterm significance="preferred"><primary>XwcTextEscapement</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XmbTextEscapement</function></funcdef>
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
<paramdef>char<parameter> *string</parameter></paramdef>
<paramdef>int<parameter> num_bytes</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XwcTextEscapement</function></funcdef>
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
<paramdef>wchar_t<parameter> *string</parameter></paramdef>
<paramdef>int<parameter> num_wchars</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>font_set</emphasis>
</term>
<listitem>
<para>
Specifies the font set.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>string</emphasis>
</term>
<listitem>
<para>
Specifies the character string.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>num_bytes</emphasis>
</term>
<listitem>
<para>
Specifies the number of bytes in the string argument.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>num_wchars</emphasis>
</term>
<listitem>
<para>
Specifies the number of characters in the string argument.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XmbTextEscapement</function>
and
<function>XwcTextEscapement</function>
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.
</para>
<para>
<!-- .LP -->
Regardless of the character rendering order,
the escapement is always positive.
</para>
<para>
<!-- .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
<function>XmbTextExtents</function>
or
<function>XwcTextExtents</function>.
<indexterm significance="preferred"><primary>XmbTextExtents</primary></indexterm>
<indexterm significance="preferred"><primary>XwcTextExtents</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XmbTextExtents</function></funcdef>
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
<paramdef>char<parameter> *string</parameter></paramdef>
<paramdef>int<parameter> num_bytes</parameter></paramdef>
<paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef>
<paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XwcTextExtents</function></funcdef>
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
<paramdef>wchar_t<parameter> *string</parameter></paramdef>
<paramdef>int<parameter> num_wchars</parameter></paramdef>
<paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef>
<paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>font_set</emphasis>
</term>
<listitem>
<para>
Specifies the font set.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>string</emphasis>
</term>
<listitem>
<para>
Specifies the character string.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>num_bytes</emphasis>
</term>
<listitem>
<para>
Specifies the number of bytes in the string argument.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>num_wchars</emphasis>
</term>
<listitem>
<para>
Specifies the number of characters in the string argument.
<!-- .ds Ov dimensions -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>overall_ink_return</emphasis>
</term>
<listitem>
<para>
Returns the overall ink dimensions.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>overall_logical_return</emphasis>
</term>
<listitem>
<para>
Returns the overall logical dimensions.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XmbTextExtents</function>
and
<function>XwcTextExtents</function>
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
<function>XmbTextEscapement</function>
or
<function>XwcTextEscapement</function>.
These metrics are relative to the drawing origin of the string,
using the fonts loaded for the specified font set.
</para>
<para>
<!-- .LP -->
If the overall_ink_return argument is non-NULL,
it is set to the bounding box of the string's character ink.
The overall_ink_return for a nondescending, 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, and height = 1.
</para>
<para>
<!-- .LP -->
If the overall_logical_return argument is non-NULL,
it is set to the bounding box that 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.
</para>
<para>
<!-- .LP -->
When the
<type>XFontSet</type>
has missing charsets,
metrics for each unavailable character are taken
from the default string returned by
<function>XCreateFontSet</function>
so that the metrics represent the text as it will actually be drawn.
The behavior for an invalid codepoint is undefined.
</para>
<para>
<!-- .LP -->
To determine the effective drawing origin for a character in a drawn string,
the client should call
<function>XmbTextPerCharExtents</function>
on the entire string, then on the character,
and subtract the x values of the returned
rectangles 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.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To obtain per-character information for a text string,
use
<function>XmbTextPerCharExtents</function>
or
<function>XwcTextPerCharExtents</function>.
<indexterm significance="preferred"><primary>XmbTextPerCharExtents</primary></indexterm>
<indexterm significance="preferred"><primary>XwcTextPerCharExtents</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>Status <function>XmbTextPerCharExtents</function></funcdef>
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
<paramdef>char<parameter> *string</parameter></paramdef>
<paramdef>int<parameter> num_bytes</parameter></paramdef>
<paramdef>XRectangle<parameter> *ink_array_return</parameter></paramdef>
<paramdef>XRectangle<parameter> *logical_array_return</parameter></paramdef>
<paramdef>int<parameter> array_size</parameter></paramdef>
<paramdef>int<parameter> *num_chars_return</parameter></paramdef>
<paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef>
<paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<funcsynopsis>
<funcprototype>
<funcdef>Status <function>XwcTextPerCharExtents</function></funcdef>
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
<paramdef>wchar_t<parameter> *string</parameter></paramdef>
<paramdef>int<parameter> num_wchars</parameter></paramdef>
<paramdef>XRectangle<parameter> *ink_array_return</parameter></paramdef>
<paramdef>XRectangle<parameter> *logical_array_return</parameter></paramdef>
<paramdef>int<parameter> array_size</parameter></paramdef>
<paramdef>int<parameter> *num_chars_return</parameter></paramdef>
<paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef>
<paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>font_set</emphasis>
</term>
<listitem>
<para>
Specifies the font set.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>string</emphasis>
</term>
<listitem>
<para>
Specifies the character string.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>num_bytes</emphasis>
</term>
<listitem>
<para>
Specifies the number of bytes in the string argument.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>num_wchars</emphasis>
</term>
<listitem>
<para>
Specifies the number of characters in the string argument.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>ink_array_return</emphasis>
</term>
<listitem>
<para>
Returns the ink dimensions for each character.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>logical_array_return</emphasis>
</term>
<listitem>
<para>
Returns the logical dimensions for each character.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>array_size</emphasis>
</term>
<listitem>
<para>
Specifies the size of ink_array_return and logical_array_return.
The caller must pass in arrays of this size.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>num_chars_return</emphasis>
</term>
<listitem>
<para>
Returns the number of characters in the string argument.
<!-- .ds Ov extents of the entire string -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>overall_ink_return</emphasis>
</term>
<listitem>
<para>
Returns the overall ink dimensions.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>overall_logical_return</emphasis>
</term>
<listitem>
<para>
Returns the overall logical dimensions.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XmbTextPerCharExtents</function>
and
<function>XwcTextPerCharExtents</function>
functions 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 and one
rectangle
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.
</para>
<para>
<!-- .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
that provides minimum spacing to other graphical features
for the corresponding character.
Other graphical features should not intersect any of the
logical_array_return rectangles.
</para>
<para>
<!-- .LP -->
Note that an
<structname>XRectangle</structname>
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
<structname>XRectangle</structname>s
of those characters are the same.
</para>
<para>
<!-- .LP -->
When the
<type>XFontSet</type>
has missing charsets, metrics for each unavailable
character are taken from the default string returned by
<function>XCreateFontSet</function>
so that the metrics represent the text as it will actually be drawn.
The behavior for an invalid codepoint is undefined.
</para>
<para>
<!-- .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 functions return a nonzero value.
</para>
<para>
<!-- .LP -->
If the overall_ink_return or overall_logical_return argument is non-NULL,
<function>XmbTextPerCharExtents</function>
and
<function>XwcTextPerCharExtents</function>
return the maximum extent of the string's metrics to overall_ink_return
or overall_logical_return, as returned by
<function>XmbTextExtents</function>
or
<function>XwcTextExtents</function>.
</para>
</sect2>
<sect2 id="Drawing_Text_Using_Font_Sets">
<title>Drawing Text Using Font Sets</title>
<!-- .XS -->
<!-- (SN Drawing Text Using Font Sets -->
<!-- .XE -->
<para>
<!-- .LP -->
The functions defined in this section
draw text at a specified location in a drawable.
They are similar to the functions
<function>XDrawText</function>,
<function>XDrawString</function>,
and
<function>XDrawImageString</function>
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 Graphics Contexts (GCs)
and possible protocol errors.
If a
<errorname>BadFont</errorname>
error is generated,
characters prior to the offending character may have been drawn.
</para>
<para>
<!-- .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 functions.
No validation that all fonts conform to some width rule is performed.
</para>
<para>
<!-- .LP -->
The text functions
<function>XmbDrawText</function>
and
<function>XwcDrawText</function>
use the following structures:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XmbTextItem</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 2.5i -->
<!-- .ta .5i 2.5i -->
typedef struct {
char *chars; /* pointer to string */
int nchars; /* number of bytes */
int delta; /* pixel delta between strings */
XFontSet font_set; /* fonts, None means don't change */
} XmbTextItem;
</literallayout>
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XwcTextItem</primary></indexterm>
<literallayout class="monospaced">
<!-- .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;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
<!-- .sp -->
To draw text using multiple font sets in a given drawable, use
<function>XmbDrawText</function>
or
<function>XwcDrawText</function>.
<indexterm significance="preferred"><primary>XmbDrawText</primary></indexterm>
<indexterm significance="preferred"><primary>XwcDrawText</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function>XmbDrawText</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>Drawable<parameter> d</parameter></paramdef>
<paramdef>GC<parameter> gc</parameter></paramdef>
<paramdef>intx,<parameter> y</parameter></paramdef>
<paramdef>XmbTextItem<parameter> *items</parameter></paramdef>
<paramdef>int<parameter> nitems</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function>XwcDrawText</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>Drawable<parameter> d</parameter></paramdef>
<paramdef>GC<parameter> gc</parameter></paramdef>
<paramdef>intx,<parameter> y</parameter></paramdef>
<paramdef>XwcTextItem<parameter> *items</parameter></paramdef>
<paramdef>int<parameter> nitems</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>d</emphasis>
</term>
<listitem>
<para>
Specifies the drawable.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>gc</emphasis>
</term>
<listitem>
<para>
Specifies the GC.
<!-- .ds Xy -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>x</emphasis>
</term>
<listitem>
<para>
<!-- .br -->
<!-- .ns -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>y</emphasis>
</term>
<listitem>
<para>
Specify the x and y coordinates(Xy.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>items</emphasis>
</term>
<listitem>
<para>
Specifies an array of text items.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>nitems</emphasis>
</term>
<listitem>
<para>
Specifies the number of text items in the array.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XmbDrawText</function>
and
<function>XwcDrawText</function>
functions 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
<symbol>None</symbol>
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 a font_set member set to
<symbol>None</symbol>
will not be drawn.
</para>
<para>
<!-- .LP -->
<function>XmbDrawText</function>
and
<function>XwcDrawText</function>
do not perform any context-dependent rendering between text segments.
Clients may compute the drawing metrics by passing each text segment to
<function>XmbTextExtents</function>
and
<function>XwcTextExtents</function>
or
<function>XmbTextPerCharExtents</function>
and
<function>XwcTextPerCharExtents</function>.
When the
<type>XFontSet</type>
has missing charsets, each unavailable character is drawn
with the default string returned by
<function>XCreateFontSet</function>.
The behavior for an invalid codepoint is undefined.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To draw text using a single font set in a given drawable, use
<function>XmbDrawString</function>
or
<function>XwcDrawString</function>.
<indexterm significance="preferred"><primary>XmbDrawString</primary></indexterm>
<indexterm significance="preferred"><primary>XwcDrawString</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function>XmbDrawString</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>Drawable<parameter> d</parameter></paramdef>
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
<paramdef>GC<parameter> gc</parameter></paramdef>
<paramdef>intx,<parameter> y</parameter></paramdef>
<paramdef>char<parameter> *string</parameter></paramdef>
<paramdef>int<parameter> num_bytes</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function>XwcDrawString</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>Drawable<parameter> d</parameter></paramdef>
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
<paramdef>GC<parameter> gc</parameter></paramdef>
<paramdef>intx,<parameter> y</parameter></paramdef>
<paramdef>wchar_t<parameter> *string</parameter></paramdef>
<paramdef>int<parameter> num_wchars</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>d</emphasis>
</term>
<listitem>
<para>
Specifies the drawable.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>font_set</emphasis>
</term>
<listitem>
<para>
Specifies the font set.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>gc</emphasis>
</term>
<listitem>
<para>
Specifies the GC.
<!-- .ds Xy -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>x</emphasis>
</term>
<listitem>
<para>
<!-- .br -->
<!-- .ns -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>y</emphasis>
</term>
<listitem>
<para>
Specify the x and y coordinates(Xy.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>string</emphasis>
</term>
<listitem>
<para>
Specifies the character string.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>num_bytes</emphasis>
</term>
<listitem>
<para>
Specifies the number of bytes in the string argument.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>num_wchars</emphasis>
</term>
<listitem>
<para>
Specifies the number of characters in the string argument.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XmbDrawString</function>
and
<function>XwcDrawString</function>
functions draw the specified text with the foreground pixel.
When the
<type>XFontSet</type>
has missing charsets, each unavailable character is drawn
with the default string returned by
<function>XCreateFontSet</function>.
The behavior for an invalid codepoint is undefined.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To draw image text using a single font set in a given drawable, use
<function>XmbDrawImageString</function>
or
<function>XwcDrawImageString</function>.
<indexterm significance="preferred"><primary>XmbDrawImageString</primary></indexterm>
<indexterm significance="preferred"><primary>XwcDrawImageString</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function>XmbDrawImageString</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>Drawable<parameter> d</parameter></paramdef>
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
<paramdef>GC<parameter> gc</parameter></paramdef>
<paramdef>intx,<parameter> y</parameter></paramdef>
<paramdef>char<parameter> *string</parameter></paramdef>
<paramdef>int<parameter> num_bytes</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function>XwcDrawImageString</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>Drawable<parameter> d</parameter></paramdef>
<paramdef>XFontSet<parameter> font_set</parameter></paramdef>
<paramdef>GC<parameter> gc</parameter></paramdef>
<paramdef>intx,<parameter> y</parameter></paramdef>
<paramdef>wchar_t<parameter> *string</parameter></paramdef>
<paramdef>int<parameter> num_wchars</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>d</emphasis>
</term>
<listitem>
<para>
Specifies the drawable.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>font_set</emphasis>
</term>
<listitem>
<para>
Specifies the font set.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>gc</emphasis>
</term>
<listitem>
<para>
Specifies the GC.
<!-- .ds Xy -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>x</emphasis>
</term>
<listitem>
<para>
<!-- .br -->
<!-- .ns -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>y</emphasis>
</term>
<listitem>
<para>
Specify the x and y coordinates(Xy.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>string</emphasis>
</term>
<listitem>
<para>
Specifies the character string.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>num_bytes</emphasis>
</term>
<listitem>
<para>
Specifies the number of bytes in the string argument.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>num_wchars</emphasis>
</term>
<listitem>
<para>
Specifies the number of characters in the string argument.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XmbDrawImageString</function>
and
<function>XwcDrawImageString</function>
functions 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
<function>XmbTextExtents</function>
or
<function>XwcTextExtents</function>
for the same text and
<type>XFontSet</type>.
</para>
<para>
<!-- .LP -->
When the
<type>XFontSet</type>
has missing charsets, each unavailable character is drawn
with the default string returned by
<function>XCreateFontSet</function>.
The behavior for an invalid codepoint is undefined.
</para>
</sect2>
</sect1>
<sect1 id="Input_Methods">
<title>Input Methods</title>
<!-- .XS -->
<!-- (SN Input Methods -->
<!-- .XE -->
<para>
<!-- .LP -->
This section provides discussions of the following X Input Method
(<acronym>XIM</acronym>) topics:
</para>
<itemizedlist>
<listitem>
<para>
Input method overview
</para>
</listitem>
<listitem>
<para>
Input method management
</para>
</listitem>
<listitem>
<para>
Input method functions
</para>
</listitem>
<listitem>
<para>
Input method values
</para>
</listitem>
<listitem>
<para>
Input context functions
</para>
</listitem>
<listitem>
<para>
Input context values
</para>
</listitem>
<listitem>
<para>
Input method callback semantics
</para>
</listitem>
<listitem>
<para>
Event filtering
</para>
</listitem>
<listitem>
<para>
Getting keyboard input
</para>
</listitem>
<listitem>
<para>
Input method conventions
</para>
</listitem>
</itemizedlist>
<sect2 id="Input_Method_Overview">
<title>Input Method Overview</title>
<!-- .XS -->
<!-- (SN Input Method Overview -->
<!-- .XE -->
<para>
<!-- .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.
</para>
<para>
<!-- .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 exist 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 an English-based keyboard.
They need to hit a combination of keystrokes
to enter a character that does not exist directly on the keyboard.
A number of algorithms have been developed for entering such characters.
These are known as European input methods, compose input methods,
or dead-key input methods.
</para>
<para>
<!-- .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 is used for writing native Japanese words.
Collectively, the two systems are called Kana.
Each set consists of 48 characters.
</para>
<para>
<!-- .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.
</para>
<para>
<!-- .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 can be very large:
approximately 50,000 have been identified in Hanzi,
the Chinese ideographic system.
</para>
<para>
<!-- .LP -->
Two major aspects of ideographic systems impact their use with computers.
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.
This makes 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.
</para>
<para>
<!-- .LP -->
In Japan, both Kana and the ideographic system Kanji are used.
In Korea, Hangul and sometimes the ideographic system Hanja are used.
Now consider entering ideographs in Japan, Korea, China, and Taiwan.
</para>
<para>
<!-- .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.
</para>
<para>
<!-- .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,
the user selects a region for conversion
and then follows the same basic method as that described for Japanese.
</para>
<para>
<!-- .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.
</para>
<para>
<!-- .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.
</para>
<para>
<!-- .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.
</para>
<sect3 id="Input_Method_Architecture">
<title>Input Method Architecture</title>
<!-- .XS -->
<!-- (SN Input Method Architecture -->
<!-- .XE -->
<para>
<!-- .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 to compose a single character (or set
of characters).
The process of composing characters from keystrokes is called
<emphasis remap='I'>preediting</emphasis>.
It may require complex algorithms and large dictionaries
involving substantial computer resources.
</para>
<para>
<!-- .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:
</para>
<itemizedlist>
<listitem>
<para>
The <emphasis remap='I'>status</emphasis> area is a logical extension of the
LEDs that exist on the physical keyboard.
It is a window that 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.
</para>
</listitem>
<listitem>
<para>
The <emphasis remap='I'>preedit</emphasis> area displays the
intermediate text for those languages that are composing prior to
the client handling the data.
</para>
</listitem>
<listitem>
<para>
The <emphasis remap='I'>auxiliary</emphasis> 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 an input method.
Auxiliary areas are managed by the input method independent of the client.
Auxiliary areas are assumed to be separate dialogs,
which are maintained by the input method.
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
There are various user interaction styles used for preediting.
The ones supported by Xlib are as follows:
</para>
<itemizedlist>
<listitem>
<para>
For <emphasis remap='I'>on-the-spot</emphasis> input methods,
preediting data will be displayed directly in the application window.
Application data is moved to allow preedit data to appear
at the point of insertion.
</para>
</listitem>
<listitem>
<para>
<emphasis remap='I'>Over-the-spot</emphasis> preediting means that the data is displayed in
a preedit window that is placed over the point of insertion.
</para>
</listitem>
<listitem>
<para>
<emphasis remap='I'>Off-the-spot</emphasis> 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.
</para>
</listitem>
<listitem>
<para>
<emphasis remap='I'>Root-window</emphasis> preediting refers to input methods that use a preedit
window that is the child of
<function>RootWindow</function>.
</para>
</listitem>
</itemizedlist>
<para>
<!-- .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 <emphasis remap='I'>input server</emphasis>.
The server to which the application should connect is dependent on
the environment when the application is started up,
that is, the user language and the actual encoding to be used for it.
The input method connection is said to be <emphasis remap='I'>locale-dependent</emphasis>.
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).
</para>
<para>
<!-- .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.
</para>
<para>
<!-- .LP -->
An input method may be based on a <emphasis remap='I'>front-end</emphasis> or a <emphasis remap='I'>back-end</emphasis>
architecture.
In a front-end architecture,
there are two separate connections to the X server:
keystrokes go directly from the X server to the input method on
one connection and other events to the regular client connection.
The input method is then acting as a filter and sends composed strings
to the client.
A front-end architecture requires synchronization between the
two connections to avoid lost key events or locking issues.
</para>
<para>
<!-- .LP -->
In a back-end architecture,
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.
</para>
<para>
<!-- .LP -->
A front-end architecture introduces synchronization issues
and a filtering mechanism for noncharacter keystrokes
(Function keys, Help, and so on).
A back-end architecture sometimes implies more communication overhead
and more process switching.
If all three processes (X server, input server, client)
are running on a single workstation,
there are two process switches for each keystroke in a back-end
architecture,
but there is only one in a front-end architecture.
</para>
<para>
<!-- .LP -->
The abstraction used by a client to communicate with an input method
is an opaque data structure represented by the
<type>XIM</type>
data type.
This data structure is returned by the
<function>XOpenIM</function>
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 to use an input method.
</para>
<para>
<!-- .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 the
<type>XIM</type>
object.
</para>
</sect3>
<sect3 id="Input_Contexts">
<title>Input Contexts</title>
<!-- .XS -->
<!-- (SN Input Contexts -->
<!-- .XE -->
<para>
<!-- .LP -->
Xlib provides the ability to manage a multi-threaded 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 the state of a particular input thread
is called an <emphasis remap='I'>input context</emphasis>.
The Xlib representation of an input context is an
<type>XIC</type>.
</para>
<para>
<!-- .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.
</para>
<para>
<!-- .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
<type>XIC</type>
is created with the
<function>XCreateIC</function>
function, providing an
<type>XIM</type>
argument and affiliating the input context to the input method
for its lifetime.
When an input method is closed with
<function>XCloseIM</function>,
all of its affiliated input contexts should not be used any more
(and should preferably be destroyed before closing the input method).
</para>
<para>
<!-- .LP -->
Considering the example of a client window with multiple text entry areas,
the application programmer could, for example, choose to implement as follows:
</para>
<itemizedlist>
<listitem>
<para>
As many input contexts are created as text entry areas, and the client
will get the input accumulated on each context each time it looks up
in that context.
</para>
</listitem>
<listitem>
<para>
A single context is created for a top-level window in the application.
If such a 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.
</para>
</listitem>
</itemizedlist>
<para>
<!-- .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.
</para>
</sect3>
<sect3 id="Getting_Keyboard_Input">
<title>Getting Keyboard Input</title>
<!-- .XS -->
<!-- (SN Getting Keyboard Input -->
<!-- .XE -->
<para>
<!-- .LP -->
To obtain characters from an input method,
a client must call the function
<function>XmbLookupString</function>
or
<function>XwcLookupString</function>
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
<function>XmbLookupString</function>
or
<function>XwcLookupString</function>
will be encoded in that locale.
</para>
</sect3>
<sect3 id="Focus_Management">
<title>Focus Management</title>
<!-- .XS -->
<!-- (SN Focus Management -->
<!-- .XE -->
<para>
<!-- .LP -->
For each text entry area in which the
<function>XmbLookupString</function>
or
<function>XwcLookupString</function>
functions are used,
there will be an associated input context.
</para>
<para>
<!-- .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
<function>XSetICFocus</function>
with the appropriate input context.
</para>
<para>
<!-- .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
<function>XUnsetICFocus</function>.
As an optimization, if
<function>XSetICFocus</function>
is called successively on two different input contexts,
setting the focus on the second
will automatically unset the focus on the first.
</para>
<para>
<!-- .LP -->
To set and unset the input context focus correctly,
it is necessary to track application-level focus changes.
Such focus changes do not necessarily correspond to X server focus changes.
</para>
<para>
<!-- .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 section 13.5.6.3).
</para>
</sect3>
<sect3 id="Geometry_Management">
<title>Geometry Management</title>
<!-- .XS -->
<!-- (SN Geometry Management -->
<!-- .XE -->
<para>
<!-- .LP -->
In most input method architectures
(on-the-spot being the notable exception),
the input method will perform the display of its own data.
To provide better visual locality,
it is often desirable to have the input method areas embedded within a client.
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.
</para>
<para>
<!-- .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:
</para>
<itemizedlist>
<listitem>
<para>
The client is responsible for the geometry of the input method window.
</para>
</listitem>
<listitem>
<para>
The input method is responsible for the contents of the input method window.
</para>
</listitem>
</itemizedlist>
<para>
<!-- .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.
</para>
<para>
<!-- .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
<symbol>XIMPreeditArea</symbol>
or
<symbol>XIMStatusArea</symbol>
in its
<structname>XIMStyles</structname>
value returned by
<function>XGetIMValues</function>.
When a client has decided that it will provide geometry management
for an input method,
it indicates that decision by setting the
<symbol>XNInputStyle</symbol>
value in the
<type>XIC</type>.
</para>
<para>
<!-- .LP -->
After a client has established with the input method
that it will do geometry management,
the client must negotiate the geometry with the input method.
The geometry is negotiated by the following steps:
</para>
<itemizedlist>
<listitem>
<para>
The client suggests an area to the input method by setting the
<symbol>XNAreaNeeded</symbol>
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.
</para>
</listitem>
<listitem>
<para>
The client will get the <acronym>XIC</acronym> value
<symbol>XNAreaNeeded</symbol>.
The input method will return its suggested size in this value.
The input method should pay attention to any constraints suggested
by the client.
</para>
</listitem>
<listitem>
<para>
The client sets the <acronym>XIC</acronym> value
<symbol>XNArea</symbol>
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.
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
Clients doing geometry management must be aware that setting other
<acronym>XIC</acronym> values may affect the geometry desired by an input method.
For example,
<symbol>XNFontSet</symbol>
and
<symbol>XNLineSpace</symbol>
may change the geometry desired by the input method.
</para>
<para>
<!-- .LP -->
The table of <acronym>XIC</acronym> values (see section 13.5.6)
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.
</para>
<para>
<!-- .LP -->
In addition,
a geometry management callback is provided
by which an input method can initiate a geometry change.
</para>
</sect3>
<sect3 id="Event_Filtering">
<title>Event Filtering</title>
<!-- .XS -->
<!-- (SN Event Filtering -->
<!-- .XE -->
<para>
<!-- .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
<function>XmbLookupString</function>
or
<function>XwcLookupString</function>
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.
</para>
<para>
<!-- .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:
</para>
<itemizedlist>
<listitem>
<para>
Expose events on preedit window in local mode.
</para>
</listitem>
<listitem>
<para>
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.
</para>
</listitem>
<listitem>
<para>
Key events can be sent to a filter before they are bound
to translations such as those the X Toolkit Intrinsics library provides.
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
Clients are expected to get the <acronym>XIC</acronym> value
<symbol>XNFilterEvents</symbol>
and augment the event mask for the client window with that event mask.
This mask may be zero.
</para>
</sect3>
<sect3 id="Callbacks">
<title>Callbacks</title>
<!-- .XS -->
<!-- (SN Callbacks -->
<!-- .XE -->
<para>
<!-- .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 that the echo of the keystrokes has to be achieved
by the client itself, tightly coupled with the input method logic.
</para>
<para>
<!-- .LP -->
When the user enters a keystroke,
the client calls
<function>XmbLookupString</function>
or
<function>XwcLookupString</function>.
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 look-up function
must call the echoing logic to insert 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,
the input method logic has to call back to the client before it returns.
The client code, that is, a callback procedure,
is called from the input method logic.
</para>
<para>
<!-- .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.
</para>
<para>
<!-- .LP -->
There are also callbacks provided for feedback of status information
and a callback to initiate a geometry request for an input method.
</para>
</sect3>
<sect3 id="Visible_Position_Feedback_Masks">
<title>Visible Position Feedback Masks</title>
<!-- .XS -->
<!-- (SN Visible Position Feedback Masks -->
<!-- .XE -->
<para>
<!-- .LP -->
In the on-the-spot input style, there is a problem when
attempting to draw preedit strings that are longer than the
available space. Once the display area is exceeded, it is not
clear how best to display the preedit string.
The visible position feedback masks of
<structname>XIMText</structname>
help resolve this problem by allowing the input method to specify hints that
indicate the essential portions of the preedit string.
For example, such hints can help developers implement
scrolling of a long preedit string within a short preedit display area.
</para>
</sect3>
<sect3 id="Preedit_String_Management">
<title>Preedit String Management</title>
<!-- .XS -->
<!-- (SN Preedit String Management -->
<!-- .XE -->
<para>
<!-- .LP -->
As highlighted before, the input method architecture provides
preediting, which supports a type of preprocessor input composition.
In this case, composition consists of interpreting a sequence
of key events and returning a committed string via
<function>XmbLookupString</function>
or
<function>XwcLookupString</function>.
This provides the basics for input methods.
</para>
<para>
<!-- .LP -->
In addition to preediting based on key events, a general framework
is provided to give a client that desires it more advanced preediting based
on the text within the client. This framework is called
<emphasis remap='I'>string conversion</emphasis> and is provided using <acronym>XIC</acronym> values.
The fundamental concept of string conversion
is to allow the input method to manipulate the client's
text independent of any user preediting operation.
</para>
<para>
<!-- .LP -->
The need for string conversion is based on
language needs and input method capabilities.
The following are some examples of string conversion:
</para>
<itemizedlist>
<listitem>
<para>
Transliteration conversion provides language-specific conversions
within the input method.
In the case of Korean input, users wish to convert a Hangul string
into a Hanja string while in preediting, after preediting,
or in other situations (for example, on a selected string).
The conversion is triggered when the user
presses a Hangul-to-Hanja key sequence (which may be input method specific).
Sometimes the user may want to invoke the conversion after finishing
preediting or on a user-selected string.
Thus, the string to be converted is in an application buffer, not in
the preedit area of the input method. The string conversion services
allow the client to request this transliteration conversion from the
input method.
There are many other transliteration conversions defined for
various languages, for example, Kana-to-Kanji conversion in Japanese.
<!-- .sp -->
The key to remember is that transliteration conversions are triggered
at the request of the user and returned to the client
immediately without affecting the preedit area of the input method.
</para>
</listitem>
<listitem>
<para>
Reconversion of a previously committed string or
a selected string is supported by many input methods as a
convenience to the user.
For example, a user tends to mistype the commit key while
preediting. In that case, some input methods provide a special
key sequence to request a ``reconvert'' operation on the
committed string, similiar to the undo facility provided by most
text editors.
Another example is where the user is proofreading a document
that has some misconversions from preediting and wants to correct
the misconverted text. Such reconversion is again triggered
by the user invoking some special action, but reconversions should
not affect the state of the preedit area.
</para>
</listitem>
<listitem>
<para>
Context-sensitive conversion is required for some languages
and input methods that need to retrieve text that surrounds the
current spot location (cursor position) of the client's buffer.
Such text is needed when the preediting operation depends on
some surrounding characters (usually preceding the spot location).
For example,
in Thai language input, certain character sequences may be invalid and
the input method may want to check whether characters constitute a
valid word. Input methods that do such context-dependent
checking need to retrieve the characters surrounding the current
cursor position to obtain complete words.
<!-- .sp -->
Unlike other conversions, this conversion is not explicitly
requested by the user.
Input methods that provide such context-sensitive conversion
continuously need to request context from the client, and any change
in the context of the spot location may affect such conversions.
The client's context would be needed if the user moves the cursor
and starts editing again.
<!-- .sp -->
For this reason, an input method supporting this type of conversion
should take notice of when the client calls
<function>XmbResetIC</function>
or
<function>XwcResetIC</function>,
which is usually an indication of a context change.
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
Context-sensitive conversions just need a copy of the client's text,
while other conversions replace the client's text with new text
to achieve the reconversion or transliteration. Yet in all
cases the result of a conversion, either immediately or via preediting,
is returned by the
<function>XmbLookupString</function>
and
<function>XwcLookupString</function>
functions.
</para>
<para>
<!-- .LP -->
String conversion support is dependent on the availability of the
<symbol>XNStringConversion</symbol>
or
<symbol>XNStringConversionCallback</symbol>
<acronym>XIC</acronym> values.
Because the input method may not support string conversions,
clients have to query the availability of string conversion
operations by checking the supported <acronym>XIC</acronym> values list by calling
<function>XGetIMValues</function>
with the
<symbol>XNQueryICValuesList</symbol>
IM value.
</para>
<para>
<!-- .LP -->
The difference between these two values is whether the
conversion is invoked by the client or the input method.
The
<symbol>XNStringConversion</symbol>
<acronym>XIC</acronym> value is used by clients to request
a string conversion from the input method. The client
is responsible for determining which events are used
to trigger the string conversion and whether the string to be
converted should be copied or deleted. The type of conversion
is determined by the input method; the client can only
pass the string to be converted. The client is guaranteed that
no
<symbol>XNStringConversionCallback</symbol>
will be issued when this value is set; thus, the client need
only set one of these values.
</para>
<para>
<!-- .LP -->
The
<symbol>XNStringConversionCallback</symbol>
<acronym>XIC</acronym> value is used by the client to notify the input method that
it will accept requests from the input method for string conversion.
If this value is set,
it is the input method's responsibility to determine which
events are used to trigger the string conversion.
When such events occur, the input method issues a call to the
client-supplied procedure to retrieve the string to be converted. The client's
callback procedure is notified whether to copy or delete the string and
is provided with hints as to the amount of text needed.
The
<structname>XIMStringConversionCallbackStruct</structname>
specifies which text should be passed back to the input method.
</para>
<para>
<!-- .LP -->
Finally, the input method may call the client's
<symbol>XNStringConversionCallback</symbol>
procedure multiple times if the string returned from the callback is
not sufficient to perform a successful conversion. The arguments
to the client's procedure allow the input method to define a
position (in character units) relative to the client's cursor position
and the size of the text needed. By varying the position and size of
the desired text in subsequent callbacks, the input method can retrieve
additional text.
</para>
<para>
<!-- .LP -->
</para>
</sect3>
</sect2>
<sect2 id="Input_Method_Management">
<title>Input Method Management</title>
<!-- .XS -->
<!-- (SN Input Method Management -->
<!-- .XE -->
<para>
<!-- .LP -->
The interface to input methods might appear to be simply creating
an input method
(<function>XOpenIM</function>)
and freeing an input method
(<function>XCloseIM</function>).
However, input methods may
require complex communication with input method servers (IM servers),
for example:
</para>
<itemizedlist>
<listitem>
<para>
If the X server, IM server, and X clients are started asynchronously,
some clients may attempt to connect to the IM server before it is
fully operational, and fail.
Therefore, some mechanism is needed to allow clients to detect when an IM
server has started.
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
It is up to clients to decide what should be done when an IM server is
not available (for example, wait, or use some other IM server).
</para>
<para>
<!-- .LP -->
</para>
<itemizedlist>
<listitem>
<para>
Some input methods may allow the underlying IM server to be switched.
Such customization may be desired without restarting the entire client.
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
To support management of input methods in these cases, the following
functions are provided:
</para>
<informaltable>
<tgroup cols='2' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<tbody>
<row>
<entry><function>XRegisterIMInstantiateCallback</function></entry>
<entry>This function allows clients to register a callback procedure
to be called when Xlib detects that an IM server is up and available.</entry>
</row>
<row>
<entry><function>XOpenIM</function></entry>
<entry>A client calls this function as a result of the callback procedure
being called.</entry>
</row>
<row>
<entry><function>XSetIMValues</function>, <function>XSetICValues</function></entry>
<entry>These functions use the <acronym>XIM</acronym> and <acronym>XIC</acronym> values,
<symbol>XNDestroyCallback</symbol>,
to allow a client
to register a callback procedure to be called when Xlib detects that
an IM server that was associated with an opened
input method is no longer available.
In addition, this function can be used to switch IM servers for those input
methods that support such functionality. The IM value for switching IM
servers is implementation-dependent; see the description below about
switching IM servers.</entry>
</row>
<row>
<entry><function>XUnregisterIMInstantiateCallback</function></entry>
<entry>This function removes a callback procedure registered by the client.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
<!-- .LP -->
Input methods that support switching of IM servers may exhibit some
side-effects:
</para>
<itemizedlist>
<listitem>
<para>
The input method will ensure that any new IM server supports any of the
input styles being used by input contexts already associated with the
input method.
However, the list of supported input styles may be different.
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
</para>
<itemizedlist>
<listitem>
<para>
Geometry management requests on previously created input contexts
may be initiated by the new IM server.
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
</para>
<sect3 id="Hot_Keys">
<title>Hot Keys</title>
<!-- .XS -->
<!-- (SN Hot Keys -->
<!-- .XE -->
<para>
<!-- .LP -->
Some clients need to guarantee which keys can be used to escape from the
input method, regardless of the input method state;
for example, the client-specific Help key or the keys to move the
input focus.
The HotKey mechanism allows clients
to specify a set of keys for this purpose. However, the input
method might not allow clients to specify hot keys.
Therefore, clients have to query support of hot keys by checking the
supported <acronym>XIC</acronym> values list by calling
<function>XGetIMValues</function>
with the
<symbol>XNQueryICValuesList</symbol>
IM value.
When the hot keys specified conflict with the key bindings of the
input method, hot keys take precedence over the key bindings of the input
method.
</para>
<para>
<!-- .LP -->
</para>
</sect3>
<sect3 id="Preedit_State_Operation">
<title>Preedit State Operation</title>
<!-- .XS -->
<!-- (SN Preedit State Operation -->
<!-- .XE -->
<para>
<!-- .LP -->
An input method may have several internal states, depending on its
implementation and the locale. However, one state that is
independent of locale and implementation is whether the input method
is currently performing a preediting operation.
Xlib provides the ability for an application to manage the preedit state
programmatically. Two methods are provided for
retrieving the preedit state of an input context.
One method is to query the state by calling
<function>XGetICValues</function>
with the
<symbol>XNPreeditState</symbol>
<acronym>XIC</acronym> value.
Another method is to receive notification whenever
the preedit state is changed. To receive such notification,
an application needs to register a callback by calling
<function>XSetICValues</function>
with the
<symbol>XNPreeditStateNotifyCallback</symbol>
<acronym>XIC</acronym> value.
In order to change the preedit state programmatically, an application
needs to call
<function>XSetICValues</function>
with
<symbol>XNPreeditState</symbol>.
</para>
<para>
<!-- .LP -->
Availability of the preedit state is input method dependent. The input
method may not provide the ability to set the state or to
retrieve the state programmatically. Therefore, clients have to
query availability of preedit state operations by checking the
supported <acronym>XIC</acronym> values list by calling
<function>XGetIMValues</function>
with the
<symbol>XNQueryICValuesList</symbol>
IM value.
</para>
</sect3>
</sect2>
<sect2 id="Input_Method_Functions">
<title>Input Method Functions</title>
<!-- .XS -->
<!-- (SN Input Method Functions -->
<!-- .XE -->
<para>
<!-- .LP -->
To open a connection, use
<function>XOpenIM</function>.
<indexterm significance="preferred"><primary>XOpenIM</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>XIM <function>XOpenIM</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>XrmDatabase<parameter> db</parameter></paramdef>
<paramdef>char<parameter> *res_name</parameter></paramdef>
<paramdef>char<parameter> *res_class</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>db</emphasis>
</term>
<listitem>
<para>
Specifies a pointer to the resource database.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>res_name</emphasis>
</term>
<listitem>
<para>
Specifies the full resource name of the application.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>res_class</emphasis>
</term>
<listitem>
<para>
Specifies the full class name of the application.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XOpenIM</function>
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 that the strings returned by
<function>XmbLookupString</function>
or
<function>XwcLookupString</function>,
for any input context affiliated with a given input method,
will be encoded in the locale current at the time the input method is opened.
</para>
<para>
<!-- .LP -->
The specific input method to which this call will be routed
is identified on the basis of the current locale.
<function>XOpenIM</function>
will identify a default input method corresponding to the
current locale.
That default can be modified using
<function>XSetLocaleModifiers</function>
for the input method modifier.
</para>
<para>
<!-- .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 database is passed to the input method.
</para>
<para>
<!-- .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.
</para>
<para>
<!-- .LP -->
The res_name and res_class arguments are not assumed to exist beyond
the call to
<function>XOpenIM</function>.
The specified resource database is assumed to exist for the lifetime
of the input method.
</para>
<para>
<!-- .LP -->
<function>XOpenIM</function>
returns NULL if no input method could be opened.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To close a connection, use
<function>XCloseIM</function>.
<indexterm significance="preferred"><primary>XCloseIM</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>Status <function>XCloseIM</function></funcdef>
<paramdef>XIM<parameter> im</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>im</emphasis>
</term>
<listitem>
<para>
Specifies the input method.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XCloseIM</function>
function closes the specified input method.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To set input method attributes, use
<function>XSetIMValues</function>.
<indexterm significance="preferred"><primary>XSetIMValues</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>char *<function>XSetIMValues</function></funcdef>
<paramdef>XIM<parameter> im</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>im</emphasis>
</term>
<listitem>
<para>
Specifies the input method.
<!-- .ds Al \ to set <acronym>XIM</acronym> values -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
...
</term>
<listitem>
<para>
Specifies the variable-length argument list(Al.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XSetIMValues</function>
function presents a variable argument list programming interface
for setting attributes of the specified input method.
It returns NULL if it succeeds;
otherwise,
it returns the name of the first argument that could not be set.
Xlib does not attempt to set arguments from the supplied list that
follow the failed argument;
all arguments in the list preceding the failed argument have been set
correctly.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To query an input method, use
<function>XGetIMValues</function>.
<indexterm significance="preferred"><primary>XGetIMValues</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>char *<function>XGetIMValues</function></funcdef>
<paramdef>XIM<parameter> im</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>im</emphasis>
</term>
<listitem>
<para>
Specifies the input method.
<!-- .ds Al \ to get XIM values -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
...
</term>
<listitem>
<para>
Specifies the variable length argument list(Al.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XGetIMValues</function>
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.
</para>
<para>
<!-- .LP -->
Each <acronym>XIM</acronym> value argument (following a name) must point to
a location where the <acronym>XIM</acronym> value is to be stored.
That is, if the <acronym>XIM</acronym> value is of type T,
the argument must be of type T*.
If T itself is a pointer type,
then
<function>XGetIMValues</function>
allocates memory to store the actual data,
and the client is responsible for freeing this data by calling
<function>XFree</function>
with the returned pointer.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To obtain the display associated with an input method, use
<function>XDisplayOfIM</function>.
<indexterm significance="preferred"><primary>XDisplayOfIM</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>Display *<function>XDisplayOfIM</function></funcdef>
<paramdef>XIM<parameter> im</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>im</emphasis>
</term>
<listitem>
<para>
Specifies the input method.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XDisplayOfIM</function>
function returns the display associated with the specified input method.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To get the locale associated with an input method, use
<function>XLocaleOfIM</function>.
<indexterm significance="preferred"><primary>XLocaleOfIM</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>char *<function>XLocaleOfIM</function></funcdef>
<paramdef>XIM<parameter> im</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>im</emphasis>
</term>
<listitem>
<para>
Specifies the input method.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XLocaleOfIM</function>
function returns the locale associated with the specified input method.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To register an input method instantiate callback, use
<function>XRegisterIMInstantiateCallback</function>.
<indexterm significance="preferred"><primary>XRegisterIMInstantiateCallback</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>Bool <function>XRegisterIMInstantiateCallback</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>XrmDatabase<parameter> db</parameter></paramdef>
<paramdef>char<parameter> *res_name</parameter></paramdef>
<paramdef>char<parameter> *res_class</parameter></paramdef>
<paramdef>XIMProc<parameter> callback</parameter></paramdef>
<paramdef>XPointer<parameter> *client_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>db</emphasis>
</term>
<listitem>
<para>
Specifies a pointer to the resource database.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>res_name</emphasis>
</term>
<listitem>
<para>
Specifies the full resource name of the application.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>res_class</emphasis>
</term>
<listitem>
<para>
Specifies the full class name of the application.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>callback</emphasis>
</term>
<listitem>
<para>
Specifies a pointer to the input method instantiate callback.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>client_data</emphasis>
</term>
<listitem>
<para>
Specifies the additional client data.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XRegisterIMInstantiateCallback</function>
function registers a callback to be invoked whenever a new input method
becomes available for the specified display that matches the current
locale and modifiers.
</para>
<para>
<!-- .LP -->
The function returns
<symbol>True</symbol>
if it succeeds; otherwise, it returns
<symbol>False</symbol>.
</para>
<para>
<!-- .LP -->
The generic prototype is as follows:
<indexterm significance="preferred"><primary>IMInstantiateCallback</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function><replaceable>IMInstantiateCallback</replaceable></function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
<paramdef>XPointer<parameter> call_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>client_data</emphasis>
</term>
<listitem>
<para>
Specifies the additional client data.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>call_data</emphasis>
</term>
<listitem>
<para>
Not used for this callback and always passed as NULL.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
To unregister an input method instantiation callback, use
<function>XUnregisterIMInstantiateCallback</function>.
<indexterm significance="preferred"><primary>XUnregisterIMInstantiateCallback</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>Bool <function>XUnregisterIMInstantiateCallback</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>XrmDatabase<parameter> db</parameter></paramdef>
<paramdef>char<parameter> *res_name</parameter></paramdef>
<paramdef>char<parameter> *res_class</parameter></paramdef>
<paramdef>XIMProc<parameter> callback</parameter></paramdef>
<paramdef>XPointer<parameter> *client_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>db</emphasis>
</term>
<listitem>
<para>
Specifies a pointer to the resource database.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>res_name</emphasis>
</term>
<listitem>
<para>
Specifies the full resource name of the application.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>res_class</emphasis>
</term>
<listitem>
<para>
Specifies the full class name of the application.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>callback</emphasis>
</term>
<listitem>
<para>
Specifies a pointer to the input method instantiate callback.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>client_data</emphasis>
</term>
<listitem>
<para>
Specifies the additional client data.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XUnregisterIMInstantiateCallback</function>
function removes an input method instantiation callback previously
registered.
The function returns
<symbol>True</symbol>
if it succeeds; otherwise, it returns
<symbol>False</symbol>.
</para>
</sect2>
<sect2 id="Input_Method_Values">
<title>Input Method Values</title>
<!-- .XS -->
<!-- (SN Input Method Values -->
<!-- .XE -->
<para>
<!-- .LP -->
The following table describes how <acronym>XIM</acronym> values are interpreted
by an input method.
The first column lists the <acronym>XIM</acronym> values.
The second column indicates how each of the <acronym>XIM</acronym> values
are treated by that input style.
</para>
<para>
<!-- .LP -->
</para>
<para>
<!-- .LP -->
The following keys apply to this table.
</para>
<informaltable>
<tgroup cols='2' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<thead>
<row>
<entry>Key</entry>
<entry>Explanation</entry>
</row>
</thead>
<tbody>
<row>
<entry>D</entry>
<entry>This value may be set using
<function>XSetIMValues</function>.
If it is not set,
a default is provided.</entry>
</row>
<row>
<entry>S</entry>
<entry>This value may be set using <function>XSetIMValues</function>.</entry>
</row>
<row>
<entry>G</entry>
<entry>This value may be read using <function>XGetIMValues</function>.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<!-- .LP -->
<informaltable>
<tgroup cols='2' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<thead>
<row>
<entry><acronym>XIM</acronym> Value</entry>
<entry>Key</entry>
</row>
</thead>
<tbody>
<row>
<entry><symbol>XNQueryInputStyle</symbol></entry>
<entry>G</entry>
</row>
<row>
<entry><symbol>XNResourceName</symbol></entry>
<entry>D-S-G</entry>
</row>
<row>
<entry><symbol>XNResourceClass</symbol></entry>
<entry>D-S-G</entry>
</row>
<row>
<entry><symbol>XNDestroyCallback</symbol></entry>
<entry>D-S-G</entry>
</row>
<row>
<entry><symbol>XNQueryIMValuesList</symbol></entry>
<entry>G</entry>
</row>
<row>
<entry><symbol>XNQueryICValuesList</symbol></entry>
<entry>G</entry>
</row>
<row>
<entry><symbol>XNVisiblePosition</symbol></entry>
<entry>G</entry>
</row>
<row>
<entry><symbol>XNR6PreeditCallback</symbol></entry>
<entry>D-S-G</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
<!-- .LP -->
<symbol>XNR6PreeditCallback</symbol>
is obsolete and its use is not recommended (see section 13.5.4.6).
</para>
<sect3 id="Query_Input_Style">
<title>Query Input Style</title>
<!-- .XS -->
<!-- (SN Query Input Style -->
<!-- .XE -->
<para>
<!-- .LP -->
A client should always query the input method to determine which input
styles are supported.
The client should then find an input style it is capable of supporting.
</para>
<para>
<!-- .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).
</para>
<para>
<!-- .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
<structname>XIMStyles</structname>.
Clients are responsible for freeing the
<structname>XIMStyles</structname>
structure.
To do so, use
<function>XFree</function>.
</para>
<para>
<!-- .LP -->
The
<structname>XIMStyles</structname>
structure is defined as follows:
</para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XIMStyle</primary></indexterm>
<indexterm significance="preferred"><primary>XIMPreeditArea</primary></indexterm>
<indexterm significance="preferred"><primary>XIMPreeditCallbacks</primary></indexterm>
<indexterm significance="preferred"><primary>XIMPreeditPosition</primary></indexterm>
<indexterm significance="preferred"><primary>XIMPreeditNothing</primary></indexterm>
<indexterm significance="preferred"><primary>XIMPreeditNone</primary></indexterm>
<indexterm significance="preferred"><primary>XIMStatusArea</primary></indexterm>
<indexterm significance="preferred"><primary>XIMStatusCallbacks</primary></indexterm>
<indexterm significance="preferred"><primary>XIMStatusNothing</primary></indexterm>
<indexterm significance="preferred"><primary>XIMStatusNone</primary></indexterm>
<indexterm significance="preferred"><primary>XIMStyles</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
typedef unsigned long XIMStyle;
#define XIMPreeditArea 0x0001L
#define XIMPreeditCallbacks 0x0002L
#define XIMPreeditPosition 0x0004L
#define XIMPreeditNothing 0x0008L
#define XIMPreeditNone 0x0010L
#define XIMStatusArea 0x0100L
#define XIMStatusCallbacks 0x0200L
#define XIMStatusNothing 0x0400L
#define XIMStatusNone 0x0800L
typedef struct {
unsigned short count_styles;
XIMStyle * supported_styles;
} XIMStyles;
</literallayout>
<para>
<!-- .LP -->
<!-- .eM -->
An
<structname>XIMStyles</structname>
structure contains the number of input styles supported
in its count_styles field.
This is also the size of the supported_styles array.
</para>
<para>
<!-- .LP -->
The supported styles is a list of bitmask combinations,
which indicate the combination of styles for each of the areas supported.
These areas are described later.
Each element in the list should select one of the bitmask values for
each area.
The list describes the complete set of combinations supported.
Only these combinations are supported by the input method.
</para>
<para>
<!-- .LP -->
The preedit category defines what type of support is provided
by the input method for preedit information.
</para>
<indexterm significance="preferred"><primary>XIMPreeditArea</primary></indexterm>
<indexterm significance="preferred"><primary>XIMPreeditPosition</primary></indexterm>
<indexterm significance="preferred"><primary>XIMPreeditCallbacks</primary></indexterm>
<indexterm significance="preferred"><primary>XIMPreeditNothing</primary></indexterm>
<indexterm significance="preferred"><primary>XIMPreeditNone</primary></indexterm>
<informaltable>
<tgroup cols='2' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<tbody>
<row>
<entry><symbol>XIMPreeditArea</symbol></entry>
<entry>If chosen,
the input method would require the client to provide some area values
for it to do its preediting.
Refer to <acronym>XIC</acronym> values
<symbol>XNArea</symbol>
and
<symbol>XNAreaNeeded</symbol>.</entry>
</row>
<row>
<entry><symbol>XIMPreeditPosition</symbol></entry>
<entry>If chosen,
the input method would require the client to provide positional values.
Refer to <acronym>XIC</acronym> values
<symbol>XNSpotLocation</symbol>
and
<symbol>XNFocusWindow</symbol>.</entry>
</row>
<row>
<entry><symbol>XIMPreeditCallbacks</symbol></entry>
<entry>If chosen,
the input method would require the client to define the set of preedit callbacks.
Refer to <acronym>XIC</acronym> values
<symbol>XNPreeditStartCallback</symbol>,
<symbol>XNPreeditDoneCallback</symbol>,
<symbol>XNPreeditDrawCallback</symbol>,
and
<symbol>XNPreeditCaretCallback</symbol>.</entry>
</row>
<row>
<entry><symbol>XIMPreeditNothing</symbol></entry>
<entry>If chosen, the input method can function without any preedit values.</entry>
</row>
<row>
<entry><symbol>XIMPreeditNone</symbol></entry>
<entry>The input method does not provide any preedit feedback.
Any preedit value is ignored.
This style is mutually exclusive with the other preedit styles.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
<!-- .LP -->
The status category defines what type of support is provided
by the input method for status information.
</para>
<indexterm significance="preferred"><primary>XIMStatusArea</primary></indexterm>
<indexterm significance="preferred"><primary>XIMStatusCallbacks</primary></indexterm>
<indexterm significance="preferred"><primary>XIMStatusNothing</primary></indexterm>
<indexterm significance="preferred"><primary>XIMStatusNone</primary></indexterm>
<informaltable>
<tgroup cols='2' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<tbody>
<row>
<entry><symbol>XIMStatusArea</symbol></entry>
<entry>The input method requires the client to provide
some area values for it to do its status feedback.
See
<symbol>XNArea</symbol>
and
<symbol>XNAreaNeeded</symbol>.</entry>
</row>
<row>
<entry><symbol>XIMStatusCallbacks</symbol></entry>
<entry>The input method requires the client to define the set of status callbacks,
<symbol>XNStatusStartCallback</symbol>,
<symbol>XNStatusDoneCallback</symbol>,
and
<symbol>XNStatusDrawCallback</symbol>.</entry>
</row>
<row>
<entry><symbol>XIMStatusNothing</symbol></entry>
<entry>The input method can function without any status values.</entry>
</row>
<row>
<entry><symbol>XIMStatusNone</symbol></entry>
<entry>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.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect3>
<sect3 id="Resource_Name_and_Class_c">
<title>Resource Name and Class</title>
<!-- .XS -->
<!-- (SN Resource Name and Class -->
<!-- .XE -->
<para>
<!-- .LP -->
The
<symbol>XNResourceName</symbol>
and
<symbol>XNResourceClass</symbol>
arguments are strings that specify the full name and class
used by the input method.
These values should be used as prefixes for the name and class
when looking up resources that may vary according to the input method.
If these values are not set,
the resources will not be fully specified.
</para>
<para>
<!-- .LP -->
It is not intended that values that can be set as <acronym>XIM</acronym> values be
set as resources.
</para>
<para>
<!-- .LP -->
</para>
</sect3>
<sect3 id="Destroy_Callback">
<title>Destroy Callback</title>
<!-- .XS -->
<!-- (SN Destroy Callback -->
<!-- .XE -->
<para>
<!-- .LP -->
The
<symbol>XNDestroyCallback</symbol>
argument is a pointer to a structure of type
<structname>XIMCallback</structname>.
<symbol>XNDestroyCallback</symbol>
is triggered when an input method stops its service for any reason.
After the callback is invoked, the input method is closed and the
associated input context(s) are destroyed by Xlib.
Therefore, the client should not call
<function>XCloseIM</function>
or
<function>XDestroyIC</function>.
</para>
<para>
<!-- .LP -->
The generic prototype of this callback function is as follows:
<indexterm significance="preferred"><primary>DestroyCallback</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function><replaceable>DestroyCallback</replaceable></function></funcdef>
<paramdef>XIM<parameter> im</parameter></paramdef>
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
<paramdef>XPointer<parameter> call_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>im</emphasis>
</term>
<listitem>
<para>
Specifies the input method.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>client_data</emphasis>
</term>
<listitem>
<para>
Specifies the additional client data.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>call_data</emphasis>
</term>
<listitem>
<para>
Not used for this callback and always passed as NULL.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
A DestroyCallback is always called with a NULL call_data argument.
</para>
<para>
<!-- .LP -->
</para>
</sect3>
<sect3 id="Query_IM_IC_Values_List">
<title>Query IM/IC Values List</title>
<!-- .XS -->
<!-- (SN Query IM/IC Values List -->
<!-- .XE -->
<para>
<!-- .LP -->
<symbol>XNQueryIMValuesList</symbol>
and
<symbol>XNQueryICValuesList</symbol>
are used to query about <acronym>XIM</acronym> and <acronym>XIC</acronym> values supported by the input method.
</para>
<para>
<!-- .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
<structname>XIMValuesList</structname>.
Clients are responsible for freeing the
<structname>XIMValuesList</structname>
structure.
To do so, use
<function>XFree</function>.
</para>
<para>
<!-- .LP -->
The
<structname>XIMValuesList</structname>
structure is defined as follows:
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 2.5i -->
<!-- .ta .5i 2.5i -->
typedef struct {
unsigned short count_values;
char **supported_values;
} XIMValuesList;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
</para>
</sect3>
<sect3 id="Visible_Position">
<title>Visible Position</title>
<!-- .XS -->
<!-- (SN Visible Position -->
<!-- .XE -->
<para>
<!-- .LP -->
The
<symbol>XNVisiblePosition</symbol>
argument indicates whether the visible position masks of
<type>XIMFeedback</type>
in
<structname>XIMText</structname>
are available.
</para>
<para>
<!-- .LP -->
The argument value must be a pointer to a location where the returned
value will be stored. The returned value is of type
<type>Bool</type>.
If the returned value is
<symbol>True</symbol>,
the input method uses the visible position masks of
<type>XIMFeedback</type>
in
<structname>XIMText</structname>;
otherwise, the input method does not use the masks.
</para>
<para>
<!-- .LP -->
Because this <acronym>XIM</acronym> value is optional, a client should call
<function>XGetIMValues</function>
with argument
<symbol>XNQueryIMValuesList</symbol>
before using this argument.
If the
<symbol>XNVisiblePosition</symbol>
does not exist in the IM values list returned from
<symbol>XNQueryIMValuesList</symbol>,
the visible position masks of
<type>XIMFeedback</type>
in
<structname>XIMText</structname>
are not used to indicate the visible position.
</para>
<para>
<!-- .LP -->
</para>
</sect3>
<sect3 id="Preedit_Callback_Behavior">
<title>Preedit Callback Behavior</title>
<!-- .XS -->
<!-- (SN Preedit Callback Behavior -->
<!-- .XE -->
<para>
<!-- .LP -->
The
<symbol>XNR6PreeditCallback</symbol>
argument originally included in the X11R6 specification has been
deprecated.\(dg
<!-- .\" If XNR6PreeditCallbackBehavior is not deprecated, then its type -->
<!-- .\" should be changed from *Bool to Bool. -->
<!-- .FS \(dg -->
During formulation of the X11R6 specification, the behavior of
the R6 PreeditDrawCallbacks was going to differ significantly from
that of the R5 callbacks.
Late changes to the specification converged the R5 and R6 behaviors,
eliminating the need for
<symbol>XNR6PreeditCallback</symbol>.
Unfortunately, this argument was not removed from the R6 specification
before it was published.
<!-- .FE -->
</para>
<para>
<!-- .LP -->
The
<symbol>XNR6PreeditCallback</symbol>
argument indicates whether the behavior of preedit callbacks regarding
<structname>XIMPreeditDrawCallbackStruct</structname>
values follows Release 5 or Release 6 semantics.
</para>
<para>
<!-- .LP -->
The value is of type
<type>Bool</type>.
When querying for
<symbol>XNR6PreeditCallback</symbol>,
if the returned value is
<symbol>True</symbol>,
the input method uses the Release 6 behavior;
otherwise, it uses the Release 5 behavior.
The default value is
<symbol>False</symbol>.
In order to use Release 6 semantics, the value of
<symbol>XNR6PreeditCallback</symbol>
must be set to
<symbol>True</symbol>.
</para>
<para>
<!-- .LP -->
Because this <acronym>XIM</acronym> value is optional, a client should call
<function>XGetIMValues</function>
with argument
<symbol>XNQueryIMValuesList</symbol>
before using this argument.
If the
<symbol>XNR6PreeditCallback</symbol>
does not exist in the IM values list returned from
<symbol>XNQueryIMValuesList</symbol>,
the PreeditCallback behavior is Release 5 semantics.
</para>
<para>
<!-- .LP -->
</para>
</sect3>
</sect2>
<sect2 id="Input_Context_Functions">
<title>Input Context Functions</title>
<!-- .XS -->
<!-- (SN Input Context Functions -->
<!-- .XE -->
<para>
<!-- .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 <acronym>XIC</acronym> values.
It is intended that input methods be controlled by these <acronym>XIC</acronym> values.
As new <acronym>XIC</acronym> values are created,
they should be registered with the X Consortium.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To create an input context, use
<function>XCreateIC</function>.
<indexterm significance="preferred"><primary>XCreateIC</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>XIC <function>XCreateIC</function></funcdef>
<paramdef>XIM<parameter> im</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>im</emphasis>
</term>
<listitem>
<para>
Specifies the input method.
<!-- .ds Al \ to set <acronym>XIC</acronym> values -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
...
</term>
<listitem>
<para>
Specifies the variable length argument list(Al.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XCreateIC</function>
function creates a context within the specified input method.
</para>
<para>
<!-- .LP -->
Some of the arguments are mandatory at creation time, and
the input context will not be created if those arguments are not provided.
The mandatory 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.
</para>
<para>
<!-- .LP -->
<function>XCreateIC</function>
returns a NULL value if no input context could be created.
A NULL value could be returned for any of the following reasons:
</para>
<itemizedlist>
<listitem>
<para>
A required argument was not set.
</para>
</listitem>
<listitem>
<para>
A read-only argument was set (for example,
<symbol>XNFilterEvents</symbol>).
</para>
</listitem>
<listitem>
<para>
The argument name is not recognized.
</para>
</listitem>
<listitem>
<para>
The input method encountered an input method implementation-dependent error.
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
<function>XCreateIC</function>
can generate
<errorname>BadAtom</errorname>,
<errorname>BadColor</errorname>,
<errorname>BadPixmap</errorname>,
and
<errorname>BadWindow</errorname>
errors.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To destroy an input context, use
<function>XDestroyIC</function>.
<indexterm significance="preferred"><primary>XDestroyIC</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function>XDestroyIC</function></funcdef>
<paramdef>XIC<parameter> ic</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>ic</emphasis>
</term>
<listitem>
<para>
Specifies the input context.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
<function>XDestroyIC</function>
destroys the specified input context.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To communicate to and synchronize with input method
for any changes in keyboard focus from the client side,
use
<function>XSetICFocus</function>
and
<function>XUnsetICFocus</function>.
<indexterm significance="preferred"><primary>XSetICFocus</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function>XSetICFocus</function></funcdef>
<paramdef>XIC<parameter> ic</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>ic</emphasis>
</term>
<listitem>
<para>
Specifies the input context.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XSetICFocus</function>
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.
</para>
<para>
<!-- .LP -->
Calling
<function>XSetICFocus</function>
does not affect the focus window value.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<indexterm significance="preferred"><primary>XUnsetICFocus</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function>XUnsetICFocus</function></funcdef>
<paramdef>XIC<parameter> ic</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>ic</emphasis>
</term>
<listitem>
<para>
Specifies the input context.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XUnsetICFocus</function>
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.
</para>
<para>
<!-- .LP -->
Calling
<function>XUnsetICFocus</function>
does not affect the focus window value;
the client may still receive
events from the input method that are directed to the focus window.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To reset the state of an input context to its initial state, use
<function>XmbResetIC</function>
or
<function>XwcResetIC</function>.
<indexterm significance="preferred"><primary>XmbResetIC</primary></indexterm>
<indexterm significance="preferred"><primary>XwcResetIC</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>char *<function>XmbResetIC</function></funcdef>
<paramdef>XIC<parameter> ic</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<funcsynopsis>
<funcprototype>
<funcdef>wchar_t *<function>XwcResetIC</function></funcdef>
<paramdef>XIC<parameter> ic</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>ic</emphasis>
</term>
<listitem>
<para>
Specifies the input context.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
When
<symbol>XNResetState</symbol>
is set to
<symbol>XIMInitialState</symbol>,
<function>XmbResetIC</function>
and
<function>XwcResetIC</function>
reset an input context to its initial state;
when
<symbol>XNResetState</symbol>
is set to
<symbol>XIMPreserveState</symbol>,
the current input context state is preserved.
In both cases, any input pending on that context is deleted.
The input method is required to clear the preedit area, if any,
and update the status accordingly.
Calling
<function>XmbResetIC</function>
or
<function>XwcResetIC</function>
does not change the focus.
</para>
<para>
<!-- .LP -->
The return value of
<function>XmbResetIC</function>
is its current preedit string as a multibyte string.
If there is any preedit text drawn or visible to the user,
then these procedures must return a non-NULL string.
If there is no visible preedit text,
then it is input method implementation-dependent
whether these procedures return a non-NULL string or NULL.
</para>
<para>
<!-- .LP -->
The client should free the returned string by calling
<function>XFree</function>.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To get the input method associated with an input context, use
<function>XIMOfIC</function>.
<indexterm significance="preferred"><primary>XIMOfIC</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>XIM <function>XIMOfIC</function></funcdef>
<paramdef>XIC<parameter> ic</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>ic</emphasis>
</term>
<listitem>
<para>
Specifies the input context.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XIMOfIC</function>
function returns the input method associated with the specified input context.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
Xlib provides two functions for setting and reading <acronym>XIC</acronym> values, respectively,
<function>XSetICValues</function>
and
<function>XGetICValues</function>.
Both functions have a variable-length argument list.
In that argument list, any <acronym>XIC</acronym> value's name must be denoted
with a character string using the X Portable Character Set.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To set <acronym>XIC</acronym> values, use
<function>XSetICValues</function>.
<indexterm significance="preferred"><primary>XSetICValues</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>char *<function>XSetICValues</function></funcdef>
<paramdef>XIC<parameter> ic</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>ic</emphasis>
</term>
<listitem>
<para>
Specifies the input context.
<!-- .ds Al \ to set <acronym>XIC</acronym> values -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
...
</term>
<listitem>
<para>
Specifies the variable length argument list(Al.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XSetICValues</function>
function returns NULL if no error occurred;
otherwise,
it returns the name of the first argument that could not be set.
An argument might not be set for any of the following reasons:
</para>
<itemizedlist>
<listitem>
<para>
The argument is read-only (for example,
<symbol>XNFilterEvents</symbol>).
</para>
</listitem>
<listitem>
<para>
The argument name is not recognized.
</para>
</listitem>
<listitem>
<para>
An implementation-dependent error occurs.
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
Each value to be set must be an appropriate datum,
matching the data type imposed by the semantics of the argument.
</para>
<para>
<!-- .LP -->
<function>XSetICValues</function>
can generate
<errorname>BadAtom</errorname>,
<errorname>BadColor</errorname>,
<errorname>BadCursor</errorname>,
<errorname>BadPixmap</errorname>,
and
<errorname>BadWindow</errorname>
errors.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To obtain <acronym>XIC</acronym> values, use
<function>XGetICValues</function>.
<indexterm significance="preferred"><primary>XGetICValues</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>char *<function>XGetICValues</function></funcdef>
<paramdef>XIC<parameter> ic</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>ic</emphasis>
</term>
<listitem>
<para>
Specifies the input context.
<!-- .ds Al \ to get XIC values -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
...
</term>
<listitem>
<para>
Specifies the variable length argument list(Al.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XGetICValues</function>
function returns NULL if no error occurred; otherwise,
it returns the name of the first argument that could not be obtained.
An argument could not be obtained for any of the following reasons:
</para>
<itemizedlist>
<listitem>
<para>
The argument name is not recognized.
</para>
</listitem>
<listitem>
<para>
The input method encountered an implementation-dependent error.
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
Each IC attribute value argument (following a name) must point to
a location where the IC value is to be stored.
That is, if the IC value is of type T,
the argument must be of type T*.
If T itself is a pointer type,
then
<function>XGetICValues</function>
allocates memory to store the actual data,
and the client is responsible for freeing this data by calling
<function>XFree</function>
with the returned pointer.
The exception to this rule is for an IC value of type
<type>XVaNestedList</type>
(for preedit and status attributes).
In this case, the argument must also be of type
<type>XVaNestedList</type>.
Then, the rule of changing type T to T* and freeing the allocated data
applies to each element of the nested list.
</para>
</sect2>
<sect2 id="Input_Context_Values">
<title>Input Context Values</title>
<!-- .XS -->
<!-- (SN Input Context Values -->
<!-- .XE -->
<para>
<!-- .LP -->
The following tables describe how <acronym>XIC</acronym> values are interpreted
by an input method depending on the input style chosen by the
user.
</para>
<para>
<!-- .LP -->
The first column lists the <acronym>XIC</acronym> 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 <acronym>XIC</acronym> values
are treated by that input style.
</para>
<para>
<!-- .LP -->
The following keys apply to these tables.
</para>
<informaltable>
<tgroup cols='2' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<thead>
<row>
<entry>Key</entry>
<entry>Explanation</entry>
</row>
</thead>
<tbody>
<row>
<entry>C</entry>
<entry>This value must be set with <function>XCreateIC</function>.</entry>
</row>
<row>
<entry>D</entry>
<entry>This value may be set using
<function>XCreateIC</function>.>
If it is not set,>
a default is provided.</entry>
</row>
<row>
<entry>G</entry>
<entry>This value may be read using
<function>XGetICValues</function>.</entry>
</row>
<row>
<entry>GN</entry>
<entry>This value may cause geometry negotiation when its value is set by means of
<function>XCreateIC</function>
or
<function>XSetICValues</function>.</entry>
</row>
<row>
<entry>GR</entry>
<entry>This value will be the response of the input method when any
GN value is changed.</entry>
</row>
<row>
<entry>GS</entry>
<entry>This value will cause the geometry of the input method window to be set.</entry>
</row>
<row>
<entry>O</entry>
<entry>This value must be set once and only once.
It need not be set at create time.</entry>
</row>
<row>
<entry>S</entry>
<entry>This value may be set with
<function>XSetICValues</function>.</entry>
</row>
<row>
<entry>Ignored</entry>
<entry>This value is ignored by the input method for the given input style.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<!-- .LP -->
<informaltable>
<tgroup cols='7' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<colspec colname='c3'/>
<colspec colname='c4'/>
<colspec colname='c5'/>
<colspec colname='c6'/>
<colspec colname='c7'/>
<tbody>
<row>
<entry><acronym>XIC</acronym> Value</entry>
<entry>Geometry Mangement</entry>
<entry>Preedit Callback</entry>
<entry>Preedit Position</entry>
<entry>Input Style Preedit Area</entry>
<entry>Preedit Nothing</entry>
<entry>Preedit None</entry>
</row>
<row>
<entry>Input Style</entry>
<entry></entry>
<entry>C-G</entry>
<entry>C-G</entry>
<entry>C-G</entry>
<entry>C-G</entry>
<entry>C-G</entry>
</row>
<row>
<entry>Client Window</entry>
<entry></entry>
<entry>O-G</entry>
<entry>O-G</entry>
<entry>O-G</entry>
<entry>O-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Focus Window</entry>
<entry>GN</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Resource Name</entry>
<entry></entry>
<entry>Ignored</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Resource Class</entry>
<entry></entry>
<entry>Ignored</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Geometry Callback</entry>
<entry></entry>
<entry>Ignored</entry>
<entry>Ignored</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Filter Events</entry>
<entry></entry>
<entry>G</entry>
<entry>G</entry>
<entry>G</entry>
<entry>G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Destroy Callback</entry>
<entry></entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
</row>
<row>
<entry>String Conversion Callback</entry>
<entry></entry>
<entry>S-G</entry>
<entry>S-G</entry>
<entry>S-G</entry>
<entry>S-G</entry>
<entry>S-G</entry>
</row>
<row>
<entry>String Conversion</entry>
<entry></entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
</row>
<row>
<entry>Reset State</entry>
<entry></entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>HotKey</entry>
<entry></entry>
<entry>S-G</entry>
<entry>S-G</entry>
<entry>S-G</entry>
<entry>S-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>HotKeyState</entry>
<entry></entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry><function>Preedit</function></entry>
</row>
<row>
<entry>Area</entry>
<entry>GS</entry>
<entry>Ignored</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Area Needed</entry>
<entry>GN-GR</entry>
<entry>Ignored</entry>
<entry>Ignored</entry>
<entry>S-G</entry>
<entry>Ignored</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Spot Location</entry>
<entry></entry>
<entry>Ignored</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
<entry>Ignored</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Colormap</entry>
<entry></entry>
<entry>Ignored</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Foreground</entry>
<entry></entry>
<entry>Ignored</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Background</entry>
<entry></entry>
<entry>Ignored</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Background Pixmap</entry>
<entry></entry>
<entry>Ignored</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Font Set</entry>
<entry>GN</entry>
<entry>Ignored</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Line Spacing</entry>
<entry>GN</entry>
<entry>Ignored</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Cursor</entry>
<entry></entry>
<entry>Ignored</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Preedit State</entry>
<entry></entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Preedit State Notify Callback</entry>
<entry></entry>
<entry>S-G</entry>
<entry>S-G</entry>
<entry>S-G</entry>
<entry>S-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Preedit Callbacks</entry>
<entry></entry>
<entry>C-S-G</entry>
<entry>Ignored</entry>
<entry>Ignored</entry>
<entry>Ignored</entry>
<entry>Ignored</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<!-- .LP -->
<informaltable>
<tgroup cols='6' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<colspec colname='c3'/>
<colspec colname='c4'/>
<colspec colname='c5'/>
<colspec colname='c6'/>
<thead>
<row>
<entry><acronym>XIC</acronym> Value</entry>
<entry>Geomentry Management</entry>
<entry>Status Callback</entry>
<entry>Status Area</entry>
<entry>Status Nothing</entry>
<entry>Status None</entry>
</row>
</thead>
<tbody>
<row>
<entry>Input Style</entry>
<entry></entry>
<entry>C-G</entry>
<entry>C-G</entry>
<entry>C-G</entry>
<entry>C-G</entry>
</row>
<row>
<entry>Client Window</entry>
<entry></entry>
<entry>O-G</entry>
<entry>O-G</entry>
<entry>O-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Focus Window</entry>
<entry>GN</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Resource Name</entry>
<entry></entry>
<entry>Ignored</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Resource Class</entry>
<entry></entry>
<entry>Ignored</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Geometry Callback</entry>
<entry></entry>
<entry>Ignored</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Filter Events</entry>
<entry></entry>
<entry>G</entry>
<entry>G</entry>
<entry>G</entry>
<entry>G</entry>
</row>
<row>
<entry><type>Status</type></entry>
</row>
<row>
<entry>Area</entry>
<entry>GS</entry>
<entry>Ignored</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Area Needed</entry>
<entry>GN-GR</entry>
<entry>Ignored</entry>
<entry>S-G</entry>
<entry>Ignored</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Colormap</entry>
<entry></entry>
<entry>Ignored</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Foreground</entry>
<entry></entry>
<entry>Ignored</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Background</entry>
<entry></entry>
<entry>Ignored</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Background Pixmap</entry>
<entry></entry>
<entry>Ignored</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Font Set</entry>
<entry>GN</entry>
<entry>Ignored</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Line Spacing</entry>
<entry>GN</entry>
<entry>Ignored</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Cursor</entry>
<entry></entry>
<entry>Ignored</entry>
<entry>D-S-G</entry>
<entry>D-S-G</entry>
<entry>Ignored</entry>
</row>
<row>
<entry>Status Callbacks</entry>
<entry></entry>
<entry>C-S-G</entry>
<entry>Ignored</entry>
<entry>Ignored</entry>
<entry>Ignored</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<sect3 id="Input_Style">
<title>Input Style</title>
<!-- .XS -->
<!-- (SN Input Style -->
<!-- .XE -->
<para>
<!-- .LP -->
The
<symbol>XNInputStyle</symbol>
argument specifies the input style to be used.
The value of this argument must be one of the values returned by the
<function>XGetIMValues</function>
function with the
<symbol>XNQueryInputStyle</symbol>
argument specified in the supported_styles list.
</para>
<para>
<!-- .LP -->
Note that this argument must be set at creation time
and cannot be changed.
</para>
</sect3>
<sect3 id="Client_Window">
<title>Client Window</title>
<!-- .XS -->
<!-- (SN Client Window -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XNClientWindow</primary></indexterm>
The
<symbol>XNClientWindow</symbol>
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.
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.
</para>
<para>
<!-- .LP -->
If an attempt is made to set this value a second time with
<function>XSetICValues</function>,
the string
<symbol>XNClientWindow</symbol>
will be returned by
<function>XSetICValues</function>,
and the client window will not be changed.
</para>
<para>
<!-- .LP -->
If the client window is not a valid window ID on the display
attached to the input method,
a
<errorname>BadWindow</errorname>
error can be generated when this value is used by the input method.
</para>
</sect3>
<sect3 id="Focus_Window">
<title>Focus Window</title>
<!-- .XS -->
<!-- (SN Focus Window -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XNFocusWindow</primary></indexterm>
The
<symbol>XNFocusWindow</symbol>
argument specifies the focus window.
The primary purpose of the
<symbol>XNFocusWindow</symbol>
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:
</para>
<itemizedlist>
<listitem>
<para>
Select events on it
</para>
</listitem>
<listitem>
<para>
Send events to it
</para>
</listitem>
<listitem>
<para>
Modify its properties
</para>
</listitem>
<listitem>
<para>
Grab the keyboard within that window
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
The associated value must be of type
<type>Window</type>.
If the focus window is not a valid window ID on the display
attached to the input method,
a
<errorname>BadWindow</errorname>
error can be generated when this value is used by the input method.
</para>
<para>
<!-- .LP -->
When this <acronym>XIC</acronym> value is left unspecified,
the input method will use the client window as the default focus window.
</para>
</sect3>
<sect3 id="Resource_Name_and_Class_b">
<title>Resource Name and Class</title>
<!-- .XS -->
<!-- (SN Resource Name and Class -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XNResourceName</primary></indexterm>
<indexterm significance="preferred"><primary>XNResourceClass</primary></indexterm>
The
<symbol>XNResourceName</symbol>
and
<symbol>XNResourceClass</symbol>
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.
</para>
<para>
<!-- .LP -->
It is not intended that values that can be set as <acronym>XIC</acronym> values be
set as resources.
</para>
</sect3>
<sect3 id="Geometry_Callback">
<title>Geometry Callback</title>
<!-- .XS -->
<!-- (SN Geometry Callback -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XNGeometryCallback</primary></indexterm>
The
<symbol>XNGeometryCallback</symbol>
argument is a structure of type
<structname>XIMCallback</structname>
(see section 13.5.6.13.12).
</para>
<para>
<!-- .LP -->
The
<symbol>XNGeometryCallback</symbol>
argument specifies the geometry callback that 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
method's window.
An input method that does dynamic change will need to filter any
events that it uses to initiate the change.
</para>
</sect3>
<sect3 id="Filter_Events">
<title>Filter Events</title>
<!-- .XS -->
<!-- (SN Filter Events -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XNFilterEvents</primary></indexterm>
The
<symbol>XNFilterEvents</symbol>
argument returns the event mask that an input method needs
to have selected for.
The client is expected to augment its own event mask
for the client window with this one.
</para>
<para>
<!-- .LP -->
This argument is read-only, is set by the input method at create time,
and is never changed.
</para>
<para>
<!-- .LP -->
The type of this argument is
<type>unsigned</type>
<type>long</type>.
Setting this value will cause an error.
</para>
</sect3>
<sect3 id="Destroy_Callback_b">
<title>Destroy Callback</title>
<!-- .XS -->
<!-- (SN Destroy Callback -->
<!-- .XE -->
<para>
<!-- .LP -->
The
<symbol>XNDestroyCallback</symbol>
argument is a pointer to a structure of type
<structname>XIMCallback</structname>
(see section 13.5.6.13.12). This callback is triggered when the input method
stops its service for any reason; for example, when a connection to an IM
server is broken. After the destroy callback is called,
the input context is destroyed and the input method is closed.
Therefore, the client should not call
<function>XDestroyIC</function>
and
<function>XCloseIM</function>.
</para>
<para>
<!-- .LP -->
</para>
</sect3>
<sect3 id="String_Conversion_Callback">
<title>String Conversion Callback</title>
<!-- .XS -->
<!-- (SN String Conversion Callback -->
<!-- .XE -->
<para>
<!-- .LP -->
The
<symbol>XNStringConversionCallback</symbol>
argument is a structure of type
<structname>XIMCallback</structname>
(see section 13.5.6.13.12).
</para>
<para>
<!-- .LP -->
The
<symbol>XNStringConversionCallback</symbol>
argument specifies a string conversion callback. This callback
is not required for correct operation of
either the input method or the client. It can be set by a client
to support string conversions that may be requested
by the input method. An input method that does string conversions
will filter any events that it uses to initiate the conversion.
</para>
<para>
<!-- .LP -->
Because this <acronym>XIC</acronym> value is optional, a client should call
<function>XGetIMValues</function>
with argument
<symbol>XNQueryICValuesList</symbol>
before using this argument.
</para>
<para>
<!-- .LP -->
</para>
</sect3>
<sect3 id="String_Conversion_">
<title>String Conversion </title>
<!-- .XS -->
<!-- (SN String Conversion -->
<!-- .XE -->
<para>
<!-- .LP -->
The
<symbol>XNStringConversion</symbol>
argument is a structure of type
<structname>XIMStringConversionText</structname>.
</para>
<para>
<!-- .LP -->
The
<symbol>XNStringConversion</symbol>
argument specifies the string to be converted by an input method.
This argument is not required for correct operation of either
the input method or the client.
</para>
<para>
<!-- .LP -->
String conversion facilitates the manipulation of text independent
of preediting.
It is essential for some input methods and clients to manipulate
text by performing context-sensitive conversion,
reconversion, or transliteration conversion on it.
</para>
<para>
<!-- .LP -->
Because this <acronym>XIC</acronym> value is optional, a client should call
<function>XGetIMValues</function>
with argument
<symbol>XNQueryICValuesList</symbol>
before using this argument.
</para>
<para>
<!-- .LP -->
The
<structname>XIMStringConversionText</structname>
structure is defined as follows:
</para>
<para>
<!-- .LP -->
<!-- .sM -->
<literallayout class="monospaced">
typedef struct _XIMStringConversionText {
unsigned short length;
XIMStringConversionFeedback *feedback;
Bool encoding_is_wchar;
union {
char *mbs;
wchar_t *wcs;
} string;
} XIMStringConversionText;
typedef unsigned long XIMStringConversionFeedback;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The feedback member is reserved for future use. The text to be
converted is defined by the string and length members. The length
is indicated in characters. To prevent the library from freeing memory
pointed to by an uninitialized pointer, the client should set the feedback
element to NULL.
</para>
<para>
<!-- .LP -->
</para>
</sect3>
<sect3 id="Reset_State">
<title>Reset State</title>
<!-- .XS -->
<!-- (SN Reset State -->
<!-- .XE -->
<para>
<!-- .LP -->
The
<symbol>XNResetState</symbol>
argument specifies the state the input context will return to after calling
<function>XmbResetIC</function>
or
<function>XwcResetIC</function>.
</para>
<para>
<!-- .LP -->
The <acronym>XIC</acronym> state may be set to its initial state, as specified by the
<symbol>XNPreeditState</symbol>
value when
<function>XCreateIC</function>
was called, or it may be set to preserve the current state.
</para>
<para>
<!-- .LP -->
The valid masks for
<type>XIMResetState</type>
are as follows:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XIMInitialState</primary></indexterm>
<indexterm significance="preferred"><primary>XINPreserveState</primary></indexterm>
<!-- .sM -->
</para>
<literallayout class="monospaced">
typedef unsigned long XIMResetState;
#define XIMInitialState (1L)
#define XIMPreserveState (1L<<1)
</literallayout>
<para>
<!-- .LP -->
<!-- .eM -->
If
<symbol>XIMInitialState</symbol>
is set, then
<function>XmbResetIC</function>
and
<function>XwcResetIC</function>
will return to the initial
<symbol>XNPreeditState</symbol>
state of the <acronym>XIC</acronym>.
</para>
<para>
<!-- .LP -->
If
<symbol>XIMPreserveState</symbol>
is set, then
<function>XmbResetIC</function>
and
<function>XwcResetIC</function>
will preserve the current state of the <acronym>XIC</acronym>.
</para>
<para>
<!-- .LP -->
If
<symbol>XNResetState</symbol>
is left unspecified, the default is
<symbol>XIMInitialState</symbol>.
</para>
<para>
<!-- .LP -->
<type>XIMResetState</type>
values other than those specified above will default to
<symbol>XIMInitialState</symbol>.
</para>
<para>
<!-- .LP -->
Because this <acronym>XIC</acronym> value is optional, a client should call
<function>XGetIMValues</function>
with argument
<symbol>XNQueryICValuesList</symbol>
before using this argument.
</para>
<para>
<!-- .LP -->
</para>
</sect3>
<sect3 id="Hot_Keys_b">
<title>Hot Keys</title>
<!-- .XS -->
<!-- (SN Hot Keys -->
<!-- .XE -->
<para>
<!-- .LP -->
The
<symbol>XNHotKey</symbol>
argument specifies the hot key list to the <acronym>XIC</acronym>.
The hot key list is a pointer to the structure of type
<structname>XIMHotKeyTriggers</structname>,
which specifies the key events that must be received
without any interruption of the input method.
For the hot key list set with this argument to be utilized, the client
must also set
<symbol>XNHotKeyState</symbol>
to
<symbol>XIMHotKeyStateON</symbol>.
</para>
<para>
<!-- .LP -->
Because this <acronym>XIC</acronym> value is optional, a client should call
<function>XGetIMValues</function>
with argument
<symbol>XNQueryICValuesList</symbol>
before using this functionality.
</para>
<para>
<!-- .LP -->
The value of the argument is a pointer to a structure of type
<structname>XIMHotKeyTriggers</structname>.
</para>
<para>
<!-- .LP -->
If an event for a key in the hot key list is found, then the process will
receive the event and it will be processed inside the client.
</para>
<para>
<!-- .LP -->
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 2.5i -->
<!-- .ta .5i 2.5i -->
typedef struct {
KeySym keysym;
unsigned int modifier;
unsigned int modifier_mask;
} XIMHotKeyTrigger;
typedef struct {
int num_hot_key;
XIMHotKeyTrigger *key;
} XIMHotKeyTriggers;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
</para>
<para>
<!-- .LP -->
The combination of modifier and modifier_mask are used to represent one of
three states for each modifier:
either the modifier must be on, or the modifier must be off, or the modifier
is a ``don't care'' - it may be on or off.
When a modifier_mask bit is set to 0, the state of the associated modifier
is ignored when evaluating whether the key is hot or not.
</para>
<informaltable>
<tgroup cols='3' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<colspec colname='c3'/>
<thead>
<row>
<entry>Modifier Bit</entry>
<entry>Mask Bit</entry>
<entry>Meaning</entry>
</row>
</thead>
<tbody>
<row>
<entry>0</entry>
<entry>1</entry>
<entry>The modifier must be off.</entry>
</row>
<row>
<entry>1</entry>
<entry>1</entry>
<entry>The modifier must be on.</entry>
</row>
<row>
<entry>n/a</entry>
<entry>0</entry>
<entry>Do not care if the modifier is on or off.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect3>
<sect3 id="Hot_Key_State">
<title>Hot Key State</title>
<!-- .XS -->
<!-- (SN Hot Key State -->
<!-- .XE -->
<para>
<!-- .LP -->
The
<symbol>XNHotKeyState</symbol>
argument specifies the hot key state of the input method.
This is usually used to switch the input method between hot key
operation and normal input processing.
</para>
<para>
<!-- .LP -->
The value of the argument is a pointer to a structure of type
XIMHotKeyState .
</para>
<literallayout class="monospaced">
typedef unsigned long XIMHotKeyState;
#define XIMHotKeyStateON (0x0001L)
#define XIMHotKeyStateOFF (0x0002L)
</literallayout>
<para>
<!-- .LP -->
<!-- .eM -->
</para>
<para>
<!-- .LP -->
If not specified, the default is
<symbol>XIMHotKeyStateOFF</symbol>.
</para>
<para>
<!-- .LP -->
</para>
</sect3>
<sect3 id="Preedit_and_Status_Attributes">
<title>Preedit and Status Attributes</title>
<!-- .XS -->
<!-- (SN Preedit and Status Attributes -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XNPreeditAttributes</primary></indexterm>
<indexterm significance="preferred"><primary>XNStatusAttributes</primary></indexterm>
The
<symbol>XNPreeditAttributes</symbol>
and
<symbol>XNStatusAttributes</symbol>
arguments specify to an input method the attributes to be used for the
preedit and status areas,
if any.
Those attributes are passed to
<function>XSetICValues</function>
or
<function>XGetICValues</function>
as a nested variable-length list.
The names to be used in these lists are described in the following sections.
</para>
<sect4 id="Area">
<title>Area</title>
<!-- .XS -->
<!-- (SN Area -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XNArea</primary></indexterm>
The value of the
<symbol>XNArea</symbol>
argument must be a pointer to a structure of type
<structname>XRectangle</structname>.
The interpretation of the
<symbol>XNArea</symbol>
argument is dependent on the input method style that has been set.
</para>
<para>
<!-- .LP -->
If the input method style is
<symbol>XIMPreeditPosition</symbol>,
<symbol>XNArea</symbol>
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.
</para>
<para>
<!-- .LP -->
If
<symbol>XNArea</symbol>
is not specified, is set to NULL, or is invalid,
the input method will default the clipping region
to the geometry of the
<symbol>XNFocusWindow</symbol>.
If the area specified is NULL or invalid,
the results are undefined.
</para>
<para>
<!-- .LP -->
If the input style is
<symbol>XIMPreeditArea</symbol>
or
<symbol>XIMStatusArea</symbol>,
<symbol>XNArea</symbol>
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
<symbol>XNArea</symbol>.
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
<symbol>XNArea</symbol>
is not specified, is set to NULL, or is invalid,
the results are undefined.
</para>
</sect4>
<sect4 id="Area_Needed">
<title>Area Needed</title>
<!-- .XS -->
<!-- (SN Area Needed -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XNAreaNeeded</primary></indexterm>
When set, the
<symbol>XNAreaNeeded</symbol>
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
<structname>XRectangle</structname>.
Note that the x, y values are not used
and that nonzero values for width or height are the constraints
that the client wishes the input method to respect.
</para>
<para>
<!-- .LP -->
When read, the
<symbol>XNAreaNeeded</symbol>
argument specifies the preferred geometry desired by the input method
for the area.
</para>
<para>
<!-- .LP -->
This argument is only valid if the input style is
<symbol>XIMPreeditArea</symbol>
or
<symbol>XIMStatusArea</symbol>.
It is used for geometry negotiation between the client and the input method
and has no other effect on the input method
(see section 13.5.1.5).
</para>
</sect4>
<sect4 id="Spot_Location">
<title>Spot Location</title>
<!-- .XS -->
<!-- (SN Spot Location -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XNSpotLocation</primary></indexterm>
The
<symbol>XNSpotLocation</symbol>
argument specifies to the input method the coordinates of the spot
to be used by an input method executing with
<symbol>XNInputStyle</symbol>
set to
<symbol>XIMPreeditPosition</symbol>.
When specified to any input method other than
<symbol>XIMPreeditPosition</symbol>,
this <acronym>XIC</acronym> value is ignored.
</para>
<para>
<!-- .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 the 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.
</para>
<para>
<!-- .LP -->
The value of the argument is a pointer to a structure of type
<structname>XPoint</structname>.
</para>
</sect4>
<sect4 id="Colormap">
<title>Colormap</title>
<!-- .XS -->
<!-- (SN Colormap -->
<!-- .XE -->
<para>
<!-- .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.
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XNColormap</primary></indexterm>
The
<symbol>XNColormap</symbol>
argument is used to specify a colormap ID.
The argument value is of type
<type>Colormap</type>.
An invalid argument may generate a
<errorname>BadColor</errorname>
error when it is used by the input method.
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XNStdColormap</primary></indexterm>
The
<symbol>XNStdColormap</symbol>
argument is used to indicate the name of the standard colormap
in which the input method should allocate colors.
The argument value is an
<type>Atom</type>
that should be a valid atom for calling
<function>XGetRGBColormaps</function>.
An invalid argument may generate a
<errorname>BadAtom</errorname>
error when it is used by the input method.
</para>
<para>
<!-- .LP -->
If the colormap is left unspecified,
the client window colormap becomes the default.
</para>
</sect4>
<sect4 id="Foreground_and_Background">
<title>Foreground and Background</title>
<!-- .XS -->
<!-- (SN Foreground and Background -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XNForeground</primary></indexterm>
<indexterm significance="preferred"><primary>XNBackground</primary></indexterm>
The
<symbol>XNForeground</symbol>
and
<symbol>XNBackground</symbol>
arguments specify the foreground and background pixel, respectively.
The argument value is of type
<type>unsigned</type>
<type>long</type>.
It must be a valid pixel in the input method colormap.
</para>
<para>
<!-- .LP -->
If these values are left unspecified,
the default is determined by the input method.
</para>
</sect4>
<sect4 id="Background_Pixmap">
<title>Background Pixmap</title>
<!-- .XS -->
<!-- (SN Background Pixmap -->
<!-- .XE -->
<para>
<!-- .LP -->
The
<symbol>XNBackgroundPixmap</symbol>
argument specifies a background pixmap to be used as the background of the
window.
The value must be of type
<type>Pixmap</type>.
An invalid argument may generate a
<errorname>BadPixmap</errorname>
error when it is used by the input method.
</para>
<para>
<!-- .LP -->
If this value is left unspecified,
the default is determined by the input method.
</para>
</sect4>
<sect4 id="Font_Set">
<title>Font Set</title>
<!-- .XS -->
<!-- (SN Font Set -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XNFontSet</primary></indexterm>
The
<symbol>XNFontSet</symbol>
argument specifies to the input method what font set is to be used.
The argument value is of type
<type>XFontSet</type>.
</para>
<para>
<!-- .LP -->
If this value is left unspecified,
the default is determined by the input method.
</para>
</sect4>
<sect4 id="Line_Spacing">
<title>Line Spacing</title>
<!-- .XS -->
<!-- (SN Line Spacing -->
<!-- .XE -->
<para>
<!-- .LP -->
The
<symbol>XNLineSpace</symbol>
argument specifies to the input method what line spacing is to be used
in the preedit window if more than one line is to be used.
This argument is of type
<type>int</type>.
</para>
<para>
<!-- .LP -->
If this value is left unspecified,
the default is determined by the input method.
</para>
</sect4>
<sect4 id="Cursor">
<title>Cursor</title>
<!-- .XS -->
<!-- (SN Cursor -->
<!-- .XE -->
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XNCursor</primary></indexterm>
The
<symbol>XNCursor</symbol>
argument specifies to the input method what cursor is to be used
in the specified window.
This argument is of type
<type>Cursor</type>.
</para>
<para>
<!-- .LP -->
An invalid argument may generate a
<errorname>BadCursor</errorname>
error when it is used by the input method.
If this value is left unspecified,
the default is determined by the input method.
</para>
</sect4>
<sect4 id="Preedit_State">
<title>Preedit State</title>
<!-- .XS -->
<!-- (SN Preedit State -->
<!-- .XE -->
<para>
<!-- .LP -->
The
<symbol>XNPreeditState</symbol>
argument specifies the state of input preediting for the input method.
Input preediting can be on or off.
</para>
<para>
<!-- .LP -->
The valid mask names for
<symbol>XNPreeditState</symbol>
are as follows:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XIMPreeditUnknown</primary></indexterm>
<indexterm significance="preferred"><primary>XIMPreeditEnable</primary></indexterm>
<indexterm significance="preferred"><primary>XIMPreeditDisable</primary></indexterm>
<!-- .sM -->
</para>
<!-- .LP -->
<literallayout class="monospaced">
typedef unsigned long XIMPreeditState;
#define XIMPreeditUnknown 0L
#define XIMPreeditEnable 1L
#define XIMPreeditDisable (1L<<1)
</literallayout>
<para>
<!-- .LP -->
<!-- .eM -->
If a value of
<symbol>XIMPreeditEnable</symbol>
is set, then input preediting is turned on by the input method.
</para>
<para>
<!-- .LP -->
If a value of
<symbol>XIMPreeditDisable</symbol>
is set, then input preediting is turned off by the input method.
</para>
<para>
<!-- .LP -->
If
<symbol>XNPreeditState</symbol>
is left unspecified, then the state will be implementation-dependent.
</para>
<para>
<!-- .LP -->
When
<symbol>XNResetState</symbol>
is set to
<symbol>XIMInitialState</symbol>,
the
<symbol>XNPreeditState</symbol>
value specified at the creation time will be reflected as the initial state for
<function>XmbResetIC</function>
and
<function>XwcResetIC</function>.
</para>
<para>
<!-- .LP -->
Because this <acronym>XIC</acronym> value is optional, a client should call
<function>XGetIMValues</function>
with argument
<symbol>XNQueryICValuesList</symbol>
before using this argument.
</para>
</sect4>
<sect4 id="Preedit_State_Notify_Callback">
<title>Preedit State Notify Callback</title>
<!-- .XS -->
<!-- (SN Preedit State Notify Callback -->
<!-- .XE -->
<para>
<!-- .LP -->
The preedit state notify callback is triggered by the input method
when the preediting state has changed.
The value of the
<symbol>XNPreeditStateNotifyCallback</symbol>
argument is a pointer to a structure of type
<structname>XIMCallback</structname>.
The generic prototype is as follows:
<indexterm significance="preferred"><primary>PreeditStateNotifyCallback</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function><replaceable>PreeditStateNotifyCallback</replaceable></function></funcdef>
<paramdef>XIC<parameter> ic</parameter></paramdef>
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
<paramdef>XIMPreeditStateNotifyCallbackStruct<parameter> *call_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>ic</emphasis>
</term>
<listitem>
<para>
Specifies the input context.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>client_data</emphasis>
</term>
<listitem>
<para>
Specifies the additional client data.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>call_data</emphasis>
</term>
<listitem>
<para>
Specifies the current preedit state.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<structname>XIMPreeditStateNotifyCallbackStruct</structname>
structure is defined as follows:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XIMPreeditStateNotifyCallbackStruct</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 2.5i -->
<!-- .ta .5i 2.5i -->
typedef struct _XIMPreeditStateNotifyCallbackStruct {
XIMPreeditState state;
} XIMPreeditStateNotifyCallbackStruct;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
</para>
<para>
<!-- .LP -->
Because this <acronym>XIC</acronym> value is optional, a client should call
<function>XGetIMValues</function>
with argument
<symbol>XNQueryICValuesList</symbol>
before using this argument.
</para>
</sect4>
<sect4 id="Preedit_and_Status_Callbacks">
<title>Preedit and Status Callbacks</title>
<!-- .XS -->
<!-- (SN Preedit and Status Callbacks -->
<!-- .XE -->
<para>
<!-- .LP -->
A client that wants to support the input style
<symbol>XIMPreeditCallbacks</symbol>
must provide a set of preedit callbacks to the input method.
The set of preedit callbacks is as follows:
</para>
<indexterm significance="preferred"><primary>XNPreeditStartCallback</primary></indexterm>
<indexterm significance="preferred"><primary>XNPreeditDoneCallback</primary></indexterm>
<indexterm significance="preferred"><primary>XNPreeditDrawCallback</primary></indexterm>
<indexterm significance="preferred"><primary>XNPreeditCaretCallback</primary></indexterm>
<informaltable>
<tgroup cols='2' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<tbody>
<row>
<entry><symbol>XNPreeditStartCallback</symbol></entry>
<entry>This is called when the input method starts preedit.</entry>
</row>
<row>
<entry><symbol>XNPreeditDoneCallback</symbol></entry>
<entry>This is called when the input method stops preedit.</entry>
</row>
<row>
<entry><symbol>XNPreeditDrawCallback</symbol></entry>
<entry>This is called when a number of preedit keystrokes should be echoed.</entry>
</row>
<row>
<entry><symbol>XNPreeditCaretCallback</symbol></entry>
<entry>This is called to move the text insertion point within the preedit string.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
<!-- .LP -->
A client that wants to support the input style
<symbol>XIMStatusCallbacks</symbol>
must provide a set of status callbacks to the input method.
The set of status callbacks is as follows:
</para>
<indexterm significance="preferred"><primary>XNStatusStartCallback</primary></indexterm>
<indexterm significance="preferred"><primary>XNStatusDoneCallback</primary></indexterm>
<indexterm significance="preferred"><primary>XNStatusDrawCallback</primary></indexterm>
<informaltable>
<tgroup cols='2' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<tbody>
<row>
<entry><symbol>XNStatusStartCallback</symbol></entry>
<entry>This is called when the input method initializes the status area.</entry>
</row>
<row>
<entry><symbol>XNStatusDoneCallback</symbol></entry>
<entry>This is called when the input method no longer needs the status area.</entry>
</row>
<row>
<entry><symbol>XNStatusDrawCallback</symbol></entry>
<entry>This is called when updating of the status area is required.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
<!-- .LP -->
The value of any status or preedit argument is a pointer
to a structure of type
<structname>XIMCallback</structname>.
<indexterm significance="preferred"><primary>XIMProc</primary></indexterm>
<indexterm significance="preferred"><primary>XIMCallback</primary></indexterm>
<!-- .sM -->
</para>
<para>
<!-- .LP -->
<literallayout class="monospaced">
<!-- .TA .5i 2.5i -->
<!-- .ta .5i 2.5i -->
typedef void (*XIMProc)();
typedef struct {
XPointer client_data;
XIMProc callback;
} XIMCallback;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
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.
</para>
<para>
<!-- .LP -->
Setting any of these values while doing preedit
may cause unexpected results.
</para>
</sect4>
</sect3>
</sect2>
<sect2 id="Input_Method_Callback_Semantics">
<title>Input Method Callback Semantics</title>
<!-- .XS -->
<!-- (SN Input Method Callback Semantics -->
<!-- .XE -->
<para>
<!-- .LP -->
<acronym>XIM</acronym> callbacks are procedures 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.
This information is mostly useful for X toolkit implementors.
</para>
<para>
<!-- .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.
The 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 during preedit,
terminate preedit, or update the status area.
</para>
<para>
<!-- .LP -->
All callback procedures follow the generic prototype:
<indexterm significance="preferred"><primary>CallbackPrototype</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function><replaceable>CallbackPrototype</replaceable></function></funcdef>
<paramdef>XIC<parameter> ic</parameter></paramdef>
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
<paramdef>SomeType<parameter> call_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>ic</emphasis>
</term>
<listitem>
<para>
Specifies the input context.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>client_data</emphasis>
</term>
<listitem>
<para>
Specifies the additional client data.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>call_data</emphasis>
</term>
<listitem>
<para>
Specifies data specific to the callback.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The call_data argument is a structure that expresses the arguments needed
to achieve the semantics;
that is,
it is 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.
</para>
<para>
<!-- .LP -->
The following paragraphs describe the programming semantics
and specific data structure associated with the different reasons.
</para>
<sect3 id="Geometry_Callback_b">
<title>Geometry Callback</title>
<!-- .XS -->
<!-- (SN Geometry Callback -->
<!-- .XE -->
<para>
<!-- .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:
<indexterm significance="preferred"><primary>GeometryCallback</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function><replaceable>GeometryCallback</replaceable></function></funcdef>
<paramdef>XIC<parameter> ic</parameter></paramdef>
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
<paramdef>XPointer<parameter> call_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>ic</emphasis>
</term>
<listitem>
<para>
Specifies the input context.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>client_data</emphasis>
</term>
<listitem>
<para>
Specifies the additional client data.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>call_data</emphasis>
</term>
<listitem>
<para>
Not used for this callback and always passed as NULL.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The callback is called with a NULL call_data argument.
</para>
</sect3>
<sect3 id="Destroy_Callback_c">
<title>Destroy Callback</title>
<!-- .XS -->
<!-- (SN Destroy Callback -->
<!-- .XE -->
<para>
<!-- .LP -->
The destroy callback is triggered by the input method
when it stops service for any reason.
After the callback is invoked, the input context will be freed by Xlib.
The generic prototype is as follows:
<indexterm significance="preferred"><primary>DestroyCallback</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function><replaceable>DestroyCallback</replaceable></function></funcdef>
<paramdef>XIC<parameter> ic</parameter></paramdef>
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
<paramdef>XPointer<parameter> call_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>ic</emphasis>
</term>
<listitem>
<para>
Specifies the input context.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>client_data</emphasis>
</term>
<listitem>
<para>
Specifies the additional client data.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>call_data</emphasis>
</term>
<listitem>
<para>
Not used for this callback and always passed as NULL.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The callback is called with a NULL call_data argument.
</para>
</sect3>
<sect3 id="String_Conversion_Callback_b">
<title>String Conversion Callback</title>
<!-- .XS -->
<!-- (SN String Conversion Callback -->
<!-- .XE -->
<para>
<!-- .LP -->
The string conversion callback is triggered by the input method
to request the client to return the string to be converted. The
returned string may be either a multibyte or wide character string,
with an encoding matching the locale bound to the input context.
The callback prototype is as follows:
<indexterm significance="preferred"><primary>StringConversionCallback</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function><replaceable>StringConversionCallback</replaceable></function></funcdef>
<paramdef>XIC<parameter> ic</parameter></paramdef>
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
<paramdef>XIMStringConversionCallbackStruct<parameter> *call_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>ic</emphasis>
</term>
<listitem>
<para>
Specifies the input method.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>client_data</emphasis>
</term>
<listitem>
<para>
Specifies the additional client data.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>call_data</emphasis>
</term>
<listitem>
<para>
Specifies the amount of the string to be converted.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The callback is passed an
<structname>XIMStringConversionCallbackStruct</structname>
structure in the call_data argument.
The text member is an
<structname>XIMStringConversionText</structname>
structure (see section 13.5.6.9) to be filled in by the client
and describes the text to be sent to the input method.
The data pointed to by the
string and feedback elements of the
<structname>XIMStringConversionText</structname>
structure will be freed using
<function>XFree</function>
by the input method
after the callback returns. So the client should not point to
internal buffers that are critical to the client.
Similarly, because the feedback element is currently reserved for future
use, the client should set feedback to NULL to prevent the library from
freeing memory at some random location due to an uninitialized pointer.
</para>
<para>
<!-- .LP -->
The
<structname>XIMStringConversionCallbackStruct</structname>
structure is defined as follows:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XIMStringConversionCallbackStruct</primary></indexterm>
<!-- .sM -->
</para>
<!-- .LP -->
<literallayout class="monospaced">
typedef struct _XIMStringConversionCallbackStruct {
XIMStringConversionPosition position;
XIMCaretDirection direction;
short factor;
XIMStringConversionOperation operation;
XIMStringConversionText *text;
} XIMStringConversionCallbackStruct;
typedef short XIMStringConversionPosition;
typedef unsigned short XIMStringConversionOperation;
#define XIMStringConversionSubstitution (0x0001)
#define XIMStringConversionRetrieval (0x0001)
</literallayout>
<para>
<!-- .LP -->
<!-- .eM -->
<type>XIMStringConversionPosition</type>
specifies the starting position of the string to be returned
in the
<structname>XIMStringConversionText</structname>
structure. The value identifies a position, in units of characters,
relative to the client's cursor position in the client's buffer.
</para>
<para>
<!-- .LP -->
The ending position of the text buffer is determined by
the direction and factor members. Specifically, it is the character position
relative to the starting point as defined by the
<structname>XIMCaretDirection</structname>.
The factor member of
<structname>XIMStringConversionCallbackStruct</structname>
specifies the number of
<structname>XIMCaretDirection</structname>
positions to be applied. For example, if the direction specifies
<constant>XIMLineEnd</constant>
and factor is 1, then all characters from the starting position to
the end of the current display line are returned. If the direction
specifies
<constant>XIMForwardChar</constant>
or
<constant>XIMBackwardChar</constant>,
then the factor specifies a relative position, indicated in characters,
from the starting position.
</para>
<para>
<!-- .LP -->
<type>XIMStringConversionOperation</type>
specifies whether the string to be converted should be
deleted (substitution) or copied (retrieval) from the client's
buffer. When the
<type>XIMStringConversionOperation</type>
is
<symbol>XIMStringConversionSubstitution</symbol>,
the client must delete the string to be converted from its own buffer.
When the
<type>XIMStringConversionOperation</type>
is
<symbol>XIMStringConversionRetrieval</symbol>,
the client must not delete the string to be converted from its buffer.
The substitute operation is typically used for reconversion and
transliteration conversion,
while the retrieval operation is typically used for context-sensitive
conversion.
</para>
</sect3>
<sect3 id="Preedit_State_Callbacks">
<title>Preedit State Callbacks</title>
<!-- .XS -->
<!-- (SN Preedit State Callbacks -->
<!-- .XE -->
<para>
<!-- .LP -->
When the input method turns preediting on or off, a
<function><replaceable>PreeditStartCallback</replaceable></function>
or
<function><replaceable>PreeditDoneCallback</replaceable></function>
callback is triggered to let the toolkit do the setup
or the cleanup for the preedit region.
<indexterm significance="preferred"><primary>PreeditStartCallback</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>int <function><replaceable>PreeditStartCallback</replaceable></function></funcdef>
<paramdef>XIC<parameter> ic</parameter></paramdef>
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
<paramdef>XPointer<parameter> call_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>ic</emphasis>
</term>
<listitem>
<para>
Specifies the input context.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>client_data</emphasis>
</term>
<listitem>
<para>
Specifies the additional client data.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>call_data</emphasis>
</term>
<listitem>
<para>
Not used for this callback and always passed as NULL.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
When preedit starts on the specified input context,
the callback is called with a NULL call_data argument.
<function><replaceable>PreeditStartCallback</replaceable></function>
will return the maximum size of the preedit string.
A positive number indicates the maximum number of bytes allowed
in the preedit string,
and a value of -1 indicates there is no limit.
<indexterm significance="preferred"><primary>PreeditDoneCallback</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function><replaceable>PreeditDoneCallback</replaceable></function></funcdef>
<paramdef>XIC<parameter> ic</parameter></paramdef>
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
<paramdef>XPointer<parameter> call_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>ic</emphasis>
</term>
<listitem>
<para>
Specifies the input context.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>client_data</emphasis>
</term>
<listitem>
<para>
Specifies the additional client data.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>call_data</emphasis>
</term>
<listitem>
<para>
Not used for this callback and always passed as NULL.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
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
<function><replaceable>PreeditStartCallback</replaceable></function>.
</para>
<para>
<!-- .LP -->
<function><replaceable>PreeditStartCallback</replaceable></function>
should initialize appropriate data needed for
displaying preedit information and for handling further
<function><replaceable>PreeditDrawCallback</replaceable></function>
calls.
Once
<function><replaceable>PreeditStartCallback</replaceable></function>
is called, it will not be called again before
<function><replaceable>PreeditDoneCallback</replaceable></function>
has been called.
</para>
</sect3>
<sect3 id="Preedit_Draw_Callback">
<title>Preedit Draw Callback</title>
<!-- .XS -->
<!-- (SN Preedit Draw Callback -->
<!-- .XE -->
<para>
<!-- .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:
<indexterm significance="preferred"><primary>PreeditDrawCallback</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function><replaceable>PreeditDrawCallback</replaceable></function></funcdef>
<paramdef>XIC<parameter> ic</parameter></paramdef>
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
<paramdef>XIMPreeditDrawCallbackStruct<parameter> *call_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>ic</emphasis>
</term>
<listitem>
<para>
Specifies the input context.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>client_data</emphasis>
</term>
<listitem>
<para>
Specifies the additional client data.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>call_data</emphasis>
</term>
<listitem>
<para>
Specifies the preedit drawing information.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The callback is passed an
<structname>XIMPreeditDrawCallbackStruct</structname>
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.
</para>
<para>
<!-- .LP -->
The
<structname>XIMPreeditDrawCallbackStruct</structname>
structure is defined as follows:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XIMPreeditDrawCallbackStruct</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .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;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The client must keep updating a buffer of the preedit text
and the callback arguments referring to indexes in that buffer.
The call_data fields have specific meanings according to the operation,
as follows:
</para>
<itemizedlist>
<listitem>
<para>
To indicate text deletion,
the call_data member specifies a NULL text field.
The text to be deleted is then the current text in the buffer
from position chg_first (starting at zero) on a character length
of chg_length.
</para>
</listitem>
<listitem>
<para>
When text is non-NULL,
it indicates insertion or replacement of text in the buffer.
</para>
</listitem>
<listitem>
<para>
The chg_length member
identifies the number of characters in the current preedit buffer
that are affected by this call.
A positive chg_length indicates that chg_length number of characters, starting
at chg_first, must be deleted or must be replaced by text, whose length is
specified in the
<structname>XIMText</structname>
structure.
</para>
</listitem>
<listitem>
<para>
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.
</para>
</listitem>
<listitem>
<para>
chg_length and chg_first combine to identify the modification required to
the preedit buffer; beginning at chg_first, replace chg_length number of
characters with the text in the supplied
<structname>XIMText</structname>
structure. For example, suppose the preedit buffer contains the string "ABCDE".
</para>
</listitem>
<listitem>
<para>
<literallayout class="monospaced">
<!-- .ft C -->
Text: A B C D E
^ ^ ^ ^ ^ ^
CharPos: 0 1 2 3 4 5
<!-- .sp -->
<!-- .ft P -->
</literallayout>
The CharPos in the diagram shows the location of the character position
relative to the character.
</para>
</listitem>
<listitem>
<para>
If the value of chg_first is 1 and the value of chg_length is 3, this
says to replace 3 characters beginning at character position 1 with the
string in the
<structname>XIMText</structname>
structure.
Hence, <acronym>BCD</acronym> would be replaced by the value in the structure.
</para>
</listitem>
<listitem>
<para>
Though chg_length and chg_first are both signed integers they will
never have a negative value.
</para>
</listitem>
<listitem>
<para>
The caret member
identifies the character position before which the cursor should
be placed - after modification to the preedit buffer has been completed.
For example, if caret is zero, the cursor is at
the beginning of the buffer. If the caret is one, the cursor is between
the first and second character.
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XIMText</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .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;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The text string passed is actually a structure specifying as follows:
</para>
<itemizedlist>
<listitem>
<para>
The length member is the text length in characters.
</para>
</listitem>
<listitem>
<para>
The encoding_is_wchar member is a value that indicates
if the text string is encoded in wide character or multibyte format.
The text string may be passed either as multibyte or as wide character;
the input method controls in which form data is passed.
The client's
callback routine must be able to handle data passed in either form.
</para>
</listitem>
<listitem>
<para>
The string member is the text string.
</para>
</listitem>
<listitem>
<para>
The feedback member indicates rendering type for each character in the
string member.
If string is NULL (indicating that only highlighting of the existing
preedit buffer should be updated), feedback points to length highlight
elements that should be applied to the existing preedit buffer, beginning
at chg_first.
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
The feedback member expresses 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 be mapped
to two distinct rendering styles.
</para>
<para>
<!-- .LP -->
If an input method wants to control display of the preedit string, an
input method can indicate the visibility hints using feedbacks in
a specific way.
The
<symbol>XIMVisibleToForward</symbol>,
<symbol>XIMVisibleToBackword</symbol>,
and
<symbol>XIMVisibleToCenter</symbol>
masks are exclusively used for these visibility hints.
The
<symbol>XIMVisibleToForward</symbol>
mask
indicates that the preedit text is preferably displayed in the
primary draw direction from the
caret position in the preedit area forward.
The
<symbol>XIMVisibleToBackword</symbol>
mask
indicates that the preedit text is preferably displayed from
the caret position in the preedit area backward, relative to the primary
draw direction.
The
<symbol>XIMVisibleToCenter</symbol>
mask
indicates that the preedit text is preferably displayed with
the caret position in the preedit area centered.
</para>
<para>
<!-- .LP -->
The insertion point of the preedit string could exist outside of
the visible area when visibility hints are used.
Only one of the
masks
is valid for the entire preedit string, and only one character
can hold one of these feedbacks for a given input context at one time.
This feedback may be OR'ed together with another highlight (such as
<symbol>XIMReverse</symbol>).
Only the most recently set feedback is valid, and any previous
feedback is automatically canceled. This is a hint to the client, and
the client is free to choose how to display the preedit string.
</para>
<para>
<!-- .LP -->
The feedback member also specifies how rendering of the text argument
should be performed.
If the feedback is NULL,
the callback should apply the same feedback as is used for the surrounding
characters in the preedit buffer; if chg_first is at a highlight boundary,
the client can choose which of the two highlights to use.
If feedback is not NULL, feedback specifies an array defining the
rendering for each
character of the string, and the length of the array is thus length.
</para>
<para>
<!-- .LP -->
If an input method wants to indicate that it is only updating the feedback of
the preedit text without changing the content of it,
the
<structname>XIMText</structname>
structure will contain a NULL value for the string field,
the number of characters affected (relative to chg_first)
will be in the length field,
and the feedback field will point to an array of
<type>XIMFeedback</type>.
</para>
<para>
<!-- .LP -->
Each element in the feedback array is a bitmask represented by a value of type
<type>XIMFeedback</type>.
The valid mask names are as follows:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XIMReverse</primary></indexterm>
<indexterm significance="preferred"><primary>XIMUnderline</primary></indexterm>
<indexterm significance="preferred"><primary>XIMHighlight</primary></indexterm>
<indexterm significance="preferred"><primary>XIMPrimary</primary></indexterm>
<indexterm significance="preferred"><primary>XIMSecondary</primary></indexterm>
<indexterm significance="preferred"><primary>XIMTertiary</primary></indexterm>
<indexterm significance="preferred"><primary>XIMVisibleToForward</primary></indexterm>
<indexterm significance="preferred"><primary>XIMVisibleToBackward</primary></indexterm>
<indexterm significance="preferred"><primary>XIMVisibleToCenter</primary></indexterm>
<!-- .sM -->
</para>
<literallayout class="monospaced">
typedef unsigned long XIMFeedback;
#define XIMReverse 1L
#define XIMUnderline (1L<<1)
#define XIMHighlight (1L<<2)
#define XIMPrimary (1L<<5)*
#define XIMSecondary (1L<<6)*
#define XIMTertiary (1L<<7)*
#define XIMVisibleToForward (1L<<8)
#define XIMVisibleToBackward (1L<<9)
#define XIMVisibleToCenter (1L<<10)
*† The values for XIMPrimary, XIMSecondary, and XIMTertiary were incorrectly defined in
the R5 specification. The X Consortium’s X11R5 implementation correctly implemented the val-
ues for these highlights. The value of these highlights has been corrected in this specification to
agree with the values in the Consortium’s X11R5 and X11R6 implementations.
</literallayout>
<para>
<!-- .LP -->
Characters drawn with the
<symbol>XIMReverse</symbol>
highlight should be drawn by swapping the foreground and background colors
used to draw normal, unhighlighted characters.
Characters drawn with the
<symbol>XIMUnderline</symbol>
highlight should be underlined.
Characters drawn with the
<symbol>XIMHighlight</symbol>,
<symbol>XIMPrimary</symbol>,
<symbol>XIMSecondary</symbol>,
and
<symbol>XIMTertiary</symbol>
highlights should be drawn in some unique manner that must be different
from
<symbol>XIMReverse</symbol>
and
<symbol>XIMUnderline</symbol>.
<!-- .FS \(dg -->
The values for
<symbol>XIMPrimary</symbol>,
<symbol>XIMSecondary</symbol>,
and
<symbol>XIMTertiary</symbol>
were incorrectly defined in the R5 specification.
The X Consortium's X11R5
implementation correctly implemented the values for these highlights.
The value of these highlights has been corrected in this specification
to agree with the values in the Consortium's X11R5 and X11R6 implementations.
<!-- .FE -->
</para>
</sect3>
<sect3 id="Preedit_Caret_Callback">
<title>Preedit Caret Callback</title>
<!-- .XS -->
<!-- (SN Preedit Caret Callback -->
<!-- .XE -->
<para>
<!-- .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.
<indexterm significance="preferred"><primary>PreeditCaretCallback</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function><replaceable>PreeditCaretCallback</replaceable></function></funcdef>
<paramdef>XIC<parameter> ic</parameter></paramdef>
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
<paramdef>XIMPreeditCaretCallbackStruct<parameter> *call_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>ic</emphasis>
</term>
<listitem>
<para>
Specifies the input context.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>client_data</emphasis>
</term>
<listitem>
<para>
Specifies the additional client data.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>call_data</emphasis>
</term>
<listitem>
<para>
Specifies the preedit caret information.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The input method will trigger PreeditCaretCallback
to move the text insertion point during preedit.
The call_data argument contains a pointer to an
<structname>XIMPreeditCaretCallbackStruct</structname>
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 the initial position.
</para>
<para>
<!-- .LP -->
The
<structname>XIMPreeditCaretCallbackStruct</structname>
structure is defined as follows:
<indexterm significance="preferred"><primary>XIMPreeditCaretCallbackStruct</primary></indexterm>
</para>
<para>
<!-- .LP -->
<!-- .sM -->
<literallayout class="monospaced">
<!-- .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;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<structname>XIMCaretStyle</structname>
structure is defined as follows:
</para>
<para>
<!-- .LP -->
<indexterm significance="preferred"><primary>XIMCaretStyle</primary></indexterm>
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 2.5i -->
<!-- .ta .5i 2.5i -->
typedef enum {
XIMIsInvisible, /* Disable caret feedback */
XIMIsPrimary, /* <acronym>UI</acronym> defined caret feedback */
XIMIsSecondary, /* <acronym>UI</acronym> defined caret feedback */
} XIMCaretStyle;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<structname>XIMCaretDirection</structname>
structure is defined as follows:
<indexterm significance="preferred"><primary>XIMCaretDirection</primary></indexterm>
</para>
<para>
<!-- .LP -->
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 2.5i -->
<!-- .ta .5i 2.5i -->
typedef enum {
XIMForwardChar, XIMBackwardChar,
XIMForwardWord, XIMBackwardWord,
XIMCaretUp, XIMCaretDown,
XIMNextLine, XIMPreviousLine,
XIMLineStart, XIMLineEnd,
XIMAbsolutePosition,
XIMDontChange,
} XIMCaretDirection;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
These values are defined as follows:
</para>
<indexterm significance="preferred"><primary>XIMForwardChar</primary></indexterm>
<indexterm significance="preferred"><primary>XIMBackwardChar</primary></indexterm>
<indexterm significance="preferred"><primary>XIMForwardWord</primary></indexterm>
<indexterm significance="preferred"><primary>XIMBackwardWord</primary></indexterm>
<indexterm significance="preferred"><primary>XIMCaretUp</primary></indexterm>
<indexterm significance="preferred"><primary>XIMCaretDown</primary></indexterm>
<informaltable>
<tgroup cols='2' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<tbody>
<row>
<entry><constant>XIMForwardChar</constant></entry>
<entry>Move the caret forward one character position.</entry>
</row>
<row>
<entry><constant>XIMBackwardChar</constant></entry>
<entry>Move the caret backward one character position.</entry>
</row>
<row>
<entry><constant>XIMForwardWord</constant></entry>
<entry>Move the caret forward one word.</entry>
</row>
<row>
<entry><constant>XIMBackwardWord</constant></entry>
<entry>Move the caret backward one word.</entry>
</row>
<row>
<entry><constant>XIMCaretUp</constant></entry>
<entry>Move the caret up one line keeping the current horizontal offset.</entry>
</row>
<row>
<entry><constant>XIMCaretDown</constant></entry>
<entry>Move the caret down one line keeping the current horizontal offset.</entry>
</row>
<row>
<entry><constant>XIMPreviousLine</constant></entry>
<entry>Move the caret to the beginning of the previous line.</entry>
</row>
<row>
<entry><constant>XIMNextLine</constant></entry>
<entry>Move the caret to the beginning of the next line.</entry>
</row>
<row>
<entry><constant>XIMLineStart</constant></entry>
<entry>Move the caret to the beginning of the current display line that contains the caret.</entry>
</row>
<row>
<entry><constant>XIMLineEnd</constant></entry>
<entry>Move the caret to the end of the current display line that contains the caret.</entry>
</row>
<row>
<entry><constant>XIMAbsolutePosition</constant></entry>
<entry>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 the beginning of the preedit text.</entry>
</row>
<row>
<entry><constant>XIMDontChange</constant></entry>
<entry>The caret position does not change.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<indexterm significance="preferred"><primary>XIMNextLine</primary></indexterm>
<indexterm significance="preferred"><primary>XIMPreviousLine</primary></indexterm>
<indexterm significance="preferred"><primary>XIMLineStart</primary></indexterm>
<indexterm significance="preferred"><primary>XIMLineEnd</primary></indexterm>
<indexterm significance="preferred"><primary>XIMAbsolutePosition</primary></indexterm>
<indexterm significance="preferred"><primary>XIMDontChange</primary></indexterm>
</sect3>
<sect3 id="Status_Callbacks">
<title>Status Callbacks</title>
<!-- .XS -->
<!-- (SN Status Callbacks -->
<!-- .XE -->
<para>
<!-- .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.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
When the input context is created or gains focus,
the input method calls the StatusStartCallback callback.
<indexterm significance="preferred"><primary>StatusStartCallback</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function><replaceable>StatusStartCallback</replaceable></function></funcdef>
<paramdef>XIC<parameter> ic</parameter></paramdef>
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
<paramdef>XPointer<parameter> call_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>ic</emphasis>
</term>
<listitem>
<para>
Specifies the input context.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>client_data</emphasis>
</term>
<listitem>
<para>
Specifies the additional client data.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>call_data</emphasis>
</term>
<listitem>
<para>
Not used for this callback and always passed as NULL.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The callback should initialize appropriate data for displaying status
and for responding to StatusDrawCallback calls.
Once StatusStartCallback is called,
it will not be called again before StatusDoneCallback has been called.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
When an input context
is destroyed or when it loses focus, the input method calls StatusDoneCallback.
<indexterm significance="preferred"><primary>StatusDoneCallback</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function><replaceable>StatusDoneCallback</replaceable></function></funcdef>
<paramdef>XIC<parameter> ic</parameter></paramdef>
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
<paramdef>XPointer<parameter> call_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>ic</emphasis>
</term>
<listitem>
<para>
Specifies the input context.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>client_data</emphasis>
</term>
<listitem>
<para>
Specifies the additional client data.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>call_data</emphasis>
</term>
<listitem>
<para>
Not used for this callback and always passed as NULL.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The callback may release any data allocated on
<function>StatusStart</function>.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
When an input context status has to be updated, the input method calls
StatusDrawCallback.
<indexterm significance="preferred"><primary>StatusDrawCallback</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>void <function><replaceable>StatusDrawCallback</replaceable></function></funcdef>
<paramdef>XIC<parameter> ic</parameter></paramdef>
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
<paramdef>XIMStatusDrawCallbackStruct<parameter> *call_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>ic</emphasis>
</term>
<listitem>
<para>
Specifies the input context.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>client_data</emphasis>
</term>
<listitem>
<para>
Specifies the additional client data.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>call_data</emphasis>
</term>
<listitem>
<para>
Specifies the status drawing information.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The callback should update the status area by either drawing a string
or imaging a bitmap in the status area.
</para>
<para>
<!-- .LP -->
The
<structname>XIMStatusDataType</structname>
and
<structname>XIMStatusDrawCallbackStruct</structname>
structures are defined as follows:
<indexterm significance="preferred"><primary>XIMStatusDataType</primary></indexterm>
<indexterm significance="preferred"><primary>XIMStatusDrawCallbackStruct</primary></indexterm>
</para>
<para>
<!-- .LP -->
<!-- .sM -->
<literallayout class="monospaced">
<!-- .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;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
</para>
<para>
<!-- .LP -->
The feedback styles
<symbol>XIMVisibleToForward</symbol>,
<symbol>XIMVisibleToBackword</symbol>,
and
<symbol>XIMVisibleToCenter</symbol>
are not relevant and will not appear in the
<type>XIMFeedback</type>
element of the
<structname>XIMText</structname>
structure.
</para>
<para>
<!-- .LP -->
</para>
</sect3>
</sect2>
<sect2 id="Event_Filtering_b">
<title>Event Filtering</title>
<!-- .XS -->
<!-- (SN Event Filtering -->
<!-- .XE -->
<para>
<!-- .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
<function>XFilterEvent</function>
after calling
<function>XNextEvent</function>.
Any client that uses the
<type>XIM</type>
interface should call
<function>XFilterEvent</function>
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).
</para>
<para>
<!-- .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
<function>XFilterEvent</function>.
Clients should discard filtered events.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To filter an event, use
<function>XFilterEvent</function>.
<indexterm significance="preferred"><primary>XFilterEvent</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>Bool <function>XFilterEvent</function></funcdef>
<paramdef>XEvent<parameter> *event</parameter></paramdef>
<paramdef>Window<parameter> w</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<!-- .ds Ev event to filter -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>event</emphasis>
</term>
<listitem>
<para>
Specifies the (Ev.
<!-- .ds Wi for which the filter is to be applied -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>w</emphasis>
</term>
<listitem>
<para>
Specifies the window (Wi.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
If the window argument is
<symbol>None</symbol>,
<function>XFilterEvent</function>
applies the filter to the window specified in the
<structname>XEvent</structname>
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.
</para>
<para>
<!-- .LP -->
If
<function>XFilterEvent</function>
returns
<symbol>True</symbol>,
then some input method has filtered the event,
and the client should discard the event.
If
<function>XFilterEvent</function>
returns
<symbol>False</symbol>,
then the client should continue processing the event.
</para>
<para>
<!-- .LP -->
If a grab has occurred in the client and
<function>XFilterEvent</function>
returns
<symbol>True</symbol>,
the client should ungrab the keyboard.
</para>
</sect2>
<sect2 id="Getting_Keyboard_Input_b">
<title>Getting Keyboard Input</title>
<!-- .XS -->
<!-- (SN Getting Keyboard Input -->
<!-- .XE -->
<para>
<!-- .LP -->
To get composed input from an input method,
use
<function>XmbLookupString</function>
or
<function>XwcLookupString</function>.
<indexterm significance="preferred"><primary>XmbLookupString</primary></indexterm>
<indexterm significance="preferred"><primary>XwcLookupString</primary></indexterm>
<!-- .sM -->
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XmbLookupString</function></funcdef>
<paramdef>XIC<parameter> ic</parameter></paramdef>
<paramdef>XKeyPressedEvent<parameter> *event</parameter></paramdef>
<paramdef>char<parameter> *buffer_return</parameter></paramdef>
<paramdef>int<parameter> bytes_buffer</parameter></paramdef>
<paramdef>KeySym<parameter> *keysym_return</parameter></paramdef>
<paramdef>Status<parameter> *status_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XwcLookupString</function></funcdef>
<paramdef>XIC<parameter> ic</parameter></paramdef>
<paramdef>XKeyPressedEvent<parameter> *event</parameter></paramdef>
<paramdef>wchar_t<parameter> *buffer_return</parameter></paramdef>
<paramdef>int<parameter> wchars_buffer</parameter></paramdef>
<paramdef>KeySym<parameter> *keysym_return</parameter></paramdef>
<paramdef>Status<parameter> *status_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>ic</emphasis>
</term>
<listitem>
<para>
Specifies the input context.
<!-- .ds Ev key event to be used -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>event</emphasis>
</term>
<listitem>
<para>
Specifies the (Ev.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>buffer_return</emphasis>
</term>
<listitem>
<para>
Returns a multibyte string or wide character string (if any)
from the input method.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>bytes_buffer</emphasis>
</term>
<listitem>
<para>
<!-- .br -->
<!-- .ns -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>wchars_buffer</emphasis>
</term>
<listitem>
<para>
Specifies space available in the return buffer.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>keysym_return</emphasis>
</term>
<listitem>
<para>
Returns the KeySym computed from the event if this argument is not NULL.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>status_return</emphasis>
</term>
<listitem>
<para>
Returns a value indicating what kind of data is returned.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XmbLookupString</function>
and
<function>XwcLookupString</function>
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.
</para>
<para>
<!-- .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.
</para>
<para>
<!-- .LP -->
<function>XmbLookupString</function>
returns the length of the string in bytes, and
<function>XwcLookupString</function>
returns the length of the string in characters.
Both
<function>XmbLookupString</function>
and
<function>XwcLookupString</function>
return text in the encoding of the locale bound to the input method
of the specified input context.
</para>
<para>
<!-- .LP -->
Each string returned by
<function>XmbLookupString</function>
and
<function>XwcLookupString</function>
begins in the initial state of the encoding of the locale
(if the encoding of the locale is state-dependent).
<!-- .NT -->
<note><para>
To insure proper input processing,
it is essential that the client pass only
<symbol>KeyPress</symbol>
events to
<function>XmbLookupString</function>
and
<function>XwcLookupString</function>.
Their behavior when a client passes a
<symbol>KeyRelease</symbol>
event is undefined.
</para></note>
<!-- .NE -->
</para>
<para>
<!-- .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:
</para>
<informaltable>
<tgroup cols='2' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<tbody>
<row>
<entry><symbol>XBufferOverflow</symbol></entry>
<entry>The input string to be returned is too large for the supplied buffer_return.
The required size
(<function>XmbLookupString</function>
in bytes;
<function>XwcLookupString</function>
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 to obtain the string.</entry>
</row>
<row>
<entry><symbol>XLookupNone</symbol></entry>
<entry>No consistent input has been composed so far.
The contents of buffer_return and keysym_return are not modified,
and the function returns zero.</entry>
</row>
<row>
<entry><symbol>XLookupChars</symbol></entry>
<entry>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 content of the keysym_return argument is not modified.</entry>
</row>
<row>
<entry><symbol>XLookupKeySym</symbol></entry>
<entry>A KeySym has been returned instead of a string
and is returned in keysym_return.
The content of the buffer_return argument is not modified,
and the function returns zero.</entry>
</row>
<row>
<entry><symbol>XLookupBoth</symbol></entry>
<entry>Both a KeySym and a string are returned;
<symbol>XLookupChars</symbol>
and
<symbol>XLookupKeySym</symbol>
occur simultaneously.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
<!-- .LP -->
It does not make any difference if the input context passed as an argument to
<function>XmbLookupString</function>
and
<function>XwcLookupString</function>
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
<function>XmbLookupString</function>
or
<function>XwcLookupString</function>
even though it does not have any more keyboard focus.
</para>
</sect2>
<sect2 id="Input_Method_Conventions">
<title>Input Method Conventions</title>
<!-- .XS -->
<!-- (SN Input Method Conventions -->
<!-- .XE -->
<para>
<!-- .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.
</para>
<sect3 id="Client_Conventions">
<title>Client Conventions</title>
<!-- .XS -->
<!-- (SN Client Conventions -->
<!-- .XE -->
<para>
<!-- .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.
</para>
</sect3>
<sect3 id="Synchronization_Conventions">
<title>Synchronization Conventions</title>
<!-- .XS -->
<!-- (SN Synchronization Conventions -->
<!-- .XE -->
<para>
<!-- .LP -->
A
<symbol>KeyPress</symbol>
event with a KeyCode of zero is used exclusively as a
signal that an input method has composed input that can be returned by
<function>XmbLookupString</function>
or
<function>XwcLookupString</function>.
No other use is made of a
<symbol>KeyPress</symbol>
event with KeyCode of zero.
</para>
<para>
<!-- .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:
</para>
<itemizedlist>
<listitem>
<para>
A synthetic event sent by an input method server
</para>
</listitem>
<listitem>
<para>
An artificial event created by a input method filter and pushed
onto a client's event queue
</para>
</listitem>
<listitem>
<para>
A
<symbol>KeyPress</symbol>
event whose KeyCode value is modified by an input method filter
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
When callback support is specified by the 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).
</para>
</sect3>
</sect2>
</sect1>
<sect1 id="String_Constants">
<title>String Constants</title>
<!-- .XS -->
<!-- (SN String Constants -->
<!-- .XE -->
<para>
<!-- .LP -->
The following symbols for string constants are defined in
<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.
</para>
<literallayout class="monospaced">
#define XNVaNestedList "XNVaNestedList"
#define XNSeparatorofNestedList "separatorofNestedList"
#define XNQueryInputStyle "queryInputStyle"
#define XNClientWindow "clientWindow"
#define XNInputStyle "inputStyle"
#define XNFocusWindow "focusWindow"
#define XNResourceName "resourceName"
#define XNResourceClass "resourceClass"
#define XNGeometryCallback "geometryCallback"
#define XNDestroyCallback "destroyCallback"
#define XNFilterEvents "filterEvents"
#define XNPreeditStartCallback "preeditStartCallback"
#define XNPreeditDoneCallback "preeditDoneCallback"
#define XNPreeditDrawCallback "preeditDrawCallback"
#define XNPreeditCaretCallback "preeditCaretCallback"
#define XNPreeditStateNotifyCallback "preeditStateNotifyCallback"
#define XNPreeditAttributes "preeditAttributes"
#define XNStatusStartCallback "statusStartCallback"
#define XNStatusDoneCallback "statusDoneCallback"
#define XNStatusDrawCallback "statusDrawCallback"
#define XNStatusAttributes "statusAttributes"
#define XNArea "area"
#define XNAreaNeeded "areaNeeded"
#define XNSpotLocation "spotLocation"
#define XNColormap "colorMap"
#define XNStdColormap "stdColorMap"
#define XNForeground "foreground"
#define XNBackground "background"
#define XNBackgroundPixmap "backgroundPixmap"
#define XNFontSet "fontSet"
#define XNLineSpace "lineSpace"
#define XNCursor "cursor"
#define XNQueryIMValuesList "queryIMValuesList"
#define XNQueryICValuesList "queryICValuesList"
#define XNStringConversionCallback "stringConversionCallback"
#define XNStringConversion "stringConversion"
#define XNResetState "resetState"
#define XNHotKey "hotkey"
#define XNHotKeyState "hotkeyState"
#define XNPreeditState "preeditState"
#define XNVisiblePosition "visiblePosition"
#define XNR6PreeditCallbackBehavior "r6PreeditCallback"
#define XNRequiredCharSet "requiredCharSet"
#define XNQueryOrientation "queryOrientation"
#define XNDirectionalDependentDrawing "directionalDependentDrawing"
#define XNContextualDrawing "contextualDrawing"
#define XNBaseFontName "baseFontName"
#define XNMissingCharSet "missingCharSet"
#define XNDefaultString "defaultString"
#define XNOrientation "orientation"
#define XNFontInfo "fontInfo"
#define XNOMAutomatic "omAutomatic"
</literallayout>
</sect1>
</chapter>