--- name: "uilib" section: "3" platform: "linux" package: "libcanna1g-dev" version: "3.7p3-25" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/uilib" --- # uilib(3) User interface library intro ## 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 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)](/jrKanjiControl/3.md) ## 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 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)](/jrKanjiString/3.md) 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)](/jrKanjiString/3.md), 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 #include ``` **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 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)](/XLookupKanjiString/3.md) 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)](/XLookupKanjiString/3.md), 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); ..... ```