Provided by: libcanna1g-dev_3.7p3-20_amd64 bug

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 ´@'
             (0x40) returns to the jrKanjiStatus structure's mode member.  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 information */
                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 ´@'
             (0x40) returns to the XKanjiStatus structure's mode member.  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);
               .....

                                                                                 XKANJICONTROL(3)