uilib

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:

-

Through the X window:

Outline

jrKanjiString

Converts ordinary keyboard input (input through the TTY, input with X) into Kanji strings.

jrKanjiControl

Executes the control with jrKanjiString according to the specified parameters.

XLookupKanjiString

Converts the keyboard input (key event) into Kanji strings in the X window system.

XKanjiControl

Executes the control with XLookupKanjiString according to the specified parameters.

NAME

jrKanjiString — Kana-to-Kanji Conversion for ordinary keyboard input

SYNOPSIS

#include <canna/jrkanji.h>
int jrKanjiString(context_id, ch, buffer_return, bytes_buffer, kanji_status_return)
int context_id;
int ch;
char *buffer_return;
int bytes_buffer;
jrKanjiStatus *kanji_status_return;

DESCRIPTION

jrKanjiString converts ordinary keyboard input (input through the TTY, input with X) into Kanji strings. jrKanjiString is a convenient routine which returns the character strings to be displayed. To convert the key input represented in ASCII code, into the Japanese characters, jrKanjiString specifies the input key code using ch. Romaji-to-Kana or Kana-to-Kanji Conversion is executed in jrKanjiString. For a function or cursor key, specify a special code (listed in ``FUNCTION KEYS'' below) to jrKanjiString. Do not specify the sequence caused by the key. For the context identifier specified in context_id, the value is not used as it is. Instead, a context that uses the context identifier as the key is created and used. Thus, the application program may specify any value for the context identifier to be specified for jrKanjiString. It is recommended that the input port's file descriptor be specified for this identifier. If 0 is specified for the identifier, the context prepared as the system default will be used by way of exception. It is recommended that 0 be specified unless particular consideration is given to the context. The intermediate result to be displayed is returned to the application through kanji_status_return. Responding to the input, it is necessary to display the intermediate result of Romaji-to-Kana or Kana-to-Kanji Conversion. The application must display the intermediate result according to the information returned by kanji_status_return, which is a jrKanjiStatus type structure. The jrKanjiStatus structure is defined as follows:

typedef struct {
  unsigned char *echoStr; /* Character string for local echo */
  int           length;   /* Length of the local echo character string */
  int           revPos;   /* Offset to the reverse display field
                             within local echo character string */
  int           revLen;   /* Length of the reverse display within
                             local echo echo character string */
  unsigned long info;     /* Other information */
  unsigned char *mode;    /* Mode information */
  struct {
    unsigned char *line;  /* Candidate list character string */
    int           length; /* Length of candidate list character string */
    int           revPos; /* Offset to the reverse display field
                             within candidate list character string */
    int           revLen; /* Length of reverse display field within
                             candidate list character string */
  } gline;                /* Information about the candidate list*/
} jrKanjiStatus;

When Kana-to-Kanji conversion is used during Japanese input, information such as the readings to be converted need to be echoed (local echo). jrKanjiString does not perform display such as local echo. Instead, it returns the character strings to be submitted to local echo, to the application by using the jrKanjiStatus structure. The EUC character strings to be submitted to local echo include characters already converted into Kana from Romaji and conversion candidate characters. Until the conversion is fixed, they are returned by the echoStr member. At this time, the length of local echo character string is returned by the length member. Also, the starting position and length (bytes) of reverse display area are returned by the revPos and revLen member, respectively. The buffer for local echo character strings is reserved automatically by jrKanjiString. It must be used only for reading. No character string must be written into this buffer. If no character string is to be submitted to local echo, 0 will be returned by the length member. The contents to be submitted to local echo may be the same as when jrKanjiString was previously called. (This occurs, for example, when a control code is pressed and the key is disabled.) In this case, -1 returns to the length member. Mode changes and existence of information about the candidate list are passed by the info member. If info member's KanjiModeInfo bit is on, the character string indicating the new mode will return to mode. If the info member's KanjiGLineInfo bit is on, the gline structure has contained information such as the candidate list. The character string for candidate list display returns to the gline structure's line member. The length, reverse dispaly starting position, and reverse display duration of the candidate list character string return to the gline structure's line, revPos, and revLen, respectively. If there is an EUC character string fixed during conversion, it will be stored into buffer buffer_return. In this case, the length (bytes) of this character string will return. If there is no fixed character string, the return value will be 0. Using bytes_buffer, specify the size of the buffer that is to contain the fixed character string ( buffer_return). If the fixed character string is longer than bytes_buffer, only the bytes_buffer substring is stored into buffer_return. In this case, the value specified in bytes_buffer will be the return value of jrKanjiString.

FUNCTION KEYS

For any function key that issue an Escape sequence, specify one of the following codes as ch instead of the Escape sequence:

Logical name

Code

Nfer

CANNA_KEY_Nfer

Xfer

CANNA_KEY_Xfer

Up

CANNA_KEY_Up

Left

CANNA_KEY_Left

Right

CANNA_KEY_Right

Down

CANNA_KEY_Down

Insert

CANNA_KEY_Insert

Rollup

CANNA_KEY_Rollup

Rolldown

CANNA_KEY_Rolldown

Home

CANNA_KEY_Home

Help

CANNA_KEY_Help

S-Nfer

CANNA_KEY_Shift_Nfer

S-Xfer

CANNA_KEY_Shift_Xfer

S-Up

CANNA_KEY_Shift_Up

S-Left

CANNA_KEY_Shift_Left

S-Right

CANNA_KEY_Shift_Right

S-Down

CANNA_KEY_Shift_Down

C-Nfer

CANNA_KEY_Control_Nfer

C-Xfer

CANNA_KEY_Control_Xfer

C-Up

CANNA_KEY_Control_Up

C-Left

CANNA_KEY_Control_Left

C-Right

CANNA_KEY_Control_Right

C-Down

CANNA_KEY_Control_Down

F1

CANNA_KEY_F1

PF1

CANNA_KEY_PF1

SEE ALSO

jrKanjiControl(3)

RETURN VALUE

If an error occurs during input processing, -1 will return as the return value of this function. In this case, the error message will be stored in external variable (char*)jrKanjiError. If a call to this function causes a character string to be fixed, the length (bytes) of this character string will return. Otherwise, 0 will return.

NAME

jrKanjiControl — Control the jrKanjiControl modes and processes

SYNOPSIS

#include <canna/jrkanji.h>
int jrKanjiControl(context_id, request, arg)
int context_id;
int request;
char *arg;

DESCRIPTION

jrKanjiControl executes process request for conversion context context_id. Some processes are accompanied by the argument, specified in arg. jrKanjiControl controls the following 13 functions:

request name

Function

KC_INITIALIZE

Initializes Kana-to-Kanji conversion.

KC_CHANGEMODE

Changes the input mode.

KC_SETWIDTH

Specifies the width used to display the candidate

KC_FINALIZE

Finalizes (terminates) Kana-to-Kanji conversion processing.

KC_SETUNDEFKEYFUNCTION

Sets a function for an undefined key.

KC_SETMODEINFOSTYLE

Specifies whether mode information is represented in numeric form.

KC_KAKUTEI

Fixes the currently entered character string.

KC_KILL

Deletes the currently entered character string.

KC_QUERYMODE

Queries about the current mode.

KC_SETSERVERNAME

Specifies the server to be connected.

KC_SETINITFILENAME

Specifies the customize file.

KC_CLOSEUICONTEXT

Closes the context.

KC_QUERYMAXMODESTR

Obtains the maximum length of mode display character string.

Basically, jrKanjiControl is enabled only for something specified in the context. This rule does not apply to the initialize and terminate processes. The unfixed character string condition may change, or details of the mode may vary, depending on the jrKanjiControl operation. If this may occur, pass the pointer to a structure that can contain the varied information in the arg field. This structure is defined as follows:

typedef struct {
  int      val;          /* The length of the character string in the
                            buffer returns. */
  unsigned char *buffer; /* Specifies the buffer used to store the
                            fixed character string. */
  int      bytes_buffer; /* Specifies the size of the above buffer. */
  jrKanjiStatus *ks;     /* Pointer to the structure that contains
                            information about the unfixed character string. */
} jrKanjiStatusWithValue;

The jrKanjiControl functions can be executed in the following ways:

(1)

KC_INITIALIZE — Initializes Kana-to-Kanji conversion.

(2)

KC_CHANGEMODE — Changes the input mode.

(3)

KC_SETWIDTH — Specifies the width used to display the candidate list.

(4)

KC_FINALIZE — Finalizes (terminates) processing of Kana-to-Kanji conversion

(5)

KC_SETUNDEFKEYFUNCTION — Sets a function for an undefined key.

(6)

KC_SETMODEINFOSTYLE — Specifies mode information representation.

(7)

KC_KAKUTEI, (8) KC_KILL — Kill the currently input character string.

(9)

KC_QUERYMODE — Inquiry about the mode

(10)

KC_SETSERVERNAME Specifies the server to be connected.

(11)

KC_SETINITFILENAME — Specifies the customize file.

(12)

KC_CLOSEUICONTEXT Closes the context.

(13)

KC_QUERYMAXMODESTR — Obtains the maximum length of mode display character string.

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

DESCRIPTION

XLookupKanjiString is a convenient routine that associates a key event with a Japanese character string. It uses the modifier key bit to processes such as shift, lock, and control. XLookupKanjiString enables eight- and 16-bit Japanese characters to be processed. XLookupKanjiString processes alphabetical characters in the same way as XLookupString. For Japanese character processing, Romaji-to-Kana conversion and Kana-to-Kanji conversion are done in this function. The XKanjiStatus, defined below, is used during Japanese data input:

	typedef struct _XKanjiStatus {
	    unsigned char *echoStr;     /* local echo string */
	    int length;		        /* length of echo string */
	    int revPos;                 /* reverse position  */
	    int revLen;                 /* reverse length    */
	    unsigned long info;		/* other information */
	    unsigned char *mode;	/* mode information */
	    struct {
		unsigned char *line;	/* a grance of Kanji characters */
		int length;		/* length of it */
		int revPos;		/* reverse position of it */
		int revLen;		/* reverse length of it */
	    } gline;			/* a grancing line information */
	} XKanjiStatus;

	#define KanjiModeInfo	01
	#define KanjiGLineInfo	02

When Kana-to-Kanji conversion is used during Japanese input, information such as the readings to be converted need to be echoed (local echo). XLookupKanjiString does not perform display such as local echo. Instead, it returns the character strings to be submitted to local echo, to the application by using the XKanjiStatus structure. The EUC character strings to be submitted to local echo include characters already converted into Kana from Romaji and conversion candidate characters. Until the conversion is fixed, they are returned by the echoStr member. At this time, the length of local echo character string is returned by the length member. Also, the starting position and length (bytes) of reverse display are returned by the revPos and revLen member, respectively. The buffer for local echo character strings is reserved automatically by XLookupKanjiString. It should be used only for reading. No character string must be written into this buffer. If no character string is to be submitted to local echo, 0 will return to the length member. The contents to be submitted to local echo may be the same as when XLookupKanjiString was previously called. (This occurs, for example, when the Shift key is pressed.) In this case, -1 returns to the length member. Mode changes and existence of information about the candidate list are passed by the info member. If info member's KanjiModeInfo bit is on, the character string indicating the new mode will return to mode. If the info member's KanjiGLineInfo bit is on, the gline structure has contained information such as the candidate list. The character string for candidate list display returns to the gline structure's line member. The length, reverse dispaly starting position, and reverse display duration of the candidate list character string return to the gline structure's line, revPos, and revLen, respectively. If there is an EUC character string fixed during conversion, it will be stored in buffer_return. In this case, the length (bytes) of this character string will return as the return value of this function. If there is no fixed character string, the return value will be 0.

NAME

XKanjiControl — Control the XLookupKanjiString mode and process.

SYNOPSIS

#include <X11/kanji.h>
int XKanjiControl(dpy, win, request, arg)
Display dpy;
Window win;
int request;
char *arg;

DESCRIPTION

XKanjiControl executes a process that relates to Japanese input within the window defined by dpy and win. The process is specified in request. Some processes are accompanied by the argument, specified in arg. XKanjiControl controls the following functions:

request name

Function

KC_INITIALIZE

Initializes Kana-to-Kanji conversion.

KC_CHANGEMODE

Changes the input mode.

KC_SETWIDTH

Specifies the width used to display the candidate

KC_FINALIZE

Finalizes (terminates) Kana-to-Kanji conversion processing.

KC_SETUNDEFKEYFUNCTION

Sets a function for an undefined key.

KC_SETMODEINFOSTYLE

Specifies whether mode information is represented in numeric form.

KC_KAKUTEI

Fixes the currently entered character string.

KC_KILL

Deletes the currently entered character string.

KC_QUERYMODE

Queries about the current mode.

KC_SETSERVERNAME

Specifies the server to be connected.

KC_SETINITFILENAME

Specifies the customize file.

KC_CLOSEUICONTEXT

Closes the context.

KC_QUERYMAXMODESTR

Obtains the maximum length of mode display character string.

Basically, XKanjiControl is enabled only for the window specified in the dpy and win. This rule does not apply to the initialize and terminate processes. The unfixed character string condition may change, or details of the mode may vary, depending on the XKanjiControl operation. If this may occur, pass the pointer to a structure that can contain the varied information in the arg field. This structure is defined as follows:

typedef struct {
  int      val;          /* The length of the character string in the
                            buffer returns. */
  unsigned char *buffer; /* Specifies the buffer used to store the
                            fixed character string. */
  int      bytes_buffer; /* Specifies the size of the above buffer. */
  XKanjiStatus *ks;      /* Pointer to the structure that contains
                            information about the unfixed character string. */
} XKanjiStatusWithValue;

The XKanjiControl functions can be executed in the following ways:

(1)

KC_INITIALIZE — Initializes Kana-to-Kanji conversion.

(2)

KC_CHANGEMODE — Changes the input mode.

(3)

KC_SETWIDTH — Specifies the width used to display the candidate list.

(4)

KC_FINALIZE — Finalizes (terminates) processing of Kana-to-Kanji conversion

(5)

KC_SETUNDEFKEYFUNCTION — Sets a function for an undefined key.

(6)

KC_SETMODEINFOSTYLE — Specifies mode information representation.

(7)

KC_KAKUTEI, (8) KC_KILL — Kill the currently input character string.

(9)

KC_QUERYMODE — Inquiry about the mode

(10)

KC_SETSERVERNAME — Specifies the server to be connected.

(11)

KC_SETINITFILENAME — Specifies the customize file.

(12)

KC_CLOSEUICONTEXT Closes the context.

(13)

KC_QUERYMAXMODESTR — Obtains the maximum length of mode display character string.