7674 lines
194 KiB
Plaintext
7674 lines
194 KiB
Plaintext
.\" 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
|