XLookupKanjiString(3)
XKanjiControl — Control the XLookupKanjiString mode and process.
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);
.....