xim.txt

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

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 ;