jrKanjiControl(3)

XKanjiControl — Control the XLookupKanjiString mode and process.

Section 3 libcanna1g-dev bookworm source

Description

UILIBINTROJRKANJISTRING

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.

JRKANJICONTROL

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

.....

XLookupKanjiString

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.

XKANJICONTROL

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

.....

See Also