Man Linux: Main Page and Category List

NAME

       UILib intro — User interface library intro

DESCRIPTION

       User  interface  libraries  are  responding  to one-chracter or one-key
       input, return various kinds of information.  They include  the  unfixed
       character  string,  fixed  character  string,  marked segment position,
       status display character string, and candidate list character string.

       The application program displays the data  according  to  the  returned
       information.  It can also control mode transition by triggering through
       something other than key pressing (for example, selection  through  the
       mouse).

       The  user  interface  library provides jrKanjiString and jrKanjiControl
       for the input through the TTY.  It also provides XLookupKanjiString and
       XKanjiControl for the input through the X window.

       Use of the user interface library requires the following:

       -  Through the TTY:

          Function            jrKanjiString, jrKanjiControl

          Header file         canna/jrkanji.h

          Library             libcanna.a, libcanna.so

       -  Through the X window:

          Function            XLookupKanjiString, XKanjiControl

          Header file         canna/kanji.h

          Library             libXn.a, libXn.so, libcanna.a, libcanna.so

Outline

       jrKanjiString       Converts ordinary keyboard input (input through the
                           TTY, input with X) into Kanji strings.

       jrKanjiControl      Executes the control with  jrKanjiString  according
                           to the specified parameters.

       XLookupKanjiString  Converts  the keyboard input (key event) into Kanji
                           strings in the X window system.

       XKanjiControl       Executes  the   control   with   XLookupKanjiString
                           according to the specified parameters.

NAME

       jrKanjiString — Kana-to-Kanji Conversion for ordinary keyboard input

SYNOPSIS

       #include <canna/jrkanji.h>
       int jrKanjiString(context_id, ch, buffer_return, bytes_buffer, kanji_status_return)
       int context_id;
       int ch;
       char *buffer_return;
       int bytes_buffer;
       jrKanjiStatus *kanji_status_return;

DESCRIPTION

       jrKanjiString  converts ordinary keyboard input (input through the TTY,
       input with X) into Kanji strings.

       jrKanjiString is a  convenient  routine  which  returns  the  character
       strings to be displayed.  To convert the key input represented in ASCII
       code, into the Japanese characters, jrKanjiString specifies  the  input
       key  code  using  ch.   Romaji-to-Kana  or  Kana-to-Kanji Conversion is
       executed in jrKanjiString.

       For a function or  cursor  key,  specify  a  special  code  (listed  in
       ‘‘FUNCTION KEYS’’ below) to jrKanjiString.  Do not specify the sequence
       caused by the key.

       For the context identifier specified in context_id, the  value  is  not
       used  as it is.  Instead, a context that uses the context identifier as
       the key is created and used.  Thus, the application program may specify
       any value for the context identifier to be specified for jrKanjiString.
       It is recommended that the input port’s file  descriptor  be  specified
       for this identifier.  If 0 is specified for the identifier, the context
       prepared as the system default will be used by way of exception.

       It is recommended that 0 be specified unless  particular  consideration
       is  given  to  the context.  The intermediate result to be displayed is
       returned to the application through kanji_status_return.

       Responding to the input, it is necessary to  display  the  intermediate
       result  of Romaji-to-Kana or Kana-to-Kanji Conversion.  The application
       must display the  intermediate  result  according  to  the  information
       returned   by   kanji_status_return,  which  is  a  jrKanjiStatus  type
       structure.

       The jrKanjiStatus structure is defined as follows:

       typedef struct {
         unsigned char *echoStr; /* Character string for local echo */
         int           length;   /* Length of the local echo character string */
         int           revPos;   /* Offset to the reverse display field
                                    within local echo character string */
         int           revLen;   /* Length of the reverse display within
                                    local echo echo character string */
         unsigned long info;     /* Other information */
         unsigned char *mode;    /* Mode information */
         struct {
           unsigned char *line;  /* Candidate list character string */
           int           length; /* Length of candidate list character string */
           int           revPos; /* Offset to the reverse display field
                                    within candidate list character string */
           int           revLen; /* Length of reverse display field within
                                    candidate list character string */
         } gline;                /* Information about the candidate list*/
       } jrKanjiStatus;

       When  Kana-to-Kanji  conversion  is   used   during   Japanese   input,
       information  such  as  the  readings  to be converted need to be echoed
       (local echo).  jrKanjiString does not perform  display  such  as  local
       echo.   Instead,  it  returns  the character strings to be submitted to
       local echo, to the application by using the jrKanjiStatus structure.

       The EUC character  strings  to  be  submitted  to  local  echo  include
       characters  already  converted  into  Kana  from  Romaji and conversion
       candidate characters.  Until the conversion is fixed, they are returned
       by  the  echoStr  member.   At  this  time,  the  length  of local echo
       character string is returned by the length member.  Also, the  starting
       position and length (bytes) of reverse display area are returned by the
       revPos and revLen member, respectively.   The  buffer  for  local  echo
       character  strings is reserved automatically by jrKanjiString.  It must
       be used only for reading.  No character string  must  be  written  into
       this buffer.

       If  no  character  string  is  to be submitted to local echo, 0 will be
       returned by the length member.

       The contents to be submitted to local echo may  be  the  same  as  when
       jrKanjiString was previously called.  (This occurs, for example, when a
       control code is pressed and the key is disabled.)   In  this  case,  -1
       returns to the length member.

       Mode  changes and existence of information about the candidate list are
       passed by the info member.  If info member’s KanjiModeInfo bit  is  on,
       the  character  string indicating the new mode will return to mode.  If
       the info member’s KanjiGLineInfo bit is on,  the  gline  structure  has
       contained information such as the candidate list.

       The  character  string  for candidate list display returns to the gline
       structure’s  line  member.   The  length,  reverse   dispaly   starting
       position,  and reverse display duration of the candidate list character
       string return to  the  gline  structure’s  line,  revPos,  and  revLen,
       respectively.

       If there is an EUC character string fixed during conversion, it will be
       stored into buffer buffer_return.  In this case, the length (bytes)  of
       this  character  string  will  return.  If  there is no fixed character
       string, the return value will be 0.  Using  bytes_buffer,  specify  the
       size  of  the  buffer  that  is  to  contain the fixed character string
       (buffer_return).   If  the  fixed  character  string  is  longer   than
       bytes_buffer,   only   the   bytes_buffer   substring  is  stored  into
       buffer_return.  In this case, the value specified in bytes_buffer  will
       be the return value of jrKanjiString.

FUNCTION KEYS

       For  any function key that issue an Escape sequence, specify one of the
       following codes as ch instead of the Escape sequence:

       Logical name
                   Code

       Nfer        CANNA_KEY_Nfer

       Xfer        CANNA_KEY_Xfer

       Up          CANNA_KEY_Up

       Left        CANNA_KEY_Left

       Right       CANNA_KEY_Right

       Down        CANNA_KEY_Down

       Insert      CANNA_KEY_Insert

       Rollup      CANNA_KEY_Rollup

       Rolldown    CANNA_KEY_Rolldown

       Home        CANNA_KEY_Home

       Help        CANNA_KEY_Help

       S-Nfer      CANNA_KEY_Shift_Nfer

       S-Xfer      CANNA_KEY_Shift_Xfer

       S-Up        CANNA_KEY_Shift_Up

       S-Left      CANNA_KEY_Shift_Left

       S-Right     CANNA_KEY_Shift_Right

       S-Down      CANNA_KEY_Shift_Down

       C-Nfer      CANNA_KEY_Control_Nfer

       C-Xfer      CANNA_KEY_Control_Xfer

       C-Up        CANNA_KEY_Control_Up

       C-Left      CANNA_KEY_Control_Left

       C-Right     CANNA_KEY_Control_Right

       C-Down      CANNA_KEY_Control_Down

       F1          CANNA_KEY_F1

       PF1         CANNA_KEY_PF1

SEE ALSO

       jrKanjiControl(3)

RETURN VALUE

       If an error occurs during input  processing,  -1  will  return  as  the
       return value of this function.  In this case, the error message will be
       stored in external variable (char*)jrKanjiError.

       If a call to this function causes a character string to be  fixed,  the
       length (bytes) of this character string will return.  Otherwise, 0 will
       return.

NAME

       jrKanjiControl — Control the jrKanjiControl modes and processes

SYNOPSIS

       #include <canna/jrkanji.h>
       int jrKanjiControl(context_id, request, arg)
       int context_id;
       int request;
       char *arg;

DESCRIPTION

       jrKanjiControl  executes  process  request   for   conversion   context
       context_id.   Some processes are accompanied by the argument, specified
       in arg.

       jrKanjiControl controls the following 13 functions:

       request name      Function

       KC_INITIALIZE     Initializes Kana-to-Kanji conversion.

       KC_CHANGEMODE     Changes the input mode.

       KC_SETWIDTH       Specifies the width used to display the candidate

       KC_FINALIZE       Finalizes   (terminates)   Kana-to-Kanji   conversion
                         processing.

       KC_SETUNDEFKEYFUNCTION
                         Sets a function for an undefined key.

       KC_SETMODEINFOSTYLE
                         Specifies  whether mode information is represented in
                         numeric form.

       KC_KAKUTEI        Fixes the currently entered character string.

       KC_KILL           Deletes the currently entered character string.

       KC_QUERYMODE      Queries about the current mode.

       KC_SETSERVERNAME  Specifies the server to be connected.

       KC_SETINITFILENAME
                         Specifies the customize file.

       KC_CLOSEUICONTEXT Closes the context.

       KC_QUERYMAXMODESTR
                         Obtains the maximum length of mode display  character
                         string.

       Basically,  jrKanjiControl  is  enabled only for something specified in
       the context.  This rule does not apply to the initialize and  terminate
       processes.

       The  unfixed  character  string condition may change, or details of the
       mode may vary, depending on the jrKanjiControl operation.  If this  may
       occur,  pass  the  pointer  to  a structure that can contain the varied
       information in the arg field.  This structure is defined as follows:

       typedef struct {
         int      val;          /* The length of the character string in the
                                   buffer returns. */
         unsigned char *buffer; /* Specifies the buffer used to store the
                                   fixed character string. */
         int      bytes_buffer; /* Specifies the size of the above buffer. */
         jrKanjiStatus *ks;     /* Pointer to the structure that contains
                                   information about the unfixed character string. */
       } jrKanjiStatusWithValue;

       The jrKanjiControl functions can be executed in the following ways:

       (1)   KC_INITIALIZE — Initializes Kana-to-Kanji conversion.

             KC_INITIALIZE initializes Kana-to-Kanji conversion by  specifying
             KC_INITIALIZE in the request field.  Specify one of the following
             in arg: (1) the pointer to the char  **  type  variable  used  to
             store the warning message and (2) NULL.

             The  initialize  process is basically executed automatically when
             jrKanjiString(3) is first  called.   This  is  skipped  by  using
             jrKanjiControl for initialization.

             For  example,  when  control  about  Kana-to-Kanji  conversion is
             executed using jrKanjiControl  before  use  of  jrKanjiString(3),
             Kana-to-Kanji conversion must be initialized.

             When   the   process   terminates  normally,  0  returns  as  the
             jrKanjiControl return value.  When it terminates  abnormally,  -1
             returns.

             When  KC_INITIALIZE is executed, a warning, rather than an error,
             may occur.  When it occurs, the pointer to the warning  character
             string  array  is stored in and returns to the variable specified
             in arg.  If no warning occurs, NULL is stored and returns.

             (Example)
               int res; /* Prepare for error return */
               char **warning;
               .....
               res = jrKanjiControl(0, KC_INITIALIZE, &warning);
               if (warning) {
                 char **p;

                 for (p = warning ; *p ; p++) {
                   fprintf(stderr, "%s0, *p);
                 }
               }

             In the library, malloc is done for the warning message  returning
             to  the third argument.  This message is freed when KC_INITIALIZE
             or KC_FINALIZE is executed next.  The application programmer must
             not   free  it.   The  maximum  number  of  warning  messages  is
             restricted to 64 now.  The subsequent ones are discarded.

             The following warnings may be included in a message:

             -  All  customize  files  including  those  of  the  system   are
                unavailable.

             -  The customize file contains a syntax error.

             -  The Romaji-to-Kana conversion dictionary is unavailable.

             -  The Kana-to-Kanji conversion dictionary is unavailable.

             -  Connection to the Kana-to-Kanji conversion server is disabled.

             If NULL is specified as the third argument, any  warning  message
             will be discarded.

       (2)   KC_CHANGEMODE — Changes the input mode.

             KC_CHANGEMODE  changes  the  input  mode  from  the  application.
             Specify  KC_CHANGEMODE  in  the  request  field.    Specify   the
             jrKanjiStatusWithValue structure in arg.

             The  Japanese  mode is changed by specifying the mode number with
             the val member of  jrKanjiStatusWithValue  structure.   The  mode
             number is indicated by the following macros:

             Macro number            Mode

             CANNA_MODE_AlphaMode    Alphabet mode

             CANNA_MODE_HenkanMode   Conversion input mode

             CANNA_MODE_KigoMode     Symbol input mode

             CANNA_MODE_ZenHiraKakuteiMode
                                     Full-wide Hiragana fixed input mode

             CANNA_MODE_ZenKataKakuteiMode
                                     Full-wide Katakana fixed mode

             CANNA_MODE_HanKataKakuteiMode
                                     Half-wide Katakana fixed input mode

             CANNA_MODE_ZenAlphaKakuteiMode
                                     Full-wide alphabet fixed input mode

             CANNA_MODE_HanAlphaKakuteiMode
                                     Half-wide alphabet fixed input mode

             CANNA_MODE_HexMode      Hexadecimal code input mode

             CANNA_MODE_BushuMode    Bushu input mode

             CANNA_MODE_TorokuMode   Word register mode

             This  function  causes  much  dispaly (mode name etc.) to vary in
             response to a mode change.  The display change is returned by the
             jrKanjiStatusWithValue structure specified as arg.

             (Example)
               jrKanjiStatus ks;
               jrKanjiStatusWithValue ksv;
               unsigned char buf[SOMESIZE];
               .....
               ksv.ks = &ks;
               ksv.buffer = buf;
               ksv.bytes_buffer = SOMESIZE;
               ksv.val = CANNA_MODE_HexMode;

               jrKanjiControl(context, KC_CHANGEMODE, &ksv);
               len = ksv.val;
               .....

             /* Information about the unfixed or fixed character string is returned
                by ksv. */

       (3)   KC_SETWIDTH  —  Specifies the width used to display the candidate
             list.

             KC_SETWIDTH specifies the number of columns of the area on  which
             the  candidate  list is to be displayed.  The width of one column
             equals that of an alphabetical or half-wide  Katakana  character.
             Each  full-wide  Kanji  character  occupies  two  columns.  Using
             KC_SETWIDTH, specify the width of candidate list display area  to
             be  specified  in  the  request field.  At this time, specify the
             number of columns in arg.

             (Example)
               jrKanjiControl(0, KC_SETWIDTH, (char *)60);

       (4)   KC_FINALIZE — Finalizes (terminates) processing of  Kana-to-Kanji
             conversion

             KC_FINALIZE   specifies   that   Kana-to-Kanji   conversion  also
             finalizes (terminates) at the end of the  program  and  in  other
             cases.
              Be  sure  to execute this process when terminating Kana-to-Kanji
             conversion processing.   All  contents  learned  up  to  now  are
             registered  in  the  file.   Specify  KC_FINALIZE  in the request
             field.

             When  the  process  terminates  normally,  0  returns.   When  it
             terminates abnormally, -1 returns.

             When  KC_FINALIZE  is  executed, a warning, rather than an error,
             may occur.  When it occurs, the pointer to the warning  character
             string  array  is stored in and returns to the variable specified
             in arg.  If no warning occurs, NULL is stored and returns.

             (Example)
               int res; /* Prepare for error return */
               char **warning;
               .....
               res = jrKanjiControl(0, KC_FINALIZE, &warning);
               if (warning) {
                 char **p;

                 for (p = warning ; *p ; p++) {
                   fprintf(stderr, "%s0, *p);
                 }
               }

             In the library, malloc is done for the warning message  returning
             to  the third argument.  This message is freed when KC_INITIALIZE
             or KC_FINALIZE is executed next.  The application programmer must
             not free it.

             The  maximum  number of warning messages is restricted to 64 now.
             The subsequent ones are discarded.

             The following warning may be included in a message:

             -  The dictionary cannot be unmounted.

             If NULL is specified as the third argument, any  warning  message
             will be discarded.

       (5)   KC_SETUNDEFKEYFUNCTION — Sets a function for an undefined key.

             For example, if you press CTRL-t during input of a reading, it is
             regarded as undefined key input.   The  following  processes  are
             executed, responding to undefined key input:

             Macro name  Process

             kc_normal   Beep

             kc_through  Passes the input to the application

             kc_kakutei  Fixes  the  input  and  passes  it to the application
                         program.

             kc_kill     Deletes the input and passes it  to  the  application
                         program.

             If  kc_normal is specified, the function set in external variable
             jrBeepFunc  is  called  automatically  by  the  library  when  an
             undefined  key  is input.  If the value is not set in jrBeepFunc,
             nothing occurs when ‘‘jrBeepFunc == NULL’’ appears.

             (Example)
               extern (*jrBeepFunc)(), beep();

               jrBeepFunc = beep;
               jrKanjiControl(0, KC_SETUNDEFKEYFUNCTION, kc_normal);

       (6)   KC_SETMODEINFOSTYLE — Specifies mode information  representation.

             You  may  want  to display mode information with data such as the
             bit map, rather than character strings.  In this case, return  of
             numeric  data  as mode information helps you execute the process.
             Specify KC_SETMODEINFOSTYLE in jrKanjiControl, and pass 1 to arg.
             After  this,  one  character representing the mode code (numeric)
             plus To convert the value into the mode code, subtract ’@’ (0x40)
             from  the returned character string.  For the mode codes, see the
             mode change description of Item (2) KC_CHANGEMODE.

       (7)   KC_KAKUTEI, (8) KC_KILL —  Kill  the  currently  input  character
             string.

             You may want to relinquish the currently entered character string
             for some reason.  There are two relinquishing methods.  One is to
             relinquish  the  character  string  after including the currently
             entered character string as a fixed one.  The other is to discard
             the  character  string  completely  then  relinquish it.  For the
             first method, specify  KC_KAKUTEI  in  jrKanjiControl.   For  the
             second method, specify KC_KILL.

             Each    of    the    above    influences    the   display.    The
             jrKanjiStatusWithValue  must  thus  be  specified  as  the  third
             argument.

             (Example)
               jrKanjiStatusWithValue ksv;
               jrKanjiStatus ks;
               unsigned char buf[SOMESIZE];
               .....
               ksv.ks = &ks;
               ksv.buffer = buf;
               ksv.bytes_buffer = SOMESIZE;

               jrKanjiControl(context, KC_KAKUTEI, &ksv);
               len = ksv.val;
               .....

       (9)   KC_QUERYMODE — Inquiry about the mode

             To  inquire  about  the  current  mode,  specify  KC_QUERYMODE in
             jrKanjiControl.

             Specify the pointer to the character  array  in  which  the  mode
             character string is to be stored.  The mode character string is a
             character string ending with  a  null  character.   To  return  a
             numeric  here,  specify  KC_SETMODEINFOSTYLE in jrKanjiControl to
             change the mode character string style.

             (Example)
               char currentMode[MAXMODELEN];
               .....
               jrKanjiControl(0, KC_QUERYMODE, currentMode);
               .....

       (10)  KC_SETSERVERNAME   Specifies the server to be connected.

             KC_SETSERVERNAME  enables  you  to   switch   the   Kana-to-Kanji
             conversion  server  without  terminating the application program.
             To set the server to  connect  as  the  Kana-to-Kanji  conversion
             server, specify KC_SETSERVERNAME in jrKanjiControl.  In the third
             argument, specify the name of the server to be connected.

       (11)  KC_SETINITFILENAME — Specifies the customize file.

             KC_SETINITFILENAM enables the application program to  change  the
             customize   file.    To   change   the  customize  file,  specify
             KC_SETINITFILENAME as the  second  argument  and  the  file  name
             character  string  as  the  third argument.  This process must be
             executed before KC_INTIALIZE.

             (Example)
               char *inifile = "app-own.canna"
               .....
               jrKanjiControl(0, KC_SETINITFILENAME, initfile);
               .....

       (12)  KC_CLOSEUICONTEXT   Closes the context.

             Any integer may be assigned as the context ID that represents the
             conversion context.  A context ID that has never been used can be
             assigned to  jrKanjiString  or  jrKanjiControl.   In  this  case,
             initialization  for  this  context  is  executed  to  reserve the
             required memory.

             If an input port used up to now is not used, you may want to free
             the memory reserved for the context ID assigned to this port.  To
             do so, call jrKanjiControl by specifying KC_CLOSEUICONTEXT as the
             second argument.

             Because   this   process   causes   a   display  change,  specify
             jrKanjiStatusWithValue as the third structure.

             (Example)
               jrKanjiStatusWithValue ksv;
               jrKanjiStatus ks;
               unsigned char buf[SOMESIZE];
               .....
               ksv.ks = &ks;
               ksv.buffer = buf;
               ksv.bytes_buffer = SOMESIZE;

               jrKanjiControl(0, KC_CLOSEUICONTEXT, &ksv);
               .....

       (13)  KC_QUERYMAXMODESTR — Obtains the maximum length of  mode  display
             character string.

             The  mode  display  character  string can be customized using the
             initialize file.  It is necessary to  examine  the  size  of  the
             display  area (in the customized resulting mode display character
             string) that is to be reserved.   Specify  KC_QUERYMAXMODESTR  as
             the  second argument, then call jrKanjiControl.  As a result, the
             number of columns necessary for the mode display character string
             is returned.  The number of columns is represented, defining that
             the width of one half-wide alphanumeric character is 1.

             The third argument is unused; dummy value 0 is assigned to it.

             (Example)
               int max_mode_columns;
               .....
               max_mode_columns = jrKanjiControl(0, KC_QUERYMAXMODESTR, 0);
               .....

NAME

       XLookupKanjiString — Converts the keyboard input into Kanji

SYNOPSIS

       #include <X11/Xlib.h>
       #include <X11/kanji.h>

       int
       XLookupKanjiString(event_struct, buffer_return, bytes_buffer,
                          keysym_return, status_return, kanji_status_return)
               XKeyEvent *event_struct;
               char *buffer_return;
               int bytes_buffer;
               KeySym *keysym_return;
               XComposeStatus *status_return;
               XKanjiStatus *kanji_status_return;

ARGUMENTS

              event_struct    Specifies the key event.

              buffer_return   Returns the resulting Kanji string.

              bytes_buffer    Specifies the buffer length.

              keysym_return   Returns the key symbol.  NULL may be specified

              status_return   Specifies the pointer to the XCompose structure.

              kanji_status_return
                              Returns the Kana-to-Kanji conversion status.

DESCRIPTION

       XLookupKanjiString  is a convenient routine that associates a key event
       with a Japanese character string.  It uses  the  modifier  key  bit  to
       processes such as shift, lock, and control.

       XLookupKanjiString  enables eight- and 16-bit Japanese characters to be
       processed.

       XLookupKanjiString processes alphabetical characters in the same way as
       XLookupString.

       For  Japanese character processing, Romaji-to-Kana conversion and Kana-
       to-Kanji conversion are  done  in  this  function.   The  XKanjiStatus,
       defined below, is used during Japanese data input:

            typedef struct _XKanjiStatus {
                unsigned char *echoStr;     /* local echo string */
                int length;                  /* length of echo string */
                int revPos;                 /* reverse position  */
                int revLen;                 /* reverse length    */
                unsigned long info;       /* other informations */
                unsigned char *mode; /* mode information */
                struct {
                 unsigned char *line;     /* a grance of Kanji characters */
                 int length;         /* length of it */
                 int revPos;         /* reverse position of it */
                 int revLen;         /* reverse length of it */
                } gline;             /* a grancing line information */
            } XKanjiStatus;

            #define KanjiModeInfo    01
            #define KanjiGLineInfo   02

       When   Kana-to-Kanji   conversion   is   used  during  Japanese  input,
       information such as the readings to be  converted  need  to  be  echoed
       (local  echo).   XLookupKanjiString  does  not  perform display such as
       local echo.  Instead, it returns the character strings to be  submitted
       to  local echo, to the application by using the XKanjiStatus structure.

       The EUC character  strings  to  be  submitted  to  local  echo  include
       characters  already  converted  into  Kana  from  Romaji and conversion
       candidate characters.  Until the conversion is fixed, they are returned
       by  the  echoStr  member.   At  this  time,  the  length  of local echo
       character string is returned by the length member.  Also, the  starting
       position  and  length  (bytes)  of  reverse display are returned by the
       revPos and revLen member, respectively.   The  buffer  for  local  echo
       character  strings is reserved automatically by XLookupKanjiString.  It
       should be used only for reading.  No character string must  be  written
       into this buffer.

       If  no character string is to be submitted to local echo, 0 will return
       to the length member.

       The contents to be submitted to local echo may  be  the  same  as  when
       XLookupKanjiString  was  previously called.  (This occurs, for example,
       when the Shift key is pressed.)  In this case, -1 returns to the length
       member.

       Mode  changes and existence of information about the candidate list are
       passed by the info member.  If info member’s KanjiModeInfo bit  is  on,
       the  character  string indicating the new mode will return to mode.  If
       the info member’s KanjiGLineInfo bit is on,  the  gline  structure  has
       contained information such as the candidate list.

       The  character  string  for candidate list display returns to the gline
       structure’s  line  member.   The  length,  reverse   dispaly   starting
       position,  and reverse display duration of the candidate list character
       string return to  the  gline  structure’s  line,  revPos,  and  revLen,
       respectively.

       If there is an EUC character string fixed during conversion, it will be
       stored in buffer_return.  In this case,  the  length  (bytes)  of  this
       character  string will return as the return value of this function.  If
       there is no fixed character string, the return value will be 0.

NAME

       XKanjiControl — Control the XLookupKanjiString mode and process.

SYNOPSIS

       #include <X11/kanji.h>
       int XKanjiControl(dpy, win, request, arg)
       Display dpy;
       Window win;
       int request;
       char *arg;

DESCRIPTION

       XKanjiControl executes a process that relates to Japanese input  within
       the  window  defined  by  dpy  and  win.   The  process is specified in
       request.  Some processes are accompanied by the argument, specified  in
       arg.

       XKanjiControl controls the following functions:

       request name      Function

       KC_INITIALIZE     Initializes Kana-to-Kanji conversion.

       KC_CHANGEMODE     Changes the input mode.

       KC_SETWIDTH       Specifies the width used to display the candidate

       KC_FINALIZE       Finalizes   (terminates)   Kana-to-Kanji   conversion
                         processing.

       KC_SETUNDEFKEYFUNCTION
                         Sets a function for an undefined key.

       KC_SETMODEINFOSTYLE
                         Specifies whether mode information is represented  in
                         numeric form.

       KC_KAKUTEI        Fixes the currently entered character string.

       KC_KILL           Deletes the currently entered character string.

       KC_QUERYMODE      Queries about the current mode.

       KC_SETSERVERNAME  Specifies the server to be connected.

       KC_SETINITFILENAME
                         Specifies the customize file.

       KC_CLOSEUICONTEXT Closes the context.

       KC_QUERYMAXMODESTR
                         Obtains  the maximum length of mode display character
                         string.

       Basically, XKanjiControl is enabled only for the  window  specified  in
       the  dpy  and  win.   This  rule  does  not apply to the initialize and
       terminate processes.

       The unfixed character string condition may change, or  details  of  the
       mode  may  vary, depending on the XKanjiControl operation.  If this may
       occur, pass the pointer to a structure  that  can  contain  the  varied
       information in the arg field.  This structure is defined as follows:

       typedef struct {
         int      val;          /* The length of the character string in the
                                   buffer returns. */
         unsigned char *buffer; /* Specifies the buffer used to store the
                                   fixed character string. */
         int      bytes_buffer; /* Specifies the size of the above buffer. */
         XKanjiStatus *ks;      /* Pointer to the structure that contains
                                   information about the unfixed character string. */
       } XKanjiStatusWithValue;

       The XKanjiControl functions can be executed in the following ways:

       (1)   KC_INITIALIZE — Initializes Kana-to-Kanji conversion.

             KC_INITIALIZE  initializes Kana-to-Kanji conversion by specifying
             KC_INITIALIZE in the request field.  Specify one of the following
             in  arg:  (1)  the  pointer  to the char ** type variable used to
             store the warning message and (2) NULL.  The  initialize  process
             is basically executed automatically when XLookupKanjiString(3) is
             first  called.   This  is  skipped  by  using  XKanjiControl  for
             initialization.

             For  example,  when  control  about  Kana-to-Kanji  conversion is
             executed using XKanjiControl before use of XLookupKanjiString(3),
             Kana-to-Kanji conversion must be initialized.

             When   the   process   terminates  normally,  0  returns  as  the
             XKanjiControl return value.  When it  terminates  abnormally,  -1
             returns.

             When  KC_INITIALIZE is executed, a warning, rather than an error,
             may occur.  When it occurs, the pointer to the warning  character
             string  array  is stored in and returns to the variable specified
             in arg.  If no warning occurs, NULL is stored and returns.

             (Example)
               int res; /* Prepare for error return */
               char **warning;
               .....
               res = XKanjiControl(dpy, win, KC_INITIALIZE, &warning);
               if (warning) {
                 char **p;

                 for (p = warning ; *p ; p++) {
                   fprintf(stderr, "%s0, *p);
                 }
               }

             In the library, malloc is done for the warning message  returning
             to the fourth argument.  This message is freed when KC_INITIALIZE
             or KC_FINALIZE is executed next.  The application programmer must
             not   free  it.   The  maximum  number  of  warning  messages  is
             restricted to 64 now.  The subsequent ones are discarded.

             The following warnings may be included in a message:

             -  All  customize  files  including  those  of  the  system   are
                unavailable.

             -  The customize file contains a syntax error.

             -  The Romaji-to-Kana conversion dictionary is unavailable.

             -  The Kana-to-Kanji conversion dictionary is unavailable.

             -  Connection to the Kana-to-Kanji conversion server is disabled.

             If NULL is specified as the fourth argument, any warning  message
             will be discarded.

       (2)   KC_CHANGEMODE — Changes the input mode.

             KC_CHANGEMODE  changes  the  input  mode  from  the  application.
             Specify  KC_CHANGEMODE  in  the  request  field.    Specify   the
             XKanjiStatusWithValue  structure  in  arg.   The Japanese mode is
             changed by specifying the mode number  with  the  val  member  of
             XKanjiStatusWithValue structure.  The mode number is indicated by
             the following macros:

             Macro number            Mode

             CANNA_MODE_AlphaMode    Alphabet mode

             CANNA_MODE_HenkanMode   Conversion input mode

             CANNA_MODE_KigoMode     Symbol input mode

             CANNA_MODE_ZenHiraKakuteiMode
                                     Full-wide Hiragana fixed input mode

             CANNA_MODE_ZenKataKakuteiMode
                                     Full-wide Katakana fixed mode

             CANNA_MODE_HanKataKakuteiMode
                                     Half-wide Katakana fixed input mode

             CANNA_MODE_ZenAlphaKakuteiMode
                                     Full-wide alphabet fixed input mode

             CANNA_MODE_HanAlphaKakuteiMode
                                     Half-wide alphabet fixed input mode

             CANNA_MODE_HexMode      Hexadecimal code input mode

             CANNA_MODE_BushuMode    Bushu input mode

             CANNA_MODE_TorokuMode   Word register mode

             This function causes much dispaly (mode name  etc.)  to  vary  in
             response to a mode change.  The display change is returned by the
             XKanjiStatusWithValue structure specified as arg.

             (Example)
               XKanjiStatus ks;
               XKanjiStatusWithValue ksv;
               unsigned char buf[SOMESIZE];
               .....
               ksv.ks = &ks;
               ksv.buffer = buf;
               ksv.bytes_buffer = SOMESIZE;
               ksv.val = CANNA_MODE_HexMode;

               XKanjiControl(dpy, win, KC_CHANGEMODE, &ksv);
               len = ksv.val;
               .....
               /* Information about the unfixed or fixed character string is
                  returned by ksv. */

       (3)   KC_SETWIDTH — Specifies the width used to display  the  candidate
             list.

             KC_SETWIDTH  specifies the number of columns of the area on which
             the candidate list is to be displayed.  The width of  one  column
             equals  that  of an alphabetical or half-wide Katakana character.
             Each full-wide  Kanji  character  occupies  two  columns.   Using
             KC_SETWIDTH,  specify the width of candidate list display area to
             be specified in the request field.  At  this  time,  specify  the
             number of columns in arg.

             (Example)
               XKanjiControl(dpy, win, KC_SETWIDTH, (char *)60);

       (4)   KC_FINALIZE  — Finalizes (terminates) processing of Kana-to-Kanji
             conversion

             KC_FINALIZE  specifies   that   Kana-to-Kanji   conversion   also
             finalizes  (terminates)  at  the  end of the program and in other
             cases.  Be sure to execute this process when terminating Kana-to-
             Kanji  conversion processing.  All contents learned up to now are
             registered in the  file.   Specify  KC_FINALIZE  in  the  request
             field.

             When  the  process  terminates  normally,  0  returns.   When  it
             terminates abnormally, -1 returns.

             When KC_INITIALIZE is executed, a warning, rather than an  error,
             may  occur.  When it occurs, the pointer to the warning character
             string array is stored in and returns to the  variable  specified
             in arg.  If no warning occurs, NULL is stored and returns.

             (Example)
               int res; /* Prepare for error return */
               char **warning;
               .....
               res = XKanjiControl(dpy, win, KC_FINALIZE, &warning);
               if (warning) {
                 char **p;

                 for (p = warning ; *p ; p++) {
                   fprintf(stderr, "%s0, *p);
                 }
               }

             In  the library, malloc is done for the warning message returning
             to the fourth argument.  This message is freed when KC_INITIALIZE
             or KC_FINALIZE is executed next.  The application programmer must
             not free it.

             The maximum number of warning messages is restricted to  64  now.
             The subsequent ones are discarded.

             The following warning may be included in a message:

             -  The dictionary cannot be unmounted.

             If  NULL is specified as the fourth argument, any warning message
             will be discarded.

       (5)   KC_SETUNDEFKEYFUNCTION — Sets a function for an undefined key.

             For example, if you press CTRL-t during input of a reading, it is
             regarded  as  undefined  key  input.  The following processes are
             executed, responding to undefined key input:

             Macro name  Process

             kc_normal   Beep

             kc_through  Passes the input to the application program.

             kc_kakutei  Fixes the input and  passes  it  to  the  application
                         program.

             kc_kill     Deletes  the  input  and passes it to the application
                         program.

             If kc_normal is specified, the function set in external  variable
             jrBeepFunc  is  called  automatically  by  the  library  when  an
             undefined key is input.  If the value is not set  in  jrBeepFunc,
             nothing occurs when "jrBeepFunc == NULL" appears.

             (Example)
               extern (*jrBeepFunc)(), beep();

               jrBeepFunc = beep;
               XKanjiControl(dpy, win, KC_SETUNDEFKEYFUNCTION, kc_normal);

       (6)   KC_SETMODEINFOSTYLE  — Specifies mode information representation.

             You may want to display mode information with data  such  as  the
             bit  map, rather than character strings.  In this case, return of
             numeric data as mode information helps you execute  the  process.
             Specify  KC_SETMODEINFOSTYLE in XKanjiControl, and pass 1 to arg.
             After this, one character representing the  mode  code  (numeric)
             plus To convert the value into the mode code, subtract ’@’ (0x40)
             from the returned character string.  For the mode codes, see  the
             mode change description of Item (2) KC_CHANGEMODE.

       (7)   KC_KAKUTEI,  (8)  KC_KILL  —  Kill  the currently input character
             string.

             You may want to relinquish the currently entered character string
             for some reason.  There are two relinquishing methods.  One is to
             relinquish the character string  after  including  the  currently
             entered character string as a fixed one.  The other is to discard
             the character string completely  then  relinquish  it.   For  the
             first  method,  specify  KC_KAKUTEI  in  jrKanjiControl.  For the
             second method, specify KC_KILL.

             Each   of   the    above    influences    the    display.     The
             XKanjiStatusWithValue  must  thus  be  specified  as  the  fourth
             argument.

             (Example)
               XKanjiStatusWithValue ksv;
               XKanjiStatus ks;
               unsigned char buf[SOMESIZE];
               .....
               ksv.ks = &ks;
               ksv.buffer = buf;
               ksv.bytes_buffer = SOMESIZE;

               XKanjiControl(dpy, win, KC_KAKUTEI, &ksv);
               len = ksv.val;
               .....

       (9)   KC_QUERYMODE — Inquiry about the mode

             To inquire  about  the  current  mode,  specify  KC_QUERYMODE  in
             XKanjiControl.

             Specify  the  pointer  to  the  character array in which the mode
             character string is to be stored.  The mode character string is a
             character  string  ending  with  a  null  character.  To return a
             numeric here, specify  KC_SETMODEINFOSTYLE  in  XKanjiControl  to
             change the mode character string style.

             (Example)
               char currentMode[MAXMODELEN];
               .....
               XKanjiControl(dpy, win, KC_QUERYMODE, currentMode);
               .....

       (10)  KC_SETSERVERNAME — Specifies the server to be connected.

             KC_SETSERVERNAME   enables   you   to  switch  the  Kana-to-Kanji
             conversion server without terminating  the  application  program.
             To  set  the  server  to  connect as the Kana-to-Kanji conversion
             server, specify KC_SETSERVERNAME in XKanjiControl.  In the fourth
             argument, specify the name of the server to be connected.

       (11)  KC_SETINITFILENAME — Specifies the customize file.

             KC_SETINITFILENAM  enables  the application program to change the
             customize  file.   To  change   the   customize   file,   specify
             KC_SETINITFILENAME  as  the  third  argument  and  the  file name
             character string as the fourth argument.  This  process  must  be
             executed before KC_INTIALIZE.

             (Example)
               char *inifile = "app-own.canna"
               .....
               XKanjiControl(dpy, win, KC_SETINITFILENAME, initfile);
               .....

       (12)  KC_CLOSEUICONTEXT   Closes the context.

             When   XKanjiControl   or   XLookupKanjiString   is  called,  one
             conversion context is assigned to combination  of  dpy  and  win.
             Combination  of  dpy  and  win  not used yet can be specified for
             XKanjiControl or XLookupKanjiString.  When this is  done,  a  new
             context  is  created  for  the  window and the required memory is
             reserved.

             If a window used up to now is not used, you may want to free  the
             context  memory that has been assigned to this window.  To do so,
             call XKanjiControl by specifying KC_CLOSEUICONTEXT as  the  third
             argument.

             Because   this   process   causes   a   display  change,  specify
             XKanjiStatusWithValue as the fourth structure.

             (Example)
               XKanjiStatusWithValue ksv;
               XKanjiStatus ks;
               unsigned char buf[SOMESIZE];
               .....
               ksv.ks = &ks;
               ksv.buffer = buf;
               ksv.bytes_buffer = SOMESIZE;

               XKanjiControl(dpy, win, KC_CLOSEUICONTEXT, &ksv);
               .....

       (13)  KC_QUERYMAXMODESTR — Obtains the maximum length of  mode  display
             character string.

             The  mode  display  character  string can be customized using the
             initialize file.  It is necessary to  examine  the  size  of  the
             display  area (in the customized resulting mode display character
             string) that is to be reserved.   Specify  KC_QUERYMAXMODESTR  as
             the  third  argument,  then call XKanjiControl.  As a result, the
             number of columns necessary for the mode display character string
             is  returned.   (The  number  of columns is represented, defining
             that the width of one half-wide alphanumeric character is 1.

             The fourth argument is unused; dummy value 0 is assigned to it.

             (Example)
               int max_mode_columns;
               .....
               max_mode_columns = XKanjiControl(dpy, win, KC_QUERYMAXMODESTR, 0);
               .....