xim.txt

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

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