X Window System Input Method Specifications

bluespirit

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

bluespirit

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