xim.txt

linux 下的 oxim 输入法,简单易用.

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;