UILib_intro — User interface library intro

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

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.

(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);
}
}

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)

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

Name

       XKanjiControl — Control the XLookupKanjiString mode and process.

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.

                                                                                                   UILIBINTRO(3)
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────
JRKANJISTRING(3)                            Library Functions Manual                            JRKANJISTRING(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.

                                                                                                JRKANJISTRING(3)
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────
JRKANJICONTROL(3)                           Library Functions Manual                           JRKANJICONTROL(3)

Synopsis

#include<X11/kanji.h>intXKanjiControl(dpy,win,request,arg)Displaydpy;Windowwin;intrequest;char*arg;