diff options
Diffstat (limited to 'specs/libX11/CH13')
| -rw-r--r-- | specs/libX11/CH13 | 7673 |
1 files changed, 0 insertions, 7673 deletions
diff --git a/specs/libX11/CH13 b/specs/libX11/CH13 deleted file mode 100644 index ed143c69..00000000 --- a/specs/libX11/CH13 +++ /dev/null @@ -1,7673 +0,0 @@ -.\" 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 |