diff options
Diffstat (limited to 'libX11/specs/libX11/CH13')
| -rw-r--r-- | libX11/specs/libX11/CH13 | 7673 |
1 files changed, 7673 insertions, 0 deletions
diff --git a/libX11/specs/libX11/CH13 b/libX11/specs/libX11/CH13 new file mode 100644 index 000000000..ed143c690 --- /dev/null +++ b/libX11/specs/libX11/CH13 @@ -0,0 +1,7673 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from the X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 13\fP\s-1 + +\s+1\fBLocales and Internationalized Text Functions\fP\s-1 +.sp 2 +.nr H1 13 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.na +.LP +.XS +Chapter 13: Locales and Internationalized Text Functions +.XE +An internationalized application is one 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 \fIlocalization\fP\^. +A goal of internationalization is to permit localization +without program source modifications or recompilation. +.LP +As one of the localization mechanisms, +Xlib provides an X Input Method +.Pn ( XIM ) +functional interface for internationalized text input +and an X Output Method +.Pn ( XOM ) +functional interface for internationalized text output. +.LP +Internationalization in X is based on the concept of a \fIlocale\fP. +A locale defines the localized behavior of a program at run time. +Locales affect Xlib in its: +.IP \(bu 5 +Encoding and processing of input method text +.IP \(bu 5 +Encoding of resource files and values +.IP \(bu 5 +Encoding and imaging of text strings +.IP \(bu 5 +Encoding and decoding for inter-client text communication +.LP +Characters from various languages are represented in a computer +using an encoding. +Different languages have different encodings, +and there are even different encodings for the same characters +in the same language. +.LP +This chapter defines support for localized text imaging and text input +and 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. +.LP +The Xlib internationalization functions are not meant to provide +support for multilingual applications (mixing multiple languages +within a single piece of text), but they make it possible to +implement applications that work in limited fashion with more than +one language in independent contexts. +.LP +The remainder of this chapter discusses: +.IP \(bu 5 +X locale management +.IP \(bu 5 +Locale and modifier dependencies +.IP \(bu 5 +Variable argument lists +.IP \(bu 5 +Output methods +.IP \(bu 5 +Input methods +.IP \(bu 5 +String constants +.NH 2 +X Locale Management +.XS +\*(SN X Locale Management +.XE +.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 +.PN setlocale . +This function configures the locale operation of both +the host C library and Xlib. +The operation of Xlib is governed by the LC_CTYPE category; +this is called the \fIcurrent locale\fP. +An implementation is permitted to provide implementation-dependent +mechanisms for announcing the locale in addition to +.PN setlocale . +.LP +On implementations that do not conform to the ANSI C library, +the locale announcement method is Xlib implementation-dependent. +.LP +The mechanism by which the semantic operation of Xlib is defined +for a specific locale is implementation-dependent. +.LP +.sp +X is not required to support all the locales supported by the host. +To determine if the current locale is supported by X, use +.PN XSupportsLocale . +.IN "XSupportsLocale" "" "@DEF@" +.sM +.FD 0 +Bool XSupportsLocale\^(\|) +.FN +.LP +.eM +The +.PN XSupportsLocale +function returns +.PN True +if Xlib functions are capable of operating under the current locale. +If it returns +.PN False , +Xlib locale-dependent functions for which the +.PN XLocaleNotSupported +return status is defined will return +.PN XLocaleNotSupported . +Other Xlib locale-dependent routines will operate in the ``C'' locale. +.LP +The client is responsible for selecting its locale and X modifiers. +Clients should provide a means for the user to override the clients' +locale selection at client invocation. +Most single-display X clients operate in a single locale +for both X and the host processing environment. +They will configure the locale by calling three functions: +the host locale configuration function, +.PN XSupportsLocale , +and +.PN XSetLocaleModifiers . +.LP +The semantics of certain categories of X internationalization capabilities +can be configured by setting modifiers. +Modifiers are named by implementation-dependent and locale-specific strings. +The only standard use for this capability at present +is selecting one of several styles of keyboard input method. +.LP +.sp +To configure Xlib locale modifiers for the current locale, use +.PN XSetLocaleModifiers . +.IN "XSetLocaleModifiers" "" "@DEF@" +.sM +.FD 0 +char *XSetLocaleModifiers\^(\^\fImodifier_list\fP\^) +.br + char *\fImodifier_list\fP\^; +.FN +.IP \fImodifier_list\fP 1i +Specifies the modifiers. +.LP +.eM +The +.PN XSetLocaleModifiers +function sets the X modifiers for the current locale setting. +The modifier_list argument is a null-terminated string of the form +``{@\^\fIcategory\fP\^=\^\fIvalue\fP\^}'', that is, +having zero or more concatenated ``@\^\fIcategory\fP\^=\^\fIvalue\fP\^'' +entries, where \fIcategory\fP is a category name +and \fIvalue\fP is the (possibly empty) setting for that category. +The values are encoded in the current locale. +Category names are restricted to the POSIX Portable Filename Character Set. +.LP +The local host X locale modifiers announcer (on POSIX-compliant systems, +the XMODIFIERS environment variable) is appended to the modifier_list to +provide default values on the local host. +If a given category appears more than once in the list, +the first setting in the list is used. +If a given category is not included in the full modifier list, +the category is set to an implementation-dependent default +for the current locale. +An empty value for a category explicitly specifies the +implementation-dependent default. +.LP +If the function is successful, it returns a pointer to a string. +The contents of the string are such that a subsequent call with that string +(in the same locale) will restore the modifiers to the same settings. +If modifier_list is a NULL pointer, +.PN XSetLocaleModifiers +also returns a pointer to such a string, +and the current locale modifiers are not changed. +.LP +If invalid values are given for one or more modifier categories supported by +the locale, a NULL pointer is returned, and none of the +current modifiers are changed. +.LP +At program startup, +the modifiers that are in effect are unspecified until +the first successful call to set them. Whenever the locale is changed, the +modifiers that are in effect become unspecified until the next successful call +to set them. +Clients should always call +.PN XSetLocaleModifiers +with a non-NULL modifier_list after setting the locale +before they call any locale-dependent Xlib routine. +.LP +The only standard modifier category currently defined is ``im'', +which identifies the desired input method. +The values for input method are not standardized. +A single locale may use multiple input methods, +switching input method under user control. +The modifier may specify the initial input method in effect +or an ordered list of input methods. +Multiple input methods may be specified in a single im value string +in an implementation-dependent manner. +.LP +The returned modifiers string is owned by Xlib and should not be modified or +freed by the client. +It may be freed by Xlib after the current locale or modifiers are changed. +Until freed, it will not be modified by Xlib. +.LP +The recommended procedure for clients initializing their locale and modifiers +is to obtain locale and modifier announcers separately from +one of the following prioritized sources: +.IP \(bu 5 +A command line option +.IP \(bu 5 +A resource +.IP \(bu 5 +The empty string ("\^") +.LP +The first of these that is defined should be used. +Note that when a locale command line option or locale resource is defined, +the effect should be to set all categories to the specified locale, +overriding any category-specific settings in the local host environment. +.NH 2 +Locale and Modifier Dependencies +.XS +\*(SN Locale and Modifier Dependencies +.XE +.LP +The internationalized Xlib functions operate in the current locale +configured by the host environment and X locale modifiers set by +.PN XSetLocaleModifiers +or in the locale and modifiers configured at the time +some object supplied to the function was created. +For each locale-dependent function, +the following table describes the locale (and modifiers) dependency: +.TS H +lw(1.25i) lw(2.5i) lw(2i). +_ +.sp 6p +.B +Locale from Affects the Function In +.sp 6p +_ +.sp 6p +.TH +.R + Locale Query/Configuration: +.sp 6p +T{ +.PN setlocale +T} T{ +.PN XSupportsLocale +T} T{ +Locale queried +T} + T{ +.PN XSetLocaleModifiers +T} T{ +Locale modified +T} +.sp + Resources: +.sp 6p +T{ +.PN setlocale +T} T{ +.PN XrmGetFileDatabase +T} T{ +Locale of +.PN XrmDatabase +T} + T{ +.PN XrmGetStringDatabase +T} +T{ +.PN XrmDatabase +T} T{ +.PN XrmPutFileDatabase +T} T{ +Locale of +.PN XrmDatabase +T} + T{ +.PN XrmLocaleOfDatabase +T} +.sp + Setting Standard Properties: +.sp 6p +T{ +.PN setlocale +T} T{ +.PN XmbSetWMProperties +T} T{ +Encoding of supplied/returned +T} + text (some WM_ property + text in environment locale) +.sp 6p +T{ +.PN setlocale +T} T{ +.PN XmbTextPropertyToTextList +T} T{ +Encoding of supplied/returned text +T} + T{ +.PN XwcTextPropertyToTextList +T} + T{ +.PN XmbTextListToTextProperty +T} + T{ +.PN XwcTextListToTextProperty +T} +.sp + Text Input: +.sp 6p +T{ +.PN setlocale +T} T{ +.PN XOpenIM +T} T{ +XIM input method selection +T} + T{ +.PN XRegisterIMInstantiateCallback +T} T{ +XIM selection +T} + T{ +.PN XUnregisterIMInstantiateCallback +T} T{ +XIM selection +T} +T{ +.PN XIM +T} T{ +.PN XCreateIC +T} T{ +XIC input method configuration +T} + T{ +.PN XLocaleOfIM , +and so on +T} T{ +Queried locale +T} +T{ +.PN XIC +T} T{ +.PN XmbLookupString +T} T{ +Keyboard layout +T} + T{ +.PN XwcLookupString +T} T{ +Encoding of returned text +T} +.sp + Text Drawing: +.sp 6p +T{ +.PN setlocale +T} T{ +.PN XOpenOM +T} T{ +XOM output method selection +T} + T{ +.PN XCreateFontSet +T} T{ +Charsets of fonts in +.PN XFontSet +T} +T{ +.PN XOM +T} T{ +.PN XCreateOC +T} T{ +XOC output method configuration +T} + T{ +.PN XLocaleOfOM , +and so on +T} T{ +Queried locale +T} +T{ +.PN XFontSet +T} T{ +.PN XmbDrawText , +T} T{ +Locale of supplied text +T} + T{ +.PN XwcDrawText , +and so on +T} T{ +Locale of supplied text +T} + T{ +.PN XExtentsOfFontSet , +and so on +T} T{ +Locale-dependent metrics +T} + T{ +.PN XmbTextExtents , +T} + T{ +.PN XwcTextExtents , +and so on +T} +.sp + Xlib Errors: +.sp 6p +T{ +.PN setlocale +T} T{ +.PN XGetErrorDatabaseText +T} T{ +Locale of error message +T} + T{ +.PN XGetErrorText +T} +.sp 6p +_ +.TE +.LP +Clients may assume that a locale-encoded text string returned +by an X function can be passed to a C library routine, or vice versa, +if the locale is the same at the two calls. +.LP +All text strings processed by internationalized Xlib functions are assumed +to begin in the initial state of the encoding of the locale, if the encoding +is state-dependent. +.LP +All Xlib 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 +.PN XSetLocaleModifiers +with a non-NULL argument, they must save and restore the current state on +entry and exit.) +Also, Xlib functions on implementations that conform to the ANSI C library do +not alter the global state associated with the ANSI C functions +.PN mblen , +.PN mbtowc , +.PN wctomb , +and +.PN strtok . +.NH 2 +Variable Argument Lists +.XS +\*(SN Variable Argument Lists +.XE +.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 +.PN XPointer . +A name argument that is NULL identifies the end of the list. +.LP +A variable-length argument list may contain a nested list. +If the name +.PN XNVaNestedList +is specified in place of an argument name, +then the following value is interpreted as an +.PN XVaNestedList +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. +.LP +.sp +To allocate a nested variable argument list dynamically, use +.PN XVaCreateNestedList . +.IN "XVaCreateNestedList" "" @DEF@" +.sM +.FD 0 +typedef void * XVaNestedList; + +XVaNestedList XVaCreateNestedList\^(\^\fIdummy\fP\^, ...) +.br + int \fIdummy\fP\^; +.FN +.IP \fIdummy\fP 1i +Specifies an unused argument (required by ANSI C). +.ds Al +.IP ... 1i +Specifies the variable length argument list\*(Al. +.LP +.eM +The +.PN XVaCreateNestedList +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 +.PN XFree +when it is no longer needed. +.NH 2 +Output Methods +.XS +\*(SN Output Methods +.XE +.LP +This section provides discussions of the following X Output Method +(XOM) topics: +.IP \(bu 5 +Output method overview +.IP \(bu 5 +Output method functions +.IP \(bu 5 +Output method values +.IP \(bu 5 +Output context functions +.IP \(bu 5 +Output context values +.IP \(bu 5 +Creating and freeing a font set +.IP \(bu 5 +Obtaining font set metrics +.IP \(bu 5 +Drawing text using font sets +.NH 3 +Output Method Overview +.XS +\*(SN Output Method Overview +.XE +.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. +.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. +.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: +.IP \(bu 5 +Creating a set of fonts required to draw locale-dependent text. +.IP \(bu 5 +Drawing locale-dependent text with a font set without the caller +needing to be aware of locale dependencies. +.IP \(bu 5 +Obtaining the escapement and extents in pixels of locale-dependent text. +.IP \(bu 5 +Determining if bidirectional or context-dependent drawing is required +in a specific locale with a specific font set. +.LP +Two different abstractions are used in the representation of +the output method for clients. +.LP +The abstraction used to communicate with an output method +is an opaque data structure represented by the +.PN XOM +data type. +The abstraction for representing the state of a particular output thread +is called an \fIoutput context\fP. +The Xlib representation of an output context is an +.PN XOC , +which is compatible with +.PN XFontSet +in terms of its functional interface, but is +a broader, more generalized abstraction. +.NH 3 +Output Method Functions +.XS +\*(SN Output Method Functions +.XE +.LP +To open an output method, use +.PN XOpenOM . +.IN "XOpenOM" "" "@DEF@" +.sM +.FD 0 +XOM XOpenOM\^(\^\fIdisplay\fP\^, \fIdb\fP\^, \fIres_name\fP\^, \fIres_class\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XrmDatabase \fIdb\fP\^; +.br + char *\fIres_name\fP\^; +.br + char *\fIres_class\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIdb\fP 1i +Specifies a pointer to the resource database. +.IP \fIres_name\fP 1i +Specifies the full resource name of the application. +.IP \fIres_class\fP 1i +Specifies the full class name of the application. +.LP +.eM +The +.PN XOpenOM +function opens an output method +matching the current locale and modifiers specification. +The current locale and modifiers are bound to the output method +when +.PN XOpenOM +is called. +The locale associated with an output method cannot be changed. +.LP +The specific output method to which this call will be routed +is identified on the basis of the current locale and modifiers. +.PN XOpenOM +will identify a default output method corresponding to the +current locale. +That default can be modified using +.PN XSetLocaleModifiers +to set the output method modifier. +.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. +.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. +.LP +The res_name and res_class arguments are not assumed to exist beyond +the call to +.PN XOpenOM . +The specified resource database is assumed to exist for the lifetime +of the output method. +.LP +.PN XOpenOM +returns NULL if no output method could be opened. +.LP +.sp +To close an output method, use +.PN XCloseOM . +.IN "XCloseOM" "" "@DEF@" +.sM +.FD 0 +Status XCloseOM\^(\^\fIom\fP\^) +.br + XOM \fIom\fP\^; +.FN +.IP \fIom\fP 1i +Specifies the output method. +.LP +.eM +The +.PN XCloseOM +function closes the specified output method. +.LP +.sp +To set output method attributes, use +.PN XSetOMValues . +.IN "XSetOMValues" "" "@DEF@" +.sM +.FD 0 +char * XSetOMValues\^(\^\fIom\fP\^, ...) +.br + XOM \fIom\fP\^; +.FN +.IP \fIom\fP 1i +Specifies the output method. +.ds Al \ to set XOM values +.IP ... 1i +Specifies the variable-length argument list\*(Al. +.LP +.eM +The +.PN XSetOMValues +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. +.LP +No standard arguments are currently defined by Xlib. +.LP +.sp +To query an output method, use +.PN XGetOMValues . +.IN "XGetOMValues" "" "@DEF@" +.sM +.FD 0 +char * XGetOMValues\^(\^\fIom\fP\^, ...) +.br + XOM \fIom\fP\^; +.FN +.IP \fIom\fP 1i +Specifies the output method. +.ds Al \ to get XOM values +.IP ... 1i +Specifies the variable-length argument list\*(Al. +.LP +.eM +The +.PN XGetOMValues +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. +.LP +To obtain the display associated with an output method, use +.PN XDisplayOfOM . +.IN "XDisplayOfOM" "" "@DEF@" +.sM +.FD 0 +Display * XDisplayOfOM\^(\^\fIom\fP\^) +.br + XOM \fIom\fP\^; +.FN +.IP \fIom\fP 1i +Specifies the output method. +.LP +.eM +The +.PN XDisplayOfOM +function returns the display associated with the specified output method. +.LP +.sp +To get the locale associated with an output method, use +.PN XLocaleOfOM . +.IN "XLocaleOfOM" "" "@DEF@" +.sM +.FD 0 +char * XLocaleOfOM\^(\^\fIom\fP\^) +.br + XOM \fIom\fP\^; +.FN +.IP \fIom\fP 1i +Specifies the output method. +.LP +.eM +The +.PN XLocaleOfOM +returns the locale associated with the specified output method. +.NH 3 +X Output Method Values +.XS +\*(SN X Output Method Values +.XE +.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. +.LP +.LP +The following key applies to this table. +.TS H +lw(1i) lw(4.75i). +_ +.sp 6p +.B +Key Explanation +.sp 6p +_ +.sp 6p +.TH +.R +G T{ +This value may be read using +.PN XGetOMValues . +T} +.sp 6p +_ +.TE +.LP +.TS H +lw(2.25i) c +lw(2.25i) c. +_ +.sp 6p +.B +XOM Value Key +.sp 6p +_ +.sp 6p +.TH +.R +T{ +.PN XNRequiredCharSet +T} T{ +G +T} +T{ +.PN XNQueryOrientation +T} T{ +G +T} +T{ +.PN XNDirectionalDependentDrawing +T} T{ +G +T} +T{ +.PN XNContextualDrawing +T} T{ +G +T} +.sp 6p +_ +.TE +.LP +.NH 4 +Required Char Set +.XS +\*(SN Required Char Set +.XE +.LP +The +.PN XNRequiredCharSet +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 +.PN XOMCharSetList . +.LP +The +.PN XOMCharSetList +structure is defined as follows: +.IN "XOMCharSetList" "" "@DEF@" +.sM +.LP +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + int charset_count; + char **charset_list; +} XOMCharSetList; +.De +.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. +.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 +.PN XCloseOM +with the associated +.PN XOM . +Until freed, its contents will not be modified by Xlib. +.LP +.NH 4 +Query Orientation +.XS +\*(SN Query Orientation +.XE +.LP +The +.PN XNQueryOrientation +argument returns the global orientation of text when drawn. +Other than +.PN XOMOrientation_LTR_TTB , +the set of orientations supported is locale-dependent. +The value of the argument is a pointer to a structure of type +.PN XOMOrientation . +Clients are responsible for freeing the +.PN XOMOrientation +structure by using +.PN XFree ; +this also frees the contents of the structure. +.LP +.sM +.Ds 0 +.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; +.De +.LP +.eM +The possible value for XOrientation may be: +.IP \(bu 5 +.PN XOMOrientation_LTR_TTB +left-to-right, top-to-bottom global orientation +.IP \(bu 5 +.PN XOMOrientation_RTL_TTB +right-to-left, top-to-bottom global orientation +.IP \(bu 5 +.PN XOMOrientation_TTB_LTR +top-to-bottom, left-to-right global orientation +.IP \(bu 5 +.PN XOMOrientation_TTB_RTL +top-to-bottom, right-to-left global orientation +.IP \(bu 5 +.PN XOMOrientation_Context +contextual global orientation +.LP +.NH 4 +Directional Dependent Drawing +.XS +\*(SN Directional Dependent Drawing +.XE +.LP +The +.PN XNDirectionalDependentDrawing +argument indicates whether the text rendering functions +implement implicit handling of directional text. If this value +is +.PN True , +the output method has knowledge of directional +dependencies and reorders text as necessary when +rendering text. If this value is +.PN False , +the output method does not implement any directional text +handling, and all character directions are assumed to be left-to-right. +.LP +Regardless of the rendering order of characters, +the origins of all characters are on the primary draw direction side +of the drawing origin. +.LP +This OM value presents functionality identical to the +.PN XDirectionalDependentDrawing +function. +.NH 4 +Context Dependent Drawing +.XS +\*(SN Context Dependent Drawing +.XE +.LP +The +.PN XNContextualDrawing +argument indicates whether the text rendering functions +implement implicit context-dependent drawing. If this value is +.PN True , +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. +.LP +This OM value presents functionality identical to the +.PN XContextualDrawing +function. +.NH 3 +Output Context Functions +.XS +\*(SN Output Context Functions +.XE +.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 +.PN XOC +can be used anywhere an +.PN XFontSet +can be used, and vice versa; +.PN XFontSet +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, +.PN XFontSet +is widely used in several interfaces, so +.PN XOC +is defined as an upward compatible type of +.PN XFontSet . +.LP +.sp +To create an output context, use +.PN XCreateOC . +.IN "XCreateOC" "" "@DEF@" +.sM +.FD 0 +XOC XCreateOC\^(\^\fIom\fP\^, ...) +.br + XOM \fIom\fP\^; +.FN +.IP \fIom\fP 1i +Specifies the output method. +.ds Al \ to set XOC values +.IP ... 1i +Specifies the variable-length argument list\*(Al. +.LP +.eM +The +.PN XCreateOC +function creates an output context within the specified output method. +.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. +.LP +.PN XCreateOC +returns NULL if no output context could be created. +NULL can be returned for any of the following reasons: +.IP \(bu 5 +A required argument was not set. +.IP \(bu 5 +A read-only argument was set. +.IP \(bu 5 +An argument name is not recognized. +.IP \(bu 5 +The output method encountered an output method implementation-dependent error. +.LP +.PN XCreateOC +can generate a +.PN BadAtom +error. +.LP +.sp +To destroy an output context, use +.PN XDestroyOC . +.IN "XDestroyOC" "" "@DEF@" +.sM +.FD 0 +void XDestroyOC\^(\^\fIoc\fP\^) +.br + XOC \fIoc\fP\^; +.FN +.IP \fIoc\fP 1i +Specifies the output context. +.LP +.eM +The +.PN XDestroyOC +function destroys the specified output context. +.LP +.sp +To get the output method associated with an output context, use +.PN XOMOfOC . +.IN "XOMOfOC" "" "@DEF@" +.sM +.FD 0 +XOM XOMOfOC\^(\^\fIoc\fP\^) +.br + XOC \fIoc\fP\^; +.FN +.IP \fIoc\fP 1i +Specifies the output context. +.LP +.eM +The +.PN XOMOfOC +function returns the output method associated with the +specified output context. +.LP +.sp +Xlib provides two functions for setting and reading output context values, +respectively, +.PN XSetOCValues +and +.PN XGetOCValues . +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. +.LP +.sp +To set XOC values, use +.PN XSetOCValues . +.IN "XSetOCValues" "" "@DEF@" +.sM +.FD 0 +char * XSetOCValues\^(\^\fIoc\fP\^, ...) +.br + XOC \fIoc\fP\^; +.FN +.IP \fIoc\fP 1i +Specifies the output context. +.ds Al \ to set XOC values +.IP ... 1i +Specifies the variable-length argument list\*(Al. +.LP +.eM +The +.PN XSetOCValues +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: +.IP \(bu 5 +The argument is read-only. +.IP \(bu 5 +The argument name is not recognized. +.IP \(bu 5 +An implementation-dependent error occurs. +.LP +Each value to be set must be an appropriate datum, +matching the data type imposed by the semantics of the argument. +.LP +.PN XSetOCValues +can generate a +.PN BadAtom +error. +.LP +.sp +To obtain XOC values, use +.PN XGetOCValues . +.IN "XGetOCValues" "" "@DEF@" +.sM +.FD 0 +char * XGetOCValues\^(\^\fIoc\fP\^, ...) +.br + XOC \fIoc\fP\^; +.FN +.IP \fIoc\fP 1i +Specifies the output context. +.ds Al \ to get XOC values +.IP ... 1i +Specifies the variable-length argument list\*(Al. +.LP +.eM +The +.PN XGetOCValues +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: +.IP \(bu 5 +The argument name is not recognized. +.IP \(bu 5 +An implementation-dependent error occurs. +.LP +Each argument value +following a name must point to a location where the value is to be stored. +.NH 3 +Output Context Values +.XS +\*(SN Output Context Values +.XE +.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. +.LP +The following keys apply to this table. +.TS H +lw(1i) lw(4.75i). +_ +.sp 6p +.B +Key Explanation +.sp 6p +_ +.TH +.R +C T{ +This value must be set with +.PN XCreateOC . +T} +D T{ +This value may be set using +.PN XCreateOC . +If it is not set, +.br +a default is provided. +T} +G T{ +This value may be read using +.PN XGetOCValues . +T} +S T{ +This value must be set using +.PN XSetOCValues . +T} +.sp 6p +_ +.TE +.LP +.TS H +l c c +l c c. +_ +.sp 6p +.B +XOC Value Alternative Interface Key +.sp 6p +_ +.sp 6p +.TH +.R +T{ +BaseFontName +T} T{ +.PN XCreateFontSet +T} T{ +C-G +T} +T{ +MissingCharSet +T} T{ +.PN XCreateFontSet +T} T{ +G +T} +T{ +DefaultString +T} T{ +.PN XCreateFontSet +T} T{ +G +T} +T{ +Orientation +T} T{ +\- +T} T{ +D-S-G +T} +T{ +ResourceName +T} T{ +\- +T} T{ +S-G +T} +T{ +ResourceClass +T} T{ +\- +T} T{ +S-G +T} +T{ +FontInfo +T} T{ +.PN XFontsOfFontSet +T} T{ +G +T} +T{ +OMAutomatic +T} T{ +\- +T} T{ +G +T} +.sp 6p +_ +.TE +.LP +.NH 4 +Base Font Name +.XS +\*(SN Base Font Name +.XE +.LP +The +.PN XNBaseFontName +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. +.LP +Use of XLFD font names permits Xlib to obtain the fonts needed for a +variety of locales from a single locale-independent base font name. +The single base font name should name a family of fonts whose members +are encoded in the various charsets needed by the locales of interest. +.LP +An XLFD base font name can explicitly name a charset needed for the locale. +This allows the user to specify an exact font for use with a charset required +by a locale, fully controlling the font selection. +.LP +If a base font name is not an XLFD name, +Xlib will attempt to obtain an XLFD name from the font properties +for the font. +If Xlib is successful, the +.PN XGetOCValues +function will return this XLFD name instead of the client-supplied name. +.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, +.PN XCreateOC +returns NULL. +.LP +When querying for the +.PN XNBaseFontName +XOC value, +.PN XGetOCValues +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 +.PN XDestroyOC +with the associated +.PN XOC . +Until freed, the string contents will not be modified by Xlib. +.NH 4 +Missing CharSet +.XS +\*(SN Missing CharSet +.XE +.LP +The +.PN XNMissingCharSet +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 +.PN XOMCharSetList . +.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. +.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 +.PN XDestroyOC +with the associated +.PN XOC . +Until freed, its contents will not be modified by Xlib. +.NH 4 +Default String +.XS +\*(SN Default String +.XE +.LP +When a drawing or measuring function is called with an +.PN XOC +that has missing charsets, some characters in the locale will not be +drawable. +The +.PN XNDefaultString +argument returns a pointer to a string that represents the glyphs +that are drawn with this +.PN XOC +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 +.PN XOC . +.LP +If the +.PN XNDefaultString +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 +.PN XDestroyOC +with the associated +.PN XOC . +Until freed, its contents will not be modified by Xlib. +.NH 4 +Orientation +.XS +\*(SN Orientation +.XE +.LP +The +.PN XNOrientation +argument specifies the current orientation of text when drawn. The value of +this argument is one of the values returned by the +.PN XGetOMValues +function with the +.PN XNQueryOrientation +argument specified in the +.PN XOrientation +list. +The value of the argument is of type +.PN XOrientation . +When +.PN XNOrientation +is queried, the value specifies the current orientation. +When +.PN XNOrientation +is set, a value is used to set the current orientation. +.LP +When +.PN XOMOrientation_Context +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 +.PN XOMOrientation_LTR_TTB . +.LP +The +.PN XNOrientation +value does not change the prime drawing direction +for Xlib drawing functions. +.NH 4 +Resource Name and Class +.XS +\*(SN Resource Name and Class +.XE +.LP +The +.PN XNResourceName +and +.PN XNResourceClass +arguments are strings that specify the full name and class +used by the client to obtain resources for the 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. +.LP +It is not intended that values that can be set as XOM values be +set as resources. +.LP +When querying for the +.PN XNResourceName +or +.PN XNResourceClass +XOC value, +.PN XGetOCValues +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 +.PN XDestroyOC +with the associated +.PN XOC +or when the associated value is changed via +.PN XSetOCValues . +Until freed, the string contents will not be modified by Xlib. +.NH 4 +Font Info +.XS +\*(SN Font Info +.XE +.LP +The +.PN XNFontInfo +argument specifies a list of one or more +.PN XFontStruct +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 +.PN XOMFontInfo . +.LP +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + int num_font; + XFontStruct **font_struct_list; + char **font_name_list; +} XOMFontInfo; +.De +.LP +.eM +A list of pointers to the +.PN XFontStruct +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 +.PN XFontStruct +structures and font names is returned to num_font. +.LP +Because it is not guaranteed that a given character will be imaged using a +single font glyph, +there is no provision for mapping a character or default string +to the font properties, font ID, or direction hint for the font +for the character. +The client may access the +.PN XFontStruct +list to obtain these values for all the fonts currently in use. +.LP +Xlib does not guarantee that fonts are loaded from the server +at the creation of an +.PN XOC . +Xlib may choose to cache font data, loading it only as needed to draw text +or compute text dimensions. +Therefore, existence of the per_char metrics in the +.PN XFontStruct +structures in the +.PN XFontStructSet +is undefined. +Also, note that all properties in the +.PN XFontStruct +structures are in the STRING encoding. +.LP +The client must not free the +.PN XOMFontInfo +struct itself; it will be freed when the +.PN XOC +is closed. +.NH 4 +OM Automatic +.XS +\*(SN OM Automatic +.XE +.LP +The +.PN XNOMAutomatic +argument returns whether the associated output context was created by +.PN XCreateFontSet +or not. Because the +.PN XFreeFontSet +function not only destroys the output context but also closes the implicit +output method associated with it, +.PN XFreeFontSet +should be used with any output context created by +.PN XCreateFontSet . +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 +.PN XNOMAutomatic +is set to determine whether +.PN XFreeFontSet +or +.PN XDestroyOC +should be used to destroy the output context. +.NH 3 +Creating and Freeing a Font Set +.XS +\*(SN Creating and Freeing a Font Set +.XE +.LP +Xlib international text drawing is done using a set of one or more fonts, +as needed for the locale of the text. +Fonts are loaded according to a list of base font names +supplied by the client and the charsets required by the locale. +The +.PN XFontSet +is an opaque type representing the state of a particular output thread +and is equivalent to the type +.PN XOC . +.LP +.sp +The +.PN XCreateFontSet +function is a convenience function for creating an output context using +only default values. The returned +.PN XFontSet +has an implicitly created +.PN XOM . +This +.PN XOM +has an OM value +.PN XNOMAutomatic +automatically set to +.PN True +so that the output context self indicates whether it was created by +.PN XCreateOC +or +.PN XCreateFontSet . +.IN "XCreateFontSet" "" "@DEF@" +.sM +.FD 0 +XFontSet XCreateFontSet\^(\^\fIdisplay\fP\^, \fIbase_font_name_list\fP\^, \fImissing_charset_list_return\fP\^, +.br + \fImissing_charset_count_return\fP\^, \fIdef_string_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + char *\fIbase_font_name_list\fP\^; +.br + char ***\fImissing_charset_list_return\fP\^; +.br + int *\fImissing_charset_count_return\fP\^; +.br + char **\fIdef_string_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIbase_font_name_list\fP 1i +Specifies the base font names. +.IP \fImissing_charset_list_return\fP 1i +Returns the missing charsets. +.IP \fImissing_charset_count_return\fP 1i +Returns the number of missing charsets. +.IP \fIdef_string_return\fP 1i +Returns the string drawn for missing charsets. +.LP +.eM +The +.PN XCreateFontSet +function creates a font set for the specified display. +The font set is bound to the current locale when +.PN XCreateFontSet +is called. +The font set may be used in subsequent calls to obtain font +and character information and to image text in the locale of the font set. +.LP +The base_font_name_list argument is a list of base font names +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. +.LP +Use of XLFD font names permits Xlib to obtain the fonts needed for a +variety of locales from a single locale-independent base font name. +The single base font name should name a family of fonts whose members +are encoded in the various charsets needed by the locales of interest. +.LP +An XLFD base font name can explicitly name a charset needed for the locale. +This allows the user to specify an exact font for use with a charset required +by a locale, fully controlling the font selection. +.LP +If a base font name is not an XLFD name, +Xlib will attempt to obtain an XLFD name from the font properties +for the font. +If this action is successful in obtaining an XLFD name, the +.PN XBaseFontNameListOfFontSet +function will return this XLFD name instead of the client-supplied name. +.LP +Xlib uses the following algorithm to select the fonts +that will be used to display text with the +.PN XFontSet . +.LP +For each font charset required by the locale, +the base font name list is searched for the first appearance of one +of the following cases that names a set of fonts that exist at the server: +.IP \(bu 5 +The first XLFD-conforming base font name that specifies the required +charset or a superset of the required charset in its +.PN CharSetRegistry +and +.PN CharSetEncoding +fields. +The implementation may use a base font name whose specified charset +is a superset of the required charset, for example, +an ISO8859-1 font for an ASCII charset. +.IP \(bu 5 +The first set of one or more XLFD-conforming base font names +that specify one or more charsets that can be remapped to support the +required charset. +The Xlib implementation may recognize various mappings +from a required charset to one or more other charsets +and use the fonts for those charsets. +For example, JIS Roman is ASCII with tilde and backslash replaced +by yen and overbar; +Xlib may load an ISO8859-1 font to support this character set +if a JIS Roman font is not available. +.IP \(bu 5 +The first XLFD-conforming font name or the first non-XLFD font name +for which an XLFD font name can be obtained, combined with the +required charset (replacing the +.PN CharSetRegistry +and +.PN CharSetEncoding +fields in the XLFD font name). +As in case 1, +the implementation may use a charset that is a superset +of the required charset. +.IP \(bu 5 +The first font name that can be mapped in some implementation-dependent +manner to one or more fonts that support imaging text in the charset. +.LP +For example, assume that a locale required the charsets: +.LP +.Ds 0 +ISO8859-1 +JISX0208.1983 +JISX0201.1976 +GB2312-1980.0 +.De +.LP +The user could supply a base_font_name_list that explicitly specifies the +charsets, ensuring that specific fonts are used if they exist. +For example: +.LP +.Ds 0 +"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240-JISX0208.1983-0,\\ +-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120-JISX0201.1976-0,\\ +-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240-GB2312-1980.0,\\ +-Adobe-Courier-Bold-R-Normal--25-180-75-75-M-150-ISO8859-1" +.De +.LP +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: +.LP +.Ds 0 +"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\ +-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120,\\ +-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\ +-Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150" +.De +.LP +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: +.LP +.Ds 0 +"-*-*-*-R-Normal--*-180-100-100-*-*" +.De +.LP +If +.PN XCreateFontSet +is unable to create the font set, +either because there is insufficient memory or because the current locale +is not supported, +.PN XCreateFontSet +returns NULL, missing_charset_list_return is set to NULL, +and missing_charset_count_return +is set to zero. +If fonts exist for all of the charsets required by the current locale, +.PN XCreateFontSet +returns a valid +.PN XFontSet , +missing_charset_list_return is set to NULL, +and missing_charset_count_return is set to zero. +.LP +If no font exists for one or more of the required charsets, +.PN XCreateFontSet +sets missing_charset_list_return to a +list of one or more null-terminated charset names for which no font exists +and sets missing_charset_count_return to the number of missing fonts. +The charsets are from the list of the required charsets for +the encoding of the locale and do not include any charsets to which Xlib +may be able to remap a required charset. +.LP +If no font exists for any of the required charsets +or if the locale definition in Xlib requires that a font exist +for a particular charset and a font is not found for that charset, +.PN XCreateFontSet +returns NULL. +Otherwise, +.PN XCreateFontSet +returns a valid +.PN XFontSet +to font_set. +.LP +When an Xmb/wc drawing or measuring function is called with an +.PN XFontSet +that has missing charsets, some characters in the locale will not be +drawable. +If def_string_return is non-NULL, +.PN XCreateFontSet +returns a pointer to a string that represents the glyphs +that are drawn with this +.PN XFontSet +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 +.PN XFontSet . +.LP +If the string returned to def_string_return is the empty string ("\^"), +no glyphs are drawn, and the escapement is zero. +The returned string is null-terminated. +It is owned by Xlib and should not be modified or freed by the client. +It will be freed by a call to +.PN XFreeFontSet +with the associated +.PN XFontSet . +Until freed, its contents will not be modified by Xlib. +.LP +The client is responsible for constructing an error message from the +missing charset and default string information and may choose to continue +operation in the case that some fonts did not exist. +.LP +The returned +.PN XFontSet +and missing charset list should be freed with +.PN XFreeFontSet +and +.PN XFreeStringList , +respectively. +The client-supplied base_font_name_list may be freed +by the client after calling +.PN XCreateFontSet . +.LP +.sp +To obtain a list of +.PN XFontStruct +structures and full font names given an +.PN XFontSet , +use +.PN XFontsOfFontSet . +.IN "XFontsOfFontSet" "" "@DEF@" +.sM +.FD 0 +int XFontsOfFontSet\^(\^\fIfont_set\fP\^, \fIfont_struct_list_return\fP\^, \fIfont_name_list_return\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.br + XFontStruct ***\fIfont_struct_list_return\fP\^; +.br + char ***\fIfont_name_list_return\fP\^; +.FN +.IP \fIfont_set\fP 1i +Specifies the font set. +.IP \fIfont_struct_list_return\fP 1i +Returns the list of font structs. +.IP \fIfont_name_list_return\fP 1i +Returns the list of font names. +.LP +.eM +The +.PN XFontsOfFontSet +function returns a list of one or more +.PN XFontStructs +and font names for the fonts used by the Xmb and Xwc layers +for the given font set. +A list of pointers to the +.PN XFontStruct +structures is returned to font_struct_list_return. +A list of pointers to null-terminated, fully specified font name strings +in the locale of the font set is returned to font_name_list_return. +The font_name_list order corresponds to the font_struct_list order. +The number of +.PN XFontStruct +structures and font names is returned as the value of the function. +.LP +Because it is not guaranteed that a given character will be imaged using a +single font glyph, +there is no provision for mapping a character or default string +to the font properties, font ID, or direction hint for the font +for the character. +The client may access the +.PN XFontStruct +list to obtain these values for all the fonts currently in use. +.LP +Xlib does not guarantee that fonts are loaded from the server +at the creation of an +.PN XFontSet . +Xlib may choose to cache font data, loading it only as needed to draw text +or compute text dimensions. +Therefore, existence of the per_char metrics in the +.PN XFontStruct +structures in the +.PN XFontStructSet +is undefined. +Also, note that all properties in the +.PN XFontStruct +structures are in the STRING encoding. +.LP +The +.PN XFontStruct +and font name lists are owned by Xlib +and should not be modified or freed by the client. +They will be freed by a call to +.PN XFreeFontSet +with the associated +.PN XFontSet . +Until freed, their contents will not be modified by Xlib. +.LP +.sp +To obtain the base font name list and the selected font name list given an +.PN XFontSet , +use +.PN XBaseFontNameListOfFontSet . +.IN "XBaseFontNameListOfFontSet" "" "@DEF@" +.sM +.FD 0 +char *XBaseFontNameListOfFontSet\^(\^\fIfont_set\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.FN +.IP \fIfont_set\fP 1i +Specifies the font set. +.LP +.eM +The +.PN XBaseFontNameListOfFontSet +function returns the original base font name list supplied +by the client when the +.PN XFontSet +was created. +A null-terminated string containing a list of +comma-separated font names is returned +as the value of the function. +White space may appear immediately on either side of separating commas. +.LP +If +.PN XCreateFontSet +obtained an XLFD name from the font properties for the font specified +by a non-XLFD base name, the +.PN XBaseFontNameListOfFontSet +function will return the XLFD name instead of the non-XLFD base name. +.LP +The base font name list is owned by Xlib and should not be modified or +freed by the client. +It will be freed by a call to +.PN XFreeFontSet +with the associated +.PN XFontSet . +Until freed, its contents will not be modified by Xlib. +.LP +.sp +To obtain the locale name given an +.PN XFontSet , +use +.PN XLocaleOfFontSet . +.IN "XLocaleOfFontSet" "" "@DEF@" +.sM +.FD 0 +char *XLocaleOfFontSet\^(\^\fIfont_set\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.FN +.IP \fIfont_set\fP 1i +Specifies the font set. +.LP +.eM +The +.PN XLocaleOfFontSet +function +returns the name of the locale bound to the specified +.PN XFontSet , +as a null-terminated string. +.LP +The returned locale name string is owned by Xlib +and should not be modified or freed by the client. +It may be freed by a call to +.PN XFreeFontSet +with the associated +.PN XFontSet . +Until freed, it will not be modified by Xlib. +.LP +.sp +The +.PN XFreeFontSet +function is a convenience function for freeing an output context. +.PN XFreeFontSet +also frees its associated +.PN XOM +if the output context was created by +.PN XCreateFontSet . +.IN "XFreeFontSet" "" "@DEF@" +.sM +.FD 0 +void XFreeFontSet\^(\^\fIdisplay\fP\^, \fIfont_set\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XFontSet \fIfont_set\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIfont_set\fP 1i +Specifies the font set. +.LP +.eM +The +.PN XFreeFontSet +function frees the specified font set. +The associated base font name list, font name list, +.PN XFontStruct +list, and +.PN XFontSetExtents , +if any, are freed. +.NH 3 +Obtaining Font Set Metrics +.XS +\*(SN Obtaining Font Set Metrics +.XE +.LP +Metrics for the internationalized text drawing functions +are defined in terms of a primary draw direction, +which is the default direction in which the character origin advances +for each succeeding character in the string. +The Xlib interface is currently defined to support only a left-to-right +primary draw direction. +The drawing origin is the position passed to the drawing function +when the text is drawn. +The baseline is a line drawn through the drawing origin parallel +to the primary draw direction. +Character ink is the pixels painted in the foreground color +and does not include interline or intercharacter spacing +or image text background pixels. +.LP +The drawing functions are allowed to implement implicit text +directionality control, reversing the order in which characters are +rendered along the primary draw direction in response to locale-specific +lexical analysis of the string. +.LP +Regardless of the character rendering order, +the origins of all characters are on the primary draw direction side +of the drawing origin. +The screen location of a particular character image may be determined with +.PN XmbTextPerCharExtents +or +.PN XwcTextPerCharExtents . +.LP +The drawing functions are allowed to implement context-dependent +rendering, where the glyphs drawn for a string are not simply a +concatenation of the glyphs that represent each individual character. +A string of two characters drawn with +.PN XmbDrawString +may render differently than if the two characters +were drawn with separate calls to +.PN XmbDrawString . +If the client appends or inserts a character +in a previously drawn string, +the client may need to redraw some adjacent characters +to obtain proper rendering. +.LP +.sp +To find out about direction-dependent rendering, use +.PN XDirectionalDependentDrawing . +.IN "XDirectionalDependentDrawing" "" "@DEF@" +.sM +.FD 0 +Bool XDirectionalDependentDrawing\^(\^\fIfont_set\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.FN +.IP \fIfont_set\fP 1i +Specifies the font set. +.LP +.eM +The +.PN XDirectionalDependentDrawing +function returns +.PN True +if the drawing functions implement implicit text directionality; +otherwise, it returns +.PN False . +.LP +.sp +To find out about context-dependent rendering, use +.PN XContextualDrawing . +.IN "XContextualDrawing" "" "@DEF@" +.sM +.FD 0 +Bool XContextualDrawing\^(\^\fIfont_set\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.FN +.IP \fIfont_set\fP 1i +Specifies the font set. +.LP +.eM +The +.PN XContextualDrawing +function returns +.PN True +if text drawn with the font set might include context-dependent drawing; +otherwise, it returns +.PN False . +.LP +.sp +To find out about context-dependent or direction-dependent rendering, use +.PN XContextDependentDrawing . +.IN "XContextDependentDrawing" "" "@DEF@" +.sM +.FD 0 +Bool XContextDependentDrawing\^(\^\fIfont_set\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.FN +.IP \fIfont_set\fP 1i +Specifies the font set. +.LP +.eM +The +.PN XContextDependentDrawing +function returns +.PN True +if the drawing functions implement implicit text directionality or +if text drawn with the font_set might include context-dependent drawing; +otherwise, it returns +.PN False . +.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. +.LP +The maximum character extents for the fonts that are used by the text +drawing layers can be accessed by the +.PN XFontSetExtents +structure: +.IN "XFontSetExtents" "" "@DEF@" +.LP +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + XRectangle max_ink_extent; /* over all drawable characters */ + XRectangle max_logical_extent; /* over all drawable characters */ +} XFontSetExtents; +.De +.LP +The +.PN XRectangle +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. +.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 +.PN XmbTextExtents +and +.PN XwcTextExtents +for detailed semantics. +.LP +The max_logical_extent member gives the maximum extent, +over all drawable characters, of the rectangles +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. +.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. +.LP +The rectangles for a given character in a string can be obtained from +.PN XmbPerCharExtents +or +.PN XwcPerCharExtents . +.LP +.sp +To obtain the maximum extents structure given an +.PN XFontSet , +use +.PN XExtentsOfFontSet . +.IN "XExtentsOfFontSet" "" "@DEF@" +.sM +.FD 0 +XFontSetExtents *XExtentsOfFontSet\^(\^\fIfont_set\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.FN +.IP \fIfont_set\fP 1i +Specifies the font set. +.LP +.eM +The +.PN XExtentsOfFontSet +function returns an +.PN XFontSetExtents +structure for the fonts used by the Xmb and Xwc layers +for the given font set. +.LP +The +.PN XFontSetExtents +structure is owned by Xlib and should not be modified +or freed by the client. +It will be freed by a call to +.PN XFreeFontSet +with the associated +.PN XFontSet . +Until freed, its contents will not be modified by Xlib. +.LP +.sp +To obtain the escapement in pixels of the specified text as a value, +use +.PN XmbTextEscapement +or +.PN XwcTextEscapement . +.IN "XmbTextEscapement" "" "@DEF@" +.IN "XwcTextEscapement" "" "@DEF@" +.sM +.FD 0 +int XmbTextEscapement\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.br + char *\fIstring\fP\^; +.br + int \fInum_bytes\fP\^; +.FN +.FD 0 +int XwcTextEscapement\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.br + wchar_t *\fIstring\fP\^; +.br + int \fInum_wchars\fP\^; +.FN +.IP \fIfont_set\fP 1i +Specifies the font set. +.IP \fIstring\fP 1i +Specifies the character string. +.IP \fInum_bytes\fP 1i +Specifies the number of bytes in the string argument. +.IP \fInum_wchars\fP 1i +Specifies the number of characters in the string argument. +.LP +.eM +The +.PN XmbTextEscapement +and +.PN XwcTextEscapement +functions return the escapement in pixels of the specified string as a value, +using the fonts loaded for the specified font set. +The escapement is the distance in pixels in the primary draw +direction from the drawing origin to the origin of the next character to +be drawn, assuming that the rendering of the next character is not +dependent on the supplied string. +.LP +Regardless of the character rendering order, +the escapement is always positive. +.LP +.sp +To obtain the overall_ink_return and overall_logical_return arguments, +the overall bounding box of the string's image, and a logical bounding box, +use +.PN XmbTextExtents + or +.PN XwcTextExtents . +.IN "XmbTextExtents" "" "@DEF@" +.IN "XwcTextExtents" "" "@DEF@" +.sM +.FD 0 +int XmbTextExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^, \fIoverall_ink_return\fP\^, \fIoverall_logical_return\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.br + char *\fIstring\fP\^; +.br + int \fInum_bytes\fP\^; +.br + XRectangle *\fIoverall_ink_return\fP\^; +.br + XRectangle *\fIoverall_logical_return\fP\^; +.FN +.FD 0 +int XwcTextExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^, +\fIoverall_ink_return\fP\^, \fIoverall_logical_return\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.br + wchar_t *\fIstring\fP\^; +.br + int \fInum_wchars\fP\^; +.br + XRectangle *\fIoverall_ink_return\fP\^; +.br + XRectangle *\fIoverall_logical_return\fP\^; +.FN +.IP \fIfont_set\fP 1i +Specifies the font set. +.IP \fIstring\fP 1i +Specifies the character string. +.IP \fInum_bytes\fP 1i +Specifies the number of bytes in the string argument. +.IP \fInum_wchars\fP 1i +Specifies the number of characters in the string argument. +.ds Ov dimensions +.IP \fIoverall_ink_return\fP 1i +Returns the overall ink \*(Ov. +.IP \fIoverall_logical_return\fP 1i +Returns the overall logical \*(Ov. +.LP +.eM +The +.PN XmbTextExtents +and +.PN XwcTextExtents +functions set the components of the specified overall_ink_return and +overall_logical_return +arguments to the overall bounding box of the string's image +and a logical bounding box for spacing purposes, respectively. +They return the value returned by +.PN XmbTextEscapement +or +.PN XwcTextEscapement . +These metrics are relative to the drawing origin of the string, +using the fonts loaded for the specified font set. +.LP +If the overall_ink_return argument is non-NULL, +it is set to the bounding box of the string's character ink. +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. +.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. +.LP +When the +.PN XFontSet +has missing charsets, +metrics for each unavailable character are taken +from the default string returned by +.PN XCreateFontSet +so that the metrics represent the text as it will actually be drawn. +The behavior for an invalid codepoint is undefined. +.LP +To determine the effective drawing origin for a character in a drawn string, +the client should call +.PN XmbTextPerCharExtents +on the entire string, then on the character, +and subtract the x values of the returned +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. +.LP +.sp +To obtain per-character information for a text string, +use +.PN XmbTextPerCharExtents +or +.PN XwcTextPerCharExtents . +.IN "XmbTextPerCharExtents" "" "@DEF@" +.IN "XwcTextPerCharExtents" "" "@DEF@" +.sM +.FD 0 +Status XmbTextPerCharExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^, \fIink_array_return\fP\^, +.br + \fIlogical_array_return\fP\^, \fIarray_size\fP\^, \fInum_chars_return\fP\^, \fIoverall_ink_return\fP\^, \fIoverall_logical_return\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.br + char *\fIstring\fP\^; +.br + int \fInum_bytes\fP\^; +.br + XRectangle *\fIink_array_return\fP\^; +.br + XRectangle *\fIlogical_array_return\fP\^; +.br + int \fIarray_size\fP\^; +.br + int *\fInum_chars_return\fP\^; +.br + XRectangle *\fIoverall_ink_return\fP\^; +.br + XRectangle *\fIoverall_logical_return\fP\^; +.FN +.FD 0 +Status XwcTextPerCharExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^, \fIink_array_return\fP\^, +.br + \fIlogical_array_return\fP\^, \fIarray_size\fP\^, \fInum_chars_return\fP\^, \fIoverall_ink_return\fP\^, \fIoverall_ink_return\fP\^) +.br + XFontSet \fIfont_set\fP\^; +.br + wchar_t *\fIstring\fP\^; +.br + int \fInum_wchars\fP\^; +.br + XRectangle *\fIink_array_return\fP\^; +.br + XRectangle *\fIlogical_array_return\fP; +.br + int \fIarray_size\fP\^; +.br + int *\fInum_chars_return\fP\^; +.br + XRectangle *\fIoverall_ink_return\fP\^; +.br + XRectangle *\fIoverall_logical_return\fP\^; +.FN +.IP \fIfont_set\fP 1i +Specifies the font set. +.IP \fIstring\fP 1i +Specifies the character string. +.IP \fInum_bytes\fP 1i +Specifies the number of bytes in the string argument. +.IP \fInum_wchars\fP 1i +Specifies the number of characters in the string argument. +.IP \fIink_array_return\fP 1i +Returns the ink dimensions for each character. +.IP \fIlogical_array_return\fP 1i +Returns the logical dimensions for each character. +.IP \fIarray_size\fP 1i +Specifies the size of ink_array_return and logical_array_return. +The caller must pass in arrays of this size. +.IP \fInum_chars_return\fP 1i +Returns the number of characters in the string argument. +.ds Ov extents of the entire string +.IP \fIoverall_ink_return\fP 1i +Returns the overall ink \*(Ov. +.IP \fIoverall_logical_return\fP 1i +Returns the overall logical \*(Ov. +.LP +.eM +The +.PN XmbTextPerCharExtents +and +.PN XwcTextPerCharExtents +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. +.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. +.LP +Note that an +.PN XRectangle +represents the effective drawing dimensions of the character, +regardless of the number of font glyphs that are used to draw +the character or the direction in which the character is drawn. +If multiple characters map to a single character glyph, +the dimensions of all the +.PN XRectangles +of those characters are the same. +.LP +When the +.PN XFontSet +has missing charsets, metrics for each unavailable +character are taken from the default string returned by +.PN XCreateFontSet +so that the metrics represent the text as it will actually be drawn. +The behavior for an invalid codepoint is undefined. +.LP +If the array_size is too small for the number of characters in the +supplied text, the functions return zero +and num_chars_return is set to the number of rectangles required. +Otherwise, the functions return a nonzero value. +.LP +If the overall_ink_return or overall_logical_return argument is non-NULL, +.PN XmbTextPerCharExtents +and +.PN XwcTextPerCharExtents +return the maximum extent of the string's metrics to overall_ink_return +or overall_logical_return, as returned by +.PN XmbTextExtents +or +.PN XwcTextExtents . +.NH 3 +Drawing Text Using Font Sets +.XS +\*(SN Drawing Text Using Font Sets +.XE +.LP +The functions defined in this section +draw text at a specified location in a drawable. +They are similar to the functions +.PN XDrawText , +.PN XDrawString , +and +.PN XDrawImageString +except that they work with font sets instead of single fonts +and interpret the text based on the locale of the font set +instead of treating the bytes of the string as direct font indexes. +See section 8.6 for details of the use of Graphics Contexts (GCs) +and possible protocol errors. +If a +.PN BadFont +error is generated, +characters prior to the offending character may have been drawn. +.LP +The text is drawn using the fonts loaded for the specified font set; +the font in the GC is ignored and may be modified by the functions. +No validation that all fonts conform to some width rule is performed. +.LP +The text functions +.PN XmbDrawText +and +.PN XwcDrawText +use the following structures: +.LP +.IN "XmbTextItem" "" "@DEF@" +.sM +.Ds 0 +.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; +.De +.LP +.IN "XwcTextItem" "" "@DEF@" +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + wchar_t *chars; /* pointer to wide char string */ + int nchars; /* number of wide characters */ + int delta; /* pixel delta between strings */ + XFontSet font_set; /* fonts, None means don't change */ +} XwcTextItem; +.De +.LP +.eM +.sp +To draw text using multiple font sets in a given drawable, use +.PN XmbDrawText +or +.PN XwcDrawText . +.IN "XmbDrawText" "" "@DEF@" +.IN "XwcDrawText" "" "@DEF@" +.sM +.FD 0 +void XmbDrawText\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + XmbTextItem *\fIitems\fP\^; +.br + int \fInitems\fP\^; +.FN +.FD 0 +void XwcDrawText\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + XwcTextItem *\fIitems\fP\^; +.br + int \fInitems\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIgc\fP 1i +Specifies the GC. +.ds Xy +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.IP \fIitems\fP 1i +Specifies an array of text items. +.IP \fInitems\fP 1i +Specifies the number of text items in the array. +.LP +.eM +The +.PN XmbDrawText +and +.PN XwcDrawText +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 +.PN None +in an item causes the font set to be used for this and subsequent text items +in the text_items list. +Leading text items with a font_set member set to +.PN None +will not be drawn. +.LP +.PN XmbDrawText +and +.PN XwcDrawText +do not perform any context-dependent rendering between text segments. +Clients may compute the drawing metrics by passing each text segment to +.PN XmbTextExtents +and +.PN XwcTextExtents +or +.PN XmbTextPerCharExtents +and +.PN XwcTextPerCharExtents . +When the +.PN XFontSet +has missing charsets, each unavailable character is drawn +with the default string returned by +.PN XCreateFontSet . +The behavior for an invalid codepoint is undefined. +.LP +.sp +To draw text using a single font set in a given drawable, use +.PN XmbDrawString +or +.PN XwcDrawString . +.IN "XmbDrawString" "" "@DEF@" +.IN "XwcDrawString" "" "@DEF@" +.sM +.FD 0 +void XmbDrawString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + XFontSet \fIfont_set\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + char *\fIstring\fP\^; +.br + int \fInum_bytes\fP\^; +.FN +.FD 0 +void XwcDrawString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + XFontSet \fIfont_set\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + wchar_t *\fIstring\fP\^; +.br + int \fInum_wchars\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIfont_set\fP 1i +Specifies the font set. +.IP \fIgc\fP 1i +Specifies the GC. +.ds Xy +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.IP \fIstring\fP 1i +Specifies the character string. +.IP \fInum_bytes\fP 1i +Specifies the number of bytes in the string argument. +.IP \fInum_wchars\fP 1i +Specifies the number of characters in the string argument. +.LP +.eM +The +.PN XmbDrawString +and +.PN XwcDrawString +functions draw the specified text with the foreground pixel. +When the +.PN XFontSet +has missing charsets, each unavailable character is drawn +with the default string returned by +.PN XCreateFontSet . +The behavior for an invalid codepoint is undefined. +.LP +.sp +To draw image text using a single font set in a given drawable, use +.PN XmbDrawImageString +or +.PN XwcDrawImageString . +.IN "XmbDrawImageString" "" "@DEF@" +.IN "XwcDrawImageString" "" "@DEF@" +.sM +.FD 0 +void XmbDrawImageString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + XFontSet \fIfont_set\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + char *\fIstring\fP\^; +.br + int \fInum_bytes\fP\^; +.FN +.FD 0 +void XwcDrawImageString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + XFontSet \fIfont_set\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + wchar_t *\fIstring\fP\^; +.br + int \fInum_wchars\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.IP \fIfont_set\fP 1i +Specifies the font set. +.IP \fIgc\fP 1i +Specifies the GC. +.ds Xy +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.IP \fIstring\fP 1i +Specifies the character string. +.IP \fInum_bytes\fP 1i +Specifies the number of bytes in the string argument. +.IP \fInum_wchars\fP 1i +Specifies the number of characters in the string argument. +.LP +.eM +The +.PN XmbDrawImageString +and +.PN XwcDrawImageString +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 +.PN XmbTextExtents +or +.PN XwcTextExtents +for the same text and +.PN XFontSet . +.LP +When the +.PN XFontSet +has missing charsets, each unavailable character is drawn +with the default string returned by +.PN XCreateFontSet . +The behavior for an invalid codepoint is undefined. +.NH 2 +Input Methods +.XS +\*(SN Input Methods +.XE +.LP +This section provides discussions of the following X Input Method +(XIM) topics: +.IP \(bu 5 +Input method overview +.IP \(bu 5 +Input method management +.IP \(bu 5 +Input method functions +.IP \(bu 5 +Input method values +.IP \(bu 5 +Input context functions +.IP \(bu 5 +Input context values +.IP \(bu 5 +Input method callback semantics +.IP \(bu 5 +Event filtering +.IP \(bu 5 +Getting keyboard input +.IP \(bu 5 +Input method conventions +.NH 3 +Input Method Overview +.XS +\*(SN Input Method Overview +.XE +.LP +This section provides definitions for terms and concepts used +for internationalized text input and a brief overview of the +intended use of the mechanisms provided by Xlib. +.LP +A large number of languages in the world use alphabets +consisting of a small set of symbols (letters) to form words. +To enter text into a computer in an alphabetic language, +a user usually has a keyboard on which there 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. +.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. +.LP +Korean also has a phonetic symbol set, called Hangul. +Each of the 24 basic phonetic symbols (14 consonants and 10 vowels) +represents a specific sound. +A syllable is composed of two or three parts: +the initial consonants, the vowels, and the optional last consonants. +With Hangul, +syllables can be treated as the basic units on which text processing is done. +For example, +a delete operation may work on a phonetic symbol or a syllable. +Korean code sets include several thousands of these syllables. +A user types the phonetic symbols that make up the syllables of the words +to be entered. +The display may change as each phonetic symbol is entered. +For example, +when the second phonetic symbol of a syllable is entered, +the first phonetic symbol may change its shape and size. +Likewise, when the third phonetic symbol is entered, +the first two phonetic symbols may change their shape and size. +.LP +Not all languages rely solely on alphabetic or phonetic systems. +Some languages, including Japanese and Korean, employ an +ideographic writing system. +In an ideographic system, rather than taking a small set of +symbols and combining them in different ways to create words, +each word consists of one unique symbol (or, occasionally, several symbols). +The number of symbols can be very large: +approximately 50,000 have been identified in Hanzi, +the Chinese ideographic system. +.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. +.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. +.LP +In Japan, either Kana or English characters are typed and then a region +is selected (sometimes automatically) for conversion to Kanji. +Several Kanji characters may have the same phonetic representation. +If that is the case with the string entered, +a menu of characters is presented and +the user must choose the appropriate one. +If no choice is necessary or a preference has been established, +the input method does the substitution directly. +When Latin characters are converted to Kana or Kanji, +it is called a romaji conversion. +.LP +In Korea, it is usually acceptable to keep Korean text in Hangul form, +but some people may choose to write Hanja-originated words in Hanja +rather than in Hangul. +To change Hangul to Hanja, +the user selects a region for conversion +and then follows the same basic method as that described for Japanese. +.LP +Probably because there are well-accepted phonetic writing systems +for Japanese and Korean, +computer input methods in these countries for entering ideographs +are fairly standard. +Keyboard keys have both English characters and phonetic symbols +engraved on them, and the user can switch between the two sets. +.LP +The situation is different for Chinese. +While there is a phonetic system called Pinyin promoted by authorities, +there is no consensus for entering Chinese text. +Some vendors use a phonetic decomposition (Pinyin or another), +others use ideographic decomposition of Chinese words, +with various implementations and keyboard layouts. +There are about 16 known methods, none of which is a clear standard. +.LP +Also, there are actually two ideographic sets used: +Traditional Chinese (the original written Chinese) +and Simplified Chinese. +Several years ago, +the People's Republic of China launched a campaign to simplify +some ideographic characters and eliminate redundancies altogether. +Under the plan, +characters would be streamlined every five years. +Characters have been revised several times now, +resulting in the smaller, simpler set that makes up Simplified Chinese. +.NH 4 +Input Method Architecture +.XS +\*(SN Input Method Architecture +.XE +.LP +As shown in the previous section, +there are many different input methods in use today, +each varying with language, culture, and history. +A common feature of many input methods is that the user may type +multiple keystrokes to compose a single character (or set +of characters). +The process of composing characters from keystrokes is called +\fIpreediting\fP. +It may require complex algorithms and large dictionaries +involving substantial computer resources. +.LP +Input methods may require one or more areas in which to show the +feedback of the actual keystrokes, to propose disambiguation to the +user, to list dictionaries, and so on. +The input method areas of concern are as follows: +.IP \(bu 5 +The \fIstatus\fP area is 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. +.IP \(bu 5 +The \fIpreedit\fP area displays the +intermediate text for those languages that are composing prior to +the client handling the data. +.IP \(bu 5 +The \fIauxiliary\fP area is used for pop-up menus and customizing +dialogs that may be required for an input method. +There may be multiple auxiliary areas for 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. +.LP +There are various user interaction styles used for preediting. +The ones supported by Xlib are as follows: +.IP \(bu 5 +For \fIon-the-spot\fP input methods, +preediting data will be displayed directly in the application window. +Application data is moved to allow preedit data to appear +at the point of insertion. +.IP \(bu 5 +\fIOver-the-spot\fP preediting means that the data is displayed in +a preedit window that is placed over the point of insertion. +.IP \(bu 5 +\fIOff-the-spot\fP preediting means that the preedit window is +inside the application window but not at the point of insertion. +Often, this type of window is placed at the bottom of the application window. +.IP \(bu 5 +\fIRoot-window\fP preediting refers to input methods that use a preedit +window that is the child of +.PN RootWindow . +.LP +It would require a lot of computing resources if portable applications +had to include input methods for all the languages in the world. +To avoid this, +a goal of the Xlib design is to allow an application +to communicate with an input method placed in a separate process. +Such a process is called an \fIinput server\fP. +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 \fIlocale-dependent\fP. +It is also user-dependent. +For a given language, the user can choose, to some extent, +the user interface style of input method (if choice is possible among +several). +.LP +Using an input server implies communication overhead, +but applications can be migrated without relinking. +Input methods can be implemented either as a +stub communicating to an input server or as a local library. +.LP +An input method may be based on a \fIfront-end\fP or a \fIback-end\fP +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. +.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. +.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. +.LP +The abstraction used by a client to communicate with an input method +is an opaque data structure represented by the +.PN XIM +data type. +This data structure is returned by the +.PN XOpenIM +function, which opens an input method on a given display. +Subsequent operations on this data structure encapsulate all communication +between client and input method. +There is no need for an X client to use any networking library +or natural language package to use an input method. +.LP +A single input server may be used for one or more languages, +supporting one or more encoding schemes. +But the strings returned from an input method will always be encoded +in the (single) locale associated with the +.PN XIM +object. +.NH 4 +Input Contexts +.XS +\*(SN Input Contexts +.XE +.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 \fIinput context\fP. +The Xlib representation of an input context is an +.PN XIC . +.LP +An input context is the abstraction retaining the state, properties, +and semantics of communication between a client and an input method. +An input context is a combination of an input method, a locale +specifying the encoding of the character strings to be returned, +a client window, internal state information, +and various layout or appearance characteristics. +The input context concept somewhat matches for input the graphics context +abstraction defined for graphics output. +.LP +One input context belongs to exactly one input method. +Different input contexts may be associated with the same input method, +possibly with the same client window. +An +.PN XIC +is created with the +.PN XCreateIC +function, providing an +.PN XIM +argument and affiliating the input context to the input method +for its lifetime. +When an input method is closed with +.PN XCloseIM , +all of its affiliated input contexts should not be used any more +(and should preferably be destroyed before closing the input method). +.LP +Considering the example of a client window with multiple text entry areas, +the application programmer could, for example, choose to implement as follows: +.IP \(bu 5 +As many input contexts are created as text entry areas, and the client +will get the input accumulated on each context each time it looks up +in that context. +.IP \(bu 5 +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. +.LP +A range of choices can be made by application designers to use +either a single or multiple input contexts, +according to the needs of their application. +.NH 4 +Getting Keyboard Input +.XS +\*(SN Getting Keyboard Input +.XE +.LP +To obtain characters from an input method, +a client must call the function +.PN XmbLookupString +or +.PN XwcLookupString +with an input context created from that input method. +Both a locale and display are bound to an input method when it is opened, +and an input context inherits this locale and display. +Any strings returned by +.PN XmbLookupString +or +.PN XwcLookupString +will be encoded in that locale. +.NH 4 +Focus Management +.XS +\*(SN Focus Management +.XE +.LP +For each text entry area in which the +.PN XmbLookupString +or +.PN XwcLookupString +functions are used, +there will be an associated input context. +.LP +When the application focus moves to a text entry area, +the application must set the input context focus to the +input context associated with that area. +The input context focus is set by calling +.PN XSetICFocus +with the appropriate input context. +.LP +Also, when the application focus moves out of a text entry area, the +application should unset the focus for the associated input context +by calling +.PN XUnsetICFocus . +As an optimization, if +.PN XSetICFocus +is called successively on two different input contexts, +setting the focus on the second +will automatically unset the focus on the first. +.LP +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. +.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). +.NH 4 +Geometry Management +.XS +\*(SN Geometry Management +.XE +.LP +In most input method architectures +(on-the-spot being the notable exception), +the input method will perform the display of its own data. +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. +.LP +The fundamental concept on which geometry management for input method windows +is based is the proper division of responsibilities between the +client (or toolkit) and the input method. +The division of responsibilities is as follows: +.IP \(bu 5 +The client is responsible for the geometry of the input method window. +.IP \(bu 5 +The input method is responsible for the contents of the input method window. +.LP +An input method is able to suggest a size to the client, +but it cannot suggest a placement. +Also the input method can only suggest a size. +It does not determine the size, +and it must accept the size it is given. +.LP +Before a client provides geometry management for an input method, +it must determine if geometry management is needed. +The input method indicates the need for geometry management +by setting +.PN XIMPreeditArea +or +.PN XIMStatusArea +in its +.PN XIMStyles +value returned by +.PN XGetIMValues . +When a client has decided that it will provide geometry management +for an input method, +it indicates that decision by setting the +.PN XNInputStyle +value in the +.PN XIC . +.LP +After a client has established with the input method +that it will do geometry management, +the client must negotiate the geometry with the input method. +The geometry is negotiated by the following steps: +.IP \(bu 5 +The client suggests an area to the input method by setting the +.PN XNAreaNeeded +value for that area. +If the client has no constraints for the input method, +it either will not suggest an area or will set the width and height to zero. +Otherwise, it will set one of the values. +.IP \(bu 5 +The client will get the XIC value +.PN XNAreaNeeded . +The input method will return its suggested size in this value. +The input method should pay attention to any constraints suggested +by the client. +.IP \(bu 5 +The client sets the XIC value +.PN XNArea +to inform the input method of the geometry of its window. +The client should try to honor the geometry requested by the input method. +The input method must accept this geometry. +.LP +Clients doing geometry management must be aware that setting other +XIC values may affect the geometry desired by an input method. +For example, +.PN XNFontSet +and +.PN XNLineSpacing +may change the geometry desired by the input method. +.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. +.LP +In addition, +a geometry management callback is provided +by which an input method can initiate a geometry change. +.NH 4 +Event Filtering +.XS +\*(SN Event Filtering +.XE +.LP +A filtering mechanism is provided to allow input methods +to capture X events transparently to clients. +It is expected that toolkits (or clients) using +.PN XmbLookupString +or +.PN XwcLookupString +will call this filter at some point in the event processing mechanism +to make sure that events needed by an input method can be filtered +by that input method. +.LP +If there were no filter, +a client could receive and discard events that are necessary +for the proper functioning of an input method. +The following provides a few examples of such events: +.IP \(bu 5 +Expose events on preedit window in local mode. +.IP \(bu 5 +Events may be used by an input method to communicate with an input server. +Such input server protocol-related events have to be intercepted +if one does not want to disturb client code. +.IP \(bu 5 +Key events can be sent to a filter before they are bound +to translations such as those the X Toolkit Intrinsics library provides. +.LP +Clients are expected to get the XIC value +.PN XNFilterEvents +and augment the event mask for the client window with that event mask. +This mask may be zero. +.NH 4 +Callbacks +.XS +\*(SN Callbacks +.XE +.LP +When an on-the-spot input method is implemented, +only the client can insert or delete preedit data in place +and possibly scroll existing text. +This means that the echo of the keystrokes has to be achieved +by the client itself, tightly coupled with the input method logic. +.LP +When the user enters a keystroke, +the client calls +.PN XmbLookupString +or +.PN XwcLookupString . +At this point, in the on-the-spot case, +the echo of the keystroke in the preedit has not yet been done. +Before returning to the client logic that handles the input characters, +the 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. +.LP +There are a number of cases where the input method logic has to +call back the client. +Each of those cases is associated with a well-defined callback action. +It is possible for the client to specify, for each input context, +what callback is to be called for each action. +.LP +There are also callbacks provided for feedback of status information +and a callback to initiate a geometry request for an input method. +.NH 4 +Visible Position Feedback Masks +.XS +\*(SN Visible Position Feedback Masks +.XE +.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 +.PN XIMText +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. +.NH 4 +Preedit String Management +.XS +\*(SN Preedit String Management +.XE +.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 +.PN XmbLookupString +or +.PN XwcLookupString . +This provides the basics for input methods. +.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 +\fIstring conversion\fP 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. +.LP +The need for string conversion is based on +language needs and input method capabilities. +The following are some examples of string conversion: +.IP \(bu 5 +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. +.IP \(bu 5 +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. +.IP \(bu 5 +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 +.PN XmbResetIC +or +.PN XwcResetIC , +which is usually an indication of a context change. +.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 +.PN XmbLookupString +and +.PN XwcLookupString +functions. +.LP +String conversion support is dependent on the availability of the +.PN XNStringConversion +or +.PN XNStringConversionCallback +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 +.PN XGetIMValues +with the +.PN XNQueryICValuesList +IM value. +.LP +The difference between these two values is whether the +conversion is invoked by the client or the input method. +The +.PN XNStringConversion +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 +.PN XNStringConversionCallback +will be issued when this value is set; thus, the client need +only set one of these values. +.LP +The +.PN XNStringConversionCallback +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 +.PN XIMStringConversionCallbackStruct +specifies which text should be passed back to the input method. +.LP +Finally, the input method may call the client's +.PN XNStringConversionCallback +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. +.LP +.NH 3 +Input Method Management +.XS +\*(SN Input Method Management +.XE +.LP +The interface to input methods might appear to be simply creating +an input method +.Pn ( XOpenIM ) +and freeing an input method +.Pn ( XCloseIM ). +However, input methods may +require complex communication with input method servers (IM servers), +for example: +.IP \(bu 5 +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. +.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). +.LP +.IP \(bu 5 +Some input methods may allow the underlying IM server to be switched. +Such customization may be desired without restarting the entire client. +.LP +To support management of input methods in these cases, the following +functions are provided: +.TS +lw(2.4i) lw(3.3i). +T{ +.PN XRegisterIMInstantiateCallback +T} T{ +This function allows clients to register a callback procedure +to be called when Xlib detects that an IM server is up and available. +T} +T{ +.PN XOpenIM +T} T{ +A client calls this function as a result of the callback procedure +being called. +T} +T{ +.PN XSetIMValue , +.PN XSetICValue +T} T{ +These functions use the XIM and XIC values, +.PN XNDestroyCallback , +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. +.sp 4p +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. +T} +T{ +.PN XUnregisterIMInstantiateCallback +T} T{ +This function removes a callback procedure registered by the client. +T} +.TE +.LP +Input methods that support switching of IM servers may exhibit some +side-effects: +.IP \(bu 5 +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. +.LP +.IP \(bu 5 +Geometry management requests on previously created input contexts +may be initiated by the new IM server. +.LP +.NH 4 +Hot Keys +.XS +\*(SN Hot Keys +.XE +.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 +.PN XGetIMValues +with the +.PN XNQueryICValuesList +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. +.LP +.NH 4 +Preedit State Operation +.XS +\*(SN Preedit State Operation +.XE +.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 +.PN XGetICValues +with the +.PN XNPreeditState +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 +.PN XSetICValues +with the +.PN XNPreeditStateNotifyCallback +XIC value. +In order to change the preedit state programmatically, an application +needs to call +.PN XSetICValues +with +.PN XNPreeditState. +.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 +.PN XGetIMValues +with the +.PN XNQueryICValuesList +IM value. +.NH 3 +Input Method Functions +.XS +\*(SN Input Method Functions +.XE +.LP +To open a connection, use +.PN XOpenIM . +.IN "XOpenIM" "" "@DEF@" +.sM +.FD 0 +XIM XOpenIM\^(\^\fIdisplay\fP\^, \fIdb\fP\^, \fIres_name\fP\^, \fIres_class\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XrmDatabase \fIdb\fP\^; +.br + char *\fIres_name\fP\^; +.br + char *\fIres_class\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIdb\fP 1i +Specifies a pointer to the resource database. +.IP \fIres_name\fP 1i +Specifies the full resource name of the application. +.IP \fIres_class\fP 1i +Specifies the full class name of the application. +.LP +.eM +The +.PN XOpenIM +function opens an input method, +matching the current locale and modifiers specification. +Current locale and modifiers are bound to the input method at opening time. +The locale associated with an input method cannot be changed dynamically. +This implies that the strings returned by +.PN XmbLookupString +or +.PN XwcLookupString , +for any input context affiliated with a given input method, +will be encoded in the locale current at the time the input method is opened. +.LP +The specific input method to which this call will be routed +is identified on the basis of the current locale. +.PN XOpenIM +will identify a default input method corresponding to the +current locale. +That default can be modified using +.PN XSetLocaleModifiers +for the input method modifier. +.LP +The db argument is the resource database to be used by the input method +for looking up resources that are private to the input method. +It is not intended that this database be used to look +up values that can be set as IC values in an input context. +If db is NULL, +no database is passed to the input method. +.LP +The res_name and res_class arguments specify the resource name +and class of the application. +They are intended to be used as prefixes by the input method +when looking up resources that are common to all input contexts +that may be created for this input method. +The characters used for resource names and classes must be in the +X Portable Character Set. +The resources looked up are not fully specified +if res_name or res_class is NULL. +.LP +The res_name and res_class arguments are not assumed to exist beyond +the call to +.PN XOpenIM . +The specified resource database is assumed to exist for the lifetime +of the input method. +.LP +.PN XOpenIM +returns NULL if no input method could be opened. +.LP +.sp +To close a connection, use +.PN XCloseIM . +.IN "XCloseIM" "" "@DEF@" +.sM +.FD 0 +Status XCloseIM\^(\^\fIim\fP\^) +.br + XIM \fIim\fP\^; +.FN +.IP \fIim\fP 1i +Specifies the input method. +.LP +.eM +The +.PN XCloseIM +function closes the specified input method. +.LP +.sp +To set input method attributes, use +.PN XSetIMValues . +.IN "XSetIMValues" "" "@DEF@" +.sM +.FD 0 +char * XSetIMValues\^(\^\fIim\fP\^, ...) +.br + XIM \fIim\fP\^; +.FN +.IP \fIim\fP 1i +Specifies the input method. +.ds Al \ to set XIM values +.IP ... 1i +Specifies the variable-length argument list\*(Al. +.LP +.eM +The +.PN XSetIMValues +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. +.LP +.sp +To query an input method, use +.PN XGetIMValues . +.IN "XGetIMValues" "" "@DEF@" +.sM +.FD 0 +char * XGetIMValues\^(\^\fIim\fP\^, ...) +.br + XIM \fIim\fP\^; +.FN +.IP \fIim\fP 1i +Specifies the input method. +.ds Al \ to get XIM values +.IP ... 1i +Specifies the variable length argument list\*(Al. +.LP +.eM +The +.PN XGetIMValues +function presents a variable argument list programming interface +for querying properties or features of the specified input method. +This function returns NULL if it succeeds; +otherwise, +it returns the name of the first argument that could not be obtained. +.LP +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 +.PN XGetIMValues +allocates memory to store the actual data, +and the client is responsible for freeing this data by calling +.PN XFree +with the returned pointer. +.LP +.sp +To obtain the display associated with an input method, use +.PN XDisplayOfIM . +.IN "XDisplayOfIM" "" "@DEF@" +.sM +.FD 0 +Display * XDisplayOfIM\^(\^\fIim\fP\^) +.br + XIM \fIim\fP\^; +.FN +.IP \fIim\fP 1i +Specifies the input method. +.LP +.eM +The +.PN XDisplayOfIM +function returns the display associated with the specified input method. +.LP +.sp +To get the locale associated with an input method, use +.PN XLocaleOfIM . +.IN "XLocaleOfIM" "" "@DEF@" +.sM +.FD 0 +char * XLocaleOfIM\^(\^\fIim\fP\^) +.br + XIM \fIim\fP\^; +.FN +.IP \fIim\fP 1i +Specifies the input method. +.LP +.eM +The +.PN XLocaleOfIM +function returns the locale associated with the specified input method. +.LP +.sp +To register an input method instantiate callback, use +.PN XRegisterIMInstantiateCallback . +.IN "XRegisterIMInstantiateCallback" "" "@DEF@" +.sM +.FD 0 +Bool XRegisterIMInstantiateCallback\^(\^\fIdisplay\fP\^, \fIdb\fP\^, \fIres_name\fP\^, \fIres_class\fP\^, \fIcallback\fP\^, \fIclient_data\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XrmDatabase \fIdb\fP\^; +.br + char *\fIres_name\fP\^; +.br + char *\fIres_class\fP\^; +.br + XIMProc \fIcallback\fP\^; +.br + XPointer *\fIclient_data\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIdb\fP 1i +Specifies a pointer to the resource database. +.IP \fIres_name\fP 1i +Specifies the full resource name of the application. +.IP \fIres_class\fP 1i +Specifies the full class name of the application. +.IP \fIcallback\fP 1i +Specifies a pointer to the input method instantiate callback. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.LP +.eM +The +.PN XRegisterIMInstantiateCallback +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. +.LP +The function returns +.PN True + if it succeeds; otherwise, it returns +.PN False . +.LP +The generic prototype is as follows: +.IN "IMInstantiateCallback" "" "@DEF@" +.sM +.FD 0 +void IMInstantiateCallback\^(\^\fIdisplay\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + XPointer \fIcall_data\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Not used for this callback and always passed as NULL. +.LP +.eM +To unregister an input method instantiation callback, use +.PN XUnregisterIMInstantiateCallback . +.IN "XUnregisterIMInstantiateCallback" "" "@DEF@" +.sM +.FD 0 +Bool XUnregisterIMInstantiateCallback\^(\^\fIdisplay\fP\^, \fIdb\fP\^, \fIres_name\fP\^, \fIres_class\fP\^, \fIcallback\fP\^, \fIclient_data\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XrmDatabase \fIdb\fP\^; +.br + char *\fIres_name\fP\^; +.br + char *\fIres_class\fP\^; +.br + XIMProc \fIcallback\fP\^; +.br + XPointer *\fIclient_data\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIdb\fP 1i +Specifies a pointer to the resource database. +.IP \fIres_name\fP 1i +Specifies the full resource name of the application. +.IP \fIres_class\fP 1i +Specifies the full class name of the application. +.IP \fIcallback\fP 1i +Specifies a pointer to the input method instantiate callback. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.LP +.eM +The +.PN XUnregisterIMInstantiateCallback +function removes an input method instantiation callback previously +registered. +The function returns +.PN True +if it succeeds; otherwise, it returns +.PN False . +.NH 3 +Input Method Values +.XS +\*(SN Input Method Values +.XE +.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. +.LP +.LP +The following keys apply to this table. +.TS H +lw(1i) lw(4.75i). +_ +.sp 6p +.B +Key Explanation +.sp 6p +_ +.TH +.R +D T{ +This value may be set using +.PN XSetIMValues . +If it is not set, +.br +a default is provided. +T} +S T{ +This value may be set using +.PN XSetIMValues . +T} +G T{ +This value may be read using +.PN XGetIMValues . +T} +.sp 6p +_ +.TE +.LP +.TS H +lw(2.25i) c +lw(2.25i) c. +_ +.sp 6p +.B +XIM Value Key +.sp 6p +_ +.sp 6p +.TH +.R +T{ +.PN XNQueryInputStyle +T} T{ +G +T} +T{ +.PN XNResourceName +T} T{ +D-S-G +T} +T{ +.PN XNResourceClass +T} T{ +D-S-G +T} +T{ +.PN XNDestroyCallback +T} T{ +D-S-G +T} +T{ +.PN XNQueryIMValuesList +T} T{ +G +T} +T{ +.PN XNQueryICValuesList +T} T{ +G +T} +T{ +.PN XNVisiblePosition +T} T{ +G +T} +T{ +.PN XNR6PreeditCallbackBehavior +T} T{ +D-S-G +T} +.sp 6p +_ +.TE +.LP +.PN XNR6PreeditCallbackBehavior +is obsolete and its use is not recommended (see section 13.5.4.6). +.LP +.NH 4 +Query Input Style +.XS +\*(SN Query Input Style +.XE +.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. +.LP +If the client cannot find an input style that it can support, +it should negotiate with the user the continuation of the program +(exit, choose another input method, and so on). +.LP +The argument value must be a pointer to a location +where the returned value will be stored. +The returned value is a pointer to a structure of type +.PN XIMStyles . +Clients are responsible for freeing the +.PN XIMStyles +structure. +To do so, use +.PN XFree . +.LP +The +.PN XIMStyles +structure is defined as follows: +.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 +.Ds 0 +typedef unsigned long XIMStyle; +.De +.TS +lw(.5i) lw(2i) lw(2.5i). +T{ +#define +T} T{ +.PN XIMPreeditArea +T} T{ +0x0001L +T} +T{ +#define +T} T{ +.PN XIMPreeditCallbacks +T} T{ +0x0002L +T} +T{ +#define +T} T{ +.PN XIMPreeditPosition +T} T{ +0x0004L +T} +T{ +#define +T} T{ +.PN XIMPreeditNothing +T} T{ +0x0008L +T} +T{ +#define +T} T{ +.PN XIMPreeditNone +T} T{ +0x0010L +T} +.sp +T{ +#define +T} T{ +.PN XIMStatusArea +T} T{ +0x0100L +T} +T{ +#define +T} T{ +.PN XIMStatusCallbacks +T} T{ +0x0200L +T} +T{ +#define +T} T{ +.PN XIMStatusNothing +T} T{ +0x0400L +T} +T{ +#define +T} T{ +.PN XIMStatusNone +T} T{ +0x0800L +T} +.TE +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + unsigned short count_styles; + XIMStyle * supported_styles; +} XIMStyles; +.De +.LP +.eM +An +.PN XIMStyles +structure contains the number of input styles supported +in its count_styles field. +This is also the size of the supported_styles array. +.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. +.LP +The preedit category defines what type of support is provided +by the input method for preedit information. +.IN "XIMPreeditArea" "" "@DEF@" +.IN "XIMPreeditPosition" "" "@DEF@" +.IN "XIMPreeditCallbacks" "" "@DEF@" +.IN "XIMPreeditNothing" "" "@DEF@" +.IN "XIMPreeditNone" "" "@DEF@" +.TS +lw(1.5i) lw(4.25i). +T{ +.PN XIMPreeditArea +T} T{ +If chosen, +the input method would require the client to provide some area values +for it to do its preediting. +Refer to XIC values +.PN XNArea +and +.PN XNAreaNeeded . +T} +T{ +.PN XIMPreeditPosition +T} T{ +If chosen, +the input method would require the client to provide positional values. +Refer to XIC values +.PN XNSpotLocation +and +.PN XNFocusWindow . +T} +T{ +.PN XIMPreeditCallbacks +T} T{ +If chosen, +the input method would require the client to define the set of preedit callbacks. +Refer to XIC values +.PN XNPreeditStartCallback , +.PN XNPreeditDoneCallback , +.PN XNPreeditDrawCallback , +and +.PN XNPreeditCaretCallback . +T} +T{ +.PN XIMPreeditNothing +T} T{ +If chosen, the input method can function without any preedit values. +T} +T{ +.PN XIMPreeditNone +T} T{ +The input method does not provide any preedit feedback. +Any preedit value is ignored. +This style is mutually exclusive with the other preedit styles. +T} +.TE +.LP +The status category defines what type of support is provided +by the input method for status information. +.IN "XIMStatusArea" "" "@DEF@" +.IN "XIMStatusCallbacks" "" "@DEF@" +.IN "XIMStatusNothing" "" "@DEF@" +.IN "XIMStatusNone" "" "@DEF@" +.TS +lw(1.5i) lw(4.25i). +T{ +.PN XIMStatusArea +T} T{ +The input method requires the client to provide +some area values for it to do its status feedback. +See +.PN XNArea +and +.PN XNAreaNeeded . +T} +T{ +.PN XIMStatusCallbacks +T} T{ +The input method requires the client to define the set of status callbacks, +.PN XNStatusStartCallback , +.PN XNStatusDoneCallback , +and +.PN XNStatusDrawCallback . +T} +T{ +.PN XIMStatusNothing +T} T{ +The input method can function without any status values. +T} +T{ +.PN XIMStatusNone +T} T{ +The input method does not provide any status feedback. +If chosen, any status value is ignored. +This style is mutually exclusive with the other status styles. +T} +.TE +.NH 4 +Resource Name and Class +.XS +\*(SN Resource Name and Class +.XE +.LP +The +.PN XNResourceName +and +.PN XNResourceClass +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. +.LP +It is not intended that values that can be set as XIM values be +set as resources. +.LP +.NH 4 +Destroy Callback +.XS +\*(SN Destroy Callback +.XE +.LP +The +.PN XNDestroyCallback +argument is a pointer to a structure of type +.PN XIMCallback . +.PN XNDestroyCallback +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 +.PN XCloseIM +or +.PN XDestroyIC . +.LP +The generic prototype of this callback function is as follows: +.IN "DestroyCallback" "" "@DEF@" +.sM +.FD 0 +void DestroyCallback\^(\^\fIim\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + XIM \fIim\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + XPointer \fIcall_data\fP\^; +.FN +.IP \fIim\fP 1i +Specifies the input method. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Not used for this callback and always passed as NULL. +.LP +.eM +A DestroyCallback is always called with a NULL call_data argument. +.LP +.NH 4 +Query IM/IC Values List +.XS +\*(SN Query IM/IC Values List +.XE +.LP +.PN XNQueryIMValuesList +and +.PN XNQueryICValuesList +are used to query about XIM and XIC values supported by the input method. +.LP +The argument value must be a pointer to a location where the returned +value will be stored. The returned value is a pointer to a structure +of type +.PN XIMValuesList . +Clients are responsible for freeing the +.PN XIMValuesList +structure. +To do so, use +.PN XFree . +.LP +The +.PN XIMValuesList +structure is defined as follows: +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct { + unsigned short count_values; + char **supported_values; +} XIMValuesList; +.De +.LP +.eM +.NH 4 +Visible Position +.XS +\*(SN Visible Position +.XE +.LP +The +.PN XNVisiblePosition +argument indicates whether the visible position masks of +.PN XIMFeedback +in +.PN XIMText +are available. +.LP +The argument value must be a pointer to a location where the returned +value will be stored. The returned value is of type +.PN Bool . +If the returned value is +.PN True , +the input method uses the visible position masks of +.PN XIMFeedback +in +.PN XIMText ; +otherwise, the input method does not use the masks. +.LP +Because this XIM value is optional, a client should call +.PN XGetIMValues +with argument +.PN XNQueryIMValues +before using this argument. +If the +.PN XNVisiblePosition +does not exist in the IM values list returned from +.PN XNQueryIMValues , +the visible position masks of +.PN XIMFeedback +in +.PN XIMText +are not used to indicate the visible position. +.LP +.NH 4 +Preedit Callback Behavior +.XS +\*(SN Preedit Callback Behavior +.XE +.LP +The +.PN XNR6PreeditCallbackBehavior +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 +.PN XNR6PreeditCallbackBehavior . +Unfortunately, this argument was not removed from the R6 specification +before it was published. +.FE +.LP +The +.PN XNR6PreeditCallbackBehavior +argument indicates whether the behavior of preedit callbacks regarding +.PN XIMPreeditDrawCallbackStruct +values follows Release 5 or Release 6 semantics. +.LP +The value is of type +.PN Bool . +When querying for +.PN XNR6PreeditCallbackBehavior , +if the returned value is +.PN True , +the input method uses the Release 6 behavior; +otherwise, it uses the Release 5 behavior. +The default value is +.PN False . +In order to use Release 6 semantics, the value of +.PN XNR6PreeditCallbackBehavior +must be set to +.PN True . +.LP +Because this XIM value is optional, a client should call +.PN XGetIMValues +with argument +.PN XNQueryIMValues +before using this argument. +If the +.PN XNR6PreeditCallbackBehavior +does not exist in the IM values list returned from +.PN XNQueryIMValues , +the PreeditCallback behavior is Release 5 semantics. +.LP +.NH 3 +Input Context Functions +.XS +\*(SN Input Context Functions +.XE +.LP +An input context is an abstraction that is used to contain both the data +required (if any) by an input method and the information required +to display that data. +There may be multiple input contexts for one input method. +The programming interfaces for creating, reading, or modifying +an input context use a variable argument list. +The name elements of the argument lists are referred to as XIC values. +It is intended that input methods be controlled by these XIC values. +As new XIC values are created, +they should be registered with the X Consortium. +.LP +.sp +To create an input context, use +.PN XCreateIC . +.IN "XCreateIC" "" "@DEF@" +.sM +.FD 0 +XIC XCreateIC\^(\^\fIim\fP\^, ...) +.br + XIM \fIim\fP\^; +.FN +.IP \fIim\fP 1i +Specifies the input method. +.ds Al \ to set XIC values +.IP ... 1i +Specifies the variable length argument list\*(Al. +.LP +.eM +The +.PN XCreateIC +function creates a context within the specified input method. +.LP +Some of the arguments are mandatory at creation time, and +the input context will not be created if 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. +.LP +.PN XCreateIC +returns a NULL value if no input context could be created. +A NULL value could be returned for any of the following reasons: +.IP \(bu 5 +A required argument was not set. +.IP \(bu 5 +A read-only argument was set (for example, +.PN XNFilterEvents ). +.IP \(bu 5 +The argument name is not recognized. +.IP \(bu 5 +The input method encountered an input method implementation-dependent error. +.LP +.PN XCreateIC +can generate +.PN BadAtom , +.PN BadColor , +.PN BadPixmap , +and +.PN BadWindow +errors. +.LP +.sp +To destroy an input context, use +.PN XDestroyIC . +.IN "XDestroyIC" "" "@DEF@" +.sM +.FD 0 +void XDestroyIC\^(\^\fIic\fP\^) +.br + XIC \fIic\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.LP +.eM +.PN XDestroyIC +destroys the specified input context. +.LP +.sp +To communicate to and synchronize with input method +for any changes in keyboard focus from the client side, +use +.PN XSetICFocus +and +.PN XUnsetICFocus . +.IN "XSetICFocus" "" "@DEF@" +.sM +.FD 0 +void XSetICFocus\^(\^\fIic\fP\^) +.br + XIC \fIic\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.LP +.eM +The +.PN XSetICFocus +function allows a client to notify an input method that the focus window +attached to the specified input context has received keyboard focus. +The input method should take action to provide appropriate feedback. +Complete feedback specification is a matter of user interface policy. +.LP +Calling +.PN XSetICFocus +does not affect the focus window value. +.LP +.sp +.IN "XUnsetICFocus" "" "@DEF@" +.sM +.FD 0 +void XUnsetICFocus\^(\^\fIic\fP\^) +.br + XIC \fIic\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.LP +.eM +The +.PN XUnsetICFocus +function allows a client to notify an input method that the specified input context +has lost the keyboard focus and that no more input is expected on the focus window +attached to that input context. +The input method should take action to provide appropriate feedback. +Complete feedback specification is a matter of user interface policy. +.LP +Calling +.PN XUnsetICFocus +does not affect the focus window value; +the client may still receive +events from the input method that are directed to the focus window. +.LP +.sp +To reset the state of an input context to its initial state, use +.PN XmbResetIC +or +.PN XwcResetIC . +.IN "XmbResetIC" "" "@DEF@" +.IN "XwcResetIC" "" "@DE@" +.sM +.FD 0 +char * XmbResetIC\^(\^\fIic\fP\^) +.br + XIC \fIic\fP\^; +.FN +.FD 0 +wchar_t * XwcResetIC\^(\^\fIic\fP\^) +.br + XIC \fIic\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.LP +.eM +When +.PN XNResetState +is set to +.PN XIMInitialState , +.PN XmbResetIC +and +.PN XwcResetIC +reset an input context to its initial state; +when +.PN XNResetState +is set to +.PN XIMPreserveState , +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 +.PN XmbResetIC +or +.PN XwcResetIC +does not change the focus. +.LP +The return value of +.PN XmbResetIC +is its current preedit string as a multibyte string. +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. +.LP +The client should free the returned string by calling +.PN XFree . +.LP +.sp +To get the input method associated with an input context, use +.PN XIMOfIC . +.IN "XIMOfIC" "" "@DEF@" +.sM +.FD 0 +XIM XIMOfIC\^(\^\fIic\fP\^) +.br + XIC \fIic\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.LP +.eM +The +.PN XIMOfIC +function returns the input method associated with the specified input context. +.LP +.sp +Xlib provides two functions for setting and reading XIC values, respectively, +.PN XSetICValues +and +.PN XGetICValues . +Both functions have a variable-length argument list. +In that argument list, any XIC value's name must be denoted +with a character string using the X Portable Character Set. +.LP +.sp +To set XIC values, use +.PN XSetICValues . +.IN "XSetICValues" "" "@DEF@" +.sM +.FD 0 +char * XSetICValues\^(\^\fIic\fP\^, ...) +.br + XIC \fIic\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.ds Al \ to set XIC values +.IP ... 1i +Specifies the variable length argument list\*(Al. +.LP +.eM +The +.PN XSetICValues +function returns NULL if no error occurred; +otherwise, +it returns the name of the first argument that could not be set. +An argument might not be set for any of the following reasons: +.IP \(bu 5 +The argument is read-only (for example, +.PN XNFilterEvents ). +.IP \(bu 5 +The argument name is not recognized. +.IP \(bu 5 +An implementation-dependent error occurs. +.LP +Each value to be set must be an appropriate datum, +matching the data type imposed by the semantics of the argument. +.LP +.PN XSetICValues +can generate +.PN BadAtom , +.PN BadColor , +.PN BadCursor , +.PN BadPixmap , +and +.PN BadWindow +errors. +.LP +.sp +To obtain XIC values, use +.PN XGetICValues . +.IN "XGetICValues" "" "@DEF@" +.sM +.FD 0 +char * XGetICValues\^(\^\fIic\fP\^, ...) +.br + XIC \fIic\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.ds Al \ to get XIC values +.IP ... 1i +Specifies the variable length argument list\*(Al. +.LP +.eM +The +.PN XGetICValues +function returns NULL if no error occurred; otherwise, +it returns the name of the first argument that could not be obtained. +An argument could not be obtained for any of the following reasons: +.IP \(bu 5 +The argument name is not recognized. +.IP \(bu 5 +The input method encountered an implementation-dependent error. +.LP +Each 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 +.PN XGetICValues +allocates memory to store the actual data, +and the client is responsible for freeing this data by calling +.PN XFree +with the returned pointer. +The exception to this rule is for an IC value of type +.PN XVaNestedList +(for preedit and status attributes). +In this case, the argument must also be of type +.PN XVaNestedList . +Then, the rule of changing type T to T* and freeing the allocated data +applies to each element of the nested list. +.NH 3 +Input Context Values +.XS +\*(SN Input Context Values +.XE +.LP +The following tables describe how XIC values are interpreted +by an input method depending on the input style chosen by the +user. +.LP +The first column lists the XIC values. +The second column indicates which values are involved in affecting, +negotiating, and setting the geometry of the input method windows. +The subentries under the third column indicate the different +input styles that are supported. +Each of these columns indicates how each of the XIC values +are treated by that input style. +.LP +The following keys apply to these tables. +.TS H +lw(1i) lw(4.75i). +_ +.sp 6p +.B +Key Explanation +.sp 6p +_ +.TH +.R +C T{ +This value must be set with +.PN XCreateIC . +T} +D T{ +This value may be set using +.PN XCreateIC . +If it is not set, +a default is provided. +T} +G T{ +This value may be read using +.PN XGetICValues . +T} +GN T{ +This value may cause geometry negotiation when its value is set by means of +.PN XCreateIC +or +.PN XSetICValues . +T} +GR T{ +This value will be the response of the input method when any +GN value is changed. +T} +GS T{ +This value will cause the geometry of the input method window to be set. +T} +O T{ +This value must be set once and only once. +It need not be set at create time. +T} +S T{ +This value may be set with +.PN XSetICValues . +T} +Ignored T{ +This value is ignored by the input method for the given input style. +T} +.sp 6p +_ +.TE +.LP +.TS H +c c c s s s s +l c c c c c c +c c c c c c c +l c c c c c c. +_ +.sp 6p +.B + Input Style +XIC Value Geometry Preedit Preedit Preedit Preedit Preedit + Management Callback Position Area Nothing None +.sp 6p +_ +.sp 6p +.TH +.R +Input Style C-G C-G C-G C-G C-G +Client Window O-G O-G O-G O-G Ignored +Focus Window GN D-S-G D-S-G D-S-G D-S-G Ignored +Resource Name Ignored D-S-G D-S-G D-S-G Ignored +Resource Class Ignored D-S-G D-S-G D-S-G Ignored +Geometry Callback Ignored Ignored D-S-G Ignored Ignored +Filter Events G G G G Ignored +Destroy Callback D-S-G D-S-G D-S-G D-S-G D-S-G +String Conversion Callback S-G S-G S-G S-G S-G +String Conversion D-S-G D-S-G D-S-G D-S-G D-S-G +Reset State D-S-G D-S-G D-S-G D-S-G Ignored +HotKey S-G S-G S-G S-G Ignored +HotKeyState D-S-G D-S-G D-S-G D-S-G Ignored +.sp 6p +\fBPreedit\fP +Area GS Ignored D-S-G D-S-G Ignored Ignored +Area Needed GN-GR Ignored Ignored S-G Ignored Ignored +Spot Location Ignored D-S-G Ignored Ignored Ignored +Colormap Ignored D-S-G D-S-G D-S-G Ignored +Foreground Ignored D-S-G D-S-G D-S-G Ignored +Background Ignored D-S-G D-S-G D-S-G Ignored +Background Pixmap Ignored D-S-G D-S-G D-S-G Ignored +Font Set GN Ignored D-S-G D-S-G D-S-G Ignored +Line Spacing GN Ignored D-S-G D-S-G D-S-G Ignored +Cursor Ignored D-S-G D-S-G D-S-G Ignored +Preedit State D-S-G D-S-G D-S-G D-S-G Ignored +Preedit State Notify Callback S-G S-G S-G S-G Ignored +Preedit Callbacks C-S-G Ignored Ignored Ignored Ignored +.sp 6p +_ +.TE +.LP +.TS H +c c c s s s +l c c c c c +c c c c c c +l c c c c c. +_ +.sp 6p +.B + Input Style +XIC Value Geometry Status Status Status Status + Management Callback Area Nothing None +.sp 6p +_ +.sp 6p +.TH +.R +Input Style C-G C-G C-G C-G +Client Window O-G O-G O-G Ignored +Focus Window GN D-S-G D-S-G D-S-G Ignored +Resource Name Ignored D-S-G D-S-G Ignored +Resource Class Ignored D-S-G D-S-G Ignored +Geometry Callback Ignored D-S-G Ignored Ignored +Filter Events G G G G +.sp 6p +\fBStatus\fP +Area GS Ignored D-S-G Ignored Ignored +Area Needed GN-GR Ignored S-G Ignored Ignored +Colormap Ignored D-S-G D-S-G Ignored +Foreground Ignored D-S-G D-S-G Ignored +Background Ignored D-S-G D-S-G Ignored +Background Pixmap Ignored D-S-G D-S-G Ignored +Font Set GN Ignored D-S-G D-S-G Ignored +Line Spacing GN Ignored D-S-G D-S-G Ignored +Cursor Ignored D-S-G D-S-G Ignored +Status Callbacks C-S-G Ignored Ignored Ignored +.sp 6p +_ +.TE +.NH 4 +Input Style +.XS +\*(SN Input Style +.XE +.LP +The +.PN XNInputStyle +argument specifies the input style to be used. +The value of this argument must be one of the values returned by the +.PN XGetIMValues +function with the +.PN XNQueryInputStyle +argument specified in the supported_styles list. +.LP +Note that this argument must be set at creation time +and cannot be changed. +.NH 4 +Client Window +.XS +\*(SN Client Window +.XE +.LP +.IN "XNClientWindow" "" "@DEF@" +The +.PN XNClientWindow +argument specifies to the input method the client window in +which the input method +can display data or create subwindows. +Geometry values for input method areas are given with respect to the client +window. +Dynamic change of client window is not supported. +This argument may be set only once and +should be set before any input is done using this input context. +If it is not set, +the input method may not operate correctly. +.LP +If an attempt is made to set this value a second time with +.PN XSetICValues , +the string +.PN XNClientWindow +will be returned by +.PN XSetICValues , +and the client window will not be changed. +.LP +If the client window is not a valid window ID on the display +attached to the input method, +a +.PN BadWindow +error can be generated when this value is used by the input method. +.NH 4 +Focus Window +.XS +\*(SN Focus Window +.XE +.LP +.IN "XNFocusWindow" "" "@DEF@" +The +.PN XNFocusWindow +argument specifies the focus window. +The primary purpose of the +.PN XNFocusWindow +is to identify the window that will receive the key event when input +is composed. +In addition, the input method may possibly affect the focus window +as follows: +.IP \(bu 5 +Select events on it +.IP \(bu 5 +Send events to it +.IP \(bu 5 +Modify its properties +.IP \(bu 5 +Grab the keyboard within that window +.LP +The associated value must be of type +.PN Window . +If the focus window is not a valid window ID on the display +attached to the input method, +a +.PN BadWindow +error can be generated when this value is used by the input method. +.LP +When this XIC value is left unspecified, +the input method will use the client window as the default focus window. +.NH 4 +Resource Name and Class +.XS +\*(SN Resource Name and Class +.XE +.LP +.IN "XNResourceName" "" "@DEF@" +.IN "XNResourceClass" "" "@DEF@" +The +.PN XNResourceName +and +.PN XNResourceClass +arguments are strings that specify the full name and class +used by the client to obtain resources for the client window. +These values should be used as prefixes for name and class +when looking up resources that may vary according to the input context. +If these values are not set, +the resources will not be fully specified. +.LP +It is not intended that values that can be set as XIC values be +set as resources. +.NH 4 +Geometry Callback +.XS +\*(SN Geometry Callback +.XE +.LP +.IN "XNGeometryCallback" "" "@DEF@" +The +.PN XNGeometryCallback +argument is a structure of type +.PN XIMCallback +(see section 13.5.6.13.12). +.LP +The +.PN XNGeometryCallback +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. +.NH 4 +Filter Events +.XS +\*(SN Filter Events +.XE +.LP +.IN "XNFilterEvents" "" "@DEF@" +The +.PN XNFilterEvents +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. +.LP +This argument is read-only, is set by the input method at create time, +and is never changed. +.LP +The type of this argument is +.PN unsigned +.PN long . +Setting this value will cause an error. +.NH 4 +Destroy Callback +.XS +\*(SN Destroy Callback +.XE +.LP +The +.PN XNDestroyCallback +argument is a pointer to a structure of type +.PN XIMCallback +(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 +.PN XDestroyIC +and +.PN XCloseIM . +.LP +.NH 4 +String Conversion Callback +.XS +\*(SN String Conversion Callback +.XE +.LP +The +.PN XNStringConversionCallback +argument is a structure of type +.PN XIMCallback +(see section 13.5.6.13.12). +.LP +The +.PN XNStringConversionCallback +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. +.LP +Because this XIC value is optional, a client should call +.PN XGetIMValues +with argument +.PN XNQueryICValuesList +before using this argument. +.LP +.NH 4 +String Conversion +.XS +\*(SN String Conversion +.XE +.LP +The +.PN XNStringConversion +argument is a structure of type +.PN XIMStringConversionText . +.LP +The +.PN XNStringConversion +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. +.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. +.LP +Because this XIC value is optional, a client should call +.PN XGetIMValues +with argument +.PN XNQueryICValuesList +before using this argument. +.LP +The +.PN XIMStringConversionText +structure is defined as follows: +.LP +.sM +.Ds 0 + +typedef struct _XIMStringConversionText { + unsigned short length; + XIMStringConversionFeedback *feedback; + Bool encoding_is_wchar; + union { + char *mbs; + wchar_t *wcs; + } string; +} XIMStringConversionText; + +typedef unsigned long XIMStringConversionFeedback; +.De +.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. +.LP +.NH 4 +Reset State +.XS +\*(SN Reset State +.XE +.LP +The +.PN XNResetState +argument specifies the state the input context will return to after calling +.PN XmbResetIC +or +.PN XwcResetIC . +.LP +The XIC state may be set to its initial state, as specified by the +.PN XNPreeditState +value when +.PN XCreateIC +was called, or it may be set to preserve the current state. +.LP +The valid masks for +.PN XIMResetState +are as follows: +.LP +.IN "XIMInitialState" "" "@DEF@" +.IN "XINPreserveState" "" "@DEF@" +.sM +.LP +.Ds 0 +typedef unsigned long XIMResetState; +.De +.TS +lw(.5i) lw(2i) lw(2i). +T{ +#define +T} T{ +.PN XIMInitialState +T} T{ +(1L) +T} +T{ +#define +T} T{ +.PN XIMPreserveState +T} T{ +(1L<<1) +T} +.TE +.LP +.eM +If +.PN XIMInitialState +is set, then +.PN XmbResetIC +and +.PN XwcResetIC +will return to the initial +.PN XNPreeditState +state of the XIC. +.LP +If +.PN XIMPreserveState +is set, then +.PN XmbResetIC +and +.PN XwcResetIC +will preserve the current state of the XIC. +.LP +If +.PN XNResetState +is left unspecified, the default is +.PN XIMInitialState . +.LP +.PN XIMResetState +values other than those specified above will default to +.PN XIMInitialState . +.LP +Because this XIC value is optional, a client should call +.PN XGetIMValues +with argument +.PN XNQueryICValuesList +before using this argument. +.LP +.NH 4 +Hot Keys +.XS +\*(SN Hot Keys +.XE +.LP +The +.PN XNHotKey +argument specifies the hot key list to the XIC. +The hot key list is a pointer to the structure of type +.PN XIMHotKeyTriggers , +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 +.PN XNHotKeyState +to +.PN XIMHotKeyStateON . +.LP +Because this XIC value is optional, a client should call +.PN XGetIMValues +with argument +.PN XNQueryICValuesList +before using this functionality. +.LP +The value of the argument is a pointer to a structure of type +.PN XIMHotKeyTriggers . +.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. +.LP +.sM +.Ds 0 +.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; +.De +.LP +.eM +.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. +.TS H +lw(1i) lw(1i) lw(3i). +_ +.sp 6p +.B +Modifier Bit Mask Bit Meaning +.sp 6p +_ +.sp 6p +.TH +.R +T{ +0 +T} T{ +1 +T} T{ +The modifier must be off. +T} +T{ +1 +T} T{ +1 +T} T{ +The modifier must be on. +T} +T{ +n/a +T} T{ +0 +T} T{ +Do not care if the modifier is on or off. +T} +.sp 6p +_ +.TE +.NH 4 +Hot Key State +.XS +\*(SN Hot Key State +.XE +.LP +The +.PN XNHotKeyState +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. +.LP +The value of the argument is a pointer to a structure of type +XIMHotKeyState . +.LP +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef unsigned long XIMHotKeyState; +.De +.TS +lw(.5i) lw(3i) lw(2i). +T{ +#define +T} T{ +.PN XIMHotKeyStateON +T} T{ +(0x0001L) +T} +T{ +#define +T} T{ +.PN XIMHotKeyStateOFF +T} T{ +(0x0002L) +T} +.TE +.LP +.eM +.LP +If not specified, the default is +.PN XIMHotKeyStateOFF . +.LP +.NH 4 +Preedit and Status Attributes +.XS +\*(SN Preedit and Status Attributes +.XE +.LP +.IN "XNPreeditAttributes" "" "@DEF@" +.IN "XNStatusAttributes" "" "@DEF@" +The +.PN XNPreeditAttributes +and +.PN XNStatusAttributes +arguments specify to an input method the attributes to be used for the +preedit and status areas, +if any. +Those attributes are passed to +.PN XSetICValues +or +.PN XGetICValues +as a nested variable-length list. +The names to be used in these lists are described in the following sections. +.NH 5 +Area +.XS +\*(SN Area +.XE +.LP +.IN "XNArea" "" "@DEF@" +The value of the +.PN XNArea +argument must be a pointer to a structure of type +.PN XRectangle. +The interpretation of the +.PN XNArea +argument is dependent on the input method style that has been set. +.LP +If the input method style is +.PN XIMPreeditPosition , +.PN XNArea +specifies the clipping region within which preediting will take place. +If the focus window has been set, +the coordinates are assumed to be relative to the focus window. +Otherwise, the coordinates are assumed to be relative to the client window. +If neither has been set, +the results are undefined. +.LP +If +.PN XNArea +is not specified, is set to NULL, or is invalid, +the input method will default the clipping region +to the geometry of the +.PN XNFocusWindow . +If the area specified is NULL or invalid, +the results are undefined. +.LP +If the input style is +.PN XIMPreeditArea +or +.PN XIMStatusArea , +.PN XNArea +specifies the geometry provided by the client to the input method. +The input method may use this area to display its data, +either preedit or status depending on the area designated. +The input method may create a window as a child of the client window +with dimensions that fit the +.PN XNArea . +The coordinates are relative to the client window. +If the client window has not been set yet, +the input method should save these values +and apply them when the client window is set. +If +.PN XNArea +is not specified, is set to NULL, or is invalid, +the results are undefined. +.NH 5 +Area Needed +.XS +\*(SN Area Needed +.XE +.LP +.IN "XNAreaNeeded" "" "@DEF@" +When set, the +.PN XNAreaNeeded +argument specifies the geometry suggested by the client for this area +(preedit or status). +The value associated with the argument must be a pointer to a +structure of type +.PN XRectangle . +Note that the x, y values are not used +and that nonzero values for width or height are the constraints +that the client wishes the input method to respect. +.LP +When read, the +.PN XNAreaNeeded +argument specifies the preferred geometry desired by the input method +for the area. +.LP +This argument is only valid if the input style is +.PN XIMPreeditArea +or +.PN XIMStatusArea . +It is used for geometry negotiation between the client and the input method +and has no other effect on the input method +(see section 13.5.1.5). +.NH 5 +Spot Location +.XS +\*(SN Spot Location +.XE +.LP +.IN "XNSpotLocation" "" "@DEF@" +The +.PN XNSpotLocation +argument specifies to the input method the coordinates of the spot +to be used by an input method executing with +.PN XNInputStyle +set to +.PN XIMPreeditPosition . +When specified to any input method other than +.PN XIMPreeditPosition , +this XIC value is ignored. +.LP +The x coordinate specifies the position where the next character +would be inserted. +The y coordinate is the position of the baseline used +by 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. +.LP +The value of the argument is a pointer to a structure of type +.PN XPoint . +.NH 5 +Colormap +.XS +\*(SN Colormap +.XE +.LP +Two different arguments can be used to indicate what colormap the input method +should use to allocate colors, a colormap ID, or a standard colormap name. +.LP +.IN "XNColormap" "" "@DEF@" +The +.PN XNColormap +argument is used to specify a colormap ID. +The argument value is of type +.PN Colormap . +An invalid argument may generate a +.PN BadColor +error when it is used by the input method. +.LP +.IN "XNStdColormap" "" "@DEF@" +The +.PN XNStdColormap +argument is used to indicate the name of the standard colormap +in which the input method should allocate colors. +The argument value is an +.PN Atom +that should be a valid atom for calling +.PN XGetRGBColormaps . +An invalid argument may generate a +.PN BadAtom +error when it is used by the input method. +.LP +If the colormap is left unspecified, +the client window colormap becomes the default. +.NH 5 +Foreground and Background +.XS +\*(SN Foreground and Background +.XE +.LP +.IN "XNForeground" "" "@DEF@" +.IN "XNBackground" "" "@DEF@" +The +.PN XNForeground +and +.PN XNBackground +arguments specify the foreground and background pixel, respectively. +The argument value is of type +.PN unsigned +.PN long . +It must be a valid pixel in the input method colormap. +.LP +If these values are left unspecified, +the default is determined by the input method. +.NH 5 +Background Pixmap +.XS +\*(SN Background Pixmap +.XE +.LP +The +.PN XNBackgroundPixmap +argument specifies a background pixmap to be used as the background of the +window. +The value must be of type +.PN Pixmap . +An invalid argument may generate a +.PN BadPixmap +error when it is used by the input method. +.LP +If this value is left unspecified, +the default is determined by the input method. +.NH 5 +Font Set +.XS +\*(SN Font Set +.XE +.LP +.IN "XNFontSet" "" "@DEF@" +The +.PN XNFontSet +argument specifies to the input method what font set is to be used. +The argument value is of type +.PN XFontSet . +.LP +If this value is left unspecified, +the default is determined by the input method. +.NH 5 +Line Spacing +.XS +\*(SN Line Spacing +.XE +.LP +The +.PN XNLineSpace +argument specifies to the input method what line spacing is to be used +in the preedit window if more than one line is to be used. +This argument is of type +.PN int . +.LP +If this value is left unspecified, +the default is determined by the input method. +.NH 5 +Cursor +.XS +\*(SN Cursor +.XE +.LP +.IN "XNCursor" "" "DEF@" +The +.PN XNCursor +argument specifies to the input method what cursor is to be used +in the specified window. +This argument is of type +.PN Cursor . +.LP +An invalid argument may generate a +.PN BadCursor +error when it is used by the input method. +If this value is left unspecified, +the default is determined by the input method. +.NH 5 +Preedit State +.XS +\*(SN Preedit State +.XE +.LP +The +.PN XNPreeditState +argument specifies the state of input preediting for the input method. +Input preediting can be on or off. +.LP +The valid mask names for +.PN XNPreeditState +are as follows: +.LP +.IN "XIMPreeditUnknown" "" "@DEV@" +.IN "XIMPreeditEnable" "" "@DEF@" +.IN "XIMPreeditDisable" "" "@DEV@" +.sM +.LP +.Ds 0 +typedef unsigned long XIMPreeditState; +.De +.TS +lw(.5i) lw(2i) lw(2i). +T{ +#define +T} T{ +.PN XIMPreeditUnknown +T} T{ +0L +T} +T{ +#define +T} T{ +.PN XIMPreeditEnable +T} T{ +1L +T} +T{ +#define +T} T{ +.PN XIMPreeditDisable +T} T{ +(1L<<1) +T} +.TE +.LP +.eM +If a value of +.PN XIMPreeditEnable +is set, then input preediting is turned on by the input method. +.LP +If a value of +.PN XIMPreeditDisable +is set, then input preediting is turned off by the input method. +.LP +If +.PN XNPreeditState +is left unspecified, then the state will be implementation-dependent. +.LP +When +.PN XNResetState +is set to +.PN XIMInitialState , +the +.PN XNPreeditState +value specified at the creation time will be reflected as the initial state for +.PN XmbResetIC +and +.PN XwcResetIC . +.LP +Because this XIC value is optional, a client should call +.PN XGetIMValues +with argument +.PN XNQueryICValuesList +before using this argument. +.NH 5 +Preedit State Notify Callback +.XS +\*(SN Preedit State Notify Callback +.XE +.LP +The preedit state notify callback is triggered by the input method +when the preediting state has changed. +The value of the +.PN XNPreeditStateNotifyCallback +argument is a pointer to a structure of type +.PN XIMCallback . +The generic prototype is as follows: +.IN "PreeditStateNotifyCallback" "" "@DEF@" +.sM +.FD 0 +void PreeditStateNotifyCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + XIC \fIic\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + XIMPreeditStateNotifyCallbackStruct *\fIcall_data\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Specifies the current preedit state. +.LP +.eM +The +.PN XIMPreeditStateNotifyCallbackStruct +structure is defined as follows: +.LP +.IN "XIMPreeditStateNotifyCallbackStruct" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct _XIMPreeditStateNotifyCallbackStruct { + XIMPreeditState state; +} XIMPreeditStateNotifyCallbackStruct; +.De +.LP +.eM +.LP +Because this XIC value is optional, a client should call +.PN XGetIMValues +with argument +.PN XNQueryICValuesList +before using this argument. +.NH 5 +Preedit and Status Callbacks +.XS +\*(SN Preedit and Status Callbacks +.XE +.LP +A client that wants to support the input style +.PN XIMPreeditCallbacks +must provide a set of preedit callbacks to the input method. +The set of preedit callbacks is as follows: +.IN "XNPreeditStartCallback" "" "@DEF@" +.IN "XNPreeditDoneCallback" "" "@DEF@" +.IN "XNPreeditDrawCallback" "" "@DEF@" +.IN "XNPreeditCaretCallback" "" "@DEF@" +.TS +lw(1.75i) lw(4i). +T{ +.PN XNPreeditStartCallback +T} T{ +This is called when the input method starts preedit. +T} +T{ +.PN XNPreeditDoneCallback +T} T{ +This is called when the input method stops preedit. +T} +T{ +.PN XNPreeditDrawCallback +T} T{ +This is called when a number of preedit keystrokes should be echoed. +T} +T{ +.PN XNPreeditCaretCallback +T} T{ +This is called to move the text insertion point within the preedit string. +T} +.TE +.LP +A client that wants to support the input style +.PN XIMStatusCallbacks +must provide a set of status callbacks to the input method. +The set of status callbacks is as follows: +.IN "XNStatusStartCallback" "" "@DEF@" +.IN "XNStatusDoneCallback" "" "@DEF@" +.IN "XNStatusDrawCallback" "" "@DEF@" +.TS +lw(1.75i) lw(4i). +T{ +.PN XNStatusStartCallback +T} T{ +This is called when the input method initializes the status area. +T} +T{ +.PN XNStatusDoneCallback +T} T{ +This is called when the input method no longer needs the status area. +T} +T{ +.PN XNStatusDrawCallback +T} T{ +This is called when updating of the status area is required. +T} +.TE +.LP +The value of any status or preedit argument is a pointer +to a structure of type +.PN XIMCallback . +.IN "XIMProc" "" "@DEF@" +.IN "XIMCallback" "" "@DEF@" +.sM +.LP +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef void (*XIMProc)(); + +typedef struct { + XPointer client_data; + XIMProc callback; +} XIMCallback; +.De +.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. +.LP +Setting any of these values while doing preedit +may cause unexpected results. +.NH 3 +Input Method Callback Semantics +.XS +\*(SN Input Method Callback Semantics +.XE +.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. +.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. +.LP +All callback procedures follow the generic prototype: +.IN "CallbackPrototype" "" "@DEF@" +.sM +.FD 0 +void CallbackPrototype\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + XIC \fIic\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + SomeType \fIcall_data\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Specifies data specific to the callback. +.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. +.LP +The following paragraphs describe the programming semantics +and specific data structure associated with the different reasons. +.NH 4 +Geometry Callback +.XS +\*(SN Geometry Callback +.XE +.LP +The geometry callback is triggered by the input method +to indicate that it wants the client to negotiate geometry. +The generic prototype is as follows: +.IN "GeometryCallback" "" "@DEF@" +.sM +.FD 0 +void GeometryCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + XIC \fIic\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + XPointer \fIcall_data\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Not used for this callback and always passed as NULL. +.LP +.eM +The callback is called with a NULL call_data argument. +.NH 4 +Destroy Callback +.XS +\*(SN Destroy Callback +.XE +.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 +.FD 0 +void DestroyCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + XIC \fIic\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + XPointer \fIcall_data\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Not used for this callback and always passed as NULL. +.LP +.eM +The callback is called with a NULL call_data argument. +.NH 4 +String Conversion Callback +.XS +\*(SN String Conversion Callback +.XE +.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 +.FD 0 +void StringConversionCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + XIC \fIic\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + XIMStringConversionCallbackStruct *\fIcall_data\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input method. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Specifies the amount of the string to be converted. +.LP +.eM +The callback is passed an +.PN XIMStringConversionCallbackStruct +structure in the call_data argument. +The text member is an +.PN XIMStringConversionText +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 +.PN XIMStringConversionText +structure will be freed using +.PN XFree +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. +.LP +The +.PN XIMStringConversionCallbackStruct +structure is defined as follows: +.LP +.IN "XIMStringConversionCallbackStruct" "" "@DEF@" +.sM +.LP +.Ds 0 +typedef struct _XIMStringConversionCallbackStruct { + XIMStringConversionPosition position; + XIMCaretDirection direction; + short factor; + XIMStringConversionOperation operation; + XIMStringConversionText *text; +} XIMStringConversionCallbackStruct; + +typedef short XIMStringConversionPosition; + +typedef unsigned short XIMStringConversionOperation; + +.De +.LP +.TS +lw(.5i) lw(3i) lw(2i). +T{ +#define +T} T{ +.PN XIMStringConversionSubstitution +T} T{ +(0x0001) +T} +T{ +#define +T} T{ +.PN XIMStringConversionRetrieval +T} T{ +(0x0002) +T} +.TE +.LP +.eM +.PN XIMStringConversionPosition +specifies the starting position of the string to be returned +in the +.PN XIMStringConversionText +structure. The value identifies a position, in units of characters, +relative to the client's cursor position in the client's buffer. +.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 +.PN XIMCaretDirection . +The factor member of +.PN XIMStringConversionCallbackStruct +specifies the number of +.PN XIMCaretDirection +positions to be applied. For example, if the direction specifies +.PN XIMLineEnd +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 +.PN XIMForwardChar +or +.PN XIMBackwardChar , +then the factor specifies a relative position, indicated in characters, +from the starting position. +.LP +.PN XIMStringConversionOperation +specifies whether the string to be converted should be +deleted (substitution) or copied (retrieval) from the client's +buffer. When the +.PN XIMStringConversionOperation +is +.PN XIMStringConversionSubstitution , +the client must delete the string to be converted from its own buffer. +When the +.PN XIMStringConversionOperation +is +.PN XIMStringConversionRetrieval , +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. +.NH 4 +Preedit State Callbacks +.XS +\*(SN Preedit State Callbacks +.XE +.LP +When the input method turns preediting on or off, a +.PN PreeditStartCallback +or +.PN PreeditDoneCallback +callback is triggered to let the toolkit do the setup +or the cleanup for the preedit region. +.IN "PreeditStartCallback" "" "@DEF@" +.sM +.FD 0 +int PreeditStartCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + XIC \fIic\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + XPointer \fIcall_data\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Not used for this callback and always passed as NULL. +.LP +.eM +When preedit starts on the specified input context, +the callback is called with a NULL call_data argument. +.PN PreeditStartCallback +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 +.FD 0 +void PreeditDoneCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + XIC \fIic\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + XPointer \fIcall_data\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Not used for this callback and always passed as NULL. +.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 +.PN PreeditStartCallback . +.LP +.PN PreeditStartCallback +should initialize appropriate data needed for +displaying preedit information and for handling further +.PN PreeditDrawCallback +calls. +Once +.PN PreeditStartCallback +is called, it will not be called again before +.PN PreeditDoneCallback +has been called. +.NH 4 +Preedit Draw Callback +.XS +\*(SN Preedit Draw Callback +.XE +.LP +This callback is triggered to draw and insert, delete or replace, +preedit text in the preedit region. +The preedit text may include unconverted input text such as Japanese Kana, +converted text such as Japanese Kanji characters, or characters of both kinds. +That string is either a multibyte or wide character string, +whose encoding matches the locale bound to the input context. +The callback prototype +is as follows: +.IN "PreeditDrawCallback" "" "@DEF@" +.sM +.FD 0 +void PreeditDrawCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + XIC \fIic\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + XIMPreeditDrawCallbackStruct *\fIcall_data\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Specifies the preedit drawing information. +.LP +.eM +The callback is passed an +.PN XIMPreeditDrawCallbackStruct +structure in the call_data argument. +The text member of this structure contains the text to be drawn. +After the string has been drawn, +the caret should be moved to the specified location. +.LP +The +.PN XIMPreeditDrawCallbackStruct +structure is defined as follows: +.LP +.IN "XIMPreeditDrawCallbackStruct" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct _XIMPreeditDrawCallbackStruct { + int caret; /* Cursor offset within preedit string */ + int chg_first; /* Starting change position */ + int chg_length; /* Length of the change in character count */ + XIMText *text; +} XIMPreeditDrawCallbackStruct; +.De +.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: +.IP \(bu 5 +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. +.IP \(bu 5 +When text is non-NULL, +it indicates insertion or replacement of text in the buffer. +.IP +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 +.PN XIMText +structure. +.IP +A chg_length value of zero indicates that text must be inserted +right at the position specified by chg_first. +A value of zero for chg_first specifies the first character in the buffer. +.IP +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 +.PN XIMText +structure. For example, suppose the preedit buffer contains the string "ABCDE". +.IP +.DS I +.ft C +Text: A B C D E + ^ ^ ^ ^ ^ ^ +CharPos: 0 1 2 3 4 5 +.sp +.ft P +.DE +The CharPos in the diagram shows the location of the character position +relative to the character. +.IP +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 +.PN XIMText +structure. +Hence, BCD would be replaced by the value in the structure. +.IP +Though chg_length and chg_first are both signed integers they will +never have a negative value. +.IP \(bu 5 +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. +.LP +.IN "XIMText" "" @DEF@" +.sM +.Ds +.TA .5i 1.5i 3i +typedef struct _XIMText { + unsigned short length; + XIMFeedback * feedback; + Bool encoding_is_wchar; + union { + char * multi_byte; + wchar_t * wide_char; + } string; +} XIMText; +.De +.LP +.eM +The text string passed is actually a structure specifying as follows: +.IP \(bu 5 +The length member is the text length in characters. +.IP \(bu 5 +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. +.IP \(bu 5 +The string member is the text string. +.IP \(bu 5 +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. +.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. +.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 +.PN XIMVisibleToForward , +.PN XIMVisibleToBackward , +and +.PN XIMVisibleCenter +masks are exclusively used for these visibility hints. +The +.PN XIMVisibleToForward +mask +indicates that the preedit text is preferably displayed in the +primary draw direction from the +caret position in the preedit area forward. +The +.PN XIMVisibleToBackward +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 +.PN XIMVisibleCenter +mask +indicates that the preedit text is preferably displayed with +the caret position in the preedit area centered. +.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 +.PN XIMReverse ). +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. +.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. +.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 +.PN XIMText +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 +.PN XIMFeedback . +.LP +Each element in the feedback array is a bitmask represented by a value of type +.PN XIMFeedback . +The valid mask names are as follows: +.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 +.LP +.Ds 0 +typedef unsigned long XIMFeedback; +.De +.TS +lw(.5i) lw(2i) lw(2i). +T{ +#define +T} T{ +.PN XIMReverse +T} T{ +1L +T} +T{ +#define +T} T{ +.PN XIMUnderline +T} T{ +(1L<<1) +T} +T{ +#define +T} T{ +.PN XIMHighlight +T} T{ +(1L<<2) +T} +T{ +#define +T} T{ +.PN XIMPrimary +T} T{ +(1L<<5)\(dg +T} +T{ +#define +T} T{ +.PN XIMSecondary +T} T{ +(1L<<6)\(dg +T} +T{ +#define +T} T{ +.PN XIMTertiary +T} T{ +(1L<<7)\(dg +T} +T{ +#define +T} T{ +.PN XIMVisibleToForward +T} T{ +(1L<<8) +T} +T{ +#define +T} T{ +.PN XIMVisibleToBackward +T} T{ +(1L<<9) +T} +T{ +#define +T} T{ +.PN XIMVisibleCenter +T} T{ +(1L<<10) +T} +.TE +.LP +.eM +.LP +Characters drawn with the +.PN XIMReverse +highlight should be drawn by swapping the foreground and background colors +used to draw normal, unhighlighted characters. +Characters drawn with the +.PN XIMUnderline +highlight should be underlined. +Characters drawn with the +.PN XIMHighlight , +.PN XIMPrimary , +.PN XIMSecondary , +and +.PN XIMTertiary +highlights should be drawn in some unique manner that must be different +from +.PN XIMReverse +and +.PN XIMUnderline . +.FS \(dg +The values for +.PN XIMPrimary , +.PN XIMSecondary , +and +.PN XIMTertiary +were incorrectly defined in the R5 specification. +The X Consortium's X11R5 +implementation correctly implemented the values for these highlights. +The value of these highlights has been corrected in this specification +to agree with the values in the Consortium's X11R5 and X11R6 implementations. +.FE +.NH 4 +Preedit Caret Callback +.XS +\*(SN Preedit Caret Callback +.XE +.LP +An input method may have its own navigation keys to allow the user +to move the text insertion point in the preedit area +(for example, to move backward or forward). +Consequently, input method needs to indicate to the client that it +should move the text insertion point. +It then calls the PreeditCaretCallback. +.IN "PreeditCaretCallback" "" "@DEF@" +.sM +.FD 0 +void PreeditCaretCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + XIC \fIic\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + XIMPreeditCaretCallbackStruct *\fIcall_data\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Specifies the preedit caret information. +.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 +.PN XIMPreeditCaretCallbackStruct +structure, +which indicates where the caret should be moved. +The callback must move the insertion point to its new location +and return, in field position, the new offset value from the initial position. +.LP +The +.PN XIMPreeditCaretCallbackStruct +structure is defined as follows: +.IN "XIMPreeditCaretCallbackStruct" "" "@DEF@" +.LP +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef struct _XIMPreeditCaretCallbackStruct { + int position; /* Caret offset within preedit string */ + XIMCaretDirection direction; /* Caret moves direction */ + XIMCaretStyle style; /* Feedback of the caret */ +} XIMPreeditCaretCallbackStruct; +.De +.LP +.eM +The +.PN XIMCaretStyle +structure is defined as follows: +.LP +.IN "XIMCaretStyle" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef enum { + XIMIsInvisible, /* Disable caret feedback */ + XIMIsPrimary, /* UI defined caret feedback */ + XIMIsSecondary, /* UI defined caret feedback */ +} XIMCaretStyle; +.De +.LP +.eM +The +.PN XIMCaretDirection +structure is defined as follows: +.IN "XIMCaretDirection" "" "@DEF@" +.LP +.sM +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef enum { + XIMForwardChar, XIMBackwardChar, + XIMForwardWord, XIMBackwardWord, + XIMCaretUp, XIMCaretDown, + XIMNextLine, XIMPreviousLine, + XIMLineStart, XIMLineEnd, + XIMAbsolutePosition, + XIMDontChange, + } XIMCaretDirection; +.De +.LP +.eM +These values are defined as follows: +.IN "XIMForwardChar" "" "@DEF@" +.IN "XIMBackwardChar" "" "@DEF@" +.IN "XIMForwardWord" "" "@DEF@" +.IN "XIMBackwardWord" "" "@DEF@" +.IN "XIMCaretUp" "" "@DEF@" +.IN "XIMCaretDown" "" "@DEF@" +.TS +lw(1.5i) lw(4.25i). +T{ +.PN XIMForwardChar +T} T{ +Move the caret forward one character position. +T} +T{ +.PN XIMBackwardChar +T} T{ +Move the caret backward one character position. +T} +T{ +.PN XIMForwardWord +T} T{ +Move the caret forward one word. +T} +T{ +.PN XIMBackwardWord +T} T{ +Move the caret backward one word. +T} +T{ +.PN XIMCaretUp +T} T{ +Move the caret up one line keeping the current horizontal offset. +T} +T{ +.PN XIMCaretDown +T} T{ +Move the caret down one line keeping the current horizontal offset. +T} +T{ +.PN XIMPreviousLine +T} T{ +Move the caret to the beginning of the previous line. +T} +T{ +.PN XIMNextLine +T} T{ +Move the caret to the beginning of the next line. +T} +T{ +.PN XIMLineStart +T} T{ +Move the caret to the beginning of the current display line +that contains the caret. +T} +T{ +.PN XIMLineEnd +T} T{ +Move the caret to the end of the current display line +that contains the caret. +T} +T{ +.PN XIMAbsolutePosition +T} T{ +The callback must move to the location specified by the position field +of the callback data, indicated in characters, starting from the beginning +of the preedit text. +Hence, a value of zero means move back to the beginning of the preedit text. +T} +T{ +.PN XIMDontChange +T} T{ +The caret position does not change. +T} +.TE +.IN "XIMNextLine" "" "@DEF@" +.IN "XIMPreviousLine" "" "@DEF@" +.IN "XIMLineStart" "" "@DEF@" +.IN "XIMLineEnd" "" "@DEF@" +.IN "XIMAbsolutePosition" "" "@DEF@" +.IN "XIMDontChange" "" "@DEF@" +.NH 4 +Status Callbacks +.XS +\*(SN Status Callbacks +.XE +.LP +An input method may communicate changes in the status of an input context +(for example, created, destroyed, or focus changes) with three status +callbacks: StatusStartCallback, StatusDoneCallback, and StatusDrawCallback. +.LP +.sp +When the input context is created or gains focus, +the input method calls the StatusStartCallback callback. +.IN "StatusStartCallback" "" "@DEF@" +.sM +.FD 0 +void StatusStartCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + XIC \fIic\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + XPointer \fIcall_data\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Not used for this callback and always passed as NULL. +.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. +.LP +.sp +When an input context +is destroyed or when it loses focus, the input method calls StatusDoneCallback. +.IN "StatusDoneCallback" "" "@DEF@" +.sM +.FD 0 +void StatusDoneCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + XIC \fIic\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + XPointer \fIcall_data\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Not used for this callback and always passed as NULL. +.LP +.eM +The callback may release any data allocated on +.PN StatusStart . +.LP +.sp +When an input context status has to be updated, the input method calls +StatusDrawCallback. +.IN "StatusDrawCallback" "" "@DEF@" +.sM +.FD 0 +void StatusDrawCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^) +.br + XIC \fIic\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + XIMStatusDrawCallbackStruct *\fIcall_data\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.IP \fIcall_data\fP 1i +Specifies the status drawing information. +.LP +.eM +The callback should update the status area by either drawing a string +or imaging a bitmap in the status area. +.LP +The +.PN XIMStatusDataType +and +.PN XIMStatusDrawCallbackStruct +structures are defined as follows: +.IN "XIMStatusDataType" "" "@DEF@" +.IN "XIMStatusDrawCallbackStruct" "" "@DEF@" +.LP +.sM +.Ds 0 +.TA .5i 1i 3i +.ta .5i 1i 3i +typedef enum { + XIMTextType, + XIMBitmapType, +} XIMStatusDataType; + +typedef struct _XIMStatusDrawCallbackStruct { + XIMStatusDataType type; + union { + XIMText *text; + Pixmap bitmap; + } data; +} XIMStatusDrawCallbackStruct; +.De +.LP +.eM +.LP +The feedback styles +.PN XIMVisibleToForward , +.PN XIMVisibleToBackward , +and +.PN XIMVisibleToCenter +are not relevant and will not appear in the +.PN XIMFeedback +element of the +.PN XIMText +structure. +.LP +.NH 3 +Event Filtering +.XS +\*(SN Event Filtering +.XE +.LP +Xlib provides the ability for an input method +to register a filter internal to Xlib. +This filter is called by a client (or toolkit) by calling +.PN XFilterEvent +after calling +.PN XNextEvent . +Any client that uses the +.PN XIM +interface should call +.PN XFilterEvent +to allow input methods to process their events without knowledge +of the client's dispatching mechanism. +A client's user interface policy may determine the priority +of event filters with respect to other event-handling mechanisms +(for example, modal grabs). +.LP +Clients may not know how many filters there are, if any, +and what they do. +They may only know if an event has been filtered on return of +.PN XFilterEvent . +Clients should discard filtered events. +.sp +.LP +To filter an event, use +.PN XFilterEvent . +.IN "XFilterEvent" "" "@DEF@" +.sM +.FD 0 +Bool XFilterEvent\^(\^\fIevent\fP\^, \fIw\fP\^) +.br + XEvent *\fIevent\fP\^; +.br + Window \fIw\fP\^; +.FN +.ds Ev event to filter +.IP \fIevent\fP 1i +Specifies the \*(Ev. +.ds Wi for which the filter is to be applied +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.LP +.eM +If the window argument is +.PN None , +.PN XFilterEvent +applies the filter to the window specified in the +.PN XEvent +structure. +The window argument is provided so that layers above Xlib +that do event redirection can indicate to which window an event +has been redirected. +.LP +If +.PN XFilterEvent +returns +.PN True , +then some input method has filtered the event, +and the client should discard the event. +If +.PN XFilterEvent +returns +.PN False , +then the client should continue processing the event. +.LP +If a grab has occurred in the client and +.PN XFilterEvent +returns +.PN True , +the client should ungrab the keyboard. +.NH 3 +Getting Keyboard Input +.XS +\*(SN Getting Keyboard Input +.XE +.LP +To get composed input from an input method, +use +.PN XmbLookupString +or +.PN XwcLookupString . +.IN "XmbLookupString" "" "@DEF@" +.IN "XwcLookupString" "" "@DEF@" +.sM +.FD 0 +int XmbLookupString\^(\^\fIic\fP\^, \fIevent\fP\^, \fIbuffer_return\fP\^, \fIbytes_buffer\fP\^, \fIkeysym_return\fP\^, \fIstatus_return\fP\^) +.br + XIC \fIic\fP\^; +.br + XKeyPressedEvent *\fIevent\fP; +.br + char *\fIbuffer_return\fP\^; +.br + int \fIbytes_buffer\fP\^; +.br + KeySym *\fIkeysym_return\fP\^; +.br + Status *\fIstatus_return\fP\^; +.FN +.FD 0 +int XwcLookupString\^(\^\fIic\fP\^, \fIevent\fP\^, \fIbuffer_return\fP\^, \fIbytes_buffer\fP\^, \fIkeysym_return\fP\^, \fIstatus_return\fP\^) +.br + XIC \fIic\fP\^; +.br + XKeyPressedEvent *\fIevent\fP\^; +.br + wchar_t *\fIbuffer_return\fP\^; +.br + int \fIwchars_buffer\fP\^; +.br + KeySym *\fIkeysym_return\fP\^; +.br + Status *\fIstatus_return\fP\^; +.FN +.IP \fIic\fP 1i +Specifies the input context. +.ds Ev key event to be used +.IP \fIevent\fP 1i +Specifies the \*(Ev. +.IP \fIbuffer_return\fP 1i +Returns a multibyte string or wide character string (if any) +from the input method. +.IP \fIbytes_buffer\fP 1i +.br +.ns +.IP \fIwchars_buffer\fP 1i +Specifies space available in the return buffer. +.IP \fIkeysym_return\fP 1i +Returns the KeySym computed from the event if this argument is not NULL. +.IP \fIstatus_return\fP 1i +Returns a value indicating what kind of data is returned. +.LP +.eM +The +.PN XmbLookupString +and +.PN XwcLookupString +functions return the string from the input method specified +in the buffer_return argument. +If no string is returned, +the buffer_return argument is unchanged. +.LP +The KeySym into which the KeyCode from the event was mapped is returned +in the keysym_return argument if it is non-NULL and the status_return +argument indicates that a KeySym was returned. +If both a string and a KeySym are returned, +the KeySym value does not necessarily correspond to the string returned. +.LP +.PN XmbLookupString +returns the length of the string in bytes, and +.PN XwcLookupString +returns the length of the string in characters. +Both +.PN XmbLookupString +and +.PN XwcLookupString +return text in the encoding of the locale bound to the input method +of the specified input context. +.LP +Each string returned by +.PN XmbLookupString +and +.PN XwcLookupString +begins in the initial state of the encoding of the locale +(if the encoding of the locale is state-dependent). +.NT +To insure proper input processing, +it is essential that the client pass only +.PN KeyPress +events to +.PN XmbLookupString +and +.PN XwcLookupString . +Their behavior when a client passes a +.PN KeyRelease +event is undefined. +.NE +.LP +Clients should check the status_return argument before +using the other returned values. +These two functions both return a value to status_return +that indicates what has been returned in the other arguments. +The possible values returned are: +.TS +lw(1.5i) lw(4.3i). +T{ +.PN XBufferOverflow +T} T{ +The input string to be returned is too large for the supplied buffer_return. +The required size +.Pn ( XmbLookupString +in bytes; +.PN XwcLookupString +in characters) is returned as the value of the function, +and the contents of buffer_return and keysym_return are not modified. +The client should recall the function with the same event +and a buffer of adequate size to obtain the string. +T} +T{ +.PN XLookupNone +T} T{ +No consistent input has been composed so far. +The contents of buffer_return and keysym_return are not modified, +and the function returns zero. +T} +T{ +.PN XLookupChars +T} T{ +Some input characters have been composed. +They are placed in the buffer_return argument, +and the string length is returned as the value of the function. +The string is encoded in the locale bound to the input context. +The content of the keysym_return argument is not modified. +T} +T{ +.PN XLookupKeySym +T} T{ +A KeySym has been returned instead of a string +and is returned in keysym_return. +The content of the buffer_return argument is not modified, +and the function returns zero. +T} +T{ +.PN XLookupBoth +T} T{ +Both a KeySym and a string are returned; +.PN XLookupChars +and +.PN XLookupKeySym +occur simultaneously. +T} +.TE +.LP +It does not make any difference if the input context passed as an argument to +.PN XmbLookupString +and +.PN XwcLookupString +is the one currently in possession of the focus or not. +Input may have been composed within an input context before it lost the focus, +and that input may be returned on subsequent calls to +.PN XmbLookupString +or +.PN XwcLookupString +even though it does not have any more keyboard focus. +.NH 3 +Input Method Conventions +.XS +\*(SN Input Method Conventions +.XE +.LP +The input method architecture is transparent to the client. +However, clients should respect a number of conventions in order +to work properly. +Clients must also be aware of possible effects of synchronization +between input method and library in the case of a remote input server. +.NH 4 +Client Conventions +.XS +\*(SN Client Conventions +.XE +.LP +A well-behaved client (or toolkit) should first query the input method style. +If the client cannot satisfy the requirements of the supported styles +(in terms of geometry management or callbacks), +it should negotiate with the user continuation of the program +or raise an exception or error of some sort. +.NH 4 +Synchronization Conventions +.XS +\*(SN Synchronization Conventions +.XE +.LP +A +.PN KeyPress +event with a KeyCode of zero is used exclusively as a +signal that an input method has composed input that can be returned by +.PN XmbLookupString +or +.PN XwcLookupString . +No other use is made of a +.PN KeyPress +event with KeyCode of zero. +.LP +Such an event may be generated by either a front-end +or a back-end input method in an implementation-dependent manner. +Some possible ways to generate this event include: +.IP \(bu 5 +A synthetic event sent by an input method server +.IP \(bu 5 +An artificial event created by a input method filter and pushed +onto a client's event queue +.IP \(bu 5 +A +.PN KeyPress +event whose KeyCode value is modified by an input method filter +.LP +When callback support is specified by 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). +.NH 2 +String Constants +.XS +\*(SN String Constants +.XE +.LP +The following symbols for string constants are defined in +.hN X11/Xlib.h . +Although they are shown here with particular macro definitions, +they may be implemented as macros, as global symbols, or as a +mixture of the two. The string pointer value itself +is not significant; clients must not assume that inequality of two +values implies inequality of the actual string data. +.IN "XNVaNestedList" "" "@DEF@" +.IN "XNSeparatorofNestedList "" "@DEF@" +.IN "XNQueryInputStyle" "" "@DEF@" +.IN "XNClientWindow" "" "@DEF@" +.IN "XNInputStyle" "" "@DEF@" +.IN "XNFocusWindow" "" "@DEF@" +.IN "XNResourceName" "" "@DEF@" +.IN "XNResourceClass" "" "@DEF@" +.IN "XNGeometryCallback" "" "@DEF@" +.IN "XNDestroyCallback" "" "@DEF@" +.IN "XNFilterEvents" "" "@DEF@" +.IN "XNPreeditStartCallback" "" "@DEF@" +.IN "XNPreeditDoneCallback" "" "@DEF@" +.IN "XNPreeditDrawCallback" "" "@DEF@" +.IN "XNPreeditCaretCallback" "" "@DEF@" +.IN "XNPreeditStateNotifyCallback" "" "@DEF@" +.IN "XNPreeditAttributes" "" "@DEF@" +.IN "XNStatusStartCallback" "" "@DEF@" +.IN "XNStatusDoneCallback" "" "@DEF@" +.IN "XNStatusDrawCallback" "" "@DEF@" +.IN "XNStatusAttributes" "" "@DEF@" +.IN "XNArea" "" "@DEF@" +.IN "XNAreaNeeded" "" "@DEF@" +.IN "XNSpotLocation" "" "@DEF@" +.IN "XNColormap" "" "@DEF@" +.IN "XNStdColormap" "" "@DEF@" +.IN "XNForeground" "" "@DEF@" +.IN "XNBackground" "" "@DEF@" +.IN "XNBackgroundPixmap" "" "@DEF@" +.IN "XNFontSet" "" "@DEF@" +.IN "XNLineSpace" "" "@DEF@" +.IN "XNCursor" "" "@DEF@" +.TS +lw(.5i) lw(2.75i) lw(2.5i). +T{ +#define +T} T{ +.PN XNVaNestedList +T} T{ +"XNVaNestedList" +T} +T{ +#define +T} T{ +.PN XNSeparatorofNestedList +T} T{ +"separatorofNestedList" +T} +T{ +#define +T} T{ +.PN XNQueryInputStyle +T} T{ +"queryInputStyle" +T} +T{ +#define +T} T{ +.PN XNClientWindow +T} T{ +"clientWindow" +T} +T{ +#define +T} T{ +.PN XNInputStyle +T} T{ +"inputStyle" +T} +T{ +#define +T} T{ +.PN XNFocusWindow +T} T{ +"focusWindow" +T} +T{ +#define +T} T{ +.PN XNResourceName +T} T{ +"resourceName" +T} +T{ +#define +T} T{ +.PN XNResourceClass +T} T{ +"resourceClass" +T} +T{ +#define +T} T{ +.PN XNGeometryCallback +T} T{ +"geometryCallback" +T} +T{ +#define +T} T{ +.PN XNDestroyCallback +T} T{ +"destroyCallback" +T} +T{ +#define +T} T{ +.PN XNFilterEvents +T} T{ +"filterEvents" +T} +T{ +#define +T} T{ +.PN XNPreeditStartCallback +T} T{ +"preeditStartCallback" +T} +T{ +#define +T} T{ +.PN XNPreeditDoneCallback +T} T{ +"preeditDoneCallback" +T} +T{ +#define +T} T{ +.PN XNPreeditDrawCallback +T} T{ +"preeditDrawCallback" +T} +T{ +#define +T} T{ +.PN XNPreeditCaretCallback +T} T{ +"preeditCaretCallback" +T} +T{ +#define +T} T{ +.PN XNPreeditStateNotifyCallback +T} T{ +"preeditStateNotifyCallback" +T} +T{ +#define +T} T{ +.PN XNPreeditAttributes +T} T{ +"preeditAttributes" +T} +.TE +.sp -1 +.TS +lw(.5i) lw(2.75i) lw(2.5i). +T{ +#define +T} T{ +.PN XNStatusStartCallback +T} T{ +"statusStartCallback" +T} +T{ +#define +T} T{ +.PN XNStatusDoneCallback +T} T{ +"statusDoneCallback" +T} +T{ +#define +T} T{ +.PN XNStatusDrawCallback +T} T{ +"statusDrawCallback" +T} +T{ +#define +T} T{ +.PN XNStatusAttributes +T} T{ +"statusAttributes" +T} +T{ +#define +T} T{ +.PN XNArea +T} T{ +"area" +T} +T{ +#define +T} T{ +.PN XNAreaNeeded +T} T{ +"areaNeeded" +T} +T{ +#define +T} T{ +.PN XNSpotLocation +T} T{ +"spotLocation" +T} +T{ +#define +T} T{ +.PN XNColormap +T} T{ +"colorMap" +T} +T{ +#define +T} T{ +.PN XNStdColormap +T} T{ +"stdColorMap" +T} +T{ +#define +T} T{ +.PN XNForeground +T} T{ +"foreground" +T} +T{ +#define +T} T{ +.PN XNBackground +T} T{ +"background" +T} +T{ +#define +T} T{ +.PN XNBackgroundPixmap +T} T{ +"backgroundPixmap" +T} +T{ +#define +T} T{ +.PN XNFontSet +T} T{ +"fontSet" +T} +T{ +#define +T} T{ +.PN XNLineSpace +T} T{ +"lineSpace" +T} +T{ +#define +T} T{ +.PN XNCursor +T} T{ +"cursor" +T} +.TE +.sp -1 +.TS +lw(.5i) lw(2.75i) lw(2.5i). +T{ +#define +T} T{ +.PN XNQueryIMValuesList +T} T{ +"queryIMValuesList" +T} +T{ +#define +T} T{ +.PN XNQueryICValuesList +T} T{ +"queryICValuesList" +T} +T{ +#define +T} T{ +.PN XNStringConversionCallback +T} T{ +"stringConversionCallback" +T} +T{ +#define +T} T{ +.PN XNStringConversion +T} T{ +"stringConversion" +T} +T{ +#define +T} T{ +.PN XNResetState +T} T{ +"resetState" +T} +T{ +#define +T} T{ +.PN XNHotKey +T} T{ +"hotkey" +T} +T{ +#define +T} T{ +.PN XNHotKeyState +T} T{ +"hotkeyState" +T} +T{ +#define +T} T{ +.PN XNPreeditState +T} T{ +"preeditState" +T} +T{ +#define +T} T{ +.PN XNVisiblePosition +T} T{ +"visiblePosition" +T} +T{ +#define +T} T{ +.PN XNR6PreeditCallbackBehavior +T} T{ +"r6PreeditCallback" +T} +.TE +.sp -1 +.IN "XNQueryIMValuesList" "" "@DEF@" +.IN "XNQueryICValuesList" "" "@DEF@" +.IN "XNStringConversionCallback" "" "@DEF@" +.IN "XNStringConversion" "" "@DEF@" +.IN "XNResetState" "" "@DEF@" +.IN "XNHotKey" "" "@DEF@" +.IN "XNHotKeyState" "" "@DEF@" +.IN "XNPreeditState" "" "@DEF@" +.IN "XNVisiblePosition" "" "@DEF@" +.IN "XNR6PreeditCallbackBehavior" "" "@DEF@" +.TS +lw(.5i) lw(2.75i) lw(2.5i). +T{ +#define +T} T{ +.PN XNRequiredCharSet +T} T{ +"requiredCharSet" +T} +T{ +#define +T} T{ +.PN XNQueryOrientation +T} T{ +"queryOrientation" +T} +T{ +#define +T} T{ +.PN XNDirectionalDependentDrawing +T} T{ +"directionalDependentDrawing" +T} +T{ +#define +T} T{ +.PN XNContextualDrawing +T} T{ +"contextualDrawing" +T} +T{ +#define +T} T{ +.PN XNBaseFontName +T} T{ +"baseFontName" +T} +T{ +#define +T} T{ +.PN XNMissingCharSet +T} T{ +"missingCharSet" +T} +T{ +#define +T} T{ +.PN XNDefaultString +T} T{ +"defaultString" +T} +T{ +#define +T} T{ +.PN XNOrientation +T} T{ +"orientation" +T} +T{ +#define +T} T{ +.PN XNFontInfo +T} T{ +"fontInfo" +T} +T{ +#define +T} T{ +.PN XNOMAutomatic +T} T{ +"omAutomatic" +T} +.TE +.IN "XNRequiredCharSet" "" "@DEF@" +.IN "XNQueryOrientation" "" "@DEF@" +.IN "XNDirectionalDependentDrawing" "" "@DEF@" +.IN "XNContextualDrawing" "" "@DEF@" +.IN "XNBaseFontName" "" "@DEF@" +.IN "XNMissingCharSet" "" "@DEF@" +.IN "XNDefaultString" "" "@DEF@" +.IN "XNOrientation" "" "@DEF@" +.IN "XNFontInfo" "" "@DEF@" +.IN "XNOMAutomatic" "" "@DEF@" +.bp |