UILIBINTRO(3)

📦 version 3.7p3, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 UILIBINTRO(3) — the vibe check 💖

okay bestie, welcome to UILIBINTRO(3), the Library Functions Manual page that's basically the group chat intro for the whole user interface library situation. let's get into it ✨

🌸 NAME 🌸

UILib_intro — User interface library intro 🫶

✨ DESCRIPTION ✨

so like, user interface libraries are out here responding to one-character or one-key input, and they hand you back all kinds of info. we're talking:

  • the unfixed character string
  • the fixed character string
  • marked segment position
  • status display character string
  • candidate list character string

the application program then 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 🖱️). iconic behavior honestly.

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. two paths, both slaying 💅

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.

🎀 JRKANJISTRING(3) 🎀

(this one's JRKANJISTRING(3) in the Library Functions Manual, bestie, keep up 💖)

💜 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. no cap, that's the whole job.

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. the way it just does that for you? obsessed.

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. like, literally don't, that's not the move 🙈

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. special little exception behavior, we love to see it 👑

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. so like, it's giving the receipts, not doing the decorating 💅

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. read-only, bestie, do not touch 🚫

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. truncation era, we stay aware 🫶

🔥 FUNCTION KEYS 🔥

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

  • 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(3) 👑

(yes bestie, new page, JRKANJICONTROL(3), still the Library Functions Manual 💖)

🌸 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:

  • 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 only enabled for the thing that's specified in the context. 💅 That's the whole rule. (And no, it does not apply to the initialize and terminate processes — those two are the exception, they do their own thing.)

Also, heads up: the unfixed character string condition may change, and the details of the mode may vary, depending on which jrKanjiControl operation you're running. If that's a possibility for you, pass the pointer to a structure that can hold all that varied info in the arg field. That structure is defined like this:

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 — you do it by specifying KC_INITIALIZE in the request field. For arg, specify one of these two things: (1) the pointer to the char ** type variable you're using to store the warning message, or (2) NULL. 🎀

The initialize process is basically run automatically the first time jrKanjiString(3) gets called. Using jrKanjiControl for initialization skips that automatic run.

So, for example: when control about Kana-to-Kanji conversion gets executed using jrKanjiControl before you ever use jrKanjiString(3), then Kana-to-Kanji conversion must be initialized. No skipping, bestie. 🙈

When the process terminates normally, 0 comes back as the jrKanjiControl return value. When it terminates abnormally, -1 comes back.

When KC_INITIALIZE is executed, a warning — not an error — may happen. When it does, the pointer to the warning character string array gets stored in, and returned to, the variable you specified in arg. If no warning happens, NULL gets stored and returned. 💖

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 that returns to the third argument. That message gets 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 — anything after that gets 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, and specify the jrKanjiStatusWithValue structure in arg.

The Japanese mode gets changed by specifying the mode number with the val member of the jrKanjiStatusWithValue structure. That mode number is indicated by these macros:

  • 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 display (mode name etc.) to vary in response to a mode change. The display change gets returned by the jrKanjiStatusWithValue structure you 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 where the candidate list is going to be displayed. The width of one column equals the width of an alphabetical or half-wide Katakana character. Each full-wide Kanji character takes up two columns. 👑 Using KC_SETWIDTH, you specify the width of the candidate list display area in the request field. And at that point, you 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 you're terminating Kana-to-Kanji conversion processing. All contents learned up to now get 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 — not an error — may happen. When it does, the pointer to the warning character string array gets stored in, and returned to, the variable you specified in arg. If no warning happens, NULL gets stored and returned.

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 that returns to the third argument. That message gets 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. Anything after that gets 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 ⌨️

So like, if you press CTRL-t during input of a reading, that counts as undefined key input. 👀 These are the processes that get executed in response to undefined key input:

  • 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 the external variable jrBeepFunc gets called automatically by the library whenever an undefined key is input. If no value is 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 🎨

Maybe you wanna display mode info with data like a bit map, instead of character strings. In that case, having the mode info come back as numeric data helps you run the process. ✨ Specify KC_SETMODEINFOSTYLE in jrKanjiControl, and pass 1 to arg.

After that, 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 therefore 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 where 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 instead, specify KC_SETMODEINFOSTYLE in jrKanjiControl to change the mode character string style. ⭐

(Example)
  char currentMode[MAXMODELEN];
  .....
  jrKanjiControl(0, KC_QUERYMODE, currentMode);
  .....

(10) KC_SETSERVERNAME — tells it which server to talk to 🛰️

KC_SETSERVERNAME is the glow-up that lets you swap out the Kana-to-Kanji conversion server without killing your whole app. Bestie, no restart required. To set which server to connect to as the Kana-to-Kanji conversion server, drop KC_SETSERVERNAME into jrKanjiControl. Then in the third argument, hand over the name of the server you want to connect to.

(11) KC_SETINITFILENAME — specifies the customize file 📄✨

KC_SETINITFILENAME lets your application program change the customize file. To actually change it, pass KC_SETINITFILENAME as the second argument and the file name character string as the third argument. Heads up though: this process must be executed before KC_INTIALIZE. Order matters, okay? 💅

(Example)
  char *inifile = "app-own.canna"
  .....
  jrKanjiControl(0, KC_SETINITFILENAME, initfile);
  .....

(12) KC_CLOSEUICONTEXT — closes the context 🚪

Any integer at all can be the context ID that represents the conversion context. Like, a context ID that has never been used can totally be assigned to jrKanjiString or jrKanjiControl — and in that case, initialization for that context runs and reserves the memory it needs. Iconic, it just handles itself.

But if you're done with an input port and not using it anymore, you might want to free the memory reserved for that context ID. To do that, call jrKanjiControl and specify KC_CLOSEUICONTEXT as the second argument. 🧹

Because this process causes a display change, specify jrKanjiStatusWithValue as the third structure. Don't forget, bestie, or the display gets weird.

(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 — gets the max length of the mode display character string 📏

The mode display character string can be customized using the initialize file. So you need to figure out the size of the display area to reserve — in the customized resulting mode display character string, that is. Specify KC_QUERYMAXMODESTR as the second argument, then call jrKanjiControl. As a result, you get back the number of columns necessary for the mode display character string. The number of columns is represented defining the width of one half-wide alphanumeric character as 1.

The third argument is unused; assign the dummy value 0 to it. It's just vibing there.

(Example)
  int max_mode_columns;
  .....
  max_mode_columns = jrKanjiControl(0, KC_QUERYMAXMODESTR, 0);
  .....

🌸 XLookupKanjiString(3) 🌸

NAME

XLookupKanjiString — turns your 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. The whole reason we're here. ✨
  • 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 process stuff like shift, lock, and control. Lowkey does it all.

XLookupKanjiString enables eight- and 16-bit Japanese characters to be processed. Fr fr, both widths. 🌈

XLookupKanjiString processes alphabetical characters in the same way as XLookupString. Same energy.

For Japanese character processing, Romaji-to-Kana conversion and Kana-to-Kanji conversion are done right inside 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 like the readings to be converted needs to be echoed (that's local echo, bestie). XLookupKanjiString does not do display stuff like local echo itself. Instead, it hands the character strings that should go to local echo back to the application through the XKanjiStatus structure. DIY display, but make it ✨informed✨.

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 come back through the echoStr member. At that time, the length of the 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 members, 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. Hands off, okay? 🚫✍️

If no character string is to be submitted to local echo, 0 will return to the length member. Nothing to echo, nothing to report.

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. Not me getting a negative length 💀 it's normal, it means "same as before."

Mode changes and existence of information about the candidate list are passed by the info member. If the 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. Vibe check passed. 🎀

The character string for candidate list display returns to the gline structure's line member. The length, reverse display 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. Periodt. 💅

🔥 XKanjiControl(3) 🔥

NAME

XKanjiControl — controls the XLookupKanjiString mode and process. The remote control of Japanese input. 🎛️

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. Pick your request, optionally bring a friend. 🫶

XKanjiControl controls the following functions:

  • 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. Those two are the exception, the main characters, the ones who roam free. 👑

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 kicks off Kana-to-Kanji conversion, and you get it going by putting KC_INITIALIZE in the request field. In arg, pass one of these two things: (1) a pointer to a char ** type variable you're using to stash the warning message, or (2) NULL. Lowkey, the initialize step happens automatically the first time XLookupKanjiString(3) gets called — so this is the manual version, and you'd only bother because you're skipping the auto one by using XKanjiControl for initialization instead. 💅

So for example: if you're driving Kana-to-Kanji conversion with XKanjiControl before you ever touch XLookupKanjiString(3), you must initialize Kana-to-Kanji conversion yourself. No skipping, bestie. ✨

When it wraps up cleanly, 0 comes back as the XKanjiControl return value. When it goes sideways, you get -1.

Here's the cute part: when KC_INITIALIZE runs, you might get a warning rather than a full-blown error. If that happens, the pointer to the warning character string array gets stored into — and returned to — the variable you named in arg. If nothing warns, NULL is what gets stored and returned. 🫶

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

Inside the library, malloc is done for that warning message headed back to the fourth argument. It gets freed the next time KC_INITIALIZE or KC_FINALIZE runs. The application programmer must not free it. Periodt. And heads up — the maximum number of warning messages is restricted to 64 now. Anything after that? Discarded. 💀

These are the warnings that may show up 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 you hand it NULL as the fourth argument, any warning message just gets discarded. Bye. 🙈

(2) KC_CHANGEMODE — Changes the input mode

KC_CHANGEMODE lets the application change the input mode. Put KC_CHANGEMODE in the request field, and pass the XKanjiStatusWithValue structure in arg. You flip the Japanese mode by specifying the mode number with the val member of the XKanjiStatusWithValue structure. The mode numbers are these macros right here:

  • 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 makes a bunch of display stuff (mode name, etc.) change in response to the mode switch. That display change comes back through the XKanjiStatusWithValue structure you 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 sets the number of columns of the area where the candidate list gets displayed. One column's width equals that of an alphabetical or half-wide Katakana character. Every full-wide Kanji character eats up two columns. With KC_SETWIDTH, you specify the width of the candidate list display area in the request field — and at that moment, you pass 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 says 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. Everything learned up to now gets 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.

This is the warning that 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

Okay so picture this: you press CTRL-t while typing a reading, and it's treated as undefined key input. These are the processes that run in response to undefined key input:

  • 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 whenever an undefined key comes in. If no value is set in jrBeepFunc, nothing happens when jrBeepFunc == NULL appears. 💀

(Example)

  extern (*jrBeepFunc)(), beep();

  jrBeepFunc = beep;
  XKanjiControl(dpy, win, KC_SETUNDEFKEYFUNCTION, kc_normal);

(6) KC_SETMODEINFOSTYLE — Specifies mode information representation

Maybe you wanna display mode information using data like a bit map instead of character strings. In that case, getting numeric data back as mode information helps you run your process. Specify KC_SETMODEINFOSTYLE in XKanjiControl, and pass 1 to arg. After that, 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, go look at the mode change description of Item (2) KC_CHANGEMODE. 🦋

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

Sometimes you just wanna relinquish the currently entered character string, for whatever 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. That means the XKanjiStatusWithValue must be specified as the fourth argument. No cap.

(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

Wanna know what mode you're in? Specify KC_QUERYMODE in XKanjiControl.

Specify the pointer to the character array where the mode character string is to be stored. The mode character string is a character string ending with a null character. If you want a numeric back here instead, 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 lets you 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 lets the application program 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);
                 .....

okay so bestie, we're still deep in the control-function lore and it's giving very specific but honestly kinda iconic. let's keep going 💅

💖 (12) KC_CLOSEUICONTEXT — closes the context

so when XKanjiControl or XLookupKanjiString gets called, one conversion context gets assigned to the combination of dpy and win. that's just the vibe. and a combination of dpy and win that hasn't been used yet can be specified for XKanjiControl or XLookupKanjiString. when that happens, a new context is created for the window and the required memory is reserved. slay.

now if a window that was used up to now is not used anymore, you may want to free the context memory that has been assigned to this window. to do that, call XKanjiControl by specifying KC_CLOSEUICONTEXT as the third argument. because this process causes a display change, specify XKanjiStatusWithValue as the fourth structure. important!! don't skip that part, bestie.

               (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. you need to examine the size of the display area — in the customized resulting mode display character string — that is to be reserved. so 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 by defining that the width of one half-wide alphanumeric character is 1, iykyk)

the fourth argument is unused; dummy value 0 is assigned to it. no cap.

               (Example)
                 int max_mode_columns;
                 .....
                 max_mode_columns = XKanjiControl(dpy, win, KC_QUERYMAXMODESTR, 0);
                 .....

and that's a wrap on this part of XKANJICONTROL(3), bestie 🫶 the footer is doing its source/version + date moment, and the whole page signs off as XKANJICONTROL(3) — periodt 💅✨🎀🦋

📦 where this page comes from