1 files changed, 10326 insertions, 10326 deletions

diff --git a/libX11/specs/libX11/CH13.xml b/libX11/specs/libX11/CH13.xml
index 4ebe19c57..65a92e729 100644
--- a/libX11/specs/libX11/CH13.xml
+++ b/libX11/specs/libX11/CH13.xml
@@ -1,10326 +1,10326 @@
-<?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 recompilation.

-</para>

-<para>

-As one of the localization mechanisms, Xlib provides an X Input Method (<acronym>XIM</acronym>)

-functional interface 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 characters 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 applications (mixing multiple languages within a single piece of text),

-but they make it possible to implement applications that work in limited

-fashion with more than one language in independent contexts.

-</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>.

-</para>

-<indexterm significance="preferred"><primary>XSetLocaleModifiers</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xsetlocalemodifiers'>

-<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>

-<!-- .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'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <colspec colname='c3'/>

-  <thead>

-    <row>

-      <entry align='center'>Locale from</entry>

-      <entry align='center'>Affects the Function</entry>

-      <entry align='center'>In</entry>

-    </row>

-  </thead>

-  <tbody>

-    <row>

-      <entry nameend='c3' namest='c1'>

-      <emphasis role='bold'>Locale Query/Configuration:</emphasis></entry>

-    </row>

-    <row>

-      <entry morerows='1'><function>setlocale</function></entry>

-      <entry><function>XSupportsLocale</function></entry>

-      <entry>Locale queried</entry>

-    </row>

-    <row>

-      <entry><function>XSetLocaleModifiers</function></entry>

-      <entry>Locale modified</entry>

-    </row>

-    <row>

-      <entry nameend='c3' namest='c1'>

-      <emphasis role='bold'>Resources:</emphasis></entry>

-    </row>

-    <row>

-      <entry><function>setlocale</function></entry>

-      <entry>

-        <para><function>XrmGetFileDatabase</function></para>

-        <para><function>XrmGetStringDatabase</function></para>

-      </entry>

-      <entry>Locale of <type>XrmDatabase</type></entry>

-    </row>

-    <row>

-      <entry><type>XrmDatabase</type></entry>

-      <entry>

-        <para><function>XrmPutFileDatabase</function></para>

-        <para><function>XrmLocaleOfDatabase</function></para>

-      </entry>

-      <entry>Locale of <type>XrmDatabase</type></entry>

-    </row>

-    <row>

-      <entry nameend='c3' namest='c1'>

-      <emphasis role='bold'>Setting Standard Properties:</emphasis></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>

-        <para><function>XmbTextPropertyToTextList</function></para>

-        <para><function>XwcTextPropertyToTextList</function></para>

-        <para><function>XmbTextListToTextProperty</function></para>

-        <para><function>XwcTextListToTextProperty</function></para>

-      </entry>

-      <entry>Encoding of supplied/returned text</entry>

-    </row>

-    <row>

-      <entry nameend='c3' namest='c1'>

-      <emphasis role='bold'>Text Input:</emphasis></entry>

-    </row>

-    <row>

-      <entry morerows='2'><function>setlocale</function></entry>

-      <entry><function>XOpenIM</function></entry>

-      <entry><acronym>XIM</acronym> input method selection</entry>

-    </row>

-    <row>

-      <entry><function>XRegisterIMInstantiateCallback</function></entry>

-      <entry><acronym>XIM</acronym> selection</entry>

-    </row>

-    <row>

-      <entry><function>XUnregisterIMInstantiateCallback</function></entry>

-      <entry><acronym>XIM</acronym> selection</entry>

-    </row>

-    <row>

-      <entry morerows='1'><type>XIM</type></entry>

-      <entry><function>XCreateIC</function></entry>

-      <entry><acronym>XIC</acronym> input method configuration</entry>

-    </row>

-    <row>

-      <entry><function>XLocaleOfIM</function>,  and so on</entry>

-      <entry>Queried locale</entry>

-    </row>

-    <row>

-      <entry morerows='1'><type>XIC</type></entry>

-      <entry><function>XmbLookupString</function></entry>

-      <entry>Keyboard layout</entry>

-    </row>

-    <row>

-      <entry><function>XwcLookupString</function></entry>

-      <entry>Encoding of returned text</entry>

-    </row>

-    <row>

-      <entry nameend='c3' namest='c1'>

-      <emphasis role='bold'>Text Drawing:</emphasis></entry>

-    </row>

-    <row>

-      <entry morerows='1'><function>setlocale</function></entry>

-      <entry><function>XOpenOM</function></entry>

-      <entry><acronym>XOM</acronym> output method selection</entry>

-    </row>

-    <row>

-      <entry><function>XCreateFontSet</function></entry>

-      <entry>Charsets of fonts in XFontSet</entry>

-    </row>

-    <row>

-      <entry morerows='1'><type>XOM</type></entry>

-      <entry><function>XCreateOC</function></entry>

-      <entry><acronym>XOC</acronym> output method configuration</entry>

-    </row>

-    <row>

-      <entry><function>XLocaleOfOM</function>,  and so on</entry>

-      <entry>Queried locale</entry>

-    </row>

-    <row>

-      <entry morerows='2'><type>XFontSet</type></entry>

-      <entry><function>XmbDrawText</function>,</entry>

-      <entry>Locale of supplied text</entry>

-    </row>

-    <row>

-      <entry><function>XwcDrawText</function>, and so on</entry>

-      <entry>Locale of supplied text</entry>

-    </row>

-    <row>

-      <entry>

-        <para><function>XExtentsOfFontSet</function>,  and so on</para>

-        <para><function>XmbTextExtents</function>,</para>

-        <para><function>XwcTextExtents</function>,  and so on</para>

-      </entry>

-      <entry>Locale-dependent metrics</entry>

-    </row>

-    <row>

-      <entry nameend='c3' namest='c1'>

-      <emphasis role='bold'>Xlib Errors:</emphasis></entry>

-    </row>

-    <row>

-      <entry><function>setlocale</function></entry>

-      <entry>

-        <para><function>XGetErrorDatabaseText</function>,</para>

-        <para><function>XGetErrorText</function>,  and so on</para>

-      </entry>

-      <entry>Locale of error message</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>.

-</para>

-<indexterm significance="preferred"><primary>XVaCreateNestedList</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xvacreatenestedlist'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XOpenOM</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xopenom'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XCloseOM</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xcloseom'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XSetOMValues</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xsetomvalues'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XGetOMValues</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xgetomvalues'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XDisplayOfOM</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xdisplayofom'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XLocaleOfOM</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xlocaleofom'>

-<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>

-<!-- .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'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <thead>

-    <row>

-      <entry align='left'>Key</entry>

-      <entry align='left'>Explanation</entry>

-    </row>

-  </thead>

-  <tbody>

-    <row>

-      <entry>G</entry>

-      <entry>This value may be read using <function>XGetOMValues</function>.</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<para></para>

-

-<informaltable>

-  <tgroup cols='2'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <thead>

-    <row>

-      <entry align='left'><acronym>XOM</acronym> Value</entry>

-      <entry align='left'>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>.

-</para>

-<indexterm significance="preferred"><primary>XCreateOC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xcreateoc'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XDestroyOC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xdestroyoc'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XOMOfOC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xomofoc'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XSetOCValues</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xsetocvalues'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XGetOCValues</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xgetocvalues'>

-<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>

-<!-- .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'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <thead>

-    <row>

-      <entry align='left'>Key</entry>

-      <entry align='left'>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>

-

-<para></para>

-

-<informaltable>

-  <tgroup cols='3'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <colspec colname='c3'/>

-  <thead>

-    <row>

-      <entry align='left'><acronym>XOC</acronym> Value</entry>

-      <entry align='left'>Alternative Interface</entry>

-      <entry align='left'>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>.

-</para>

-<indexterm significance="preferred"><primary>XCreateFontSet</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xcreatefontset'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XFontsOfFontSet</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xfontsoffontset'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XBaseFontNameListOfFontSet</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xbasefontnamelistoffontset'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XLocaleOfFontSet</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xlocaleoffontset'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XFreeFontSet</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xfreefontset'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XDirectionalDependentDrawing</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xdirectionaldependentdrawing'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XContextualDrawing</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xcontextualdrawing'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XContextDependentDrawing</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xcontextdependentdrawing'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XExtentsOfFontSet</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xextentsoffontset'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XmbTextEscapement</primary></indexterm>

-<indexterm significance="preferred"><primary>XwcTextEscapement</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xmbtextescapement'>

-<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 id='xwctextescapement'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XmbTextExtents</primary></indexterm>

-<indexterm significance="preferred"><primary>XwcTextExtents</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xmbtextextents'>

-<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 id='xwctextextents'>

-  <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>

-<!-- .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 &lt;= -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 &gt;= 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>.

-</para>

-<indexterm significance="preferred"><primary>XmbTextPerCharExtents</primary></indexterm>

-<indexterm significance="preferred"><primary>XwcTextPerCharExtents</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xmbtextpercharextents'>

-<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 id='xwctextpercharextents'>

-<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>

-<!-- .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 <link linkend="Drawing_Text">section 8.6</link> 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>.

-</para>

-<indexterm significance="preferred"><primary>XmbDrawText</primary></indexterm>

-<indexterm significance="preferred"><primary>XwcDrawText</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xmbdrawtext'>

-<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 id='xwcdrawtext'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XmbDrawString</primary></indexterm>

-<indexterm significance="preferred"><primary>XwcDrawString</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xmbdrawstring'>

-<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 id='xwcdrawstring'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XmbDrawImageString</primary></indexterm>

-<indexterm significance="preferred"><primary>XwcDrawImageString</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xmbdrawimagestring'>

-<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 id='xwcdrawimagestring'>

-<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>

-<!-- .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 <link linkend="Focus_Window">section 13.5.6.3</link>).

-</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 <link linkend="Input_Context_Values">section 13.5.6</link>)

-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'>

-  <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>.

-</para>

-<indexterm significance="preferred"><primary>XOpenIM</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xopenim'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XCloseIM</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xcloseim'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XSetIMValues</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xsetimvalues'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XGetIMValues</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xgetimvalues'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XDisplayOfIM</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xdisplayofim'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XLocaleOfIM</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xlocaleofim'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XRegisterIMInstantiateCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xregisteriminstantiatecallback'>

-<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>

-<!-- .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:

-</para>

-<indexterm significance="preferred"><primary>IMInstantiateCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='iminstantiatecallback'>

-<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>

-<!-- .LP -->

-<!-- .eM -->

-To unregister an input method instantiation callback, use

-<function>XUnregisterIMInstantiateCallback</function>.

-</para>

-<indexterm significance="preferred"><primary>XUnregisterIMInstantiateCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xunregisteriminstantiatecallback'>

-<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>

-<!-- .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'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <thead>

-    <row>

-      <entry align='left'>Key</entry>

-      <entry align='left'>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>

-

-<para></para>

-

-<informaltable>

-  <tgroup cols='2'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <thead>

-    <row>

-      <entry align='left'><acronym>XIM</acronym> Value</entry>

-      <entry align='left'>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 <link linkend="Preedit_Callback_Behavior">section 13.5.4.6</link>).

-</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'>

-  <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'>

-  <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:

-</para>

-<indexterm significance="preferred"><primary>DestroyCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='destroycallback'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XCreateIC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xcreateic'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XDestroyIC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xdestroyic'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XSetICFocus</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xseticfocus'>

-<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>

-<!-- .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>

-<indexterm significance="preferred"><primary>XUnsetICFocus</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xunseticfocus'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XmbResetIC</primary></indexterm>

-<indexterm significance="preferred"><primary>XwcResetIC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xmbresetic'>

-<funcprototype>

-  <funcdef>char *<function>XmbResetIC</function></funcdef>

-  <paramdef>XIC<parameter> ic</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<funcsynopsis id='xwcresetic'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XIMOfIC</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='ximofic'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XSetICValues</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xseticvalues'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XGetICValues</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xgeticvalues'>

-<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>

-<!-- .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'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <thead>

-    <row>

-      <entry align='left'>Key</entry>

-      <entry align='left'>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>

-

-<para></para>

-

-<!-- .LP -->

-<informaltable>

-  <tgroup cols='7'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <colspec colname='c3'/>

-  <colspec colname='c4'/>

-  <colspec colname='c5'/>

-  <colspec colname='c6'/>

-  <colspec colname='c7'/>

-  <thead>

-    <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>

-    </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>

-      <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>

-

-<para></para>

-

-<!-- .LP -->

-<informaltable>

-  <tgroup cols='6'>

-  <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 <link linkend="Preedit_and_Status_Callbacks">section 13.5.6.13.12</link>).

-</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 <link linkend="Preedit_and_Status_Callbacks">section 13.5.6.13.12</link>).

-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 <link linkend="Preedit_and_Status_Callbacks">section 13.5.6.13.12</link>).

-</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&lt;&lt;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'>

-  <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 <link linkend="Geometry_Management">section 13.5.1.5</link>).

-</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&lt;&lt;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:

-</para>

-<indexterm significance="preferred"><primary>PreeditStateNotifyCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='preeditstatenotifycallback'>

-<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>

-<!-- .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'>

-  <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'>

-  <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:

-</para>

-<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>

-<!-- .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:

-</para>

-<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>

-<!-- .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:

-</para>

-<indexterm significance="preferred"><primary>DestroyCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='destroycallback_xic'>

-<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>

-<!-- .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:

-</para>

-<indexterm significance="preferred"><primary>StringConversionCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='stringconversioncallback'>

-<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>

-<!-- .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 <link linkend="String_Conversion_">section 13.5.6.9</link>)

-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.

-</para>

-<indexterm significance="preferred"><primary>PreeditStartCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='preeditstartcallback'>

-<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>

-<!-- .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.

-</para>

-<indexterm significance="preferred"><primary>PreeditDoneCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='preeditdonecallback'>

-<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>

-<!-- .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:

-</para>

-<indexterm significance="preferred"><primary>PreeditDrawCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='preeditdrawcallback'>

-<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>

-<!-- .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&lt;&lt;1)

-#define     XIMHighlight                   (1L&lt;&lt;2)

-#define     XIMPrimary                     (1L&lt;&lt;5)*

-#define     XIMSecondary                   (1L&lt;&lt;6)*

-#define     XIMTertiary                    (1L&lt;&lt;7)*

-#define     XIMVisibleToForward            (1L&lt;&lt;8)

-#define     XIMVisibleToBackward           (1L&lt;&lt;9)

-#define     XIMVisibleToCenter               (1L&lt;&lt;10)

-

-*† The values for XIMPrimary, XIMSecondary, and XIMTertiary 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.

-

-</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.

-</para>

-<indexterm significance="preferred"><primary>PreeditCaretCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='preeditcaretcallback'>

-<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>

-<!-- .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'>

-  <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.

-</para>

-<indexterm significance="preferred"><primary>StatusStartCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='statusstartcallback'>

-<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>

-<!-- .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.

-</para>

-<indexterm significance="preferred"><primary>StatusDoneCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='statusdonecallback'>

-<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>

-<!-- .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.

-</para>

-<indexterm significance="preferred"><primary>StatusDrawCallback</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='statusdrawcallback'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XFilterEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xfilterevent'>

-<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>

-<!-- .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>.

-</para>

-<indexterm significance="preferred"><primary>XmbLookupString</primary></indexterm>

-<indexterm significance="preferred"><primary>XwcLookupString</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis id='xmblookupstring'>

-<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 id='xwclookupstring'>

-<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>

-<!-- .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'>

-  <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

-<filename class="headerfile">&lt;X11/Xlib.h&gt;</filename>.

-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>

+<?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 recompilation.
+</para>
+<para>
+As one of the localization mechanisms, Xlib provides an X Input Method (<acronym>XIM</acronym>)
+functional interface 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 characters 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 applications (mixing multiple languages within a single piece of text),
+but they make it possible to implement applications that work in limited
+fashion with more than one language in independent contexts.
+</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>.
+</para>
+<indexterm significance="preferred"><primary>XSetLocaleModifiers</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetlocalemodifiers'>
+<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>
+<!-- .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'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <colspec colname='c3'/>
+  <thead>
+    <row>
+      <entry align='center'>Locale from</entry>
+      <entry align='center'>Affects the Function</entry>
+      <entry align='center'>In</entry>
+    </row>
+  </thead>
+  <tbody>
+    <row>
+      <entry nameend='c3' namest='c1'>
+      <emphasis role='bold'>Locale Query/Configuration:</emphasis></entry>
+    </row>
+    <row>
+      <entry morerows='1'><function>setlocale</function></entry>
+      <entry><function>XSupportsLocale</function></entry>
+      <entry>Locale queried</entry>
+    </row>
+    <row>
+      <entry><function>XSetLocaleModifiers</function></entry>
+      <entry>Locale modified</entry>
+    </row>
+    <row>
+      <entry nameend='c3' namest='c1'>
+      <emphasis role='bold'>Resources:</emphasis></entry>
+    </row>
+    <row>
+      <entry><function>setlocale</function></entry>
+      <entry>
+        <para><function>XrmGetFileDatabase</function></para>
+        <para><function>XrmGetStringDatabase</function></para>
+      </entry>
+      <entry>Locale of <type>XrmDatabase</type></entry>
+    </row>
+    <row>
+      <entry><type>XrmDatabase</type></entry>
+      <entry>
+        <para><function>XrmPutFileDatabase</function></para>
+        <para><function>XrmLocaleOfDatabase</function></para>
+      </entry>
+      <entry>Locale of <type>XrmDatabase</type></entry>
+    </row>
+    <row>
+      <entry nameend='c3' namest='c1'>
+      <emphasis role='bold'>Setting Standard Properties:</emphasis></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>
+        <para><function>XmbTextPropertyToTextList</function></para>
+        <para><function>XwcTextPropertyToTextList</function></para>
+        <para><function>XmbTextListToTextProperty</function></para>
+        <para><function>XwcTextListToTextProperty</function></para>
+      </entry>
+      <entry>Encoding of supplied/returned text</entry>
+    </row>
+    <row>
+      <entry nameend='c3' namest='c1'>
+      <emphasis role='bold'>Text Input:</emphasis></entry>
+    </row>
+    <row>
+      <entry morerows='2'><function>setlocale</function></entry>
+      <entry><function>XOpenIM</function></entry>
+      <entry><acronym>XIM</acronym> input method selection</entry>
+    </row>
+    <row>
+      <entry><function>XRegisterIMInstantiateCallback</function></entry>
+      <entry><acronym>XIM</acronym> selection</entry>
+    </row>
+    <row>
+      <entry><function>XUnregisterIMInstantiateCallback</function></entry>
+      <entry><acronym>XIM</acronym> selection</entry>
+    </row>
+    <row>
+      <entry morerows='1'><type>XIM</type></entry>
+      <entry><function>XCreateIC</function></entry>
+      <entry><acronym>XIC</acronym> input method configuration</entry>
+    </row>
+    <row>
+      <entry><function>XLocaleOfIM</function>,  and so on</entry>
+      <entry>Queried locale</entry>
+    </row>
+    <row>
+      <entry morerows='1'><type>XIC</type></entry>
+      <entry><function>XmbLookupString</function></entry>
+      <entry>Keyboard layout</entry>
+    </row>
+    <row>
+      <entry><function>XwcLookupString</function></entry>
+      <entry>Encoding of returned text</entry>
+    </row>
+    <row>
+      <entry nameend='c3' namest='c1'>
+      <emphasis role='bold'>Text Drawing:</emphasis></entry>
+    </row>
+    <row>
+      <entry morerows='1'><function>setlocale</function></entry>
+      <entry><function>XOpenOM</function></entry>
+      <entry><acronym>XOM</acronym> output method selection</entry>
+    </row>
+    <row>
+      <entry><function>XCreateFontSet</function></entry>
+      <entry>Charsets of fonts in XFontSet</entry>
+    </row>
+    <row>
+      <entry morerows='1'><type>XOM</type></entry>
+      <entry><function>XCreateOC</function></entry>
+      <entry><acronym>XOC</acronym> output method configuration</entry>
+    </row>
+    <row>
+      <entry><function>XLocaleOfOM</function>,  and so on</entry>
+      <entry>Queried locale</entry>
+    </row>
+    <row>
+      <entry morerows='2'><type>XFontSet</type></entry>
+      <entry><function>XmbDrawText</function>,</entry>
+      <entry>Locale of supplied text</entry>
+    </row>
+    <row>
+      <entry><function>XwcDrawText</function>, and so on</entry>
+      <entry>Locale of supplied text</entry>
+    </row>
+    <row>
+      <entry>
+        <para><function>XExtentsOfFontSet</function>,  and so on</para>
+        <para><function>XmbTextExtents</function>,</para>
+        <para><function>XwcTextExtents</function>,  and so on</para>
+      </entry>
+      <entry>Locale-dependent metrics</entry>
+    </row>
+    <row>
+      <entry nameend='c3' namest='c1'>
+      <emphasis role='bold'>Xlib Errors:</emphasis></entry>
+    </row>
+    <row>
+      <entry><function>setlocale</function></entry>
+      <entry>
+        <para><function>XGetErrorDatabaseText</function>,</para>
+        <para><function>XGetErrorText</function>,  and so on</para>
+      </entry>
+      <entry>Locale of error message</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>.
+</para>
+<indexterm significance="preferred"><primary>XVaCreateNestedList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xvacreatenestedlist'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XOpenOM</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xopenom'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XCloseOM</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcloseom'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XSetOMValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetomvalues'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XGetOMValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetomvalues'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XDisplayOfOM</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdisplayofom'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XLocaleOfOM</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xlocaleofom'>
+<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>
+<!-- .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'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <thead>
+    <row>
+      <entry align='left'>Key</entry>
+      <entry align='left'>Explanation</entry>
+    </row>
+  </thead>
+  <tbody>
+    <row>
+      <entry>G</entry>
+      <entry>This value may be read using <function>XGetOMValues</function>.</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para></para>
+
+<informaltable>
+  <tgroup cols='2'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <thead>
+    <row>
+      <entry align='left'><acronym>XOM</acronym> Value</entry>
+      <entry align='left'>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>.
+</para>
+<indexterm significance="preferred"><primary>XCreateOC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcreateoc'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XDestroyOC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdestroyoc'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XOMOfOC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xomofoc'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XSetOCValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetocvalues'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XGetOCValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetocvalues'>
+<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>
+<!-- .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'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <thead>
+    <row>
+      <entry align='left'>Key</entry>
+      <entry align='left'>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>
+
+<para></para>
+
+<informaltable>
+  <tgroup cols='3'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <colspec colname='c3'/>
+  <thead>
+    <row>
+      <entry align='left'><acronym>XOC</acronym> Value</entry>
+      <entry align='left'>Alternative Interface</entry>
+      <entry align='left'>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>.
+</para>
+<indexterm significance="preferred"><primary>XCreateFontSet</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcreatefontset'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XFontsOfFontSet</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xfontsoffontset'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XBaseFontNameListOfFontSet</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xbasefontnamelistoffontset'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XLocaleOfFontSet</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xlocaleoffontset'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XFreeFontSet</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xfreefontset'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XDirectionalDependentDrawing</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdirectionaldependentdrawing'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XContextualDrawing</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcontextualdrawing'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XContextDependentDrawing</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcontextdependentdrawing'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XExtentsOfFontSet</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xextentsoffontset'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XmbTextEscapement</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcTextEscapement</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmbtextescapement'>
+<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 id='xwctextescapement'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XmbTextExtents</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcTextExtents</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmbtextextents'>
+<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 id='xwctextextents'>
+  <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>
+<!-- .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 &lt;= -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 &gt;= 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>.
+</para>
+<indexterm significance="preferred"><primary>XmbTextPerCharExtents</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcTextPerCharExtents</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmbtextpercharextents'>
+<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 id='xwctextpercharextents'>
+<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>
+<!-- .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 <link linkend="Drawing_Text">section 8.6</link> 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>.
+</para>
+<indexterm significance="preferred"><primary>XmbDrawText</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcDrawText</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmbdrawtext'>
+<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 id='xwcdrawtext'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XmbDrawString</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcDrawString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmbdrawstring'>
+<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 id='xwcdrawstring'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XmbDrawImageString</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcDrawImageString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmbdrawimagestring'>
+<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 id='xwcdrawimagestring'>
+<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>
+<!-- .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 <link linkend="Focus_Window">section 13.5.6.3</link>).
+</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 <link linkend="Input_Context_Values">section 13.5.6</link>)
+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'>
+  <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>.
+</para>
+<indexterm significance="preferred"><primary>XOpenIM</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xopenim'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XCloseIM</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcloseim'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XSetIMValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetimvalues'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XGetIMValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetimvalues'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XDisplayOfIM</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdisplayofim'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XLocaleOfIM</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xlocaleofim'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XRegisterIMInstantiateCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xregisteriminstantiatecallback'>
+<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>
+<!-- .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:
+</para>
+<indexterm significance="preferred"><primary>IMInstantiateCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='iminstantiatecallback'>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+To unregister an input method instantiation callback, use
+<function>XUnregisterIMInstantiateCallback</function>.
+</para>
+<indexterm significance="preferred"><primary>XUnregisterIMInstantiateCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xunregisteriminstantiatecallback'>
+<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>
+<!-- .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'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <thead>
+    <row>
+      <entry align='left'>Key</entry>
+      <entry align='left'>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>
+
+<para></para>
+
+<informaltable>
+  <tgroup cols='2'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <thead>
+    <row>
+      <entry align='left'><acronym>XIM</acronym> Value</entry>
+      <entry align='left'>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 <link linkend="Preedit_Callback_Behavior">section 13.5.4.6</link>).
+</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'>
+  <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'>
+  <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:
+</para>
+<indexterm significance="preferred"><primary>DestroyCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='destroycallback'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XCreateIC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcreateic'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XDestroyIC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdestroyic'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XSetICFocus</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xseticfocus'>
+<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>
+<!-- .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>
+<indexterm significance="preferred"><primary>XUnsetICFocus</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xunseticfocus'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XmbResetIC</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcResetIC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmbresetic'>
+<funcprototype>
+  <funcdef>char *<function>XmbResetIC</function></funcdef>
+  <paramdef>XIC<parameter> ic</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<funcsynopsis id='xwcresetic'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XIMOfIC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='ximofic'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XSetICValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xseticvalues'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XGetICValues</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgeticvalues'>
+<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>
+<!-- .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'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <thead>
+    <row>
+      <entry align='left'>Key</entry>
+      <entry align='left'>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>
+
+<para></para>
+
+<!-- .LP -->
+<informaltable>
+  <tgroup cols='7'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <colspec colname='c3'/>
+  <colspec colname='c4'/>
+  <colspec colname='c5'/>
+  <colspec colname='c6'/>
+  <colspec colname='c7'/>
+  <thead>
+    <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>
+    </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>
+      <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>
+
+<para></para>
+
+<!-- .LP -->
+<informaltable>
+  <tgroup cols='6'>
+  <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 <link linkend="Preedit_and_Status_Callbacks">section 13.5.6.13.12</link>).
+</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 <link linkend="Preedit_and_Status_Callbacks">section 13.5.6.13.12</link>).
+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 <link linkend="Preedit_and_Status_Callbacks">section 13.5.6.13.12</link>).
+</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&lt;&lt;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'>
+  <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 <link linkend="Geometry_Management">section 13.5.1.5</link>).
+</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&lt;&lt;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:
+</para>
+<indexterm significance="preferred"><primary>PreeditStateNotifyCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='preeditstatenotifycallback'>
+<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>
+<!-- .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'>
+  <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'>
+  <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:
+</para>
+<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>
+<!-- .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:
+</para>
+<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>
+<!-- .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:
+</para>
+<indexterm significance="preferred"><primary>DestroyCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='destroycallback_xic'>
+<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>
+<!-- .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:
+</para>
+<indexterm significance="preferred"><primary>StringConversionCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='stringconversioncallback'>
+<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>
+<!-- .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 <link linkend="String_Conversion_">section 13.5.6.9</link>)
+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.
+</para>
+<indexterm significance="preferred"><primary>PreeditStartCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='preeditstartcallback'>
+<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>
+<!-- .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.
+</para>
+<indexterm significance="preferred"><primary>PreeditDoneCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='preeditdonecallback'>
+<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>
+<!-- .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:
+</para>
+<indexterm significance="preferred"><primary>PreeditDrawCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='preeditdrawcallback'>
+<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>
+<!-- .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&lt;&lt;1)
+#define     XIMHighlight                   (1L&lt;&lt;2)
+#define     XIMPrimary                     (1L&lt;&lt;5)*
+#define     XIMSecondary                   (1L&lt;&lt;6)*
+#define     XIMTertiary                    (1L&lt;&lt;7)*
+#define     XIMVisibleToForward            (1L&lt;&lt;8)
+#define     XIMVisibleToBackward           (1L&lt;&lt;9)
+#define     XIMVisibleToCenter               (1L&lt;&lt;10)
+
+*† The values for XIMPrimary, XIMSecondary, and XIMTertiary 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.
+
+</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.
+</para>
+<indexterm significance="preferred"><primary>PreeditCaretCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='preeditcaretcallback'>
+<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>
+<!-- .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'>
+  <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.
+</para>
+<indexterm significance="preferred"><primary>StatusStartCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='statusstartcallback'>
+<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>
+<!-- .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.
+</para>
+<indexterm significance="preferred"><primary>StatusDoneCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='statusdonecallback'>
+<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>
+<!-- .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.
+</para>
+<indexterm significance="preferred"><primary>StatusDrawCallback</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='statusdrawcallback'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XFilterEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xfilterevent'>
+<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>
+<!-- .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>.
+</para>
+<indexterm significance="preferred"><primary>XmbLookupString</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcLookupString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmblookupstring'>
+<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 id='xwclookupstring'>
+<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>
+<!-- .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'>
+  <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
+<filename class="headerfile">&lt;X11/Xlib.h&gt;</filename>.
+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>