diff options
Diffstat (limited to 'specs/libX11/CH13.xml')
| -rw-r--r-- | specs/libX11/CH13.xml | 10350 |
1 files changed, 10350 insertions, 0 deletions
diff --git a/specs/libX11/CH13.xml b/specs/libX11/CH13.xml new file mode 100644 index 00000000..eca66fdc --- /dev/null +++ b/specs/libX11/CH13.xml @@ -0,0 +1,10350 @@ +<chapter id="locales_and_internationalized_text_functions"> +<title>Locales and Internationalized Text Functions</title> + +<para> +An internationalized application is one that is adaptable to the requirements of different native +languages, local customs, and character string encodings. The process of adapting the operation +to a particular native language, local custom, or string encoding is called localization. A goal of +internationalization is to permit localization without program source modifications or recompila- +tion. +</para> +<para> +As one of the localization mechanisms, Xlib provides an X Input Method (XIM) functional inter- +face for internationalized text input and an X Output Method (XOM) functional interface for +internationalized text output. +</para> +<para> +Internationalization in X is based on the concept of a locale. A locale defines the localized +behavior of a program at run time. Locales affect Xlib in its: +</para> + +<itemizedlist> + <listitem><para>Encoding and processing of input method text</para></listitem> + <listitem><para>Encoding of resource files and values</para></listitem> + <listitem><para>Encoding and imaging of text strings</para></listitem> + <listitem><para>Encoding and decoding for inter-client text communication</para></listitem> +</itemizedlist> + + +<para> +• +Encoding and decoding for inter-client text communication +Characters from various languages are represented in a computer using an encoding. Different +languages have different encodings, and there are even different encodings for the same charac- +ters in the same language. +</para> +<para> +This chapter defines support for localized text imaging and text input and describes the locale +mechanism that controls all locale-dependent Xlib functions. Sets of functions are provided for +multibyte (char *) text as well as wide character (wchar_t) text in the form supported by the host +C language environment. The multibyte and wide character functions are equivalent except for +the form of the text argument. +</para> +<para> +The Xlib internationalization functions are not meant to provide support for multilingual applica- +tions (mixing multiple languages within a single piece of text), but they make it possible to imple- +ment applications that work in limited fashion with more than one language in independent con- +texts. +</para> +<para> +The remainder of this chapter discusses: +</para> + +<itemizedlist> + <listitem><para>X locale management</para></listitem> + <listitem><para>Locale and modifier dependencies</para></listitem> + <listitem><para>Variable argument lists</para></listitem> + <listitem><para>Output methods</para></listitem> + <listitem><para>Input methods</para></listitem> + <listitem><para>String constants</para></listitem> +</itemizedlist> + + +<sect1 id="X_Locale_Management"> +<title>X Locale Management</title> +<!-- .XS --> +<!-- (SN X Locale Management --> +<!-- .XE --> +<para> +<!-- .LP --> +X supports one or more of the locales defined by the host environment. +On implementations that conform to the ANSI C library, +the locale announcement method is +<function>setlocale .</function> +This function configures the locale operation of both +the host C library and Xlib. +The operation of Xlib is governed by the LC_CTYPE category; +this is called the <emphasis remap='I'>current locale</emphasis>. +An implementation is permitted to provide implementation-dependent +mechanisms for announcing the locale in addition to +<function>setlocale .</function> +</para> +<para> +<!-- .LP --> +On implementations that do not conform to the ANSI C library, +the locale announcement method is Xlib implementation-dependent. +</para> +<para> +<!-- .LP --> +The mechanism by which the semantic operation of Xlib is defined +for a specific locale is implementation-dependent. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +X is not required to support all the locales supported by the host. +To determine if the current locale is supported by X, use +<function>XSupportsLocale .</function> +</para> + +<para>Bool XSupportsLocale()</para> + +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XSupportsLocale</function> +function returns +<function>True</function> +if Xlib functions are capable of operating under the current locale. +If it returns +<function>False ,</function> +Xlib locale-dependent functions for which the +<function>XLocaleNotSupported </function> +return status is defined will return +<function>XLocaleNotSupported .</function> +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> +<!-- .IN "XSetLocaleModifiers" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>char<function> *XSetLocaleModifiers</function></funcdef> + <paramdef>char<parameter> *modifier_list</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>modifier_list</emphasis> + </term> + <listitem> + <para> +Specifies the modifiers. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XSetLocaleModifiers</function> +function sets the X modifiers for the current locale setting. +The modifier_list argument is a null-terminated string of the form +``{@<emphasis remap='I'>category</emphasis>=<emphasis remap='I'>value</emphasis>}'', that is, +having zero or more concatenated ``@<emphasis remap='I'>category</emphasis>=<emphasis remap='I'>value</emphasis>'' +entries, where <emphasis remap='I'>category</emphasis> is a category name +and <emphasis remap='I'>value</emphasis> is the (possibly empty) setting for that category. +The values are encoded in the current locale. +Category names are restricted to the POSIX Portable Filename Character Set. +</para> +<para> +<!-- .LP --> +The local host X locale modifiers announcer (on POSIX-compliant systems, +the XMODIFIERS environment variable) is appended to the modifier_list to +provide default values on the local host. +If a given category appears more than once in the list, +the first setting in the list is used. +If a given category is not included in the full modifier list, +the category is set to an implementation-dependent default +for the current locale. +An empty value for a category explicitly specifies the +implementation-dependent default. +</para> +<para> +<!-- .LP --> +If the function is successful, it returns a pointer to a string. +The contents of the string are such that a subsequent call with that string +(in the same locale) will restore the modifiers to the same settings. +If modifier_list is a NULL pointer, +<function>XSetLocaleModifiers</function> +also returns a pointer to such a string, +and the current locale modifiers are not changed. +</para> +<para> +<!-- .LP --> +If invalid values are given for one or more modifier categories supported by +the locale, a NULL pointer is returned, and none of the +current modifiers are changed. +</para> +<para> +<!-- .LP --> +At program startup, +the modifiers that are in effect are unspecified until +the first successful call to set them. Whenever the locale is changed, the +modifiers that are in effect become unspecified until the next successful call +to set them. +Clients should always call +<function>XSetLocaleModifiers</function> +with a non-NULL modifier_list after setting the locale +before they call any locale-dependent Xlib routine. +</para> +<para> +<!-- .LP --> +The only standard modifier category currently defined is ``im'', +which identifies the desired input method. +The values for input method are not standardized. +A single locale may use multiple input methods, +switching input method under user control. +The modifier may specify the initial input method in effect +or an ordered list of input methods. +Multiple input methods may be specified in a single im value string +in an implementation-dependent manner. +</para> +<para> +<!-- .LP --> +The returned modifiers string is owned by Xlib and should not be modified or +freed by the client. +It may be freed by Xlib after the current locale or modifiers are changed. +Until freed, it will not be modified by Xlib. +</para> +<para> +<!-- .LP --> +The recommended procedure for clients initializing their locale and modifiers +is to obtain locale and modifier announcers separately from +one of the following prioritized sources: +</para> +<itemizedlist> + <listitem> + <para> +A command line option + </para> + </listitem> + <listitem> + <para> +A resource + </para> + </listitem> + <listitem> + <para> +The empty string ("") + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +The first of these that is defined should be used. +Note that when a locale command line option or locale resource is defined, +the effect should be to set all categories to the specified locale, +overriding any category-specific settings in the local host environment. +</para> +</sect1> +<sect1 id="Locale_and_Modifier_Dependencies"> +<title>Locale and Modifier Dependencies</title> +<!-- .XS --> +<!-- (SN Locale and Modifier Dependencies --> +<!-- .XE --> +<para> +<!-- .LP --> +The internationalized Xlib functions operate in the current locale +configured by the host environment and X locale modifiers set by +<function>XSetLocaleModifiers</function> +or in the locale and modifiers configured at the time +some object supplied to the function was created. +For each locale-dependent function, +the following table describes the locale (and modifiers) dependency: +</para> + +<informaltable> + <tgroup cols='3' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <thead> + <row> + <entry>Locale from</entry> + <entry>Affects the Function</entry> + <entry>In</entry> + </row> + </thead> + <tbody> + <row> + <entry></entry> + <entry>Locale Query/Configuration:</entry> + </row> + <row> + <entry><function>setlocale</function></entry> + <entry><function>XSupportsLocale</function></entry> + <entry>Locale queried</entry> + </row> + <row> + <entry></entry> + <entry><function>XSetLocaleModifiers</function></entry> + <entry>Locale modified</entry> + </row> + <row> + <entry></entry> + </row> + <row> + <entry></entry> + <entry>Resources:</entry> + </row> + <row> + <entry><function>setlocale</function></entry> + <entry><function>XrmGetFileDatabase</function></entry> + <entry>Locale of <function>XrmDatabase</function></entry> + </row> + <row> + <entry></entry> + <entry><function>XrmGetStringDatabase</function></entry> + </row> + <row> + <entry><function>XrmDatabase</function></entry> + <entry><function>XrmPutFileDatabase</function></entry> + <entry>Locale of <function>XrmDatabase</function></entry> + </row> + <row> + <entry></entry> + <entry><function>XrmLocaleOfDatabase</function></entry> + </row> + <row> + <entry></entry> + </row> + <row> + <entry></entry> + <entry>Setting Standard Properties:</entry> + </row> + <row> + <entry><function>setlocale</function></entry> + <entry><function>XmbSetWMProperties</function></entry> + <entry>Encoding of supplied/returned + text (some WM_ property + text in environment locale)</entry> + </row> + <row> + <entry><function>setlocale</function></entry> + <entry><function>XmbTextPropertyToTextList</function></entry> + <entry>Encoding of supplied/returned text</entry> + </row> + <row> + <entry></entry> + <entry><function>XwcTextPropertyToTextList</function></entry> + </row> + <row> + <entry></entry> + <entry><function>XmbTextListToTextProperty</function></entry> + </row> + <row> + <entry></entry> + <entry><function>XwcTextListToTextProperty</function></entry> + </row> + <row> + <entry></entry> + </row> + <row> + <entry></entry> + <entry>Text Input:</entry> + </row> + <row> + <entry><function>setlocale</function></entry> + <entry><function>XOpenIM</function></entry> + <entry>XIM input method selection</entry> + </row> + <row> + <entry></entry> + <entry><function>XRegisterIMInstantiateCallback</function></entry> + <entry>XIM selection</entry> + </row> + <row> + <entry></entry> + <entry><function>XUnregisterIMInstantiateCallback</function></entry> + <entry>XIM selection</entry> + </row> + <row> + <entry><function>XIM</function></entry> + <entry><function>XCreateIC</function></entry> + <entry>XIC input method configuration</entry> + </row> + <row> + <entry></entry> + <entry><function>XLocaleOfIM , </function> and so on</entry> + <entry>Queried locale</entry> + </row> + <row> + <entry><function>XIC</function></entry> + <entry><function>XmbLookupString</function></entry> + <entry>Keyboard layout</entry> + </row> + <row> + <entry></entry> + <entry><function>XwcLookupString</function></entry> + <entry>Encoding of returned text</entry> + </row> + <row> + <entry></entry> + </row> + <row> + <entry></entry> + <entry>Text Drawing:</entry> + </row> + <row> + <entry><function>setlocale</function></entry> + <entry><function>XOpenOM</function></entry> + <entry>XOM output method selection</entry> + </row> + <row> + <entry></entry> + <entry><function>XCreateFontSet</function></entry> + <entry>Charsets of fonts in XFontSet</entry> + </row> + <row> + <entry><function>XOM</function></entry> + <entry><function>XCreateOC</function></entry> + <entry>XOC output method configuration</entry> + </row> + <row> + <entry></entry> + <entry><function>XLocaleOfOM , </function> and so on</entry> + <entry>Queried locale</entry> + </row> + <row> + <entry><function>XFontSet</function></entry> + <entry><function>XmbDrawText ,</function></entry> + <entry>Locale of supplied text</entry> + </row> + <row> + <entry></entry> + <entry><function>XwcDrawText ,</function> and so on</entry> + <entry>Locale of supplied text</entry> + </row> + <row> + <entry></entry> + <entry><function>XExtentsOfFontSet ,</function> and so on</entry> + <entry>Locale-dependent metrics</entry> + </row> + <row> + <entry></entry> + <entry><function>XmbTextExtents ,</function></entry> + </row> + <row> + <entry></entry> + <entry><function>XwcTextExtents , </function> and so on</entry> + </row> + <row> + <entry></entry> + </row> + <row> + <entry></entry> + <entry>Xlib Errors:</entry> + </row> + <row> + <entry><function>setlocale</function></entry> + <entry><function>XGetErrorDatabaseText</function></entry> + <entry>Locale of error message</entry> + </row> + <row> + <entry></entry> + <entry><function>XGetErrorText</function></entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +<!-- .LP --> +Clients may assume that a locale-encoded text string returned +by an X function can be passed to a C library routine, or vice versa, +if the locale is the same at the two calls. +</para> +<para> +<!-- .LP --> +All text strings processed by internationalized Xlib functions are assumed +to begin in the initial state of the encoding of the locale, if the encoding +is state-dependent. +</para> +<para> +<!-- .LP --> +All Xlib functions behave as if they do not change the current locale +or X modifier setting. +(This means that if they do change locale or call +<function>XSetLocaleModifiers</function> +with a non-NULL argument, they must save and restore the current state on +entry and exit.) +Also, Xlib functions on implementations that conform to the ANSI C library do +not alter the global state associated with the ANSI C functions +<function>mblen , </function> +<function>mbtowc , </function> +<function>wctomb ,</function> +and +<function>strtok .</function> +</para> +</sect1> +<sect1 id="Variable_Argument_Lists"> +<title>Variable Argument Lists</title> +<!-- .XS --> +<!-- (SN Variable Argument Lists --> +<!-- .XE --> +<para> +<!-- .LP --> +Various functions in this chapter have arguments that conform +to the ANSI C variable argument list calling convention. +Each function denoted with an argument of the form ``...'' takes +a variable-length list of name and value pairs, +where each name is a string and each value is of type +<function>XPointer .</function> +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 +<function>XNVaNestedList</function> +is specified in place of an argument name, +then the following value is interpreted as an +<function>XVaNestedList</function> +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> +<!-- .IN "XVaCreateNestedList" "" @DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>XVaNestedList<function> XVaCreateNestedList</function></funcdef> + <paramdef>int<parameter> dummy</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>dummy</emphasis> + </term> + <listitem> + <para> +Specifies an unused argument (required by ANSI C). +<!-- .ds Al --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + ... + </term> + <listitem> + <para> +Specifies the variable length argument list(Al. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XVaCreateNestedList</function> +function allocates memory and copies its arguments into +a single list pointer, +which may be used as a value for arguments requiring a list value. +Any entries are copied as specified. +Data passed by reference is not copied; +the caller must ensure data remains valid for the lifetime +of the nested list. +The list should be freed using +<function>XFree</function> +when it is no longer needed. +</para> +</sect1> +<sect1 id="Output_Methods"> +<title>Output Methods</title> +<!-- .XS --> +<!-- (SN Output Methods --> +<!-- .XE --> +<para> +<!-- .LP --> +This section provides discussions of the following X Output Method +(XOM) 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 +<function>XOM</function> +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 +<function>XOC ,</function> +which is compatible with +<function>XFontSet</function> +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> +<!-- .IN "XOpenOM" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>XOM<function> XOpenOM</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XrmDatabase<parameter> db</parameter></paramdef> + <paramdef>char<parameter> *res_name</parameter></paramdef> + <paramdef>char<parameter> *res_class</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>db</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to the resource database. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>res_name</emphasis> + </term> + <listitem> + <para> +Specifies the full resource name of the application. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>res_class</emphasis> + </term> + <listitem> + <para> +Specifies the full class name of the application. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XOpenOM</function> +function opens an output method +matching the current locale and modifiers specification. +The current locale and modifiers are bound to the output method +when +<function>XOpenOM</function> +is called. +The locale associated with an output method cannot be changed. +</para> +<para> +<!-- .LP --> +The specific output method to which this call will be routed +is identified on the basis of the current locale and modifiers. +<function>XOpenOM</function> +will identify a default output method corresponding to the +current locale. +That default can be modified using +<function>XSetLocaleModifiers</function> +to set the output method modifier. +</para> +<para> +<!-- .LP --> +The db argument is the resource database to be used by the output method +for looking up resources that are private to the output method. +It is not intended that this database be used to look +up values that can be set as OC values in an output context. +If db is NULL, +no database is passed to the output method. +</para> +<para> +<!-- .LP --> +The res_name and res_class arguments specify the resource name +and class of the application. +They are intended to be used as prefixes by the output method +when looking up resources that are common to all output contexts +that may be created for this output method. +The characters used for resource names and classes must be in the +X Portable Character Set. +The resources looked up are not fully specified +if res_name or res_class is NULL. +</para> +<para> +<!-- .LP --> +The res_name and res_class arguments are not assumed to exist beyond +the call to +<function>XOpenOM .</function> +The specified resource database is assumed to exist for the lifetime +of the output method. +</para> +<para> +<!-- .LP --> +<function>XOpenOM</function> +returns NULL if no output method could be opened. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To close an output method, use +<function>XCloseOM .</function> +<!-- .IN "XCloseOM" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>Status<function> XCloseOM</function></funcdef> + <paramdef>XOM<parameter> om</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>om</emphasis> + </term> + <listitem> + <para> +Specifies the output method. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XCloseOM</function> +function closes the specified output method. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To set output method attributes, use +<function>XSetOMValues .</function> +<!-- .IN "XSetOMValues" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>char<function> *</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 XOM values --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + ... + </term> + <listitem> + <para> +Specifies the variable-length argument list(Al. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>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> +<!-- .IN "XGetOMValues" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>char<function> *</function></funcdef> + <paramdef>XOM<parameter> om</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>om</emphasis> + </term> + <listitem> + <para> +Specifies the output method. +<!-- .ds Al \ to get XOM values --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + ... + </term> + <listitem> + <para> +Specifies the variable-length argument list(Al. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XGetOMValues</function> +function presents a variable argument list programming interface +for querying properties or features of the specified output method. +This function returns NULL if it succeeds; +otherwise, +it returns the name of the first argument that could not be obtained. +</para> +<para> +<!-- .LP --> +To obtain the display associated with an output method, use +<function>XDisplayOfOM .</function> +<!-- .IN "XDisplayOfOM" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>Display<function> *</function></funcdef> + <paramdef>XOM<parameter> om</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>om</emphasis> + </term> + <listitem> + <para> +Specifies the output method. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XDisplayOfOM</function> +function returns the display associated with the specified output method. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To get the locale associated with an output method, use +<function>XLocaleOfOM .</function> +<!-- .IN "XLocaleOfOM" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>char<function> *</function></funcdef> + <paramdef>XOM<parameter> om</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>om</emphasis> + </term> + <listitem> + <para> +Specifies the output method. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XLocaleOfOM</function> +returns the locale associated with the specified output method. +</para> +</sect2> +<sect2 id="X_Output_Method_Values"> +<title>X Output Method Values</title> +<!-- .XS --> +<!-- (SN X Output Method Values --> +<!-- .XE --> +<para> +<!-- .LP --> +The following table describes how XOM values are interpreted by an +output method. +The first column lists the XOM values. The second column indicates +how each of the XOM values are treated by a particular output style. +</para> +<para> +<!-- .LP --> +</para> +<para> +<!-- .LP --> +The following key applies to this table. +</para> + +<informaltable> + <tgroup cols='2' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <thead> + <row> + <entry>Key</entry> + <entry>Explanation</entry> + </row> + </thead> + <tbody> + <row> + <entry>G</entry> + <entry>This value may be read using <function>XGetOMValues .</function></entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<informaltable> + <tgroup cols='2' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <thead> + <row> + <entry>XOM Value</entry> + <entry>Key</entry> + </row> + </thead> + <tbody> + <row> + <entry><function>XNRequiredCharSet</function></entry> + <entry>G</entry> + </row> + <row> + <entry><function>XNQueryOrientation</function></entry> + <entry>G</entry> + </row> + <row> + <entry><function>XNDirectionalDependentDrawing</function></entry> + <entry>G</entry> + </row> + <row> + <entry><function>XNContextualDrawing</function></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 +<function>XNRequiredCharSet</function> +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 +<function>XOMCharSetList .</function> +</para> +<para> +<!-- .LP --> +The +<function>XOMCharSetList</function> +structure is defined as follows: +<!-- .IN "XOMCharSetList" "" "@DEF@" --> +<!-- .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 +<function>XOM .</function> +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 +<function>XNQueryOrientation</function> +argument returns the global orientation of text when drawn. +Other than +<function>XOMOrientation_LTR_TTB ,</function> +the set of orientations supported is locale-dependent. +The value of the argument is a pointer to a structure of type +<function>XOMOrientation .</function> +Clients are responsible for freeing the +<function>XOMOrientation</function> +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> +<function>XOMOrientation_LTR_TTB </function> +left-to-right, top-to-bottom global orientation + </para> + </listitem> + <listitem> + <para> +<function>XOMOrientation_RTL_TTB </function> +right-to-left, top-to-bottom global orientation + </para> + </listitem> + <listitem> + <para> +<function>XOMOrientation_TTB_LTR </function> +top-to-bottom, left-to-right global orientation + </para> + </listitem> + <listitem> + <para> +<function>XOMOrientation_TTB_RTL </function> +top-to-bottom, right-to-left global orientation + </para> + </listitem> + <listitem> + <para> +<function>XOMOrientation_Context </function> +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 +<function>XNDirectionalDependentDrawing</function> +argument indicates whether the text rendering functions +implement implicit handling of directional text. If this value +is +<function>True ,</function> +the output method has knowledge of directional +dependencies and reorders text as necessary when +rendering text. If this value is +<function>False ,</function> +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 +<function>XNContextualDrawing</function> +argument indicates whether the text rendering functions +implement implicit context-dependent drawing. If this value is +<function>True ,</function> +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 XOC values. +It is intended that output methods be controlled by these XOC values. +As new XOC values are created, +they should be registered with the X Consortium. +An +<function>XOC</function> +can be used anywhere an +<function>XFontSet</function> +can be used, and vice versa; +<function>XFontSet</function> +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, +<function>XFontSet</function> +is widely used in several interfaces, so +<function>XOC</function> +is defined as an upward compatible type of +<function>XFontSet .</function> +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To create an output context, use +<function>XCreateOC .</function> +<!-- .IN "XCreateOC" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>XOC<function> XCreateOC</function></funcdef> + <paramdef>XOM<parameter> om</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>om</emphasis> + </term> + <listitem> + <para> +Specifies the output method. +<!-- .ds Al \ to set XOC values --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + ... + </term> + <listitem> + <para> +Specifies the variable-length argument list(Al. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>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 +<function>BadAtom</function> +error. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To destroy an output context, use +<function>XDestroyOC .</function> +<!-- .IN "XDestroyOC" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XDestroyOC</function></funcdef> + <paramdef>XOC<parameter> oc</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>oc</emphasis> + </term> + <listitem> + <para> +Specifies the output context. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XDestroyOC</function> +function destroys the specified output context. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To get the output method associated with an output context, use +<function>XOMOfOC .</function> +<!-- .IN "XOMOfOC" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>XOM<function> XOMOfOC</function></funcdef> + <paramdef>XOC<parameter> oc</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>oc</emphasis> + </term> + <listitem> + <para> +Specifies the output context. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XOMOfOC</function> +function returns the output method associated with the +specified output context. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +Xlib provides two functions for setting and reading output context values, +respectively, +<function>XSetOCValues</function> +and +<function>XGetOCValues .</function> +Both functions have a variable-length argument list. +In that argument list, any XOC value's name must be denoted +with a character string using the X Portable Character Set. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To set XOC values, use +<function>XSetOCValues .</function> +<!-- .IN "XSetOCValues" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>char<function> *</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 XOC values --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + ... + </term> + <listitem> + <para> +Specifies the variable-length argument list(Al. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>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 +<function>BadAtom </function> +error. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To obtain XOC values, use +<function>XGetOCValues .</function> +<!-- .IN "XGetOCValues" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>char<function> *</function></funcdef> + <paramdef>XOC<parameter> oc</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>oc</emphasis> + </term> + <listitem> + <para> +Specifies the output context. +<!-- .ds Al \ to get XOC values --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + ... + </term> + <listitem> + <para> +Specifies the variable-length argument list(Al. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XGetOCValues</function> +function returns NULL if no error occurred; otherwise, +it returns the name of the first argument that could not be obtained. +An argument might not be obtained for any of the following reasons: +</para> +<itemizedlist> + <listitem> + <para> +The argument name is not recognized. + </para> + </listitem> + <listitem> + <para> +An implementation-dependent error occurs. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +Each argument value +following a name must point to a location where the value is to be stored. +</para> +</sect2> + +<sect2 id="Output_Context_Values"> +<title>Output Context Values</title> +<!-- .XS --> +<!-- (SN Output Context Values --> +<!-- .XE --> +<para> +<!-- .LP --> +The following table describes how XOC values are interpreted +by an output method. +The first column lists the XOC 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 XOC values is treated. +</para> +<!-- .LP --> +<para> +The following keys apply to this table. +</para> +<informaltable> + <tgroup cols='2' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <thead> + <row> + <entry>Key</entry> + <entry>Explanation</entry> + </row> + </thead> + <tbody> + <row> + <entry>C</entry> + <entry>This value must be set with <function>XCreateOC .</function></entry> + </row> + <row> + <entry>D</entry> + <entry>This value may be set using <function>XCreateOC .</function> + If it is not set,a default is provided.</entry> + </row> + <row> + <entry>G</entry> + <entry>This value may be read using <function>XGetOCValues .</function></entry> + </row> + <row> + <entry>S</entry> + <entry>This value must be set using <function>XSetOCValues .</function></entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<!-- .LP --> +<informaltable> + <tgroup cols='3' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <thead> + <row> + <entry>XOC Value</entry> + <entry>Alternative Interface</entry> + <entry>Key</entry> + </row> + </thead> + <tbody> + <row> + <entry>BaseFontName</entry> + <entry><function>XCreateFontSet</function></entry> + <entry>C-G</entry> + </row> + <row> + <entry>MissingCharSet</entry> + <entry><function>XCreateFontSet</function></entry> + <entry>G</entry> + </row> + <row> + <entry>DefaultString</entry> + <entry><function>XCreateFontSet</function></entry> + <entry>G</entry> + </row> + <row> + <entry>Orientation</entry> + <entry>-</entry> + <entry>D-S-G</entry> + </row> + <row> + <entry>ResourceName</entry> + <entry>-</entry> + <entry>S-G</entry> + </row> + <row> + <entry>ResourceClass</entry> + <entry>-</entry> + <entry>S-G</entry> + </row> + <row> + <entry>FontInfo</entry> + <entry><function>XFontsOfFontSet</function></entry> + <entry>G</entry> + </row> + <row> + <entry>OMAutomatic</entry> + <entry>-</entry> + <entry>G</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +<!-- .LP --> +</para> +<sect3 id="Base_Font_Name"> +<title>Base Font Name</title> +<!-- .XS --> +<!-- (SN Base Font Name --> +<!-- .XE --> +<para> +<!-- .LP --> +The +<function>XNBaseFontName</function> +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 XLFD font names permits Xlib to obtain the fonts needed for a +variety of locales from a single locale-independent base font name. +The single base font name should name a family of fonts whose members +are encoded in the various charsets needed by the locales of interest. +</para> +<para> +<!-- .LP --> +An XLFD base font name can explicitly name a charset needed for the locale. +This allows the user to specify an exact font for use with a charset required +by a locale, fully controlling the font selection. +</para> +<para> +<!-- .LP --> +If a base font name is not an XLFD name, +Xlib will attempt to obtain an XLFD name from the font properties +for the font. +If Xlib is successful, the +<function>XGetOCValues</function> +function will return this XLFD 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 +<function>XNBaseFontName</function> +XOC 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 +<function>XOC .</function> +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 +<function>XNMissingCharSet</function> +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 +<function>XOMCharSetList .</function> +</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 +<function>XOC .</function> +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 +<function>XOC</function> +that has missing charsets, some characters in the locale will not be +drawable. +The +<function>XNDefaultString</function> +argument returns a pointer to a string that represents the glyphs +that are drawn with this +<function>XOC</function> +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 +<function>XOC .</function> +</para> +<para> +<!-- .LP --> +If the +<function>XNDefaultString</function> +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 +<function>XOC .</function> +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 +<function>XNOrientation</function> +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 +<function>XNQueryOrientation</function> +argument specified in the +<function>XOrientation</function> +list. +The value of the argument is of type +<function>XOrientation .</function> +When +<function>XNOrientation</function> +is queried, the value specifies the current orientation. +When +<function>XNOrientation</function> +is set, a value is used to set the current orientation. +</para> +<para> +<!-- .LP --> +When +<function>XOMOrientation_Context</function> +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 +<function>XOMOrientation_LTR_TTB .</function> +</para> +<para> +<!-- .LP --> +The +<function>XNOrientation</function> +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 +<function>XNResourceName</function> +and +<function>XNResourceClass</function> +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 XOM values be +set as resources. +</para> +<para> +<!-- .LP --> +When querying for the +<function>XNResourceName</function> +or +<function>XNResourceClass</function> +XOC 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 +<function>XOC</function> +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 +<function>XNFontInfo</function> +argument specifies a list of one or more +<function>XFontStruct</function> +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 +<function>XOMFontInfo .</function> +</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 +<function>XFontStruct</function> +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 +<function>XFontStruct</function> +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 +<function>XFontStruct</function> +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 +<function>XOC .</function> +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 +<function>XFontStruct</function> +structures in the +<function>XFontStructSet</function> +is undefined. +Also, note that all properties in the +<function>XFontStruct</function> +structures are in the STRING encoding. +</para> +<para> +<!-- .LP --> +The client must not free the +<function>XOMFontInfo</function> +struct itself; it will be freed when the +<function>XOC</function> +is closed. +</para> +</sect3> +<sect3 id="OM_Automatic"> +<title>OM Automatic</title> +<!-- .XS --> +<!-- (SN OM Automatic --> +<!-- .XE --> +<para> +<!-- .LP --> +The +<function>XNOMAutomatic</function> +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 +<function>XNOMAutomatic</function> +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 +<function>XFontSet</function> +is an opaque type representing the state of a particular output thread +and is equivalent to the type +<function>XOC .</function> +</para> +<para> +<!-- .LP --> +<!-- .sp --> +The +<function>XCreateFontSet</function> +function is a convenience function for creating an output context using +only default values. The returned +<function>XFontSet</function> +has an implicitly created +<function>XOM .</function> +This +<function>XOM</function> +has an OM value +<function>XNOMAutomatic</function> +automatically set to +<function>True</function> +so that the output context self indicates whether it was created by +<function>XCreateOC</function> +or +<function>XCreateFontSet .</function> +<!-- .IN "XCreateFontSet" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>XFontSet<function> XCreateFontSet</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>char<parameter> *base_font_name_list</parameter></paramdef> + <paramdef>char<parameter> ***missing_charset_list_return</parameter></paramdef> + <paramdef>int<parameter> *missing_charset_count_return</parameter></paramdef> + <paramdef>char<parameter> **def_string_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>base_font_name_list</emphasis> + </term> + <listitem> + <para> +Specifies the base font names. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>missing_charset_list_return</emphasis> + </term> + <listitem> + <para> +Returns the missing charsets. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>missing_charset_count_return</emphasis> + </term> + <listitem> + <para> +Returns the number of missing charsets. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>def_string_return</emphasis> + </term> + <listitem> + <para> +Returns the string drawn for missing charsets. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XCreateFontSet</function> +function creates a font set for the specified display. +The font set is bound to the current locale when +<function>XCreateFontSet</function> +is called. +The font set may be used in subsequent calls to obtain font +and character information and to image text in the locale of the font set. +</para> +<para> +<!-- .LP --> +The base_font_name_list argument is a list of base font names +that Xlib uses to load the fonts needed for the locale. +The base font names are a comma-separated list. +The string is null-terminated +and is assumed to be in the Host Portable Character Encoding; +otherwise, the result is implementation-dependent. +White space immediately on either side of a separating comma is ignored. +</para> +<para> +<!-- .LP --> +Use of XLFD font names permits Xlib to obtain the fonts needed for a +variety of locales from a single locale-independent base font name. +The single base font name should name a family of fonts whose members +are encoded in the various charsets needed by the locales of interest. +</para> +<para> +<!-- .LP --> +An XLFD base font name can explicitly name a charset needed for the locale. +This allows the user to specify an exact font for use with a charset required +by a locale, fully controlling the font selection. +</para> +<para> +<!-- .LP --> +If a base font name is not an XLFD name, +Xlib will attempt to obtain an XLFD name from the font properties +for the font. +If this action is successful in obtaining an XLFD name, the +<function>XBaseFontNameListOfFontSet</function> +function will return this XLFD 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 +<function>XFontSet .</function> +</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 XLFD-conforming base font name that specifies the required +charset or a superset of the required charset in its +<function>CharSetRegistry</function> +and +<function>CharSetEncoding</function> +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 XLFD-conforming base font names +that specify one or more charsets that can be remapped to support the +required charset. +The Xlib implementation may recognize various mappings +from a required charset to one or more other charsets +and use the fonts for those charsets. +For example, JIS Roman is ASCII with tilde and backslash replaced +by yen and overbar; +Xlib may load an ISO8859-1 font to support this character set +if a JIS Roman font is not available. + </para> + </listitem> + <listitem> + <para> +The first XLFD-conforming font name or the first non-XLFD font name +for which an XLFD font name can be obtained, combined with the +required charset (replacing the +<function>CharSetRegistry</function> +and +<function>CharSetEncoding</function> +fields in the XLFD 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 XLFD 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 +<function>XFontSet ,</function> +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 +<function>XFontSet</function> +to font_set. +</para> +<para> +<!-- .LP --> +When an Xmb/wc drawing or measuring function is called with an +<function>XFontSet</function> +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 +<function>XFontSet</function> +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 +<function>XFontSet .</function> +</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 +<function>XFontSet .</function> +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 +<function>XFontSet</function> +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 +<function>XFontStruct</function> +structures and full font names given an +<function>XFontSet ,</function> +use +<function>XFontsOfFontSet .</function> +<!-- .IN "XFontsOfFontSet" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int<function> XFontsOfFontSet</function></funcdef> + <paramdef>XFontSet<parameter> font_set</parameter></paramdef> + <paramdef>XFontStruct<parameter> ***font_struct_list_return</parameter></paramdef> + <paramdef>char<parameter> ***font_name_list_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>font_set</emphasis> + </term> + <listitem> + <para> +Specifies the font set. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>font_struct_list_return</emphasis> + </term> + <listitem> + <para> +Returns the list of font structs. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>font_name_list_return</emphasis> + </term> + <listitem> + <para> +Returns the list of font names. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XFontsOfFontSet</function> +function returns a list of one or more +<function>XFontStructs</function> +and font names for the fonts used by the Xmb and Xwc layers +for the given font set. +A list of pointers to the +<function>XFontStruct</function> +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 +<function>XFontStruct</function> +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 +<function>XFontStruct</function> +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 +<function>XFontSet .</function> +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 +<function>XFontStruct</function> +structures in the +<function>XFontStructSet</function> +is undefined. +Also, note that all properties in the +<function>XFontStruct</function> +structures are in the STRING encoding. +</para> +<para> +<!-- .LP --> +The +<function>XFontStruct</function> +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 +<function>XFontSet .</function> +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 +<function>XFontSet ,</function> +use +<function>XBaseFontNameListOfFontSet .</function> +<!-- .IN "XBaseFontNameListOfFontSet" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>char<function> *XBaseFontNameListOfFontSet</function></funcdef> + <paramdef>XFontSet<parameter> font_set</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>font_set</emphasis> + </term> + <listitem> + <para> +Specifies the font set. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XBaseFontNameListOfFontSet</function> +function returns the original base font name list supplied +by the client when the +<function>XFontSet</function> +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 XLFD name from the font properties for the font specified +by a non-XLFD base name, the +<function>XBaseFontNameListOfFontSet</function> +function will return the XLFD name instead of the non-XLFD 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 +<function>XFontSet .</function> +Until freed, its contents will not be modified by Xlib. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To obtain the locale name given an +<function>XFontSet ,</function> +use +<function>XLocaleOfFontSet .</function> +<!-- .IN "XLocaleOfFontSet" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>char<function> *XLocaleOfFontSet</function></funcdef> + <paramdef>XFontSet<parameter> font_set</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>font_set</emphasis> + </term> + <listitem> + <para> +Specifies the font set. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XLocaleOfFontSet</function> +function +returns the name of the locale bound to the specified +<function>XFontSet ,</function> +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 +<function>XFontSet .</function> +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 +<function>XOM</function> +if the output context was created by +<function>XCreateFontSet .</function> +<!-- .IN "XFreeFontSet" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XFreeFontSet</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XFontSet<parameter> font_set</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>font_set</emphasis> + </term> + <listitem> + <para> +Specifies the font set. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XFreeFontSet</function> +function frees the specified font set. +The associated base font name list, font name list, +<function>XFontStruct</function> +list, and +<function>XFontSetExtents , </function> +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> +<!-- .IN "XDirectionalDependentDrawing" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>Bool<function> XDirectionalDependentDrawing</function></funcdef> + <paramdef>XFontSet<parameter> font_set</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>font_set</emphasis> + </term> + <listitem> + <para> +Specifies the font set. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XDirectionalDependentDrawing</function> +function returns +<function>True</function> +if the drawing functions implement implicit text directionality; +otherwise, it returns +<function>False .</function> +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To find out about context-dependent rendering, use +<function>XContextualDrawing .</function> +<!-- .IN "XContextualDrawing" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>Bool<function> XContextualDrawing</function></funcdef> + <paramdef>XFontSet<parameter> font_set</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>font_set</emphasis> + </term> + <listitem> + <para> +Specifies the font set. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XContextualDrawing</function> +function returns +<function>True</function> +if text drawn with the font set might include context-dependent drawing; +otherwise, it returns +<function>False .</function> +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To find out about context-dependent or direction-dependent rendering, use +<function>XContextDependentDrawing .</function> +<!-- .IN "XContextDependentDrawing" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>Bool<function> XContextDependentDrawing</function></funcdef> + <paramdef>XFontSet<parameter> font_set</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>font_set</emphasis> + </term> + <listitem> + <para> +Specifies the font set. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XContextDependentDrawing</function> +function returns +<function>True</function> +if the drawing functions implement implicit text directionality or +if text drawn with the font_set might include context-dependent drawing; +otherwise, it returns +<function>False .</function> +</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 +<function>XFontSetExtents</function> +structure: +<!-- .IN "XFontSetExtents" "" "@DEF@" --> +</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 +<function>XRectangle</function> +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>XmbPerCharExtents</function> +or +<function>XwcPerCharExtents .</function> +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To obtain the maximum extents structure given an +<function>XFontSet ,</function> +use +<function>XExtentsOfFontSet .</function> +<!-- .IN "XExtentsOfFontSet" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>XFontSetExtents<function> *XExtentsOfFontSet</function></funcdef> + <paramdef>XFontSet<parameter> font_set</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>font_set</emphasis> + </term> + <listitem> + <para> +Specifies the font set. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XExtentsOfFontSet</function> +function returns an +<function>XFontSetExtents</function> +structure for the fonts used by the Xmb and Xwc layers +for the given font set. +</para> +<para> +<!-- .LP --> +The +<function>XFontSetExtents</function> +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 +<function>XFontSet .</function> +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> +<!-- .IN "XmbTextEscapement" "" "@DEF@" --> +<!-- .IN "XwcTextEscapement" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int<function> XmbTextEscapement</function></funcdef> + <paramdef>XFontSet<parameter> font_set</parameter></paramdef> + <paramdef>char<parameter> *string</parameter></paramdef> + <paramdef>int<parameter> num_bytes</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<funcsynopsis> +<funcprototype> + <funcdef>int<function> XwcTextEscapement</function></funcdef> + <paramdef>XFontSet<parameter> font_set</parameter></paramdef> + <paramdef>wchar_t<parameter> *string</parameter></paramdef> + <paramdef>int<parameter> num_wchars</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>font_set</emphasis> + </term> + <listitem> + <para> +Specifies the font set. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>string</emphasis> + </term> + <listitem> + <para> +Specifies the character string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_bytes</emphasis> + </term> + <listitem> + <para> +Specifies the number of bytes in the string argument. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_wchars</emphasis> + </term> + <listitem> + <para> +Specifies the number of characters in the string argument. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XmbTextEscapement</function> +and +<function>XwcTextEscapement</function> +functions return the escapement in pixels of the specified string as a value, +using the fonts loaded for the specified font set. +The escapement is the distance in pixels in the primary draw +direction from the drawing origin to the origin of the next character to +be drawn, assuming that the rendering of the next character is not +dependent on the supplied string. +</para> +<para> +<!-- .LP --> +Regardless of the character rendering order, +the escapement is always positive. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To obtain the overall_ink_return and overall_logical_return arguments, +the overall bounding box of the string's image, and a logical bounding box, +use +<function>XmbTextExtents</function> + or +<function>XwcTextExtents .</function> +<!-- .IN "XmbTextExtents" "" "@DEF@" --> +<!-- .IN "XwcTextExtents" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int<function> XmbTextExtents</function></funcdef> + <paramdef>XFontSet<parameter> font_set</parameter></paramdef> + <paramdef>char<parameter> *string</parameter></paramdef> + <paramdef>int<parameter> num_bytes</parameter></paramdef> + <paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef> + <paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<funcsynopsis> +<funcprototype> + <funcdef>int<function> XwcTextExtents</function></funcdef> + <paramdef>XFontSet<parameter> font_set</parameter></paramdef> + <paramdef>wchar_t<parameter> *string</parameter></paramdef> + <paramdef>int<parameter> num_wchars</parameter></paramdef> + <paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef> + <paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>font_set</emphasis> + </term> + <listitem> + <para> +Specifies the font set. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>string</emphasis> + </term> + <listitem> + <para> +Specifies the character string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_bytes</emphasis> + </term> + <listitem> + <para> +Specifies the number of bytes in the string argument. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_wchars</emphasis> + </term> + <listitem> + <para> +Specifies the number of characters in the string argument. +<!-- .ds Ov dimensions --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>overall_ink_return</emphasis> + </term> + <listitem> + <para> +Returns the overall ink dimensions. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>overall_logical_return</emphasis> + </term> + <listitem> + <para> +Returns the overall logical dimensions. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XmbTextExtents</function> +and +<function>XwcTextExtents</function> +functions set the components of the specified overall_ink_return and +overall_logical_return +arguments to the overall bounding box of the string's image +and a logical bounding box for spacing purposes, respectively. +They return the value returned by +<function>XmbTextEscapement</function> +or +<function>XwcTextEscapement .</function> +These metrics are relative to the drawing origin of the string, +using the fonts loaded for the specified font set. +</para> +<para> +<!-- .LP --> +If the overall_ink_return argument is non-NULL, +it is set to the bounding box of the string's character ink. +The overall_ink_return for a nondescending, horizontally drawn +Latin character is conventionally entirely above the baseline; +that is, overall_ink_return.height <= -overall_ink_return.y. +The overall_ink_return for a nonkerned character +is entirely at, and to the right of, the origin; +that is, overall_ink_return.x >= 0. +A character consisting of a single pixel at the origin would set +overall_ink_return fields y = 0, x = 0, width = 1, and height = 1. +</para> +<para> +<!-- .LP --> +If the overall_logical_return argument is non-NULL, +it is set to the bounding box that provides minimum spacing +to other graphical features for the string. +Other graphical features, for example, a border surrounding the text, +should not intersect this rectangle. +</para> +<para> +<!-- .LP --> +When the +<function>XFontSet</function> +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> +<!-- .IN "XmbTextPerCharExtents" "" "@DEF@" --> +<!-- .IN "XwcTextPerCharExtents" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>Status<function> XmbTextPerCharExtents</function></funcdef> + <paramdef>XFontSet<parameter> font_set</parameter></paramdef> + <paramdef>char<parameter> *string</parameter></paramdef> + <paramdef>int<parameter> num_bytes</parameter></paramdef> + <paramdef>XRectangle<parameter> *ink_array_return</parameter></paramdef> + <paramdef>XRectangle<parameter> *logical_array_return</parameter></paramdef> + <paramdef>int<parameter> array_size</parameter></paramdef> + <paramdef>int<parameter> *num_chars_return</parameter></paramdef> + <paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef> + <paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<funcsynopsis> +<funcprototype> + <funcdef>Status<function> XwcTextPerCharExtents</function></funcdef> + <paramdef>XFontSet<parameter> font_set</parameter></paramdef> + <paramdef>wchar_t<parameter> *string</parameter></paramdef> + <paramdef>int<parameter> num_wchars</parameter></paramdef> + <paramdef>XRectangle<parameter> *ink_array_return</parameter></paramdef> + <paramdef>XRectangle<parameter> *logical_array_return</parameter></paramdef> + <paramdef>int<parameter> array_size</parameter></paramdef> + <paramdef>int<parameter> *num_chars_return</parameter></paramdef> + <paramdef>XRectangle<parameter> *overall_ink_return</parameter></paramdef> + <paramdef>XRectangle<parameter> *overall_logical_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>font_set</emphasis> + </term> + <listitem> + <para> +Specifies the font set. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>string</emphasis> + </term> + <listitem> + <para> +Specifies the character string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_bytes</emphasis> + </term> + <listitem> + <para> +Specifies the number of bytes in the string argument. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_wchars</emphasis> + </term> + <listitem> + <para> +Specifies the number of characters in the string argument. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>ink_array_return</emphasis> + </term> + <listitem> + <para> +Returns the ink dimensions for each character. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>logical_array_return</emphasis> + </term> + <listitem> + <para> +Returns the logical dimensions for each character. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>array_size</emphasis> + </term> + <listitem> + <para> +Specifies the size of ink_array_return and logical_array_return. +The caller must pass in arrays of this size. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_chars_return</emphasis> + </term> + <listitem> + <para> +Returns the number of characters in the string argument. +<!-- .ds Ov extents of the entire string --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>overall_ink_return</emphasis> + </term> + <listitem> + <para> +Returns the overall ink dimensions. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>overall_logical_return</emphasis> + </term> + <listitem> + <para> +Returns the overall logical dimensions. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XmbTextPerCharExtents</function> +and +<function>XwcTextPerCharExtents</function> +functions return the text dimensions of each character of the specified text, +using the fonts loaded for the specified font set. +Each successive element of ink_array_return and logical_array_return +is set to the successive character's drawn metrics, +relative to the drawing origin of the string and one +rectangle +for each character in the supplied text string. +The number of elements of ink_array_return and logical_array_return +that have been set is returned to num_chars_return. +</para> +<para> +<!-- .LP --> +Each element of ink_array_return is set to the bounding box +of the corresponding character's drawn foreground color. +Each element of logical_array_return is set to the bounding box +that provides minimum spacing to other graphical features +for the corresponding character. +Other graphical features should not intersect any of the +logical_array_return rectangles. +</para> +<para> +<!-- .LP --> +Note that an +<function>XRectangle</function> +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 +<function>XRectangles</function> +of those characters are the same. +</para> +<para> +<!-- .LP --> +When the +<function>XFontSet</function> +has missing charsets, metrics for each unavailable +character are taken from the default string returned by +<function>XCreateFontSet</function> +so that the metrics represent the text as it will actually be drawn. +The behavior for an invalid codepoint is undefined. +</para> +<para> +<!-- .LP --> +If the array_size is too small for the number of characters in the +supplied text, the functions return zero +and num_chars_return is set to the number of rectangles required. +Otherwise, the functions return a nonzero value. +</para> +<para> +<!-- .LP --> +If the overall_ink_return or overall_logical_return argument is non-NULL, +<function>XmbTextPerCharExtents</function> +and +<function>XwcTextPerCharExtents</function> +return the maximum extent of the string's metrics to overall_ink_return +or overall_logical_return, as returned by +<function>XmbTextExtents</function> +or +<function>XwcTextExtents .</function> +</para> +</sect2> +<sect2 id="Drawing_Text_Using_Font_Sets"> +<title>Drawing Text Using Font Sets</title> +<!-- .XS --> +<!-- (SN Drawing Text Using Font Sets --> +<!-- .XE --> +<para> +<!-- .LP --> +The functions defined in this section +draw text at a specified location in a drawable. +They are similar to the functions +<function>XDrawText ,</function> +<function>XDrawString ,</function> +and +<function>XDrawImageString</function> +except that they work with font sets instead of single fonts +and interpret the text based on the locale of the font set +instead of treating the bytes of the string as direct font indexes. +See section 8.6 for details of the use of Graphics Contexts (GCs) +and possible protocol errors. +If a +<function>BadFont</function> +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 --> +<!-- .IN "XmbTextItem" "" "@DEF@" --> +<!-- .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 --> +<!-- .IN "XwcTextItem" "" "@DEF@" --> +<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> +<!-- .IN "XmbDrawText" "" "@DEF@" --> +<!-- .IN "XwcDrawText" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XmbDrawText</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>intx,<parameter> y</parameter></paramdef> + <paramdef>XmbTextItem<parameter> *items</parameter></paramdef> + <paramdef>int<parameter> nitems</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XwcDrawText</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>intx,<parameter> y</parameter></paramdef> + <paramdef>XwcTextItem<parameter> *items</parameter></paramdef> + <paramdef>int<parameter> nitems</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>d</emphasis> + </term> + <listitem> + <para> +Specifies the drawable. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. +<!-- .ds Xy --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>x</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>y</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates(Xy. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>items</emphasis> + </term> + <listitem> + <para> +Specifies an array of text items. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>nitems</emphasis> + </term> + <listitem> + <para> +Specifies the number of text items in the array. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XmbDrawText</function> +and +<function>XwcDrawText </function> +functions allow complex spacing and font set shifts between text strings. +Each text item is processed in turn, with the origin of a text +element advanced in the primary draw direction by the escapement of the +previous text item. +A text item delta specifies an additional escapement of the text item +drawing origin in the primary draw direction. +A font_set member other than +<function>None</function> +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 +<function>None</function> +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 +<function>XFontSet</function> +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> +<!-- .IN "XmbDrawString" "" "@DEF@" --> +<!-- .IN "XwcDrawString" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XmbDrawString</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>XFontSet<parameter> font_set</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>intx,<parameter> y</parameter></paramdef> + <paramdef>char<parameter> *string</parameter></paramdef> + <paramdef>int<parameter> num_bytes</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XwcDrawString</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>XFontSet<parameter> font_set</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>intx,<parameter> y</parameter></paramdef> + <paramdef>wchar_t<parameter> *string</parameter></paramdef> + <paramdef>int<parameter> num_wchars</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>d</emphasis> + </term> + <listitem> + <para> +Specifies the drawable. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>font_set</emphasis> + </term> + <listitem> + <para> +Specifies the font set. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. +<!-- .ds Xy --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>x</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>y</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates(Xy. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>string</emphasis> + </term> + <listitem> + <para> +Specifies the character string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_bytes</emphasis> + </term> + <listitem> + <para> +Specifies the number of bytes in the string argument. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_wchars</emphasis> + </term> + <listitem> + <para> +Specifies the number of characters in the string argument. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XmbDrawString</function> +and +<function>XwcDrawString</function> +functions draw the specified text with the foreground pixel. +When the +<function>XFontSet</function> +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> +<!-- .IN "XmbDrawImageString" "" "@DEF@" --> +<!-- .IN "XwcDrawImageString" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XmbDrawImageString</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>XFontSet<parameter> font_set</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>intx,<parameter> y</parameter></paramdef> + <paramdef>char<parameter> *string</parameter></paramdef> + <paramdef>int<parameter> num_bytes</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XwcDrawImageString</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Drawable<parameter> d</parameter></paramdef> + <paramdef>XFontSet<parameter> font_set</parameter></paramdef> + <paramdef>GC<parameter> gc</parameter></paramdef> + <paramdef>intx,<parameter> y</parameter></paramdef> + <paramdef>wchar_t<parameter> *string</parameter></paramdef> + <paramdef>int<parameter> num_wchars</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>d</emphasis> + </term> + <listitem> + <para> +Specifies the drawable. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>font_set</emphasis> + </term> + <listitem> + <para> +Specifies the font set. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the GC. +<!-- .ds Xy --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>x</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>y</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates(Xy. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>string</emphasis> + </term> + <listitem> + <para> +Specifies the character string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_bytes</emphasis> + </term> + <listitem> + <para> +Specifies the number of bytes in the string argument. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_wchars</emphasis> + </term> + <listitem> + <para> +Specifies the number of characters in the string argument. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XmbDrawImageString</function> +and +<function>XwcDrawImageString</function> +functions fill a destination rectangle with the background pixel defined +in the GC and then paint the text with the foreground pixel. +The filled rectangle is the rectangle returned to overall_logical_return by +<function>XmbTextExtents</function> +or +<function>XwcTextExtents</function> +for the same text and +<function>XFontSet .</function> +</para> +<para> +<!-- .LP --> +When the +<function>XFontSet</function> +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 +(XIM) 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 +<function>XIM</function> +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 +<function>XIM</function> +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 +<function>XIC .</function> +</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 +<function>XIC</function> +is created with the +<function>XCreateIC</function> +function, providing an +<function>XIM</function> +argument and affiliating the input context to the input method +for its lifetime. +When an input method is closed with +<function>XCloseIM ,</function> +all of its affiliated input contexts should not be used any more +(and should preferably be destroyed before closing the input method). +</para> +<para> +<!-- .LP --> +Considering the example of a client window with multiple text entry areas, +the application programmer could, for example, choose to implement as follows: +</para> +<itemizedlist> + <listitem> + <para> +As many input contexts are created as text entry areas, and the client +will get the input accumulated on each context each time it looks up +in that context. + </para> + </listitem> + <listitem> + <para> +A single context is created for a top-level window in the application. +If such a window contains several text entry areas, +each time the user moves to another text entry area, +the client has to indicate changes in the context. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +A range of choices can be made by application designers to use +either a single or multiple input contexts, +according to the needs of their application. +</para> +</sect3> +<sect3 id="Getting_Keyboard_Input"> +<title>Getting Keyboard Input</title> +<!-- .XS --> +<!-- (SN Getting Keyboard Input --> +<!-- .XE --> +<para> +<!-- .LP --> +To obtain characters from an input method, +a client must call the function +<function>XmbLookupString</function> +or +<function>XwcLookupString</function> +with an input context created from that input method. +Both a locale and display are bound to an input method when it is opened, +and an input context inherits this locale and display. +Any strings returned by +<function>XmbLookupString</function> +or +<function>XwcLookupString</function> +will be encoded in that locale. +</para> +</sect3> +<sect3 id="Focus_Management"> +<title>Focus Management</title> +<!-- .XS --> +<!-- (SN Focus Management --> +<!-- .XE --> +<para> +<!-- .LP --> +For each text entry area in which the +<function>XmbLookupString</function> +or +<function>XwcLookupString</function> +functions are used, +there will be an associated input context. +</para> +<para> +<!-- .LP --> +When the application focus moves to a text entry area, +the application must set the input context focus to the +input context associated with that area. +The input context focus is set by calling +<function>XSetICFocus</function> +with the appropriate input context. +</para> +<para> +<!-- .LP --> +Also, when the application focus moves out of a text entry area, the +application should unset the focus for the associated input context +by calling +<function>XUnsetICFocus .</function> +As an optimization, if +<function>XSetICFocus</function> +is called successively on two different input contexts, +setting the focus on the second +will automatically unset the focus on the first. +</para> +<para> +<!-- .LP --> +To set and unset the input context focus correctly, +it is necessary to track application-level focus changes. +Such focus changes do not necessarily correspond to X server focus changes. +</para> +<para> +<!-- .LP --> +If a single input context +is being used to do input for +multiple text entry areas, it will also be necessary +to set the focus window of the +input context whenever the focus window changes +(see section 13.5.6.3). +</para> +</sect3> +<sect3 id="Geometry_Management"> +<title>Geometry Management</title> +<!-- .XS --> +<!-- (SN Geometry Management --> +<!-- .XE --> +<para> +<!-- .LP --> +In most input method architectures +(on-the-spot being the notable exception), +the input method will perform the display of its own data. +To provide better visual locality, +it is often desirable to have the input method areas embedded within a client. +To do this, +the client may need to allocate space for an input method. +Xlib provides support that allows the size and position of input method +areas to be provided by a client. +The input method areas that are supported for geometry management +are the status area and the preedit area. +</para> +<para> +<!-- .LP --> +The fundamental concept on which geometry management for input method windows +is based is the proper division of responsibilities between the +client (or toolkit) and the input method. +The division of responsibilities is as follows: +</para> +<itemizedlist> + <listitem> + <para> +The client is responsible for the geometry of the input method window. + </para> + </listitem> + <listitem> + <para> +The input method is responsible for the contents of the input method window. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +An input method is able to suggest a size to the client, +but it cannot suggest a placement. +Also the input method can only suggest a size. +It does not determine the size, +and it must accept the size it is given. +</para> +<para> +<!-- .LP --> +Before a client provides geometry management for an input method, +it must determine if geometry management is needed. +The input method indicates the need for geometry management +by setting +<function>XIMPreeditArea</function> +or +<function>XIMStatusArea</function> +in its +<function>XIMStyles</function> +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 +<function>XNInputStyle</function> +value in the +<function>XIC .</function> +</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 +<function>XNAreaNeeded</function> +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 XIC value +<function>XNAreaNeeded .</function> +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 XIC value +<function>XNArea</function> +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 +XIC values may affect the geometry desired by an input method. +For example, +<function>XNFontSet</function> +and +<function>XNLineSpacing</function> +may change the geometry desired by the input method. +</para> +<para> +<!-- .LP --> +The table of XIC values (see section 13.5.6) +indicates the values that can cause the desired geometry to change +when they are set. +It is the responsibility of the client to renegotiate the geometry +of the input method window when it is needed. +</para> +<para> +<!-- .LP --> +In addition, +a geometry management callback is provided +by which an input method can initiate a geometry change. +</para> +</sect3> +<sect3 id="Event_Filtering"> +<title>Event Filtering</title> +<!-- .XS --> +<!-- (SN Event Filtering --> +<!-- .XE --> +<para> +<!-- .LP --> +A filtering mechanism is provided to allow input methods +to capture X events transparently to clients. +It is expected that toolkits (or clients) using +<function>XmbLookupString</function> +or +<function>XwcLookupString </function> +will call this filter at some point in the event processing mechanism +to make sure that events needed by an input method can be filtered +by that input method. +</para> +<para> +<!-- .LP --> +If there were no filter, +a client could receive and discard events that are necessary +for the proper functioning of an input method. +The following provides a few examples of such events: +</para> +<itemizedlist> + <listitem> + <para> +Expose events on preedit window in local mode. + </para> + </listitem> + <listitem> + <para> +Events may be used by an input method to communicate with an input server. +Such input server protocol-related events have to be intercepted +if one does not want to disturb client code. + </para> + </listitem> + <listitem> + <para> +Key events can be sent to a filter before they are bound +to translations such as those the X Toolkit Intrinsics library provides. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +Clients are expected to get the XIC value +<function>XNFilterEvents</function> +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 +<function>XIMText</function> +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 XIC 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 +<function>XNStringConversion</function> +or +<function>XNStringConversionCallback </function> +XIC values. +Because the input method may not support string conversions, +clients have to query the availability of string conversion +operations by checking the supported XIC values list by calling +<function>XGetIMValues</function> +with the +<function>XNQueryICValuesList</function> +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 +<function>XNStringConversion</function> +XIC 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 +<function>XNStringConversionCallback</function> +will be issued when this value is set; thus, the client need +only set one of these values. +</para> +<para> +<!-- .LP --> +The +<function>XNStringConversionCallback</function> +XIC 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 +<function>XIMStringConversionCallbackStruct</function> +specifies which text should be passed back to the input method. +</para> +<para> +<!-- .LP --> +Finally, the input method may call the client's +<function>XNStringConversionCallback</function> +procedure multiple times if the string returned from the callback is +not sufficient to perform a successful conversion. The arguments +to the client's procedure allow the input method to define a +position (in character units) relative to the client's cursor position +and the size of the text needed. By varying the position and size of +the desired text in subsequent callbacks, the input method can retrieve +additional text. +</para> +<para> +<!-- .LP --> +</para> +</sect3> +</sect2> +<sect2 id="Input_Method_Management"> +<title>Input Method Management</title> +<!-- .XS --> +<!-- (SN Input Method Management --> +<!-- .XE --> +<para> +<!-- .LP --> +The interface to input methods might appear to be simply creating +an input method +<function>( XOpenIM )</function> +and freeing an input method +<function>( XCloseIM ).</function> +However, input methods may +require complex communication with input method servers (IM servers), +for example: +</para> + +<itemizedlist> + <listitem> + <para> +If the X server, IM server, and X clients are started asynchronously, +some clients may attempt to connect to the IM server before it is +fully operational, and fail. +Therefore, some mechanism is needed to allow clients to detect when an IM +server has started. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +It is up to clients to decide what should be done when an IM server is +not available (for example, wait, or use some other IM server). +</para> +<para> +<!-- .LP --> +</para> +<itemizedlist> + <listitem> + <para> +Some input methods may allow the underlying IM server to be switched. +Such customization may be desired without restarting the entire client. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +To support management of input methods in these cases, the following +functions are provided: +</para> +<informaltable> + <tgroup cols='2' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <tbody> + <row> + <entry><function>XRegisterIMInstantiateCallback</function></entry> + <entry>This function allows clients to register a callback procedure + to be called when Xlib detects that an IM server is up and available.</entry> + </row> + <row> + <entry><function>XOpenIM</function></entry> + <entry>A client calls this function as a result of the callback procedure + being called.</entry> + </row> + <row> + <entry><function>XSetIMValue</function>, <function>XSetICValue</function></entry> + <entry>These functions use the XIM and XIC values, + <function>XNDestroyCallback ,</function> + 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 XIC values list by calling +<function>XGetIMValues</function> +with the +<function>XNQueryICValuesList</function> +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 +<function>XNPreeditState</function> +XIC 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 +<function>XNPreeditStateNotifyCallback</function> +XIC value. +In order to change the preedit state programmatically, an application +needs to call +<function>XSetICValues</function> +with +<function>XNPreeditState.</function> +</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 XIC values list by calling +<function>XGetIMValues</function> +with the +<function>XNQueryICValuesList</function> +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> +<!-- .IN "XOpenIM" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>XIM<function> XOpenIM</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XrmDatabase<parameter> db</parameter></paramdef> + <paramdef>char<parameter> *res_name</parameter></paramdef> + <paramdef>char<parameter> *res_class</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>db</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to the resource database. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>res_name</emphasis> + </term> + <listitem> + <para> +Specifies the full resource name of the application. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>res_class</emphasis> + </term> + <listitem> + <para> +Specifies the full class name of the application. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XOpenIM</function> +function opens an input method, +matching the current locale and modifiers specification. +Current locale and modifiers are bound to the input method at opening time. +The locale associated with an input method cannot be changed dynamically. +This implies that the strings returned by +<function>XmbLookupString</function> +or +<function>XwcLookupString ,</function> +for any input context affiliated with a given input method, +will be encoded in the locale current at the time the input method is opened. +</para> +<para> +<!-- .LP --> +The specific input method to which this call will be routed +is identified on the basis of the current locale. +<function>XOpenIM</function> +will identify a default input method corresponding to the +current locale. +That default can be modified using +<function>XSetLocaleModifiers</function> +for the input method modifier. +</para> +<para> +<!-- .LP --> +The db argument is the resource database to be used by the input method +for looking up resources that are private to the input method. +It is not intended that this database be used to look +up values that can be set as IC values in an input context. +If db is NULL, +no database is passed to the input method. +</para> +<para> +<!-- .LP --> +The res_name and res_class arguments specify the resource name +and class of the application. +They are intended to be used as prefixes by the input method +when looking up resources that are common to all input contexts +that may be created for this input method. +The characters used for resource names and classes must be in the +X Portable Character Set. +The resources looked up are not fully specified +if res_name or res_class is NULL. +</para> +<para> +<!-- .LP --> +The res_name and res_class arguments are not assumed to exist beyond +the call to +<function>XOpenIM .</function> +The specified resource database is assumed to exist for the lifetime +of the input method. +</para> +<para> +<!-- .LP --> +<function>XOpenIM</function> +returns NULL if no input method could be opened. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To close a connection, use +<function>XCloseIM .</function> +<!-- .IN "XCloseIM" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>Status<function> XCloseIM</function></funcdef> + <paramdef>XIM<parameter> im</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>im</emphasis> + </term> + <listitem> + <para> +Specifies the input method. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XCloseIM</function> +function closes the specified input method. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To set input method attributes, use +<function>XSetIMValues .</function> +<!-- .IN "XSetIMValues" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>char<function> *</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 XIM values --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + ... + </term> + <listitem> + <para> +Specifies the variable-length argument list(Al. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>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> +<!-- .IN "XGetIMValues" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>char<function> *</function></funcdef> + <paramdef>XIM<parameter> im</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>im</emphasis> + </term> + <listitem> + <para> +Specifies the input method. +<!-- .ds Al \ to get XIM values --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + ... + </term> + <listitem> + <para> +Specifies the variable length argument list(Al. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XGetIMValues</function> +function presents a variable argument list programming interface +for querying properties or features of the specified input method. +This function returns NULL if it succeeds; +otherwise, +it returns the name of the first argument that could not be obtained. +</para> +<para> +<!-- .LP --> +Each XIM value argument (following a name) must point to +a location where the XIM value is to be stored. +That is, if the XIM 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> +<!-- .IN "XDisplayOfIM" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>Display<function> *</function></funcdef> + <paramdef>XIM<parameter> im</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>im</emphasis> + </term> + <listitem> + <para> +Specifies the input method. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XDisplayOfIM</function> +function returns the display associated with the specified input method. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To get the locale associated with an input method, use +<function>XLocaleOfIM .</function> +<!-- .IN "XLocaleOfIM" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>char<function> *</function></funcdef> + <paramdef>XIM<parameter> im</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>im</emphasis> + </term> + <listitem> + <para> +Specifies the input method. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XLocaleOfIM</function> +function returns the locale associated with the specified input method. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To register an input method instantiate callback, use +<function>XRegisterIMInstantiateCallback .</function> +<!-- .IN "XRegisterIMInstantiateCallback" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>Bool<function> XRegisterIMInstantiateCallback</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XrmDatabase<parameter> db</parameter></paramdef> + <paramdef>char<parameter> *res_name</parameter></paramdef> + <paramdef>char<parameter> *res_class</parameter></paramdef> + <paramdef>XIMProc<parameter> callback</parameter></paramdef> + <paramdef>XPointer<parameter> *client_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>db</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to the resource database. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>res_name</emphasis> + </term> + <listitem> + <para> +Specifies the full resource name of the application. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>res_class</emphasis> + </term> + <listitem> + <para> +Specifies the full class name of the application. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>callback</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to the input method instantiate callback. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the additional client data. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XRegisterIMInstantiateCallback</function> +function registers a callback to be invoked whenever a new input method +becomes available for the specified display that matches the current +locale and modifiers. +</para> +<para> +<!-- .LP --> +The function returns +<function>True</function> + if it succeeds; otherwise, it returns +<function>False .</function> +</para> +<para> +<!-- .LP --> +The generic prototype is as follows: +<!-- .IN "IMInstantiateCallback" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> IMInstantiateCallback</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XPointer<parameter> client_data</parameter></paramdef> + <paramdef>XPointer<parameter> call_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the additional client data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>call_data</emphasis> + </term> + <listitem> + <para> +Not used for this callback and always passed as NULL. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +To unregister an input method instantiation callback, use +<function>XUnregisterIMInstantiateCallback .</function> +<!-- .IN "XUnregisterIMInstantiateCallback" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>Bool<function> XUnregisterIMInstantiateCallback</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XrmDatabase<parameter> db</parameter></paramdef> + <paramdef>char<parameter> *res_name</parameter></paramdef> + <paramdef>char<parameter> *res_class</parameter></paramdef> + <paramdef>XIMProc<parameter> callback</parameter></paramdef> + <paramdef>XPointer<parameter> *client_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>db</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to the resource database. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>res_name</emphasis> + </term> + <listitem> + <para> +Specifies the full resource name of the application. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>res_class</emphasis> + </term> + <listitem> + <para> +Specifies the full class name of the application. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>callback</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to the input method instantiate callback. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the additional client data. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XUnregisterIMInstantiateCallback</function> +function removes an input method instantiation callback previously +registered. +The function returns +<function>True</function> +if it succeeds; otherwise, it returns +<function>False .</function> +</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 XIM values are interpreted +by an input method. +The first column lists the XIM values. +The second column indicates how each of the XIM values +are treated by that input style. +</para> +<para> +<!-- .LP --> +</para> +<para> +<!-- .LP --> +The following keys apply to this table. +</para> +<informaltable> + <tgroup cols='2' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <thead> + <row> + <entry>Key</entry> + <entry>Explanation</entry> + </row> + </thead> + <tbody> + <row> + <entry>D</entry> + <entry>This value may be set using + <function>XSetIMValues .</function> + If it is not set, + a default is provided.</entry> + </row> + <row> + <entry>S</entry> + <entry>This value may be set using <function>XSetIMValues .</function></entry> + </row> + <row> + <entry>G</entry> + <entry>This value may be read using <function>XGetIMValues .</function></entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<!-- .LP --> +<informaltable> + <tgroup cols='2' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <thead> + <row> + <entry>XIM Value</entry> + <entry>Key</entry> + </row> + </thead> + <tbody> + <row> + <entry><function>XNQueryInputStyle</function></entry> + <entry>G</entry> + </row> + <row> + <entry><function>XNResourceName</function></entry> + <entry>D-S-G</entry> + </row> + <row> + <entry><function>XNResourceClass</function></entry> + <entry>D-S-G</entry> + </row> + <row> + <entry><function>XNDestroyCallback</function></entry> + <entry>D-S-G</entry> + </row> + <row> + <entry><function>XNQueryIMValuesList</function></entry> + <entry>G</entry> + </row> + <row> + <entry><function>XNQueryICValuesList</function></entry> + <entry>G</entry> + </row> + <row> + <entry><function>XNVisiblePosition</function></entry> + <entry>G</entry> + </row> + <row> + <entry><function>XNR6PreeditCallbackBehavior</function></entry> + <entry>D-S-G</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +<!-- .LP --> +<function>XNR6PreeditCallbackBehavior</function> +is obsolete and its use is not recommended (see section 13.5.4.6). +</para> + +<sect3 id="Query_Input_Style"> +<title>Query Input Style</title> +<!-- .XS --> +<!-- (SN Query Input Style --> +<!-- .XE --> +<para> +<!-- .LP --> +A client should always query the input method to determine which input +styles are supported. +The client should then find an input style it is capable of supporting. +</para> +<para> +<!-- .LP --> +If the client cannot find an input style that it can support, +it should negotiate with the user the continuation of the program +(exit, choose another input method, and so on). +</para> +<para> +<!-- .LP --> +The argument value must be a pointer to a location +where the returned value will be stored. +The returned value is a pointer to a structure of type +<function>XIMStyles .</function> +Clients are responsible for freeing the +<function>XIMStyles</function> +structure. +To do so, use +<function>XFree .</function> +</para> +<para> +<!-- .LP --> +The +<function>XIMStyles</function> +structure is defined as follows: +</para> + +<!-- .LP --> +<!-- .IN "XIMStyle" "" "@DEF@" --> +<!-- .IN "XIMPreeditArea" "" "@DEF@" --> +<!-- .IN "XIMPreeditCallbacks" "" "@DEF@" --> +<!-- .IN "XIMPreeditPosition" "" "@DEF@" --> +<!-- .IN "XIMPreeditNothing" "" "@DEF@" --> +<!-- .IN "XIMPreeditNone" "" "@DEF@" --> +<!-- .IN "XIMStatusArea" "" "@DEF@" --> +<!-- .IN "XIMStatusCallbacks" "" "@DEF@" --> +<!-- .IN "XIMStatusNothing" "" "@DEF@" --> +<!-- .IN "XIMStatusNone" "" "@DEF@" --> +<!-- .IN "XIMStyles" "" "@DEF@" --> +<!-- .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 +<function>XIMStyles</function> +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> +<!-- .IN "XIMPreeditArea" "" "@DEF@" --> +<!-- .IN "XIMPreeditPosition" "" "@DEF@" --> +<!-- .IN "XIMPreeditCallbacks" "" "@DEF@" --> +<!-- .IN "XIMPreeditNothing" "" "@DEF@" --> +<!-- .IN "XIMPreeditNone" "" "@DEF@" --> +<informaltable> + <tgroup cols='2' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <tbody> + <row> + <entry><function>XIMPreeditArea </function></entry> + <entry>If chosen, + the input method would require the client to provide some area values + for it to do its preediting. + Refer to XIC values + <function>XNArea</function> + and + <function>XNAreaNeeded .</function></entry> + </row> + <row> + <entry><function>XIMPreeditPosition</function></entry> + <entry>If chosen, + the input method would require the client to provide positional values. + Refer to XIC values + <function>XNSpotLocation</function> + and + <function>XNFocusWindow .</function></entry> + </row> + <row> + <entry><function>XIMPreeditCallbacks</function></entry> + <entry>If chosen, + the input method would require the client to define the set of preedit callbacks. + Refer to XIC values + <function>XNPreeditStartCallback ,</function> + <function>XNPreeditDoneCallback , </function> + <function>XNPreeditDrawCallback ,</function> + and + <function>XNPreeditCaretCallback .</function></entry> + </row> + <row> + <entry><function>XIMPreeditNothing</function></entry> + <entry>If chosen, the input method can function without any preedit values.</entry> + </row> + <row> + <entry><function>XIMPreeditNone</function></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> +<!-- .IN "XIMStatusArea" "" "@DEF@" --> +<!-- .IN "XIMStatusCallbacks" "" "@DEF@" --> +<!-- .IN "XIMStatusNothing" "" "@DEF@" --> +<!-- .IN "XIMStatusNone" "" "@DEF@" --> +<informaltable> + <tgroup cols='2' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <tbody> + <row> + <entry><function>XIMStatusArea</function></entry> + <entry>The input method requires the client to provide + some area values for it to do its status feedback. + See + <function>XNArea</function> + and + <function>XNAreaNeeded .</function></entry> + </row> + <row> + <entry><function>XIMStatusCallbacks</function></entry> + <entry>The input method requires the client to define the set of status callbacks, + <function>XNStatusStartCallback , </function> + <function>XNStatusDoneCallback ,</function> + and + <function>XNStatusDrawCallback .</function></entry> + </row> + <row> + <entry><function>XIMStatusNothing</function></entry> + <entry>The input method can function without any status values.</entry> + </row> + <row> + <entry><function>XIMStatusNone</function></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 +<function>XNResourceName</function> +and +<function>XNResourceClass</function> +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 XIM 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 +<function>XNDestroyCallback </function> +argument is a pointer to a structure of type +<function>XIMCallback .</function> +<function>XNDestroyCallback</function> +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: +<!-- .IN "DestroyCallback" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> DestroyCallback</function></funcdef> + <paramdef>XIM<parameter> im</parameter></paramdef> + <paramdef>XPointer<parameter> client_data</parameter></paramdef> + <paramdef>XPointer<parameter> call_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>im</emphasis> + </term> + <listitem> + <para> +Specifies the input method. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the additional client data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>call_data</emphasis> + </term> + <listitem> + <para> +Not used for this callback and always passed as NULL. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +A DestroyCallback is always called with a NULL call_data argument. +</para> +<para> +<!-- .LP --> +</para> +</sect3> +<sect3 id="Query_IM_IC_Values_List"> +<title>Query IM/IC Values List</title> +<!-- .XS --> +<!-- (SN Query IM/IC Values List --> +<!-- .XE --> +<para> +<!-- .LP --> +<function>XNQueryIMValuesList</function> +and +<function>XNQueryICValuesList</function> +are used to query about XIM and XIC 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 +<function>XIMValuesList .</function> +Clients are responsible for freeing the +<function>XIMValuesList</function> +structure. +To do so, use +<function>XFree .</function> +</para> +<para> +<!-- .LP --> +The +<function>XIMValuesList</function> +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 +<function>XNVisiblePosition</function> +argument indicates whether the visible position masks of +<function>XIMFeedback</function> +in +<function>XIMText</function> +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 +<function>Bool .</function> +If the returned value is +<function>True ,</function> +the input method uses the visible position masks of +<function>XIMFeedback</function> +in +<function>XIMText ;</function> +otherwise, the input method does not use the masks. +</para> +<para> +<!-- .LP --> +Because this XIM value is optional, a client should call +<function>XGetIMValues</function> +with argument +<function>XNQueryIMValues</function> +before using this argument. +If the +<function>XNVisiblePosition</function> +does not exist in the IM values list returned from +<function>XNQueryIMValues ,</function> +the visible position masks of +<function>XIMFeedback</function> +in +<function>XIMText</function> +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 +<function>XNR6PreeditCallbackBehavior</function> +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 +<function>XNR6PreeditCallbackBehavior .</function> +Unfortunately, this argument was not removed from the R6 specification +before it was published. +<!-- .FE --> +</para> +<para> +<!-- .LP --> +The +<function>XNR6PreeditCallbackBehavior</function> +argument indicates whether the behavior of preedit callbacks regarding +<function>XIMPreeditDrawCallbackStruct</function> +values follows Release 5 or Release 6 semantics. +</para> +<para> +<!-- .LP --> +The value is of type +<function>Bool .</function> +When querying for +<function>XNR6PreeditCallbackBehavior ,</function> +if the returned value is +<function>True ,</function> +the input method uses the Release 6 behavior; +otherwise, it uses the Release 5 behavior. +The default value is +<function>False .</function> +In order to use Release 6 semantics, the value of +<function>XNR6PreeditCallbackBehavior</function> +must be set to +<function>True .</function> +</para> +<para> +<!-- .LP --> +Because this XIM value is optional, a client should call +<function>XGetIMValues</function> +with argument +<function>XNQueryIMValues</function> +before using this argument. +If the +<function>XNR6PreeditCallbackBehavior</function> +does not exist in the IM values list returned from +<function>XNQueryIMValues ,</function> +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 XIC values. +It is intended that input methods be controlled by these XIC values. +As new XIC values are created, +they should be registered with the X Consortium. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To create an input context, use +<function>XCreateIC .</function> +<!-- .IN "XCreateIC" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>XIC<function> XCreateIC</function></funcdef> + <paramdef>XIM<parameter> im</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>im</emphasis> + </term> + <listitem> + <para> +Specifies the input method. +<!-- .ds Al \ to set XIC values --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + ... + </term> + <listitem> + <para> +Specifies the variable length argument list(Al. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>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, +<function>XNFilterEvents ).</function> + </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 +<function>BadAtom ,</function> +<function>BadColor ,</function> +<function>BadPixmap ,</function> +and +<function>BadWindow</function> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To destroy an input context, use +<function>XDestroyIC .</function> +<!-- .IN "XDestroyIC" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XDestroyIC</function></funcdef> + <paramdef>XIC<parameter> ic</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>ic</emphasis> + </term> + <listitem> + <para> +Specifies the input context. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XDestroyIC</function> +destroys the specified input context. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To communicate to and synchronize with input method +for any changes in keyboard focus from the client side, +use +<function>XSetICFocus</function> +and +<function>XUnsetICFocus .</function> +<!-- .IN "XSetICFocus" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XSetICFocus</function></funcdef> + <paramdef>XIC<parameter> ic</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>ic</emphasis> + </term> + <listitem> + <para> +Specifies the input context. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XSetICFocus</function> +function allows a client to notify an input method that the focus window +attached to the specified input context has received keyboard focus. +The input method should take action to provide appropriate feedback. +Complete feedback specification is a matter of user interface policy. +</para> +<para> +<!-- .LP --> +Calling +<function>XSetICFocus</function> +does not affect the focus window value. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +<!-- .IN "XUnsetICFocus" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XUnsetICFocus</function></funcdef> + <paramdef>XIC<parameter> ic</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>ic</emphasis> + </term> + <listitem> + <para> +Specifies the input context. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XUnsetICFocus</function> +function allows a client to notify an input method that the specified input context +has lost the keyboard focus and that no more input is expected on the focus window +attached to that input context. +The input method should take action to provide appropriate feedback. +Complete feedback specification is a matter of user interface policy. +</para> +<para> +<!-- .LP --> +Calling +<function>XUnsetICFocus</function> +does not affect the focus window value; +the client may still receive +events from the input method that are directed to the focus window. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To reset the state of an input context to its initial state, use +<function>XmbResetIC</function> +or +<function>XwcResetIC .</function> +<!-- .IN "XmbResetIC" "" "@DEF@" --> +<!-- .IN "XwcResetIC" "" "@DE@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>char<function> *</function></funcdef> + <paramdef>XIC<parameter> ic</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<funcsynopsis> +<funcprototype> + <funcdef>wchar_t<function> *</function></funcdef> + <paramdef>XIC<parameter> ic</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>ic</emphasis> + </term> + <listitem> + <para> +Specifies the input context. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +When +<function>XNResetState</function> +is set to +<function>XIMInitialState ,</function> +<function>XmbResetIC</function> +and +<function>XwcResetIC</function> +reset an input context to its initial state; +when +<function>XNResetState</function> +is set to +<function>XIMPreserveState ,</function> +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> +<!-- .IN "XIMOfIC" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>XIM<function> XIMOfIC</function></funcdef> + <paramdef>XIC<parameter> ic</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>ic</emphasis> + </term> + <listitem> + <para> +Specifies the input context. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XIMOfIC</function> +function returns the input method associated with the specified input context. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +Xlib provides two functions for setting and reading XIC values, respectively, +<function>XSetICValues</function> +and +<function>XGetICValues .</function> +Both functions have a variable-length argument list. +In that argument list, any XIC value's name must be denoted +with a character string using the X Portable Character Set. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To set XIC values, use +<function>XSetICValues .</function> +<!-- .IN "XSetICValues" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>char<function> *</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 XIC values --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + ... + </term> + <listitem> + <para> +Specifies the variable length argument list(Al. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>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, +<function>XNFilterEvents ).</function> + </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 +<function>BadAtom ,</function> +<function>BadColor ,</function> +<function>BadCursor ,</function> +<function>BadPixmap ,</function> +and +<function>BadWindow </function> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To obtain XIC values, use +<function>XGetICValues .</function> +<!-- .IN "XGetICValues" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>char<function> *</function></funcdef> + <paramdef>XIC<parameter> ic</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>ic</emphasis> + </term> + <listitem> + <para> +Specifies the input context. +<!-- .ds Al \ to get XIC values --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + ... + </term> + <listitem> + <para> +Specifies the variable length argument list(Al. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XGetICValues</function> +function returns NULL if no error occurred; otherwise, +it returns the name of the first argument that could not be obtained. +An argument could not be obtained for any of the following reasons: +</para> +<itemizedlist> + <listitem> + <para> +The argument name is not recognized. + </para> + </listitem> + <listitem> + <para> +The input method encountered an implementation-dependent error. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +Each IC attribute value argument (following a name) must point to +a location where the IC value is to be stored. +That is, if the IC value is of type T, +the argument must be of type T*. +If T itself is a pointer type, +then +<function>XGetICValues</function> +allocates memory to store the actual data, +and the client is responsible for freeing this data by calling +<function>XFree</function> +with the returned pointer. +The exception to this rule is for an IC value of type +<function>XVaNestedList</function> +(for preedit and status attributes). +In this case, the argument must also be of type +<function>XVaNestedList .</function> +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 XIC values are interpreted +by an input method depending on the input style chosen by the +user. +</para> +<para> +<!-- .LP --> +The first column lists the XIC values. +The second column indicates which values are involved in affecting, +negotiating, and setting the geometry of the input method windows. +The subentries under the third column indicate the different +input styles that are supported. +Each of these columns indicates how each of the XIC values +are treated by that input style. +</para> +<para> +<!-- .LP --> +The following keys apply to these tables. +</para> +<informaltable> + <tgroup cols='2' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <thead> + <row> + <entry>Key</entry> + <entry>Explanation</entry> + </row> + </thead> + <tbody> + <row> + <entry>C</entry> + <entry>This value must be set with <function>XCreateIC .</function></entry> + </row> + <row> + <entry>D</entry> + <entry>This value may be set using + <function>XCreateIC .</function>> + If it is not set,> + a default is provided.</entry> + </row> + <row> + <entry>G</entry> + <entry>This value may be read using + <function>XGetICValues .</function></entry> + </row> + <row> + <entry>GN</entry> + <entry>This value may cause geometry negotiation when its value is set by means of + <function>XCreateIC</function> + or + <function>XSetICValues .</function></entry> + </row> + <row> + <entry>GR</entry> + <entry>This value will be the response of the input method when any + GN value is changed.</entry> + </row> + <row> + <entry>GS</entry> + <entry>This value will cause the geometry of the input method window to be set.</entry> + </row> + <row> + <entry>O</entry> + <entry>This value must be set once and only once. + It need not be set at create time.</entry> + </row> + <row> + <entry>S</entry> + <entry>This value may be set with + <function>XSetICValues .</function></entry> + </row> + <row> + <entry>Ignored</entry> + <entry>This value is ignored by the input method for the given input style.</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<!-- .LP --> +<informaltable> + <tgroup cols='7' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <colspec colname='c4'/> + <colspec colname='c5'/> + <colspec colname='c6'/> + <colspec colname='c7'/> + <tbody> + <row> + <entry>XIC Value</entry> + <entry>Geometry Mangement</entry> + <entry>Preedit Callback</entry> + <entry>Preedit Position</entry> + <entry>Input Style Preedit Area</entry> + <entry>Preedit Nothing</entry> + <entry>Preedit None</entry> + </row> + <row> + <entry>Input Style</entry> + <entry></entry> + <entry>C-G</entry> + <entry>C-G</entry> + <entry>C-G</entry> + <entry>C-G</entry> + <entry>C-G</entry> + </row> + <row> + <entry>Client Window</entry> + <entry></entry> + <entry>O-G</entry> + <entry>O-G</entry> + <entry>O-G</entry> + <entry>O-G</entry> + <entry>Ignored</entry> + </row> + <row> + <entry>Focus Window</entry> + <entry>GN</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>Ignored</entry> + </row> + <row> + <entry>Resource Name</entry> + <entry></entry> + <entry>Ignored</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>Ignored</entry> + </row> + <row> + <entry>Resource Class</entry> + <entry></entry> + <entry>Ignored</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>Ignored</entry> + </row> + <row> + <entry>Geometry Callback</entry> + <entry></entry> + <entry>Ignored</entry> + <entry>Ignored</entry> + <entry>D-S-G</entry> + <entry>Ignored</entry> + <entry>Ignored</entry> + </row> + <row> + <entry>Filter Events</entry> + <entry></entry> + <entry>G</entry> + <entry>G</entry> + <entry>G</entry> + <entry>G</entry> + <entry>Ignored</entry> + </row> + <row> + <entry>Destroy Callback</entry> + <entry></entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + </row> + <row> + <entry>String Conversion Callback</entry> + <entry></entry> + <entry>S-G</entry> + <entry>S-G</entry> + <entry>S-G</entry> + <entry>S-G</entry> + <entry>S-G</entry> + </row> + <row> + <entry>String Conversion</entry> + <entry></entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + </row> + <row> + <entry>Reset State</entry> + <entry></entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>Ignored</entry> + </row> + <row> + <entry>HotKey</entry> + <entry></entry> + <entry>S-G</entry> + <entry>S-G</entry> + <entry>S-G</entry> + <entry>S-G</entry> + <entry>Ignored</entry> + </row> + <row> + <entry>HotKeyState</entry> + <entry></entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>Ignored</entry> + </row> + <row> + <entry><function>Preedit</function></entry> + </row> + <row> + <entry>Area</entry> + <entry>GS</entry> + <entry>Ignored</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>Ignored</entry> + <entry>Ignored</entry> + </row> + <row> + <entry>Area Needed</entry> + <entry>GN-GR</entry> + <entry>Ignored</entry> + <entry>Ignored</entry> + <entry>S-G</entry> + <entry>Ignored</entry> + <entry>Ignored</entry> + </row> + <row> + <entry>Spot Location</entry> + <entry></entry> + <entry>Ignored</entry> + <entry>D-S-G</entry> + <entry>Ignored</entry> + <entry>Ignored</entry> + <entry>Ignored</entry> + </row> + <row> + <entry>Colormap</entry> + <entry></entry> + <entry>Ignored</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>Ignored</entry> + </row> + <row> + <entry>Foreground</entry> + <entry></entry> + <entry>Ignored</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>Ignored</entry> + </row> + <row> + <entry>Background</entry> + <entry></entry> + <entry>Ignored</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>Ignored</entry> + </row> + <row> + <entry>Background Pixmap</entry> + <entry></entry> + <entry>Ignored</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>Ignored</entry> + </row> + <row> + <entry>Font Set</entry> + <entry>GN</entry> + <entry>Ignored</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>Ignored</entry> + </row> + <row> + <entry>Line Spacing</entry> + <entry>GN</entry> + <entry>Ignored</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>Ignored</entry> + </row> + <row> + <entry>Cursor</entry> + <entry></entry> + <entry>Ignored</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>Ignored</entry> + </row> + <row> + <entry>Preedit State</entry> + <entry></entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>D-S-G</entry> + <entry>Ignored</entry> + </row> + <row> + <entry>Preedit State Notify Callback</entry> + <entry></entry> + <entry>S-G</entry> + <entry>S-G</entry> + <entry>S-G</entry> + <entry>S-G</entry> + <entry>Ignored</entry> + </row> + <row> + <entry>Preedit Callbacks</entry> + <entry></entry> + <entry>C-S-G</entry> + <entry>Ignored</entry> + <entry>Ignored</entry> + <entry>Ignored</entry> + <entry>Ignored</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<!-- .LP --> +<informaltable> + <tgroup cols='6' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <colspec colname='c4'/> + <colspec colname='c5'/> + <colspec colname='c6'/> + <thead> + <row> + <entry>XIC 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><function>Status</function></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 +<function>XNInputStyle</function> +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 +<function>XNQueryInputStyle</function> +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 --> +<!-- .IN "XNClientWindow" "" "@DEF@" --> +The +<function>XNClientWindow</function> +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 +<function>XNClientWindow</function> +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 +<function>BadWindow </function> +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 --> +<!-- .IN "XNFocusWindow" "" "@DEF@" --> +The +<function>XNFocusWindow</function> +argument specifies the focus window. +The primary purpose of the +<function>XNFocusWindow</function> +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 +<function>Window .</function> +If the focus window is not a valid window ID on the display +attached to the input method, +a +<function>BadWindow</function> +error can be generated when this value is used by the input method. +</para> +<para> +<!-- .LP --> +When this XIC 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 --> +<!-- .IN "XNResourceName" "" "@DEF@" --> +<!-- .IN "XNResourceClass" "" "@DEF@" --> +The +<function>XNResourceName</function> +and +<function>XNResourceClass</function> +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 XIC values be +set as resources. +</para> +</sect3> +<sect3 id="Geometry_Callback"> +<title>Geometry Callback</title> +<!-- .XS --> +<!-- (SN Geometry Callback --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "XNGeometryCallback" "" "@DEF@" --> +The +<function>XNGeometryCallback</function> +argument is a structure of type +<function>XIMCallback </function> +(see section 13.5.6.13.12). +</para> +<para> +<!-- .LP --> +The +<function>XNGeometryCallback</function> +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 --> +<!-- .IN "XNFilterEvents" "" "@DEF@" --> +The +<function>XNFilterEvents</function> +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 +<function>unsigned</function> +<function>long .</function> +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 +<function>XNDestroyCallback </function> +argument is a pointer to a structure of type +<function>XIMCallback </function> +(see section 13.5.6.13.12). This callback is triggered when the input method +stops its service for any reason; for example, when a connection to an IM +server is broken. After the destroy callback is called, +the input context is destroyed and the input method is closed. +Therefore, the client should not call +<function>XDestroyIC</function> +and +<function>XCloseIM .</function> +</para> +<para> +<!-- .LP --> +</para> +</sect3> +<sect3 id="String_Conversion_Callback"> +<title>String Conversion Callback</title> +<!-- .XS --> +<!-- (SN String Conversion Callback --> +<!-- .XE --> +<para> +<!-- .LP --> +The +<function>XNStringConversionCallback</function> +argument is a structure of type +<function>XIMCallback </function> +(see section 13.5.6.13.12). +</para> +<para> +<!-- .LP --> +The +<function>XNStringConversionCallback</function> +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 XIC value is optional, a client should call +<function>XGetIMValues</function> +with argument +<function>XNQueryICValuesList</function> +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 +<function>XNStringConversion</function> +argument is a structure of type +<function>XIMStringConversionText .</function> +</para> +<para> +<!-- .LP --> +The +<function>XNStringConversion</function> +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 XIC value is optional, a client should call +<function>XGetIMValues</function> +with argument +<function>XNQueryICValuesList</function> +before using this argument. +</para> +<para> +<!-- .LP --> +The +<function>XIMStringConversionText</function> +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 +<function>XNResetState</function> +argument specifies the state the input context will return to after calling +<function>XmbResetIC</function> +or +<function>XwcResetIC .</function> +</para> +<para> +<!-- .LP --> +The XIC state may be set to its initial state, as specified by the +<function>XNPreeditState</function> +value when +<function>XCreateIC</function> +was called, or it may be set to preserve the current state. +</para> +<para> +<!-- .LP --> +The valid masks for +<function>XIMResetState</function> +are as follows: +</para> +<para> +<!-- .LP --> +<!-- .IN "XIMInitialState" "" "@DEF@" --> +<!-- .IN "XINPreserveState" "" "@DEF@" --> +<!-- .sM --> +</para> +<literallayout class="monospaced"> +typedef unsigned long XIMResetState; + +#define XIMInitialState (1L) +#define XIMPreserveState (1L<<1) + +</literallayout> + +<para> +<!-- .LP --> +<!-- .eM --> +If +<function>XIMInitialState</function> +is set, then +<function>XmbResetIC</function> +and +<function>XwcResetIC</function> +will return to the initial +<function>XNPreeditState</function> +state of the XIC. +</para> +<para> +<!-- .LP --> +If +<function>XIMPreserveState</function> +is set, then +<function>XmbResetIC</function> +and +<function>XwcResetIC</function> +will preserve the current state of the XIC. +</para> +<para> +<!-- .LP --> +If +<function>XNResetState</function> +is left unspecified, the default is +<function>XIMInitialState .</function> +</para> +<para> +<!-- .LP --> +<function>XIMResetState</function> +values other than those specified above will default to +<function>XIMInitialState .</function> +</para> +<para> +<!-- .LP --> +Because this XIC value is optional, a client should call +<function>XGetIMValues</function> +with argument +<function>XNQueryICValuesList</function> +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 +<function>XNHotKey</function> +argument specifies the hot key list to the XIC. +The hot key list is a pointer to the structure of type +<function>XIMHotKeyTriggers ,</function> +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 +<function>XNHotKeyState</function> +to +<function>XIMHotKeyStateON .</function> +</para> +<para> +<!-- .LP --> +Because this XIC value is optional, a client should call +<function>XGetIMValues</function> +with argument +<function>XNQueryICValuesList</function> +before using this functionality. +</para> +<para> +<!-- .LP --> +The value of the argument is a pointer to a structure of type +<function>XIMHotKeyTriggers .</function> +</para> +<para> +<!-- .LP --> +If an event for a key in the hot key list is found, then the process will +receive the event and it will be processed inside the client. +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 2.5i --> +<!-- .ta .5i 2.5i --> +typedef struct { + KeySym keysym; + unsigned int modifier; + unsigned int modifier_mask; +} XIMHotKeyTrigger; + +typedef struct { + int num_hot_key; + XIMHotKeyTrigger *key; +} XIMHotKeyTriggers; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +</para> +<para> +<!-- .LP --> +The combination of modifier and modifier_mask are used to represent one of +three states for each modifier: +either the modifier must be on, or the modifier must be off, or the modifier +is a ``don't care'' - it may be on or off. +When a modifier_mask bit is set to 0, the state of the associated modifier +is ignored when evaluating whether the key is hot or not. +</para> + +<informaltable> + <tgroup cols='3' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <thead> + <row> + <entry>Modifier Bit</entry> + <entry>Mask Bit</entry> + <entry>Meaning</entry> + </row> + </thead> + <tbody> + <row> + <entry>0</entry> + <entry>1</entry> + <entry>The modifier must be off.</entry> + </row> + <row> + <entry>1</entry> + <entry>1</entry> + <entry>The modifier must be on.</entry> + </row> + <row> + <entry>n/a</entry> + <entry>0</entry> + <entry>Do not care if the modifier is on or off.</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +</sect3> +<sect3 id="Hot_Key_State"> +<title>Hot Key State</title> +<!-- .XS --> +<!-- (SN Hot Key State --> +<!-- .XE --> +<para> +<!-- .LP --> +The +<function>XNHotKeyState</function> +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 +<function>XIMHotKeyStateOFF .</function> +</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 --> +<!-- .IN "XNPreeditAttributes" "" "@DEF@" --> +<!-- .IN "XNStatusAttributes" "" "@DEF@" --> +The +<function>XNPreeditAttributes</function> +and +<function>XNStatusAttributes</function> +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 --> +<!-- .IN "XNArea" "" "@DEF@" --> +The value of the +<function>XNArea</function> +argument must be a pointer to a structure of type +<function>XRectangle.</function> +The interpretation of the +<function>XNArea</function> +argument is dependent on the input method style that has been set. +</para> +<para> +<!-- .LP --> +If the input method style is +<function>XIMPreeditPosition ,</function> +<function>XNArea</function> +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 +<function>XNArea</function> +is not specified, is set to NULL, or is invalid, +the input method will default the clipping region +to the geometry of the +<function>XNFocusWindow .</function> +If the area specified is NULL or invalid, +the results are undefined. +</para> +<para> +<!-- .LP --> +If the input style is +<function>XIMPreeditArea</function> +or +<function>XIMStatusArea ,</function> +<function>XNArea</function> +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 +<function>XNArea .</function> +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 +<function>XNArea</function> +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 --> +<!-- .IN "XNAreaNeeded" "" "@DEF@" --> +When set, the +<function>XNAreaNeeded</function> +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 +<function>XRectangle .</function> +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 +<function>XNAreaNeeded</function> +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 +<function>XIMPreeditArea</function> +or +<function>XIMStatusArea .</function> +It is used for geometry negotiation between the client and the input method +and has no other effect on the input method +(see section 13.5.1.5). +</para> +</sect4> +<sect4 id="Spot_Location"> +<title>Spot Location</title> +<!-- .XS --> +<!-- (SN Spot Location --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "XNSpotLocation" "" "@DEF@" --> +The +<function>XNSpotLocation</function> +argument specifies to the input method the coordinates of the spot +to be used by an input method executing with +<function>XNInputStyle </function> +set to +<function>XIMPreeditPosition .</function> +When specified to any input method other than +<function>XIMPreeditPosition ,</function> +this XIC 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 +<function>XPoint .</function> +</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 --> +<!-- .IN "XNColormap" "" "@DEF@" --> +The +<function>XNColormap</function> +argument is used to specify a colormap ID. +The argument value is of type +<function>Colormap .</function> +An invalid argument may generate a +<function>BadColor</function> +error when it is used by the input method. +</para> +<para> +<!-- .LP --> +<!-- .IN "XNStdColormap" "" "@DEF@" --> +The +<function>XNStdColormap</function> +argument is used to indicate the name of the standard colormap +in which the input method should allocate colors. +The argument value is an +<function>Atom</function> +that should be a valid atom for calling +<function>XGetRGBColormaps .</function> +An invalid argument may generate a +<function>BadAtom</function> +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 --> +<!-- .IN "XNForeground" "" "@DEF@" --> +<!-- .IN "XNBackground" "" "@DEF@" --> +The +<function>XNForeground</function> +and +<function>XNBackground</function> +arguments specify the foreground and background pixel, respectively. +The argument value is of type +<function>unsigned</function> +<function>long .</function> +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 +<function>XNBackgroundPixmap</function> +argument specifies a background pixmap to be used as the background of the +window. +The value must be of type +<function>Pixmap .</function> +An invalid argument may generate a +<function>BadPixmap</function> +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 --> +<!-- .IN "XNFontSet" "" "@DEF@" --> +The +<function>XNFontSet</function> +argument specifies to the input method what font set is to be used. +The argument value is of type +<function>XFontSet .</function> +</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 +<function>XNLineSpace</function> +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 +<function>int .</function> +</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 --> +<!-- .IN "XNCursor" "" "DEF@" --> +The +<function>XNCursor</function> +argument specifies to the input method what cursor is to be used +in the specified window. +This argument is of type +<function>Cursor .</function> +</para> +<para> +<!-- .LP --> +An invalid argument may generate a +<function>BadCursor</function> +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 +<function>XNPreeditState</function> +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 +<function>XNPreeditState</function> +are as follows: +</para> +<para> +<!-- .LP --> +<!-- .IN "XIMPreeditUnknown" "" "@DEV@" --> +<!-- .IN "XIMPreeditEnable" "" "@DEF@" --> +<!-- .IN "XIMPreeditDisable" "" "@DEV@" --> +<!-- .sM --> +</para> +<!-- .LP --> +<literallayout class="monospaced"> +typedef unsigned long XIMPreeditState; + +#define XIMPreeditUnknown 0L +#define XIMPreeditEnable 1L +#define XIMPreeditDisable (1L<<1) + +</literallayout> + +<para> +<!-- .LP --> +<!-- .eM --> +If a value of +<function>XIMPreeditEnable</function> +is set, then input preediting is turned on by the input method. +</para> +<para> +<!-- .LP --> +If a value of +<function>XIMPreeditDisable</function> +is set, then input preediting is turned off by the input method. +</para> +<para> +<!-- .LP --> +If +<function>XNPreeditState</function> +is left unspecified, then the state will be implementation-dependent. +</para> +<para> +<!-- .LP --> +When +<function>XNResetState</function> +is set to +<function>XIMInitialState ,</function> +the +<function>XNPreeditState</function> +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 XIC value is optional, a client should call +<function>XGetIMValues</function> +with argument +<function>XNQueryICValuesList</function> +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 +<function>XNPreeditStateNotifyCallback</function> +argument is a pointer to a structure of type +<function>XIMCallback .</function> +The generic prototype is as follows: +<!-- .IN "PreeditStateNotifyCallback" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> PreeditStateNotifyCallback</function></funcdef> + <paramdef>XIC<parameter> ic</parameter></paramdef> + <paramdef>XPointer<parameter> client_data</parameter></paramdef> + <paramdef>XIMPreeditStateNotifyCallbackStruct<parameter> *call_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>ic</emphasis> + </term> + <listitem> + <para> +Specifies the input context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the additional client data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>call_data</emphasis> + </term> + <listitem> + <para> +Specifies the current preedit state. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XIMPreeditStateNotifyCallbackStruct</function> +structure is defined as follows: +</para> +<para> +<!-- .LP --> +<!-- .IN "XIMPreeditStateNotifyCallbackStruct" "" "@DEF@" --> +<!-- .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 XIC value is optional, a client should call +<function>XGetIMValues</function> +with argument +<function>XNQueryICValuesList</function> +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 +<function>XIMPreeditCallbacks</function> +must provide a set of preedit callbacks to the input method. +The set of preedit callbacks is as follows: +</para> +<!-- .IN "XNPreeditStartCallback" "" "@DEF@" --> +<!-- .IN "XNPreeditDoneCallback" "" "@DEF@" --> +<!-- .IN "XNPreeditDrawCallback" "" "@DEF@" --> +<!-- .IN "XNPreeditCaretCallback" "" "@DEF@" --> +<informaltable> + <tgroup cols='2' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <tbody> + <row> + <entry><function>XNPreeditStartCallback</function></entry> + <entry>This is called when the input method starts preedit.</entry> + </row> + <row> + <entry><function>XNPreeditDoneCallback</function></entry> + <entry>This is called when the input method stops preedit.</entry> + </row> + <row> + <entry><function>XNPreeditDrawCallback</function></entry> + <entry>This is called when a number of preedit keystrokes should be echoed.</entry> + </row> + <row> + <entry><function>XNPreeditCaretCallback</function></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 +<function>XIMStatusCallbacks</function> +must provide a set of status callbacks to the input method. +The set of status callbacks is as follows: +</para> + +<!-- .IN "XNStatusStartCallback" "" "@DEF@" --> +<!-- .IN "XNStatusDoneCallback" "" "@DEF@" --> +<!-- .IN "XNStatusDrawCallback" "" "@DEF@" --> +<informaltable> + <tgroup cols='2' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <tbody> + <row> + <entry><function>XNStatusStartCallback</function></entry> + <entry>This is called when the input method initializes the status area.</entry> + </row> + <row> + <entry><function>XNStatusDoneCallback</function></entry> + <entry>This is called when the input method no longer needs the status area.</entry> + </row> + <row> + <entry><function>XNStatusDrawCallback</function></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 +<function>XIMCallback .</function> +<!-- .IN "XIMProc" "" "@DEF@" --> +<!-- .IN "XIMCallback" "" "@DEF@" --> +<!-- .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 --> +XIM 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: +<!-- .IN "CallbackPrototype" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> CallbackPrototype</function></funcdef> + <paramdef>XIC<parameter> ic</parameter></paramdef> + <paramdef>XPointer<parameter> client_data</parameter></paramdef> + <paramdef>SomeType<parameter> call_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>ic</emphasis> + </term> + <listitem> + <para> +Specifies the input context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the additional client data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>call_data</emphasis> + </term> + <listitem> + <para> +Specifies data specific to the callback. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The call_data argument is a structure that expresses the arguments needed +to achieve the semantics; +that is, +it is a specific data structure appropriate to the callback. +In cases where no data is needed in the callback, +this call_data argument is NULL. +The client_data argument is a closure that has been initially specified +by the client when specifying the callback and passed back. +It may serve, for example, to inherit application context in the callback. +</para> +<para> +<!-- .LP --> +The following paragraphs describe the programming semantics +and specific data structure associated with the different reasons. +</para> +<sect3 id="Geometry_Callback_b"> +<title>Geometry Callback</title> +<!-- .XS --> +<!-- (SN Geometry Callback --> +<!-- .XE --> +<para> +<!-- .LP --> +The geometry callback is triggered by the input method +to indicate that it wants the client to negotiate geometry. +The generic prototype is as follows: +<!-- .IN "GeometryCallback" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> GeometryCallback</function></funcdef> + <paramdef>XIC<parameter> ic</parameter></paramdef> + <paramdef>XPointer<parameter> client_data</parameter></paramdef> + <paramdef>XPointer<parameter> call_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>ic</emphasis> + </term> + <listitem> + <para> +Specifies the input context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the additional client data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>call_data</emphasis> + </term> + <listitem> + <para> +Not used for this callback and always passed as NULL. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The callback is called with a NULL call_data argument. +</para> +</sect3> +<sect3 id="Destroy_Callback_c"> +<title>Destroy Callback</title> +<!-- .XS --> +<!-- (SN Destroy Callback --> +<!-- .XE --> +<para> +<!-- .LP --> +The destroy callback is triggered by the input method +when it stops service for any reason. +After the callback is invoked, the input context will be freed by Xlib. +The generic prototype is as follows: +<!-- .IN "DestroyCallback" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> DestroyCallback</function></funcdef> + <paramdef>XIC<parameter> ic</parameter></paramdef> + <paramdef>XPointer<parameter> client_data</parameter></paramdef> + <paramdef>XPointer<parameter> call_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>ic</emphasis> + </term> + <listitem> + <para> +Specifies the input context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the additional client data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>call_data</emphasis> + </term> + <listitem> + <para> +Not used for this callback and always passed as NULL. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The callback is called with a NULL call_data argument. +</para> +</sect3> +<sect3 id="String_Conversion_Callback_b"> +<title>String Conversion Callback</title> +<!-- .XS --> +<!-- (SN String Conversion Callback --> +<!-- .XE --> +<para> +<!-- .LP --> +The string conversion callback is triggered by the input method +to request the client to return the string to be converted. The +returned string may be either a multibyte or wide character string, +with an encoding matching the locale bound to the input context. +The callback prototype is as follows: +<!-- .IN "StringConversionCallback" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> StringConversionCallback</function></funcdef> + <paramdef>XIC<parameter> ic</parameter></paramdef> + <paramdef>XPointer<parameter> client_data</parameter></paramdef> + <paramdef>XIMStringConversionCallbackStruct<parameter> *call_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>ic</emphasis> + </term> + <listitem> + <para> +Specifies the input method. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the additional client data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>call_data</emphasis> + </term> + <listitem> + <para> +Specifies the amount of the string to be converted. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The callback is passed an +<function>XIMStringConversionCallbackStruct</function> +structure in the call_data argument. +The text member is an +<function>XIMStringConversionText</function> +structure (see section 13.5.6.9) to be filled in by the client +and describes the text to be sent to the input method. +The data pointed to by the +string and feedback elements of the +<function>XIMStringConversionText</function> +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 +<function>XIMStringConversionCallbackStruct</function> +structure is defined as follows: +</para> +<para> +<!-- .LP --> +<!-- .IN "XIMStringConversionCallbackStruct" "" "@DEF@" --> +<!-- .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 --> +<function>XIMStringConversionPosition</function> +specifies the starting position of the string to be returned +in the +<function>XIMStringConversionText</function> +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 +<function>XIMCaretDirection .</function> +The factor member of +<function>XIMStringConversionCallbackStruct </function> +specifies the number of +<function>XIMCaretDirection </function> +positions to be applied. For example, if the direction specifies +<function>XIMLineEnd</function> +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 +<function>XIMForwardChar</function> +or +<function>XIMBackwardChar ,</function> +then the factor specifies a relative position, indicated in characters, +from the starting position. +</para> +<para> +<!-- .LP --> +<function>XIMStringConversionOperation</function> +specifies whether the string to be converted should be +deleted (substitution) or copied (retrieval) from the client's +buffer. When the +<function>XIMStringConversionOperation</function> +is +<function>XIMStringConversionSubstitution ,</function> +the client must delete the string to be converted from its own buffer. +When the +<function>XIMStringConversionOperation</function> +is +<function>XIMStringConversionRetrieval ,</function> +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>PreeditStartCallback</function> +or +<function>PreeditDoneCallback</function> +callback is triggered to let the toolkit do the setup +or the cleanup for the preedit region. +<!-- .IN "PreeditStartCallback" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int<function> PreeditStartCallback</function></funcdef> + <paramdef>XIC<parameter> ic</parameter></paramdef> + <paramdef>XPointer<parameter> client_data</parameter></paramdef> + <paramdef>XPointer<parameter> call_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>ic</emphasis> + </term> + <listitem> + <para> +Specifies the input context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the additional client data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>call_data</emphasis> + </term> + <listitem> + <para> +Not used for this callback and always passed as NULL. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +When preedit starts on the specified input context, +the callback is called with a NULL call_data argument. +<function>PreeditStartCallback</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. +<!-- .IN "PreeditDoneCallback" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> PreeditDoneCallback</function></funcdef> + <paramdef>XIC<parameter> ic</parameter></paramdef> + <paramdef>XPointer<parameter> client_data</parameter></paramdef> + <paramdef>XPointer<parameter> call_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>ic</emphasis> + </term> + <listitem> + <para> +Specifies the input context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the additional client data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>call_data</emphasis> + </term> + <listitem> + <para> +Not used for this callback and always passed as NULL. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +When preedit stops on the specified input context, +the callback is called with a NULL call_data argument. +The client can release the data allocated by +<function>PreeditStartCallback .</function> +</para> +<para> +<!-- .LP --> +<function>PreeditStartCallback</function> +should initialize appropriate data needed for +displaying preedit information and for handling further +<function>PreeditDrawCallback</function> +calls. +Once +<function>PreeditStartCallback</function> +is called, it will not be called again before +<function>PreeditDoneCallback</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: +<!-- .IN "PreeditDrawCallback" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> PreeditDrawCallback</function></funcdef> + <paramdef>XIC<parameter> ic</parameter></paramdef> + <paramdef>XPointer<parameter> client_data</parameter></paramdef> + <paramdef>XIMPreeditDrawCallbackStruct<parameter> *call_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>ic</emphasis> + </term> + <listitem> + <para> +Specifies the input context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the additional client data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>call_data</emphasis> + </term> + <listitem> + <para> +Specifies the preedit drawing information. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The callback is passed an +<function>XIMPreeditDrawCallbackStruct</function> +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 +<function>XIMPreeditDrawCallbackStruct</function> +structure is defined as follows: +</para> +<para> +<!-- .LP --> +<!-- .IN "XIMPreeditDrawCallbackStruct" "" "@DEF@" --> +<!-- .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 +<function>XIMText</function> +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 +<function>XIMText</function> +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 +<function>XIMText</function> +structure. +Hence, BCD 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 --> +<!-- .IN "XIMText" "" @DEF@" --> +<!-- .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 +<function>XIMVisibleToForward ,</function> +<function>XIMVisibleToBackward ,</function> +and +<function>XIMVisibleCenter</function> +masks are exclusively used for these visibility hints. +The +<function>XIMVisibleToForward</function> +mask +indicates that the preedit text is preferably displayed in the +primary draw direction from the +caret position in the preedit area forward. +The +<function>XIMVisibleToBackward</function> +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 +<function>XIMVisibleCenter</function> +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 +<function>XIMReverse ).</function> +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 +<function>XIMText</function> +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 +<function>XIMFeedback .</function> +</para> +<para> +<!-- .LP --> +Each element in the feedback array is a bitmask represented by a value of type +<function>XIMFeedback .</function> +The valid mask names are as follows: +</para> +<para> +<!-- .LP --> +<!-- .IN "XIMReverse" "" "@DEF@" --> +<!-- .IN "XIMUnderline" "" "@DEF@" --> +<!-- .IN "XIMHighlight" "" "@DEF@" --> +<!-- .IN "XIMPrimary" "" "@DEF@" --> +<!-- .IN "XIMSecondary" "" "@DEF@" --> +<!-- .IN "XIMTertiary" "" "@DEF@" --> +<!-- .IN "XIMVisibleToForward" "" "@DEF@" --> +<!-- .IN "XIMVisibleToBackward" "" "@DEF@" --> +<!-- .IN "XIMVisibleCenter" "" "@DEF@" --> +<!-- .sM --> +</para> +<literallayout class="monospaced"> +typedef unsigned long XIMFeedback; + +#define XIMReverse 1L +#define XIMUnderline (1L<<1) +#define XIMHighlight (1L<<2) +#define XIMPrimary (1L<<5)* +#define XIMSecondary (1L<<6)* +#define XIMTertiary (1L<<7)* +#define XIMVisibleToForward (1L<<8) +#define XIMVisibleToBackward (1L<<9) +#define XIMVisibleCenter (1L<<10) + +*† The values for XIMPrimary, XIMSecondary, and XIMTertiary were incorrectly defined in +the R5 specification. The X Consortium’s X11R5 implementation correctly implemented the val- +ues for these highlights. The value of these highlights has been corrected in this specification to +agree with the values in the Consortium’s X11R5 and X11R6 implementations. + +</literallayout> + +<para> +<!-- .LP --> +Characters drawn with the +<function>XIMReverse</function> +highlight should be drawn by swapping the foreground and background colors +used to draw normal, unhighlighted characters. +Characters drawn with the +<function>XIMUnderline</function> +highlight should be underlined. +Characters drawn with the +<function>XIMHighlight ,</function> +<function>XIMPrimary ,</function> +<function>XIMSecondary ,</function> +and +<function>XIMTertiary</function> +highlights should be drawn in some unique manner that must be different +from +<function>XIMReverse</function> +and +<function>XIMUnderline .</function> +<!-- .FS \(dg --> +The values for +<function>XIMPrimary ,</function> +<function>XIMSecondary ,</function> +and +<function>XIMTertiary</function> +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. +<!-- .IN "PreeditCaretCallback" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> PreeditCaretCallback</function></funcdef> + <paramdef>XIC<parameter> ic</parameter></paramdef> + <paramdef>XPointer<parameter> client_data</parameter></paramdef> + <paramdef>XIMPreeditCaretCallbackStruct<parameter> *call_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>ic</emphasis> + </term> + <listitem> + <para> +Specifies the input context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the additional client data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>call_data</emphasis> + </term> + <listitem> + <para> +Specifies the preedit caret information. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The input method will trigger PreeditCaretCallback +to move the text insertion point during preedit. +The call_data argument contains a pointer to an +<function>XIMPreeditCaretCallbackStruct</function> +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 +<function>XIMPreeditCaretCallbackStruct</function> +structure is defined as follows: +<!-- .IN "XIMPreeditCaretCallbackStruct" "" "@DEF@" --> +</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 +<function>XIMCaretStyle</function> +structure is defined as follows: +</para> +<para> +<!-- .LP --> +<!-- .IN "XIMCaretStyle" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 2.5i --> +<!-- .ta .5i 2.5i --> +typedef enum { + XIMIsInvisible, /* Disable caret feedback */ + XIMIsPrimary, /* UI defined caret feedback */ + XIMIsSecondary, /* UI defined caret feedback */ +} XIMCaretStyle; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XIMCaretDirection</function> +structure is defined as follows: +<!-- .IN "XIMCaretDirection" "" "@DEF@" --> +</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> +<!-- .IN "XIMForwardChar" "" "@DEF@" --> +<!-- .IN "XIMBackwardChar" "" "@DEF@" --> +<!-- .IN "XIMForwardWord" "" "@DEF@" --> +<!-- .IN "XIMBackwardWord" "" "@DEF@" --> +<!-- .IN "XIMCaretUp" "" "@DEF@" --> +<!-- .IN "XIMCaretDown" "" "@DEF@" --> +<informaltable> + <tgroup cols='2' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <tbody> + <row> + <entry><function>XIMForwardChar</function></entry> + <entry>Move the caret forward one character position.</entry> + </row> + <row> + <entry><function>XIMBackwardChar</function></entry> + <entry>Move the caret backward one character position.</entry> + </row> + <row> + <entry><function>XIMForwardWord</function></entry> + <entry>Move the caret forward one word.</entry> + </row> + <row> + <entry><function>XIMBackwardWord</function></entry> + <entry>Move the caret backward one word.</entry> + </row> + <row> + <entry><function>XIMCaretUp</function></entry> + <entry>Move the caret up one line keeping the current horizontal offset.</entry> + </row> + <row> + <entry><function>XIMCaretDown</function></entry> + <entry>Move the caret down one line keeping the current horizontal offset.</entry> + </row> + <row> + <entry><function>XIMPreviousLine</function></entry> + <entry>Move the caret to the beginning of the previous line.</entry> + </row> + <row> + <entry><function>XIMNextLine</function></entry> + <entry>Move the caret to the beginning of the next line.</entry> + </row> + <row> + <entry><function>XIMLineStart</function></entry> + <entry>Move the caret to the beginning of the current display line that contains the caret.</entry> + </row> + <row> + <entry><function>XIMLineEnd</function></entry> + <entry>Move the caret to the end of the current display line that contains the caret.</entry> + </row> + <row> + <entry><function>XIMAbsolutePosition</function></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><function>XIMDontChange</function></entry> + <entry>The caret position does not change.</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<!-- .IN "XIMNextLine" "" "@DEF@" --> +<!-- .IN "XIMPreviousLine" "" "@DEF@" --> +<!-- .IN "XIMLineStart" "" "@DEF@" --> +<!-- .IN "XIMLineEnd" "" "@DEF@" --> +<!-- .IN "XIMAbsolutePosition" "" "@DEF@" --> +<!-- .IN "XIMDontChange" "" "@DEF@" --> +</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. +<!-- .IN "StatusStartCallback" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> StatusStartCallback</function></funcdef> + <paramdef>XIC<parameter> ic</parameter></paramdef> + <paramdef>XPointer<parameter> client_data</parameter></paramdef> + <paramdef>XPointer<parameter> call_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>ic</emphasis> + </term> + <listitem> + <para> +Specifies the input context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the additional client data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>call_data</emphasis> + </term> + <listitem> + <para> +Not used for this callback and always passed as NULL. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The callback should initialize appropriate data for displaying status +and for responding to StatusDrawCallback calls. +Once StatusStartCallback is called, +it will not be called again before StatusDoneCallback has been called. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +When an input context +is destroyed or when it loses focus, the input method calls StatusDoneCallback. +<!-- .IN "StatusDoneCallback" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> StatusDoneCallback</function></funcdef> + <paramdef>XIC<parameter> ic</parameter></paramdef> + <paramdef>XPointer<parameter> client_data</parameter></paramdef> + <paramdef>XPointer<parameter> call_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>ic</emphasis> + </term> + <listitem> + <para> +Specifies the input context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the additional client data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>call_data</emphasis> + </term> + <listitem> + <para> +Not used for this callback and always passed as NULL. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The callback may release any data allocated on +<function>StatusStart .</function> +</para> +<para> +<!-- .LP --> +<!-- .sp --> +When an input context status has to be updated, the input method calls +StatusDrawCallback. +<!-- .IN "StatusDrawCallback" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> StatusDrawCallback</function></funcdef> + <paramdef>XIC<parameter> ic</parameter></paramdef> + <paramdef>XPointer<parameter> client_data</parameter></paramdef> + <paramdef>XIMStatusDrawCallbackStruct<parameter> *call_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>ic</emphasis> + </term> + <listitem> + <para> +Specifies the input context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the additional client data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>call_data</emphasis> + </term> + <listitem> + <para> +Specifies the status drawing information. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The callback should update the status area by either drawing a string +or imaging a bitmap in the status area. +</para> +<para> +<!-- .LP --> +The +<function>XIMStatusDataType</function> +and +<function>XIMStatusDrawCallbackStruct</function> +structures are defined as follows: +<!-- .IN "XIMStatusDataType" "" "@DEF@" --> +<!-- .IN "XIMStatusDrawCallbackStruct" "" "@DEF@" --> +</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 +<function>XIMVisibleToForward ,</function> +<function>XIMVisibleToBackward ,</function> +and +<function>XIMVisibleToCenter</function> +are not relevant and will not appear in the +<function>XIMFeedback</function> +element of the +<function>XIMText</function> +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 +<function>XIM</function> +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> +<!-- .IN "XFilterEvent" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>Bool<function> XFilterEvent</function></funcdef> + <paramdef>XEvent<parameter> *event</parameter></paramdef> + <paramdef>Window<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<!-- .ds Ev event to filter --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>event</emphasis> + </term> + <listitem> + <para> +Specifies the (Ev. +<!-- .ds Wi for which the filter is to be applied --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the window (Wi. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +If the window argument is +<function>None ,</function> +<function>XFilterEvent </function> +applies the filter to the window specified in the +<function>XEvent</function> +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 +<function>True ,</function> +then some input method has filtered the event, +and the client should discard the event. +If +<function>XFilterEvent</function> +returns +<function>False ,</function> +then the client should continue processing the event. +</para> +<para> +<!-- .LP --> +If a grab has occurred in the client and +<function>XFilterEvent</function> +returns +<function>True ,</function> +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> +<!-- .IN "XmbLookupString" "" "@DEF@" --> +<!-- .IN "XwcLookupString" "" "@DEF@" --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int<function> XmbLookupString</function></funcdef> + <paramdef>XIC<parameter> ic</parameter></paramdef> + <paramdef>XKeyPressedEvent<parameter> *event</parameter></paramdef> + <paramdef>char<parameter> *buffer_return</parameter></paramdef> + <paramdef>int<parameter> bytes_buffer</parameter></paramdef> + <paramdef>KeySym<parameter> *keysym_return</parameter></paramdef> + <paramdef>Status<parameter> *status_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<funcsynopsis> +<funcprototype> + <funcdef>int<function> XwcLookupString</function></funcdef> + <paramdef>XIC<parameter> ic</parameter></paramdef> + <paramdef>XKeyPressedEvent<parameter> *event</parameter></paramdef> + <paramdef>wchar_t<parameter> *buffer_return</parameter></paramdef> + <paramdef>int<parameter> wchars_buffer</parameter></paramdef> + <paramdef>KeySym<parameter> *keysym_return</parameter></paramdef> + <paramdef>Status<parameter> *status_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>ic</emphasis> + </term> + <listitem> + <para> +Specifies the input context. +<!-- .ds Ev key event to be used --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>event</emphasis> + </term> + <listitem> + <para> +Specifies the (Ev. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>buffer_return</emphasis> + </term> + <listitem> + <para> +Returns a multibyte string or wide character string (if any) +from the input method. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>bytes_buffer</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>wchars_buffer</emphasis> + </term> + <listitem> + <para> +Specifies space available in the return buffer. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>keysym_return</emphasis> + </term> + <listitem> + <para> +Returns the KeySym computed from the event if this argument is not NULL. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>status_return</emphasis> + </term> + <listitem> + <para> +Returns a value indicating what kind of data is returned. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XmbLookupString</function> +and +<function>XwcLookupString</function> +functions return the string from the input method specified +in the buffer_return argument. +If no string is returned, +the buffer_return argument is unchanged. +</para> +<para> +<!-- .LP --> +The KeySym into which the KeyCode from the event was mapped is returned +in the keysym_return argument if it is non-NULL and the status_return +argument indicates that a KeySym was returned. +If both a string and a KeySym are returned, +the KeySym value does not necessarily correspond to the string returned. +</para> +<para> +<!-- .LP --> +<function>XmbLookupString</function> +returns the length of the string in bytes, and +<function>XwcLookupString</function> +returns the length of the string in characters. +Both +<function>XmbLookupString</function> +and +<function>XwcLookupString</function> +return text in the encoding of the locale bound to the input method +of the specified input context. +</para> +<para> +<!-- .LP --> +Each string returned by +<function>XmbLookupString</function> +and +<function>XwcLookupString</function> +begins in the initial state of the encoding of the locale +(if the encoding of the locale is state-dependent). +<!-- .NT --> +<note><para> +To insure proper input processing, +it is essential that the client pass only +<function>KeyPress</function> +events to +<function>XmbLookupString</function> +and +<function>XwcLookupString .</function> +Their behavior when a client passes a +<function>KeyRelease</function> +event is undefined. +</para></note> +<!-- .NE --> +</para> +<para> +<!-- .LP --> +Clients should check the status_return argument before +using the other returned values. +These two functions both return a value to status_return +that indicates what has been returned in the other arguments. +The possible values returned are: +</para> + +<informaltable> + <tgroup cols='2' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <tbody> + <row> + <entry><function>XBufferOverflow</function></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><function>XLookupNone</function></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><function>XLookupChars</function></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><function>XLookupKeySym</function></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><function>XLookupBoth</function></entry> + <entry>Both a KeySym and a string are returned; + <function>XLookupChars</function> + and + <function>XLookupKeySym</function> + 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 +<function>KeyPress</function> +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 +<function>KeyPress</function> +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 +<function>KeyPress</function> +event whose KeyCode value is modified by an input method filter + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +When callback support is specified by the client, +input methods will not take action unless they explicitly +called back the client and obtained no response +(the callback is not specified or returned invalid data). +</para> +</sect3> +</sect2> +</sect1> +<sect1 id="String_Constants"> +<title>String Constants</title> +<!-- .XS --> +<!-- (SN String Constants --> +<!-- .XE --> +<para> +<!-- .LP --> +The following symbols for string constants are defined in +<X11/Xlib.h> . +Although they are shown here with particular macro definitions, +they may be implemented as macros, as global symbols, or as a +mixture of the two. The string pointer value itself +is not significant; clients must not assume that inequality of two +values implies inequality of the actual string data. +</para> + +<literallayout class="monospaced"> +#define XNVaNestedList "XNVaNestedList" +#define XNSeparatorofNestedList "separatorofNestedList" +#define XNQueryInputStyle "queryInputStyle" +#define XNClientWindow "clientWindow" +#define XNInputStyle "inputStyle" +#define XNFocusWindow "focusWindow" +#define XNResourceName "resourceName" +#define XNResourceClass "resourceClass" +#define XNGeometryCallback "geometryCallback" +#define XNDestroyCallback "destroyCallback" +#define XNFilterEvents "filterEvents" +#define XNPreeditStartCallback "preeditStartCallback" +#define XNPreeditDoneCallback "preeditDoneCallback" +#define XNPreeditDrawCallback "preeditDrawCallback" +#define XNPreeditCaretCallback "preeditCaretCallback" +#define XNPreeditStateNotifyCallback "preeditStateNotifyCallback" +#define XNPreeditAttributes "preeditAttributes" +#define XNStatusStartCallback "statusStartCallback" +#define XNStatusDoneCallback "statusDoneCallback" +#define XNStatusDrawCallback "statusDrawCallback" +#define XNStatusAttributes "statusAttributes" +#define XNArea "area" +#define XNAreaNeeded "areaNeeded" +#define XNSpotLocation "spotLocation" +#define XNColormap "colorMap" +#define XNStdColormap "stdColorMap" +#define XNForeground "foreground" +#define XNBackground "background" +#define XNBackgroundPixmap "backgroundPixmap" +#define XNFontSet "fontSet" +#define XNLineSpace "lineSpace" +#define XNCursor "cursor" +#define XNQueryIMValuesList "queryIMValuesList" +#define XNQueryICValuesList "queryICValuesList" +#define XNStringConversionCallback "stringConversionCallback" +#define XNStringConversion "stringConversion" +#define XNResetState "resetState" +#define XNHotKey "hotkey" +#define XNHotKeyState "hotkeyState" +#define XNPreeditState "preeditState" +#define XNVisiblePosition "visiblePosition" +#define XNR6PreeditCallbackBehavior "r6PreeditCallback" +#define XNRequiredCharSet "requiredCharSet" +#define XNQueryOrientation "queryOrientation" +#define XNDirectionalDependentDrawing "directionalDependentDrawing" +#define XNContextualDrawing "contextualDrawing" +#define XNBaseFontName "baseFontName" +#define XNMissingCharSet "missingCharSet" +#define XNDefaultString "defaultString" +#define XNOrientation "orientation" +#define XNFontInfo "fontInfo" +#define XNOMAutomatic "omAutomatic" + +</literallayout> + +</sect1> +</chapter> |