X Window System, Version 11
Input Method Specifications
Public Review Draft - November 1990
(Send comments to i18n@expo.lcs.mit.edu)
Vania Joloboff
Open Software Foundation
Bill McMahon
Hewlett Packard Company
ABSTRACT
This chapter addresses the portability and interoperability of
programs in different countries. It describes specifications pro-
viding to clients of the X Window System Version 11, an interface
for input handling of characters in various languages. The
specifications make it possible to develop portable applications
independent of a particular language or a particular encoding of
characters. The specifications are consistent with related
specifications from X/Open Portability Guide, Release 3, and
ANSI-C. The reader is assumed to be familiar with those, particu-
larly with the notion of locale in the C language, therefore they
will not be detailed here.
Copyright c 1990 by the Massachusetts Institute of Technology.
Permission to use, copy, modify, and distribute this documentation for any pur-
pose and without fee is hereby granted, provided that the above copyright
notice and this permission notice appear in all copies. MIT makes no represen-
tations about the suitability for any purpose of the information in this docu-
ment. It is provided "as is" without express or implied warranty. This docu-
ment is only a draft standard of the MIT X Consortium and is therefore subject
to change.
1
XIM Public Review Draft
X Window System is a trademark of the Massachusetts Institute of Technology.
2
XIM Public Review Draft
1. Input Method Overview
The next paragraphs provide definitions for terms and concepts used in the
specification, and a brief overview of the intended use of the abstractions
developed for Xlib internationalization.
1.1. What are Input Methods ?
A large number of languages in the world rely on an alphabet, a small set of
symbols (letters) used to form words. To enter text into a computer in an
alphabetic language a user usually has a keyboard on which there exists 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 a English-based keyboard. They
need to hit a combination of keystrokes in order to enter a character that does
not exist directly on the keyboard. A number of algorithms have been developed
for entering such characters, known as European input methods, or compose input
method, or dead-keys input method.
In some alphabetic languages, the rendering of characters strings is context
sensitive. When entering characters in those languages, a keystroke does not
systematically mean appending a new symbol at the end of the string. It may
modify the existing strings. Both input and output methods may be used in such
languages.
With an ideographic writing 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 may
be very large: 150 000 have been identified in Hanzi, the Chinese ideographic
system.
There are two major aspects of ideographics system for their computer usage.
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, which make 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 specific
mechanism is required for entering characters so that a keyboard with a reason-
able number of keys can be used. Those input methods are usually based on the
language's phonetics, but there also exist methods based on the graphics pro-
perties of characters.
In addition to the ideographic characters, a number of languages often also
include a phonetic (alphabetic-based) writing system. The phonetic signs are
then engraved on the keyboard and the keystrokes are transformed to their
appropriate ideographic counterparts. Here's a brief description of the
Japanese and Korean phonetic systems:
o Japanese: There are two phonetic symbol sets: katakana and hiragana. In gen-
eral, you use katakana for words that are of foreign origin, and hiragana
for writing native Japanese words. Collectively, the two systems are called
kana. Each set consists of approximately 50 characters. You type either
kana or English characters and define the region that you want to convert to
3
XIM Public Review Draft
kanji. Several kanji characters may have the same phonetic representation.
If that's the case with your string, you get a menu of characters and choose
the appropriate one. If no choice is necessary, the input method does the
substitution directly. When Latin characters are converted to kana or Kanji,
it is called a romaji conversion.
o Korean: Hangul is a writing system that actually straddles the line between
phonetic and ideographic. It's phonetic in the sense that each of the
roughly 25 characters represents a specific sound. But between two and five
of the characters are combined to form syllables, and these syllables are
the basic units on which text processing is done. For example, a delete
operation works on a syllable rather than the individual characters within
it. And Korean code sets include several thousands of these syllables. You
type the hangul characters that make up the syllables of the words you're
entering. The display changes as you enter each hangul letter. That is, when
you enter the first letter, it fills the entire space that the final syll-
able will take up. When you enter the second, the first shrinks to about
half its size to make room for the second. When you enter the third, the
first two shrink again. And so on, up to the maximum of five letters in a
syllable.
It's usually acceptable to keep Korean text in hangul form, but some words
are more commonly written in hanja. If you want to change hangul to hanja,
you define the region to be converted, and follow the same basic method as
described for Japanese.
Probably because there are well-accepted phonetic writing systems for Japanese
and Korean, computer input methods for those languages are fairly standard.
Keyboard keys have both English characters and the local language's phonetic
symbols engraved on them. You can then switch the keyboard from English to
local mode and vice versa.
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.
Also, there are actually two ideographic sets used: Traditional Chinese, (the
original written Chinese) and Simplified Chinese. Several years back, the
People's Republic Of China launched a campaign to simplify some ideographic
characters and eliminate redundancies all together. 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.
1.1.1. Input Method Architecture
As shown in the previous paragraphs, there are many different input methods in
use today, varying with language, culture, and history. A common feature of
many input methods is that the user may type multiple keystrokes in order to
compose a single character (or set of characters). The process of composing
characters from keystrokes is called pre-editing. It may require complex
4
XIM Public Review Draft
algorithms and large dictionaries involving substantial computer resources.
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 dic-
tionaries, and so on. The input method areas with which we are concerned in
this specification are as follows.
The Status area is intended to be a logical extension of the LED's that
exist on the physical keyboard. It is an output-only window which is
intended to present the internal state of the input method that is criti-
cal to the user. The status area may consist of text data and bitmaps or
some combination.
The PreEdit area is intended to display the intermediate text for those
languages that are composing prior to the client handling the data.
The Auxiliary 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 any input method. Auxiliary areas are managed by the input
method independent of the client. Auxiliary areas are assumed to be a
separate dialog which is maintained by the input method.
There are various user interaction styles used for pre-editing. The ones that
this specification addresses are as follows.
For on-the-spot input methods, pre-editing data will be displayed in the
application window. Application data is moved to allow pre-edit data to
be displayed at the point of insertion.
Over-the-spot pre-editing means that the data is displayed in an input
method window that is placed over the point of insertion.
Off-the-spot pre-editing means that the pre-edit window is inside the
client window, but not at the point of insertion. Often this type of win-
dow is placed at the bottom of the client window.
Root-window pre-editing refers to input methods that use a pre-edit window
that is the child of RootWindow.
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, the
goal of these specifications is to allow an application to communicate with an
input method placed in a separate process. Such a process is called an input
server. The server to which the application should connect is dependent upon
the environment when the application is started up: what is the user language,
the actual encoding to be used for it. We will say that input method connec-
tion is locale dependent. 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).
Using an input server implies communication overhead, but applications can be
migrated without relinking. Specifications in this document have been designed
so input methods can be implemented either as a stub communicating to an input
server or as a local library.
5
XIM Public Review Draft
An input method may be based on a front-end or a back-end architecture. In
front-end, there are two separate connections to the X server: keystrokes go
directly from X server to the input method on one connection, other events to
the regular client connection. The input method is then acting as a filter,
and sends composed strings to the client. Front-end requires synchronization
between the two connections to avoid lost key events or locking issues.
In back-end, 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 (i.e., a server), there must be a
special communication protocol between the back-end client and the input
server.
Front-end introduces synchronization issues and filtering mechanism for non-
character keystrokes (Functions, Help, etc). Back-end sometimes implies more
communication overhead and more process switching. If all three processes are
running on a single workstation (X server, input server, client) there are two
process switch for each keystroke in back-end, but only one in frontend.
The abstraction used by a client to communicate with an input method is an
opaque data structure represented by the XIM data type. This data structure is
returned by the XOpenIM function, which opens an input method on a given
display. Subsequent operations on this data structure encapsulate all communi-
cation between client and input method. There is no need for an X client to use
any networking library or natural language package in order to use an input
method.
The specifications are not meant to provide explicit support to multi-lingual
clients (using several languages), but they make it possible to implement such
clients. For each language, a client has to open an input method for that
language. Other functions will execute within the context of a given input
method.
Characters from the various languages are represented in a computer using an
encoding. Different languages have different encodings, and there are even dif-
ferent encodings for the same characters in the same language. A client pro-
gram that can run using any encoding without any change in the source code is
said to be codeset independent.
These specifications do not have specific requirements concerning languages or
encodings supported by an input method or input server. 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
locale that was the current locale when the input method was opened.
1.2. Input Context
The specifications provide the ability to manage a multi-threaded state. A
client may be using multiple windows, each window with multiple text entries,
and the user possibly switching among them at any time. The abstraction for
representing state of a particular input thread is called an input context.
The Xlib representation of an input context is an XIC.
6
XIM Public Review Draft
An input context is the abstraction retaining the state, properties and seman-
tics 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 graph-
ics output.
One input context belongs to exactly one input method. Different XIC's may be
associated with the same input method, possibly with the same client window.
An input context is created with the XCreateIC function, providing an XIM
argument, affiliating the XIC to the input method for its lifetime. When an
input method is closed with XCloseIM, all of its affiliated input context's
should not be used any more (and preferably be destroyed too).
Considering the example of a client window with multiple text entries windows,
the application programmer could for example choose to implement:
o As many input contexts are created as text entries and the client will get
the input accumulated on each context each time it will lookup that context.
o A single context is created for a top level window in the application. If
such window contains several text entries, each time the user moves to
another text entry, the client has to indicate changes in the context.
A range of choices can be made by application designers to use either a single
or multiple XIC's, according to the needs of their application.
1.3. Getting Input
In order to obtain characters from an input method a client must call the func-
tion XmbLookupString or XwcLookupString (noted as X*LookupString) with an XIC
created from that XIM. Both a locale and display are bound to an input method
when it is opened and an XIC inherits this locale and display. Any strings
returned by X*LookupString will be encoded in that locale.
These functions are similar to XLookupString in X11 Release 4. One difference
from XLookupString is that X*LookupString returns a Status. A programmer cal-
ling X*LookupString should check this status value to know if any valid input
is being returned. If no input has been composed it will return a None status.
>From the very nature of input methods, it may take multiple keystrokes before
it returns a character or a string. To internationalize an X application, pro-
grammers should change the code so that each time it was receiving a key
(press) event and called XLookupString, it would now call X*LookupString, and
additionally check that something is returned and behave accordingly. Typi-
cally, a test should be inserted so that no action is taken if nothing is
returned.
1.4. Focus management
For each text entry object which is doing input using either of the
X*LookupString routines there will be an associated IC.
When a text entry object gets the application focus, it is the job of that text
7
XIM Public Review Draft
entry object to set the IC focus to the corresponding IC. The IC focus is set
by calling XSetICFocus with the appropriate IC.
Also, when a text entry object looses the application focus, that text entry
object should call XUnSetICFocus. As an optimization, if XSetICFocus is called
successively on two different XIC's, setting the focus on the second IC will
unset the focus on the first XIC.
Note that in order to set and unset the XIC focus correctly it will be neces-
sary for a toolkit (or application) to track focus changes. Such focus changes
do not necessarily correspond to X server focus changes.
If a toolkit (or application) is using a single XIC to do input for multiple
text entry objects, it will also be necessary for that text entry object to set
the focus window of the XIC whenever the focus window changes. (see
XNFocusWindow under XSetICValues).
1.5. Geometry Management
In most input method architectures, (on-the-spot being the notable exception)
the input method will perform the display of its own data. In order to provide
better visual locality, it is often desirable to have the input method areas
embedded within a client. In order to do this the client may need to allocate
space for an input method. This spec 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.
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.
o The client is responsible for the geometry of the input method window.
o The input method is responsible for the contents of the input method window.
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 deter-
mine the size and it must accept the size it is given.
Before a client provides geometry management for an input method it must deter-
mine if geometry management is needed. The input method indicates the need for
geometry management by setting XIMPreEditArea or XIMStatusArea in its XIMStyles
value returned by XGetIMValues. When a client has decided that it will provide
geometry management for an input method, it indicates that decision by setting
the XNInputStyle value in the XIC.
After a client has established with the input method that it will will do
geometry management, the client must negotiate the geometry with the input
method. The geometry is negotiated by the following steps.
o The client suggests an area to the input method by setting the IC's
AreaNeeded 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
8
XIM Public Review Draft
height to zero. Otherwise it will set one of the values.
o The client will get the XIC value AreaNeeded. The input method will return
its suggested size in this value. The input method should pay attention to
any constraints suggested by the client.
o The client sets the XIC value Area 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.
Clients doing geometry management must be aware that setting other IC values
may affect the geometry desired by an input method. For example, FontSet and
LineSpacing may change the geometry desired by the the input method.
The table of XIC values in section 3 indicates the values that can cause the
desired geometry to change when they are set. It is the responsibility of the
client to re-negotiate the geometry of the input method window when it is
needed.
In addition the specification provides a geometry management callback by which
an input method can initiate a geometry change.
1.6. Filtering
A filtering mechanism is provided to allow input methods to capture X events
transparently to clients. It is expected that toolkits (or clients) using
X*LookupString 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.
If there were no filter, a client could receive and discard events that are
necessary for the proper functioning of an input method. A few examples of
such events are:
o Expose events on pre-edit window in local mode.
o 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.
o Key events can be sent to a filter before they are bound to translations
such as Xt provides.
Clients are expected to get the IC value XNFilterEvent and augment the event
mask for the client window with that event mask. This mask may be NULL.
1.7. Callbacks
When an on-the-spot input method is implemented, only the client can
insert/delete pre-edit data in place, and possibly scroll existing text. This
means the echo of the keystrokes has to be achieved by the client itself,
tightly coupled with the input method logic.
When a keystroke is entered, the client calls X*LookupString. At this point,
9
XIM Public Review Draft
in the on-the-spot case, the echo of the keystroke in the pre-edit has not yet
been done. Before returning to the client logic that handles the input charac-
ters, X*LookupString must call the echoing logic for inserting the new keys-
troke. 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, input method
logic has to call back the client before it returns. As with the Xt toolkit,
the client code, i.e a callback routine, is called from the input method logic.
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
defined by these specifications. It is possible for the client to specify, for
each input context, what callback is to be called for each action.
There are also callbacks provided for feedback of status information and a
callback to initiate a geometry request for an input method.
2. Programming Interfaces.
Input method programming interface consists of a set of functions and data
types starting with prefix X. The usual Xlib programming conventions apply to X
function calls, including the two new resources XIM and XIC.
Most X interfaces have arguments which conform to ANSI-C variable argument list
calling convention. Each procedure in the sequel denoted with a "..." argument
takes a variable length list of name and value pairs where each name is of type
XIMString and each value of type XIMValue. The end of the list is identified by
a name argument containing NULL.
XIMValue is an implementation dependent typedef, which has to be large enough
to contain void * in ANSI-C implementation, and any kind of pointer or long
data in other C implementations.
typedef char * XIMString;
typedef void (*XIMProc)();
typedef SOMETHING XIMValue;
A variable length argument list may contain a nested list. If the name
XNestedList is specified in place of an argument name, then the following value
is interpreted as a XVaNestedList value which specifies a list of values logi-
cally inserted into the original list at the point of declaration. The end of
a nested list is identified with a NULL name. To dynamically allocate a nested
variable argument list, use XCreateNestedList.
#define XNVaNestedList "XNVaNestedList"
typedef void * XVaNestedList;
XVaNestedList XVaCreateNestedList(dummy, ...)
int dummy; ANSI-C requirement for variable arguments.
...; specifies the variable length argument list.
10
XIM Public Review Draft
XVaCreateNestedList allocates memory and copies its arguments into a single
list pointer which may be used as 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 XFree when no longer needed.
2.1. Opening, Closing, Querying Input Method
The functions to open and close a connection are XOpenIM and XCloseIM
XIM XOpenIM(dpy, rdb, res_name, res_class)
Display *dpy; specifies the display where the input method operates
XrmDataBase rdb;
XString res_name;
XString res_class;
XOpenIM 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 the strings returned by X*LookupString (see below),
for any IC affiliated with a given input method, will be encoded in the locale
current at the time input method is opened.
The specific input method to which this call will be routed is identified on
the basis of the current locale. XOpenIM will identify a default input method
corresponding to the current locale. That default can be modified using XSetMo-
difier for the input method modifier.
Argument rdb is the resource database to be used by the input method for look-
ing 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 rdb is NULL, no data base is passed to the input method.
Arguments res_name and res_class 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.
XOpenIM returns NULL if no input method could be opened.
Status XCloseIM(im)
XIM im;
XCloseIM closes the input method.
For querying input method use XGetIMValues.
void XGetIMValues(im, ...)
XIM im; specifies the queried input method.
...; specifies the variable length argument list to query im values.
11
XIM Public Review Draft
XGetIMValues presents a variable argument list programming interface for query-
ing properties or features of the input method. Only one argument is defined
by this version of the specifications: XNQueryInputStyle, that must be used to
query about input styles supported by the input method.
A client should always query the input method to determine what styles are sup-
ported. The client should then find an input style it is capable of support-
ing.
If the client is not capable of meeting any of the requirements for input
methods, it should ensure that the style XIMNeedNothing or XIMNeedNone is sup-
ported.
If the client cannot find an input style that it can support it should nego-
tiate with the user the continuation of the program (exit, choose another input
method, ...).
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 XIM-
Styles.
An XIMStyles structure contains in its field count_styles the number of input
styles supported. This is also the size of the array in the field
supported_styles.
Each element in the array represents a different input style supported by this
input method. The value is of type XIMStyle. It is a bit mask in which the
input method indicates its requirements, should this style be selected. These
requirements fall into the following categories.
Preedit: this category defines what type of support is provided by the input
method for pre-edit information:
XIMPreEditArea If chosen, the input method would require the client to
provide some area values for it to do its preediting.
Refer to IC values XNArea and XNAreaNeeded.
XIMPreEditPosition If chosen, the input method would require the client to
provide positional values. Refer to IC values XNSpotLo-
cation + XNFocusWindow.
XIMPreEditCallbacks If chosen, the input method would require the client to
define the set of pre-edit callbacks. Refer to IC
values XNPreEditStartCallback, XNPreEditDoneCallback,
XNPreEditDrawCallback, XNPreEditCaretCallback.
XIMPreEditNothing If chosen, the input method can function without any
PreEdit values.
XIMPreEditNone The input method does not provide any PreEdit feedback.
Any PreEdit value is ignored. This style is mutually
exclusive with the other XIMPreEdit styles.
Status: this category defines what type of support is provided by the input
12
XIM Public Review Draft
method for status information:
XIMStatusArea The input method requires the client to provide some
area values for it to do its Status feedback. Refer to
XNArea and XNAreaNeeded.
XIMStatusCallbacks The input method requires the client to define the set
of status callbacks; XNStatusStartCallback, XNStatus-
DoneCallback, XNStatusDrawCallback.
XIMStatusNothing The input method can function without any Status
values.
XIMStatusNone The input method does not provide any Status feedback.
If chosen, any Status value is ignored. This style is
mutually exclusive with the other XIMStatus styles.
Clients are responsible for freeing the XIMStyles data structure, using XFree.
typedef unsigned short XIMStyle;
#define XIMPreEditArea 0x0001L
#define XIMPreEditCallbacks 0x0002L
#define XIMPreEditPosition 0x0004L
#define XIMPreEditNothing 0x0008L
#define XIMPreEditNone 0x0010L
#define XIMStatusArea 0x0100L
#define XIMStatusCallbacks 0x0200L
#define XIMStatusNothing 0x0400L
#define XIMStatusNone 0x0800L
typedef struct {
unsigned short count_styles;
XIMStyle * supported_styles;
} XIMStyles;
3. Input Context
An input context is an abstraction used to contain 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 inter-
faces for creating, reading or modifying an input context use a variable argu-
ment list. The name elements of the argument lists are referred to as IC
values. It is intended that input methods be controlled by these IC values.
As new IC values are created they should be registered with the X Consortium.
To create an input context use XCreateIC.
XIC XCreateIC(im, ...)
XIM im; the attached input method.
...; specifies the variable length argument list to set slot values.
13
XIM Public Review Draft
XCreateIC creates a context within an input method.
Some of the arguments are mandatory at creation time. The XIC will not be
created if they are not provided. Those 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.
XCreateIC will return a NULL value if no XIC could be created. A NULL value
could be returned for any of the following reasons: a required argument was not
set, a read-only argument was set (e.g. XNFilterEvents), the argument name is
not recognized, or the input method encountered an input method implementation
dependent error.
The asynchronous errors that can be caused by XCreateIC are BadStyle, BadWin-
dow, BadAtom, BadColormap, BadPixmap
The function XDestroyIC destroys an input context.
void XDestroyIC(ic)
XIC ic;
ic must be a valid input context id.
Use functions XSetICFocus and XUnSetICFocus to communicate to and synchronize
with input method for any changes in keyboard focus from the client side.
void XSetICFocus(ic)
XIC ic; specifies the focussed XIC
XSetICFocus(ic) allows a client to notify an input method that the focus window
attached to the ic argument has received keyboard focus. The input method
should take action to provide appropriate feedback. Complete feedback specifi-
cation is a matter of user interface policy, beyond the scope of these specifi-
cations.
void XUnSetICFocus(ic)
XIC ic; specifies the focussed XIC
XICUnsetFocus allows a client to notify an input method that the ic has lost
the keyboard focus and no more input is expected on the focus window attached
to the specified ic. The input method should take action to provide appropri-
ate feedback. Complete feedback specification is a matter of user interface
policy, beyond the scope of these specifications.
To reset the state of an input context to initial state use either XmbResetIC
or XwcResetIC.
char * XmbResetIC(ic)
XIC ic; specifies the XIC to be reset
14
XIM Public Review Draft
XmbResetIC resets input context to initial state. Any input pending on that
context is deleted. Input method is required to clear pre-edit area, if any,
and update status accordingly. Calling XResetIC does not change the focus.
The return value of XmbResetIC is its current pre-edit string in multi-byte
format. It is input method implementation dependent whether this routine ever
returns any data.
The client should free this string using XFree.
char * XwcResetIC(ic)
XIC ic; specifies the XIC to be reset
XwcResetIC resets input context to initial state. Any input pending on that
context is deleted. Input method is required to clear pre-edit area, if any,
and update status accordingly. Calling XwcResetIC does not change the focus.
The return value of XwcResetIC is its current pre-edit string in wide-char for-
mat. It is input method implementation dependent whether this routine ever
returns any data.
The client should free this string using XFree.
3.1. Utility functions
To get the XIM associated with an XIC, use XIMOfIC.
XIM XIMOfIC(ic)
XIC ic;
To get the Display associated with an input method, use XDisplayOfIM.
Display * XDisplayOfIM(im)
XIM im;
To get the locale associated with an input method, use XLocaleOfIM.
char * XLocaleOfIM(im)
XIM im;
3.2. Modifying Input Contexts: XSetICValues and XGetICValues
Two functions allow for setting and reading XIC slots, respectively: XSet-
ICValues and XGetICValues. Both functions have a variable length argument
list. In that argument list, any slot name must be denoted with a character
string using the X portable character set.
char * XSetICValues(ic, ...)
XIC ic; specifies the input context to be changed
... ; specifies the variable length argument list to get slot values.
15
XIM Public Review Draft
Argument ic must be a valid input context id.
A value to be set must be an appropriate data, matching the data type imposed
by the semantics of the argument.
Returns NULL if no error occurred, otherwise the name of the first argument
that could not be set. An argument could be not set for any of the following
reasons: a read-only argument was set (e.g. XNFilterEvents), the argument name
is not recognized, or the input method encountered an input method implementa-
tion dependent error.
The asynchronous errors that can be caused by XSetICValues are BadWindow, BadA-
tom, BadColormap, BadPixmap
char * XGetICValues(ic, ...)
XIC ic;
...; specifies the variable length argument list to get slot values.
Argument ic must be a valid input context id.
Any argument value in a variable argument list (following a name) must point to
a location where the value is to be stored. XGetICValues will allocate memory
to store the values, and client is responsible for freeing it, using XFree.
Returns NULL if no error occurred, otherwise the name of the first argument
that could not be obtained. An argument could be not obtained for any of the
following reasons: the argument name is not recognized, or the input method
encountered an input method implementation dependent error.
3.3. IC Values Arguments
The following tables describe how IC values are interpreted by an input method
depending on the input style chosen by the user.
The first column lists the IC values. The second column indicates which values
are involved in affecting, negotiating and setting the geometry of the input
method windows. The sub-entries under the third column indicate the different
input styles supported. Each of these columns indicates how each of the IC
values are treated by that input style.
16
XIM Public Review Draft
___________________________________________________________________________________________
| || ||__________________________________________________|
| || Geometry ||PreEdit | PreEdit | PreEdit | PreEdit | PreEdit |
| IC Value ||Management ||Callback | Position | Area | Nothing | None |
______________________________________________________________________________________|
|Input Style || || C-G | C-G | C-G | C-G | C-G |
|Client Window || || O-G | O-G | O-G | ignored | 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 |
______________________________________________________________________________________|
|PreEdit || || | | | | |
|- Area || GS ||ignored | D-S-G | D-S-G | ignored | ignored |
|- AreaNeeded || GN-GR ||ignored | ignored | S-G | ignored | ignored |
|- SpotLocation || ||ignored | C-S-G | ignored | ignored | ignored |
|- Colormap || ||ignored | D-S-G | D-S-G | D-S-G | ignored |
|- Fg/Bg || ||ignored | D-S-G | D-S-G | D-S-G | ignored |
|- Bg Pixmap || ||ignored | D-S-G | D-S-G | D-S-G | ignored |
|- FontSet || GN ||ignored | C-S-G | C-S-G | D-S-G | ignored |
|- LineSpacing || 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 Callbacks || || C-S-G | ignored | ignored | ignored | ignored |
|____________________||___________||_________|__________|_________|_________|_________|
__________________________________________________________________________
| || || Input Style |
| || ||_______________________________________|
| IC Value || Geometry || Status | Status | Status | Status |
__________________________________________________________________________|
|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 |
|FilterEvents || || G | G | G | G |
__________________________________________________________________________|
|Status || || | | | |
|- Area || GS ||ignored | D-S-G | ignored | ignored |
|- AreaNeeded || GN-GR ||ignored | S-G | ignored | ignored |
|- Colormap || ||ignored | D-S-G | D-S-G | ignored |
|- Fg/Bg || ||ignored | D-S-G | D-S-G | ignored |
|- Bg Pixmap || ||ignored | D-S-G | D-S-G | ignored |
|- FontSet || GN ||ignored | C-S-G | D-S-G | ignored |
|- LineSpacing || GN ||ignored | D-S-G | D-S-G | ignored |
|- Cursor || ||ignored | D-S-G | D-S-G | ignored |
|___________________||___________||_________|_________|_________|_________|
Key:
C This value must be set with XCreateIC().
17
XIM Public Review Draft
D This value may be set using XCreateIC(). If not set, a default is pro-
vided.
G This value may be read using XGetICValues().
GN This IC value may cause geometry negotiation when its value is set via
XCreateIC() or XSetICValues().
GR This value will be the response of the input method when any GN value is
changed.
GS This value will cause the geometry of the input method window to be set.
O This value must be set once and only once. It need not be set at IC create
time.
S This value may be set with XSetICValues().
ignored
The IC value is ignored by the input method for the given input style.
3.3.1. Input Style
Argument XNInputStyle specifies the input style to be used. The value of this
argument must be one of the values returned by function XGetIMValues with argu-
ment XNQueryInputStyle in the supported_styles list, otherwise error BadStyle
will be raised.
This argument must be set at creation time and cannot be changed.
3.3.2. Client Window
Argument XNClientWindow specifies to 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. This
argument should be set before any input is done using this input context. If it
is not set the input method may not operate correctly.
If an attempt is made to set this value a second time with XSetICValues, the
string "XNClientWindow" will be returned by XSetICValues and the client window
shall not be changed.
If the client window is not a valid window id on the display attached to the
input method this argument can generate a BadWindow error when this value is
used by the input method.
3.3.3. Focus Window
Argument XNFocusWindow specifies the focus window. The primary purpose of the
XNFocusWindow is to identify the window which will receive the key event when
input is composed. In addition, the input method may possibly affect the focus
window: select events on it, send events to it, modify its properties, grab
18
XIM Public Review Draft
keyboard within that window.
The value associated to the argument must be of type Window. If the focus win-
dow is not a valid window id on the display attached to the input method this
argument can generate a BadWindow error when this value is used by the input
method.
When this slot is left unspecified, input method will default focus window to
client window.
3.3.4. Resource Name and Class
Arguments XNResourceName and XNResourceClass are strings that represent the
full name and class hierarchy 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 IC. If these values are
not set, the resources will not be fully specified.
It is not intended that values which can be set as IC values be set as
resources.
3.3.5. Geometry Callback
The argument XNGeometryCallback is a structure of type XIMCallback (see
PreEdit/Status Callbacks).
The argument XNGeometryCallback specifies the geometry callback which 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 pol-
icy permits an input method to request the dynamic change of that input methods
window. An input method that does dynamic change will need to filter any
events that it uses to initiate the change.
3.3.6. Filter Events
The argument XNFilterEvents will return the event mask that an input methods
needs to have selected for. The client is expected to augment its own event
mask for the client window with this one.
This argument is read-only. It is set by the input method at create time and
is never changed.
The type of this argument is unsigned long. Setting this value will cause an
error.
3.3.7. PreEdit and Status Attributes
Arguments XNPreeditAttributes and XNStatusAttributes specify to input method
the attributes to be used for the PreEdit and Status areas, if any. Those
attributes are passed to XSetICValues or XGetICValues as a nested variable
length list. The names to be used in such lists are as described in the next
subsection.
19
XIM Public Review Draft
3.3.7.1. Area
The value of the argument XNArea must be a pointer to a structure of type XRec-
tangle. The interpretation of argument XNArea is dependent on the input method
style set in the IC.
If the input method style is XIMPreEditPosition, 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. If the
focus window has not been set the coordinates are assumed to be relative to the
client window. If neither has been set, the results are undefined. If XNArea
is not specified the input method will default the clipping region to the
geometry of the XNFocusWindow. If the area specified is NULL or invalid the
results are undefined.
If the input style is XIMPreEditArea or XIMStatusArea, 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 win-
dow with dimensions that fit the 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
XNArea is not specified, is set to NULL or is invalid, the results are unde-
fined.
3.3.7.2. Area Needed
When set, argument XNAreaNeeded 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 XRectangle. The x, y values are not used.
Non-zero values for width or height are constraints that the client wishes the
input method to respect.
When read, argument XNAreaNeeded specifies the preferred geometry desired by
the input method for the area.
This argument is only valid if the input style is XIMPreEditArea or XIMSta-
tusArea. It is used for geometry negotiation between the client and the input
method and has no other effect upon the input method (refer to Geometry Manage-
ment.)
3.3.7.3. Spot Location
Argument XNSpotLocation specifies to input method the coordinates of the
"spot", to be used by an input method executing with XNInputStyle set to
XIMPreEditPosition. When specified to any input method other than NeedPosition
this slot is ignored.
The x coordinate specifies the position where the next character would be
inserted. The y coordinate is the position of the baseline used by current
text line in the focus window. The x and y coordinates are relative to the
focus window if it has been set, else they are relative to the client window.
20
XIM Public Review Draft
If neither focus window nor client window has been set the results are unde-
fined.
The value of the argument is a pointer to a structure of type XPoint.
3.3.7.4. Colormap
Two arguments can be used to indicate what colormap the input method should use
to allocate colors: one as a colormap XID, the other as a standard colormap
name. Argument XNColormap is used to specify a colormap id. Argument value is
of type Colormap. This argument may generate a BadColormap error when the
colormap is used by the input method. Argument XNStdColormap is used to indi-
cate the name of the standard colormap in which input method should to allocate
colors. Argument value is an Atom that should be a valid atom for calling
XGetStandardColormap. This argument may generate BadAtom or BadColormap error
when it is used by the input method.
If colormap is left unspecified, it is defaulted to client window colormap.
3.3.7.5. Foreground and background.
Arguments XNForeground and XNBackground specifies respectively the foreground
and background pixel. Argument value is of type unsigned long. It must be a
valid pixel in the input method colormap. Error BadPixel is raised when this
argument is used by the input method if pixel is not a valid pixel for the
colormap in use by the input method.
If these values are left unspecified, the default is determined by the input
method.
3.3.7.6. Background pixmap.
Argument XNBackgroundPixmap specifies a background pixmap to be used as the
background of the window. Slot value must be of type Pixmap. Can generate
error BadPixmap when this argument is used by the input method.
If this value is left unspecified, the default is determined by the input
method.
3.3.7.7. FontSet
Argument XNFontSet specifies to input method what fontset is to be used. Argu-
ment value is of type XFontSet.
If this value is left unspecified, the default is determined by the input
method.
3.3.7.8. Line Spacing
Argument XNLineSpace specifies to input method what line spacing is to be used
in pre-edit window if more than one line is to be used. The slot value is of
type int.
21
XIM Public Review Draft
If this value is left unspecified, the default is determined by the input
method.
3.3.7.9. Cursor
Argument XNCursor specifies to input method what cursor is to be used in the
specified window. The slot value is of type Cursor.
If this value is left unspecified, the default is determined by the input
method.
3.3.7.10. PreEdit/Status Callbacks
A client that wishes to support the input style XIMPreEditCallbacks must pro-
vide a set of pre-edit callbacks to the input method. The set of pre-edit call-
backs are:
o XNPreEditStartCallback called when the input method starts pre-edit.
o XNPreEditDoneCallback called when the input method stops pre-edit.
o XNPreEditDrawCallback called when a number pre-edit keystrokes should be
echoed.
o XNPreEditCaretCallback called to move text insertion point within pre-edit
string
A client that wishes to support the input style XIMStatusCallbacks must provide
a set of status callbacks to the input method. The set of status callbacks are:
o XNStatusStartCallback called when the input method initializes status area.
o XNStatusDoneCallback called when the input method no longer needs status
area.
o XNStatusDrawCallback called when updating the status area is required.
The value of any status or pre-edit argument is a pointer to a structure of
type XIMCallback.
typedef struct {
XIMValue client_data;
XIMProc callback;
} XIMCallback;
Each callback has some particular semantics and will carry the data expressing
the environment necessary to the client into a specific data structure. This
paragraph only describes the arguments to be used to set the callback. For a
complete description of the semantics see section 4.
Setting any of these values while doing preedit may cause unexpected results.
22
XIM Public Review Draft
4. Callbacks semantics
Callbacks are functions defined by clients or text drawing packages, 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 trig-
gered, and what their arguments are; it is mostly useful for toolkit implemen-
tors.
Callbacks are mostly provided so that clients (or text editing packages), can
implement on-the-spot pre-editing in their own window. In that case, the input
method needs to communicate and synchronize with the client. Input method
needs to communicate changes in the pre-edit window when it is under control of
the client. Those callbacks allow the client to initialize the pre-edit area,
display a new pre-edit string, move the text insertion point inside pre-edit,
terminate pre-edit, update the status area.
All callback functions follow the generic prototype:
void CallbackPrototype(ic, client_data, call_data)
XIC ic; specifies the originator of callback.
XIMValue client_data; specifies additional client data.
XCallbackStruct *callback_data; specifies specific callback data.
The callback_data is a structure expressing the arguments needed to achieve the
semantics: a specific data structure appropriate to the callback. In cases
where no data is needed in the callback, this callback_data is NULL. The
client_data argument is a closure, initially specified by the client when
specifying the callback and passed back. It may serve, for example, to inherit
application context in the callback.
The following paragraphs describe the semantics and specific data structure
associated with the different reasons.
4.1. Geometry Callback
The geometry callback is triggered by the input method to indicate that it
wants the client to negotiate geometry.
void GeometryCallback(ic, client_data, call_data)
XIC ic; specifies the originator of callback.
XIMValue client_data; client data.
void * call_data; specific callback data.
GeometryCallback is called with a NULL call_data argument.
4.2. PreEdit State Callbacks
When the input method turns input conversion on or off, PreEditStartCallback or
PreEditDoneCallback is triggered in order to let the toolkit do the setup or
the cleanup for the pre-edit region.
23
XIM Public Review Draft
int PreEditStartCallback(ic, client_data, call_data)
XIC ic; specifies the originator of callback.
XIMValue client_data; client data.
void * call_data; specific callback data.
When pre-edit starts on the specified ic, the callback is called, with a NULL
call_data argument. PreEditStartCallback will return the maximum size of the
pre-edit string. A positive number indicates the maximum number of bytes
allowed in the pre-edit string, a value of -1 indicates there is no limit.
void PreEditDoneCallback(ic, client_data, call_data)
XIC ic; specifies the originator of callback.
XIMValue client_data; client data.
void * call_data; specific callback data.
When pre-edit stops on the specified ic, the callback is called, with a NULL
call_data argument. The client can release the data allocated by PreEditStart-
Callback.
PreEditStartCallback should initialize appropriate data needed for displaying
pre-edit information and for handling further PreEditDrawCallback calls. Once
PreEditStartCallback is called, it shall not be called again before PreEdit-
DoneCallback has been called.
4.3. PreEditDraw Callback
This callback is triggered to draw and insert, delete or replace, pre-edit text
in the pre-edit region. The pre-edit 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 multi-byte or wide-character
string, whose encoding matches the locale bound to the XIC. The callback proto-
type is as follows:
void PreEditDrawCallback(ic, client_data, call_data)
XIC ic; the originator of callback.
XIMValue client_data; client data.
XIMPreEditDrawCallbackStruct *call_data; callback data.
The callback is passed a 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.
typedef struct _XIMPreEditDrawCallbackStruct {
int caret; /* Cursor offset within pre-edit string */
int chg_first; /* Starting change position */
int chg_length; /* Length of the change in character count */
XIMText text;
} XIMPreEditDrawCallbackStruct ;
24
XIM Public Review Draft
The client must keep updating a buffer of the pre-edit text, the callback argu-
ments referring to indexes in that buffer. The call_data fields have specific
meanings according to the operation:
o To indicate text deletion, the call_data specifies a NULL text field. The
text to be deleted is then the current text in buffer from position
chg_first (starting at zero) on a (character) length of chg_length.
o When text is non-NULL it indicates insertion or replacement of text in the
buffer.
A positive chg_length indicates that the characters starting from chg_first
to ch_first+chg_length must be deleted, and replaced by text, whose length
is specified in the XIMText structure.
A chg_length value of 0 indicates that text must be inserted right at the
position specified by chg_first. A value of 0 for chg_first specifies the
first character in the buffer.
o caret: index in the the pre-edit text buffer specifying the character after
which the cursor should move after text has been drawn or deleted.
typedef struct _XIMText {
unsigned short length;
XIMFeedback * feedback;
Bool encoding_is_wchar;
union {
char * multi_byte;
wchar_t * wide_char;
} string;
} XIMText;
The text string passed is actually a structure specifying:
o length: the text length in characters.
o encoding_is_wchar: indicates if the string is passed encoded in wide charac-
ter or multi-byte.
o string: the text string.
o feedback: indicates rendering type.
The feedback field express 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 (e.g. primary, secondary) or in specific ways (reverse, under-
line). When generic indications are given, the client is free to choose the
rendering style. It is necessary however that primary and secondary are mapped
to two distinct rendering styles.
The feedback field specifies how the rendering of the text argument should be
achieved. If feedback is NULL, then rendering is assumed to be the same as
rendering of other characters in the text entry. Otherwise, feedback specifies
25
XIM Public Review Draft
an array defining the rendering of each character of the string (hence the
length of the array is length).
If an IM wishes to indicate that it is only updating the feedback of the pre-
edit text without changing the content of it, XIMText should contain a NULL
value for the string field, the number of characters affected in the length
field and the feedback field should point to an array of XIMFeedback.
Each element in the array is a bit mask represented by a value of type XIMFeed-
back. The valid masks names are as follows.
typedef unsigned char XIMFeedback;
#define XIMReverse 1L
#define XIMUnderline (1L<<1)
#define XIMHighlight (1L<<2)
#define XIMPrimary (1L<<6)
#define XIMSecondary (1L<<7)
#define XIMTertiary (1L<<8)
4.4. PreEditCaretCallback
An input method may have its own "navigation keys" to allow the user to move
the text insertion point in the pre-edit area (e.g. 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
void PreEditCaretCallback(ic, client_data, call_data)
XIC ic; the originator of callback.
XIMValue client_data; specifies additional client data.
XPreEditCaretCallbackStruct *call_data; specific callback data.
Input method will trigger PreEditCaretCallback to move the text insertion point
during pre-edit. The call_data argument contains a pointer to an XPreEditCaret-
Callback structure. This structure 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 initial position.
typedef struct _XIMPreEditCaretCallbackStruct {
int position; /* Caret offset within pre-edit string */
XIMCaretDirection direction; /* Caret moves direction */
XIMCaretStyle style; /* Feedback of the caret */
} XIMPreEditCaretCallbackStruct ;
typedef enum {
XIMInvisible, /* Disable caret feedback */
XIMPrimary, /* UI defined caret feedback */
XIMSecondary, /* UI defined caret feedback */
} XIMCaretStyle;
26
XIM Public Review Draft
typedef enum {
XIMForwardChar, XIMBackwardChar,
XIMForwardWord, XIMBackwardWord,
XIMCaretUp, XIMCaretDown,
XIMNextLine, XIMPreviousLine,
XIMLineStart, XIMLineEnd,
XIMAbsolutePosition,
XIMDontChange
} XIMCaretDirection;
The meaning of those values are:
o XIMForwardChar: Move caret forward one character position
o XIMBackwardChar: Move caret backward one character position
o XIMForwardWord: Move caret forward one word position
o XIMBackwardWord: Move caret backward one word position
o XIMCaretUp: Move caret up one line keeping current offset.
o XIMCaretDown: Move caret down one line keeping current offset.
o XIMPreviousLine: Move caret up one line.
o XIMNextLine: Move caret down one line
o XIMLineStart: Move caret to beginning of the current display line containing
the caret.
o XIMLineEnd: Move caret to end of the current display line containing the
caret.
o XIMAbsolutePosition: 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 pre-edit text. Hence a value of zero means: move back
to beginning of the pre-edit text.
o XIMDontChange: The caret position does not change.
4.5. Status Callbacks
An input method may communicate changes in the status of an input context
(created, destroyed, or focus changes), with three status callbacks: Sta-
tusStartCallback , StatusDoneCallback , StatusDrawCallback
When the XIC is created or when the XIC gains focus, IM calls StatusStartCall-
back callback.
void StatusStartCallback(ic, client_data, call_data)
XIC ic; the originator of callback.
XIMValue client_data; specifies additional client data.
XIMValue call_data; specific callback data.
27
XIM Public Review Draft
The callback should initialize appropriate data for displaying status and be
prepared to further StatusDrawCallback calls. Once StatusStartCallback is
called, it shall not be called again before StatusDoneCallback has been called.
When an XIC is destroyed or when focus is lost by the XIC, IM calls StatusDone-
Callback.
void StatusDoneCallback(ic, client_data, call_data)
XIC ic; the originator of callback.
XIMValue client_data; specifies additional client data.
XIMValue call_data; specific callback data.
The callback may release any data allocated on StatusStart.
When an XIC status has to be updated, IM calls StatusDrawCallback.
void StatusDrawCallback(ic, client_data, call_data)
XIC ic; the originator of callback.
XIMValue client_data; specifies additional client data.
XIMValue call_data; specific callback data.
The callback should update the status area by either drawing a string, or imag-
ing a bitmap in the status area.
typedef enum {
TextType,
Bitmaptype,
} XIMStatusDataType;
typedef struct _XIMStatusDrawCallbackStruct {
XIMStatusDataType type;
union {
XIMText text;
Pixmap bitmap;
} data;
} XIMStatusDrawCallbackStruct ;
5. Filtering
Xlib provides the ability for an input method (or any other code) to register a
filter with Xlib. This filter is called by a client (or toolkit) by calling
XFilterEvent after calling XNextEvent. Any client that uses the XIM interface
should call 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, (e.g. modal grabs).
A package that wants to do event filtering, e.g. an input method, must register
its filter with the filtering machinery. It can add or remove filters using
the two functions XRegisterFilter, XUnRegisterFilter There may be zero or more
filters for the same event. Clients may not know how many filters there are,
28
XIM Public Review Draft
if any, and what they do. They may only know if an event has been filtered on
return of XFilterEvent. Clients should discard filtered events.
Boolean XFilterEvent(evt, window)
XEvent * evt;
Window window; specifies the window for which this filter should be applied
XFilterEvent is called with an XEvent and a Window. Window specifies the win-
dow for which this filter should be applied. If window is NULL, the window
from evt is applied. Window is provided so that layers above Xlib that do
event redirection can indicate to which window an event has been redirected.
XFilterEvent searches its list of filters for a filter that matches the display
and event type from the event and window. When XFilterEvent finds a filter
that matches it will call that filter. If that filter returns True, XFil-
terEvent immediately returns True, without looking for more filters. If no
filters are found that filter the event, False is returned. Filters are called
in the order in which they were registered.
If a grab has occurred in the client, and the filter is returning True, the
client should ungrab the keyboard.
To register a filter, use XRegisterFilter
void XRegisterFilter(display, window, event_mask, filter, client_data)
Display * display; specifies the display for which this filter is being registered
Window window; specifies the window for which this filter is being registered
unsigned long event_mask; specifies the event mask for which to call the filter.
Boolean nonmaskable; specifies whether the filter should be called on the nonmaskable events
Boolean (*filter)(); specifies the filter to be called
XIMValue client_data; additional client data to be passed to the filter.
XRegisterFilter registers a filter with the filtering machinery. This filter
will be called on further calls to XFilterEvent for events generated on the
specified display and window, when the event matches the mask. If window is
NULL, the filter will match for any window value.
For each set of display, window, filter, client_data, exactly one filter will
be registered. If a filter is registered that matches a currently registered
filter, then the specified event_mask augments the existing mask. Clients who
want to filter nonmaskable events (GraphicsExpose, NoExpose, SelectionClear,
SelectionNotify, SelectionRequest, ClientMessage and MappingNotify) should set
nonmaskable to True.
XUnRegisterFilter(display, window, filter, client_data)
Display * display; specifies the display for which this filter is being removed.
Window window; specifies the window for which this filter is being removed.
Boolean (*filter)(); specifies the filter that is to be removed
XIMValue client_data; specifies client data registered
XUnRegisterFilter removes a filter registered with XRegisterFilter. If
29
XIM Public Review Draft
display, window, filter and client_data do not match a registered filter, no
filter is removed and no error is reported.
The filter prototype is as follows.
Boolean PrototypeFilter(display, window, evt, f_data)
Display * display; the display for which filter is being called.
Window window; the window for which filter is being called.
XEvent *evt; the triggering event
XIMValue client_data; client data previously registered
{
/* if event is filtered return True, else False */
}
A filter function should not remove events from the queue (e.g. call XNex-
tEvent). It should decide from context if the event is filtered or not.
6. Getting Composed Input
To get composed input from an input method, use XmbLookupString or XwcLookup-
String.
int XmbLookupString(ic, event, buffer_return, bytes_buffer, keysym_return, status_return)
XIC ic; specifies context for input processing.
XKeyPressedEvent *event; specifies key press event.
char *buffer_return; specifies multibyte string return buffer.
int bytes_buffer; specifies space available in return buffer.
KeySym *keysym_return; specifies Out: return keysym (if any).
Status *status_return; flag specifying what is returned.
int XwcLookupString(ic, event, buffer_return, bytes_buffer, keysym_return, status_return)
XIC ic; specifies context for input processing.
XKeyPressedEvent *event; specifies key press event.
wchar_t *buffer_return; specifies wide char return buffer.
int wchars_buffer; specifies space available in buffer.
KeySym *keysym_return; specifies returned keysym (if any).
Status *status_return; flag specifying what is returned.
These functions return the string from the input method in buffer_return. If
no string is returned buffer_return is unchanged.
The keysym into which the keycode from the event was mapped is returned in
keysym_return if keysym_return is non-NULL and status 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.
XmbLookupString will return the length of the string in bytes. XwcLookupString
will return the length of the string in characters.
These functions also detect any rebound keysyms (see XRebindKeysym) and return
the specified bytes. since the last call.
30
XIM Public Review Draft
The ic argument specifies an input context identifier returned from the
XCreateIC() call. Unlike XLookupString, which returns only Latin-1 strings,
XmbLookupString and XwcLookupString return text in the codeset of the locale
bound to the input method of the specified input context.
Note that each string returned by Xmb/wcLookupString begins in the initial
state of the codeset of the locale (if the codeset of the locale is state-
dependent).
Caution: in order to insure proper input processing, it is essential that the
client pass only KeyPress events to X*LookupString. The behavior of
X*LookupString when the client passes a KeyRelease event is undefined.
Clients should check return_status before using the other returned values.
These two functions both return in return_status a value indicating what has
been returned in the other arguments:
o XBufferOverflow means that the input string to be returned is too large for
the supplied buffer_return. The required size (XmbLookupString in bytes,
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 ade-
quate size in order to obtain the string.
o XLookupNone means that no consistent input has been composed so far. The
contents of buffer_return and keysym_return are not modified, and the func-
tion returns 0 as a value.
o XLookupChars means some input characters have been composed. They are
placed in buffer_return and the string length in octets is returned as the
value of the function. The string is encoded in the locale bound to the
input context. The contents of keysym_return is not modified.
o XLookupKeySym means a KeySym has been returned instead of a string. The
keysym is returned in keysym_return. The contents of buffer_return is not
modified, and the function returns 0 as a value.
o XLookupBoth means that both a KeySym and a string are returned, XKeySym and
XString occur simultaneously.
It does not make any difference if the input context passed as an argument to
X*LookupString is the XIC 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 X*LookupString even though it
does not have any more keyboard focus.
7. Conventions
The various input method architecture are 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.
31
XIM Public Review Draft
7.1. Client Conventions.
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 con-
tinuation of the program, or raise an exception or error of some sort.
Of course, clients using a toolkit including an on-the-spot text editing facil-
ity of some sort do not need to specify such callbacks.
7.2. Conventions for Input Method Synchronization
A KeyPress event with a keycode value of 0 shall be used exclusively as a sig-
nal that an input method has composed input which can be return by
X*LookupString. No other use shall be made of a Keypress event with keycode 0.
A front-end input method shall signal to clients that they have composed input
by sending a synthetic KeyPress event to the focus window of the corresponding
XIC, with a keycode value of 0.
A back-end input method may change the keycode value of a KeyPress event to
keycode 0 to indicate that there is data to be gathered from the filter.
When callback support is specified by 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).
8. Acknowledgments
This specification was generated after discussion on the mltalk mailing list,
in several meetings, and several proposals were made by different entities or
people. The contributors to the mltalk group have been:
Tim Anderson (Motorola), Alka Badshah (OSF), Gabe Beged-Dov (HP), Chih-Chung Ko
(III), Vera Cheng (III), Michael Collins (Digital Equipment Co.), Walt Daniels
(IBM), Noritoshi Demizu (OMRON), Keisuke Fukui (Fujitsu), Hitoshoi Fukumoto
(Nihon - Sun Microsystems), Tim Greenwood (Digital Equipment Co.), John Harvey
(IBM), Fred Horman (AT&T), Vania Joloboff (OSF), Norikazu Kaiya (Fujitsu), Yuji
Kamata (IBM), Yutaka Kataoka (OMRON), Ranee Khubchandani (Sun Microsystems),
Akari Kon (NEC), Hiroshi Kuribayashi (OMRON), Teruhiko Kurosaka (Sun Microsys-
tems), Seiji Kuwari (Omron), Sandra Martin (OSF), Bill McMahon (HP), Tom McFar-
land (HP), Masato Morisaki (NTT), Nelson Ng (Sun), Takashi Nishimura (NTT Amer-
ica), Makato Nishino (IBM), Akira Ohsone (Nihon Sun), Chris Peterson (MIT), Sam
Shteingart (AT&T), Manish Sheth (AT&T), Bob Scheifler (MIT), Muneyoshi Suzuki
(NTT), Cori Mehring (Digital Equipment Co.), Frank Rojas (IBM), Shoji Sugiyama
(IBM), Eiji Tosa (IBM) Glenn Widener (Tektronix).
32