1UILIBINTRO(3) Library Functions Manual UILIBINTRO(3)
2
6 UILib intro — User interface library intro
7
9 User interface libraries are responding to one-chracter or one-key
10 input, return various kinds of information. They include the unfixed
11 character string, fixed character string, marked segment position, sta‐
12 tus display character string, and candidate list character string.
13 The application program displays the data according to the returned
15 information. It can also control mode transition by triggering through
16 something other than key pressing (for example, selection through the
17 mouse).
18 The user interface library provides jrKanjiString and jrKanjiControl
20 for the input through the TTY. It also provides XLookupKanjiString and
21 XKanjiControl for the input through the X window.
22 Use of the user interface library requires the following:
24 - Through the TTY:
26 Function jrKanjiString, jrKanjiControl
28 Header file canna/jrkanji.h
30 Library libcanna.a, libcanna.so
32 - Through the X window:
34 Function XLookupKanjiString, XKanjiControl
36 Header file canna/kanji.h
38 Library libXn.a, libXn.so, libcanna.a, libcanna.so
40
42 jrKanjiString Converts ordinary keyboard input (input through the
43 TTY, input with X) into Kanji strings.
44 jrKanjiControl Executes the control with jrKanjiString according
46 to the specified parameters.
47 XLookupKanjiString Converts the keyboard input (key event) into Kanji
49 strings in the X window system.
50 XKanjiControl Executes the control with XLookupKanjiString
52 according to the specified parameters.
53JRKANJISTRING(3) Library Functions Manual JRKANJISTRING(3)
57
61 jrKanjiString — Kana-to-Kanji Conversion for ordinary keyboard input
62
64 #include <canna/jrkanji.h>
65 int jrKanjiString(context_id, ch, buffer_return, bytes_buffer, kanji_status_return)
66 int context_id;
67 int ch;
68 char *buffer_return;
69 int bytes_buffer;
70 jrKanjiStatus *kanji_status_return;
71
73 jrKanjiString converts ordinary keyboard input (input through the TTY,
74 input with X) into Kanji strings.
75 jrKanjiString is a convenient routine which returns the character
77 strings to be displayed. To convert the key input represented in ASCII
78 code, into the Japanese characters, jrKanjiString specifies the input
79 key code using ch. Romaji-to-Kana or Kana-to-Kanji Conversion is exe‐
80 cuted in jrKanjiString.
81 For a function or cursor key, specify a special code (listed in ``FUNC‐
83 TION KEYS'' below) to jrKanjiString. Do not specify the sequence
84 caused by the key.
85 For the context identifier specified in context_id, the value is not
87 used as it is. Instead, a context that uses the context identifier as
88 the key is created and used. Thus, the application program may specify
89 any value for the context identifier to be specified for jrKanjiString.
90 It is recommended that the input port's file descriptor be specified
91 for this identifier. If 0 is specified for the identifier, the context
92 prepared as the system default will be used by way of exception.
93 It is recommended that 0 be specified unless particular consideration
95 is given to the context. The intermediate result to be displayed is
96 returned to the application through kanji_status_return.
97 Responding to the input, it is necessary to display the intermediate
99 result of Romaji-to-Kana or Kana-to-Kanji Conversion. The application
100 must display the intermediate result according to the information
101 returned by kanji_status_return, which is a jrKanjiStatus type struc‐
102 ture.
103 The jrKanjiStatus structure is defined as follows:
105 typedef struct {
107 unsigned char *echoStr; /* Character string for local echo */
108 int length; /* Length of the local echo character string */
109 int revPos; /* Offset to the reverse display field
110 within local echo character string */
111 int revLen; /* Length of the reverse display within
112 local echo echo character string */
113 unsigned long info; /* Other information */
114 unsigned char *mode; /* Mode information */
115 struct {
116 unsigned char *line; /* Candidate list character string */
117 int length; /* Length of candidate list character string */
118 int revPos; /* Offset to the reverse display field
119 within candidate list character string */
120 int revLen; /* Length of reverse display field within
121 candidate list character string */
122 } gline; /* Information about the candidate list*/
123 } jrKanjiStatus;
124 When Kana-to-Kanji conversion is used during Japanese input, informa‐
127 tion such as the readings to be converted need to be echoed (local
128 echo). jrKanjiString does not perform display such as local echo.
129 Instead, it returns the character strings to be submitted to local
130 echo, to the application by using the jrKanjiStatus structure.
131 The EUC character strings to be submitted to local echo include charac‐
133 ters already converted into Kana from Romaji and conversion candidate
134 characters. Until the conversion is fixed, they are returned by the
135 echoStr member. At this time, the length of local echo character
136 string is returned by the length member. Also, the starting position
137 and length (bytes) of reverse display area are returned by the revPos
138 and revLen member, respectively. The buffer for local echo character
139 strings is reserved automatically by jrKanjiString. It must be used
140 only for reading. No character string must be written into this buf‐
141 fer.
142 If no character string is to be submitted to local echo, 0 will be
144 returned by the length member.
145 The contents to be submitted to local echo may be the same as when
147 jrKanjiString was previously called. (This occurs, for example, when a
148 control code is pressed and the key is disabled.) In this case, -1
149 returns to the length member.
150 Mode changes and existence of information about the candidate list are
152 passed by the info member. If info member's KanjiModeInfo bit is on,
153 the character string indicating the new mode will return to mode. If
154 the info member's KanjiGLineInfo bit is on, the gline structure has
155 contained information such as the candidate list.
156 The character string for candidate list display returns to the gline
158 structure's line member. The length, reverse dispaly starting posi‐
159 tion, and reverse display duration of the candidate list character
160 string return to the gline structure's line, revPos, and revLen,
161 respectively.
162 If there is an EUC character string fixed during conversion, it will be
164 stored into buffer buffer_return. In this case, the length (bytes) of
165 this character string will return. If there is no fixed character
166 string, the return value will be 0. Using bytes_buffer, specify the
167 size of the buffer that is to contain the fixed character string (buf‐
168 fer_return). If the fixed character string is longer than bytes_buf‐
169 fer, only the bytes_buffer substring is stored into buffer_return. In
170 this case, the value specified in bytes_buffer will be the return value
171 of jrKanjiString.
172
174 For any function key that issue an Escape sequence, specify one of the
175 following codes as ch instead of the Escape sequence:
176 Logical name
178 Code
179 Nfer CANNA_KEY_Nfer
181 Xfer CANNA_KEY_Xfer
183 Up CANNA_KEY_Up
185 Left CANNA_KEY_Left
187 Right CANNA_KEY_Right
189 Down CANNA_KEY_Down
191 Insert CANNA_KEY_Insert
193 Rollup CANNA_KEY_Rollup
195 Rolldown CANNA_KEY_Rolldown
197 Home CANNA_KEY_Home
199 Help CANNA_KEY_Help
201 S-Nfer CANNA_KEY_Shift_Nfer
203 S-Xfer CANNA_KEY_Shift_Xfer
205 S-Up CANNA_KEY_Shift_Up
207 S-Left CANNA_KEY_Shift_Left
209 S-Right CANNA_KEY_Shift_Right
211 S-Down CANNA_KEY_Shift_Down
213 C-Nfer CANNA_KEY_Control_Nfer
215 C-Xfer CANNA_KEY_Control_Xfer
217 C-Up CANNA_KEY_Control_Up
219 C-Left CANNA_KEY_Control_Left
221 C-Right CANNA_KEY_Control_Right
223 C-Down CANNA_KEY_Control_Down
225 F1 CANNA_KEY_F1
227 PF1 CANNA_KEY_PF1
229
231 jrKanjiControl(3)
232
234 If an error occurs during input processing, -1 will return as the
235 return value of this function. In this case, the error message will be
236 stored in external variable (char*)jrKanjiError.
237 If a call to this function causes a character string to be fixed, the
239 length (bytes) of this character string will return. Otherwise, 0 will
240 return.
241JRKANJICONTROL(3) Library Functions Manual JRKANJICONTROL(3)
245
249 jrKanjiControl — Control the jrKanjiControl modes and processes
250
252 #include <canna/jrkanji.h>
253 int jrKanjiControl(context_id, request, arg)
254 int context_id;
255 int request;
256 char *arg;
257
259 jrKanjiControl executes process request for conversion context con‐
260 text_id. Some processes are accompanied by the argument, specified in
261 arg.
262 jrKanjiControl controls the following 13 functions:
264 request name Function
266 KC_INITIALIZE Initializes Kana-to-Kanji conversion.
268 KC_CHANGEMODE Changes the input mode.
270 KC_SETWIDTH Specifies the width used to display the candidate
272 KC_FINALIZE Finalizes (terminates) Kana-to-Kanji conversion pro‐
274 cessing.
275 KC_SETUNDEFKEYFUNCTION
277 Sets a function for an undefined key.
278 KC_SETMODEINFOSTYLE
280 Specifies whether mode information is represented in
281 numeric form.
282 KC_KAKUTEI Fixes the currently entered character string.
284 KC_KILL Deletes the currently entered character string.
286 KC_QUERYMODE Queries about the current mode.
288 KC_SETSERVERNAME Specifies the server to be connected.
290 KC_SETINITFILENAME
292 Specifies the customize file.
293 KC_CLOSEUICONTEXT Closes the context.
295 KC_QUERYMAXMODESTR
297 Obtains the maximum length of mode display character
298 string.
299 Basically, jrKanjiControl is enabled only for something specified in
301 the context. This rule does not apply to the initialize and terminate
302 processes.
303 The unfixed character string condition may change, or details of the
305 mode may vary, depending on the jrKanjiControl operation. If this may
306 occur, pass the pointer to a structure that can contain the varied
307 information in the arg field. This structure is defined as follows:
308 typedef struct {
310 int val; /* The length of the character string in the
311 buffer returns. */
312 unsigned char *buffer; /* Specifies the buffer used to store the
313 fixed character string. */
314 int bytes_buffer; /* Specifies the size of the above buffer. */
315 jrKanjiStatus *ks; /* Pointer to the structure that contains
316 information about the unfixed character string. */
317 } jrKanjiStatusWithValue;
318 The jrKanjiControl functions can be executed in the following ways:
321 (1) KC_INITIALIZE — Initializes Kana-to-Kanji conversion.
323 KC_INITIALIZE initializes Kana-to-Kanji conversion by specifying
325 KC_INITIALIZE in the request field. Specify one of the following
326 in arg: (1) the pointer to the char ** type variable used to
327 store the warning message and (2) NULL.
328 The initialize process is basically executed automatically when
330 jrKanjiString(3) is first called. This is skipped by using
331 jrKanjiControl for initialization.
332 For example, when control about Kana-to-Kanji conversion is exe‐
334 cuted using jrKanjiControl before use of jrKanjiString(3), Kana-
335 to-Kanji conversion must be initialized.
336 When the process terminates normally, 0 returns as the jrKanji‐
338 Control return value. When it terminates abnormally, -1 returns.
339 When KC_INITIALIZE is executed, a warning, rather than an error,
341 may occur. When it occurs, the pointer to the warning character
342 string array is stored in and returns to the variable specified
343 in arg. If no warning occurs, NULL is stored and returns.
344 (Example)
346 int res; /* Prepare for error return */
347 char **warning;
348 .....
349 res = jrKanjiControl(0, KC_INITIALIZE, &warning);
350 if (warning) {
351 char **p;
352 for (p = warning ; *p ; p++) {
354 fprintf(stderr, "%s0, *p);
355 }
356 }
357 In the library, malloc is done for the warning message returning
360 to the third argument. This message is freed when KC_INITIALIZE
361 or KC_FINALIZE is executed next. The application programmer must
362 not free it. The maximum number of warning messages is
363 restricted to 64 now. The subsequent ones are discarded.
364 The following warnings may be included in a message:
366 - All customize files including those of the system are unavail‐
368 able.
369 - The customize file contains a syntax error.
371 - The Romaji-to-Kana conversion dictionary is unavailable.
373 - The Kana-to-Kanji conversion dictionary is unavailable.
375 - Connection to the Kana-to-Kanji conversion server is disabled.
377 If NULL is specified as the third argument, any warning message
379 will be discarded.
380 (2) KC_CHANGEMODE — Changes the input mode.
382 KC_CHANGEMODE changes the input mode from the application. Spec‐
384 ify KC_CHANGEMODE in the request field. Specify the jrKanjiSta‐
385 tusWithValue structure in arg.
386 The Japanese mode is changed by specifying the mode number with
388 the val member of jrKanjiStatusWithValue structure. The mode
389 number is indicated by the following macros:
390 Macro number Mode
392 CANNA_MODE_AlphaMode Alphabet mode
394 CANNA_MODE_HenkanMode Conversion input mode
396 CANNA_MODE_KigoMode Symbol input mode
398 CANNA_MODE_ZenHiraKakuteiMode
400 Full-wide Hiragana fixed input mode
401 CANNA_MODE_ZenKataKakuteiMode
403 Full-wide Katakana fixed mode
404 CANNA_MODE_HanKataKakuteiMode
406 Half-wide Katakana fixed input mode
407 CANNA_MODE_ZenAlphaKakuteiMode
409 Full-wide alphabet fixed input mode
410 CANNA_MODE_HanAlphaKakuteiMode
412 Half-wide alphabet fixed input mode
413 CANNA_MODE_HexMode Hexadecimal code input mode
415 CANNA_MODE_BushuMode Bushu input mode
417 CANNA_MODE_TorokuMode Word register mode
419 This function causes much dispaly (mode name etc.) to vary in
421 response to a mode change. The display change is returned by the
422 jrKanjiStatusWithValue structure specified as arg.
423 (Example)
425 jrKanjiStatus ks;
426 jrKanjiStatusWithValue ksv;
427 unsigned char buf[SOMESIZE];
428 .....
429 ksv.ks = &ks;
430 ksv.buffer = buf;
431 ksv.bytes_buffer = SOMESIZE;
432 ksv.val = CANNA_MODE_HexMode;
433 jrKanjiControl(context, KC_CHANGEMODE, &ksv);
435 len = ksv.val;
436 .....
437 /* Information about the unfixed or fixed character string is returned
439 by ksv. */
440 (3) KC_SETWIDTH — Specifies the width used to display the candidate
443 list.
444 KC_SETWIDTH specifies the number of columns of the area on which
446 the candidate list is to be displayed. The width of one column
447 equals that of an alphabetical or half-wide Katakana character.
448 Each full-wide Kanji character occupies two columns. Using
449 KC_SETWIDTH, specify the width of candidate list display area to
450 be specified in the request field. At this time, specify the
451 number of columns in arg.
452 (Example)
454 jrKanjiControl(0, KC_SETWIDTH, (char *)60);
455 (4) KC_FINALIZE — Finalizes (terminates) processing of Kana-to-Kanji
458 conversion
459 KC_FINALIZE specifies that Kana-to-Kanji conversion also final‐
461 izes (terminates) at the end of the program and in other cases.
462 Be sure to execute this process when terminating Kana-to-Kanji
463 conversion processing. All contents learned up to now are regis‐
464 tered in the file. Specify KC_FINALIZE in the request field.
465 When the process terminates normally, 0 returns. When it termi‐
467 nates abnormally, -1 returns.
468 When KC_FINALIZE is executed, a warning, rather than an error,
470 may occur. When it occurs, the pointer to the warning character
471 string array is stored in and returns to the variable specified
472 in arg. If no warning occurs, NULL is stored and returns.
473 (Example)
475 int res; /* Prepare for error return */
476 char **warning;
477 .....
478 res = jrKanjiControl(0, KC_FINALIZE, &warning);
479 if (warning) {
480 char **p;
481 for (p = warning ; *p ; p++) {
483 fprintf(stderr, "%s0, *p);
484 }
485 }
486 In the library, malloc is done for the warning message returning
489 to the third argument. This message is freed when KC_INITIALIZE
490 or KC_FINALIZE is executed next. The application programmer must
491 not free it.
492 The maximum number of warning messages is restricted to 64 now.
494 The subsequent ones are discarded.
495 The following warning may be included in a message:
497 - The dictionary cannot be unmounted.
499 If NULL is specified as the third argument, any warning message
501 will be discarded.
502 (5) KC_SETUNDEFKEYFUNCTION — Sets a function for an undefined key.
504 For example, if you press CTRL-t during input of a reading, it is
506 regarded as undefined key input. The following processes are
507 executed, responding to undefined key input:
508 Macro name Process
510 kc_normal Beep
512 kc_through Passes the input to the application
514 kc_kakutei Fixes the input and passes it to the application pro‐
516 gram.
517 kc_kill Deletes the input and passes it to the application
519 program.
520 If kc_normal is specified, the function set in external variable
522 jrBeepFunc is called automatically by the library when an unde‐
523 fined key is input. If the value is not set in jrBeepFunc, noth‐
524 ing occurs when ``jrBeepFunc == NULL'' appears.
525 (Example)
527 extern (*jrBeepFunc)(), beep();
528 jrBeepFunc = beep;
530 jrKanjiControl(0, KC_SETUNDEFKEYFUNCTION, kc_normal);
531 (6) KC_SETMODEINFOSTYLE — Specifies mode information representation.
534 You may want to display mode information with data such as the
536 bit map, rather than character strings. In this case, return of
537 numeric data as mode information helps you execute the process.
538 Specify KC_SETMODEINFOSTYLE in jrKanjiControl, and pass 1 to arg.
539 After this, one character representing the mode code (numeric)
540 plus To convert the value into the mode code, subtract '@' (0x40)
541 from the returned character string. For the mode codes, see the
542 mode change description of Item (2) KC_CHANGEMODE.
543 (7) KC_KAKUTEI, (8) KC_KILL — Kill the currently input character
545 string.
546 You may want to relinquish the currently entered character string
548 for some reason. There are two relinquishing methods. One is to
549 relinquish the character string after including the currently
550 entered character string as a fixed one. The other is to discard
551 the character string completely then relinquish it. For the
552 first method, specify KC_KAKUTEI in jrKanjiControl. For the sec‐
553 ond method, specify KC_KILL.
554 Each of the above influences the display. The jrKanjiStatusWith‐
556 Value must thus be specified as the third argument.
557 (Example)
559 jrKanjiStatusWithValue ksv;
560 jrKanjiStatus ks;
561 unsigned char buf[SOMESIZE];
562 .....
563 ksv.ks = &ks;
564 ksv.buffer = buf;
565 ksv.bytes_buffer = SOMESIZE;
566 jrKanjiControl(context, KC_KAKUTEI, &ksv);
568 len = ksv.val;
569 .....
570 (9) KC_QUERYMODE — Inquiry about the mode
573 To inquire about the current mode, specify KC_QUERYMODE in jrKan‐
575 jiControl.
576 Specify the pointer to the character array in which the mode
578 character string is to be stored. The mode character string is a
579 character string ending with a null character. To return a
580 numeric here, specify KC_SETMODEINFOSTYLE in jrKanjiControl to
581 change the mode character string style.
582 (Example)
584 char currentMode[MAXMODELEN];
585 .....
586 jrKanjiControl(0, KC_QUERYMODE, currentMode);
587 .....
588 (10) KC_SETSERVERNAME Specifies the server to be connected.
591 KC_SETSERVERNAME enables you to switch the Kana-to-Kanji conver‐
593 sion server without terminating the application program. To set
594 the server to connect as the Kana-to-Kanji conversion server,
595 specify KC_SETSERVERNAME in jrKanjiControl. In the third argu‐
596 ment, specify the name of the server to be connected.
597 (11) KC_SETINITFILENAME — Specifies the customize file.
599 KC_SETINITFILENAM enables the application program to change the
601 customize file. To change the customize file, specify
602 KC_SETINITFILENAME as the second argument and the file name char‐
603 acter string as the third argument. This process must be exe‐
604 cuted before KC_INTIALIZE.
605 (Example)
607 char *inifile = "app-own.canna"
608 .....
609 jrKanjiControl(0, KC_SETINITFILENAME, initfile);
610 .....
611 (12) KC_CLOSEUICONTEXT Closes the context.
614 Any integer may be assigned as the context ID that represents the
616 conversion context. A context ID that has never been used can be
617 assigned to jrKanjiString or jrKanjiControl. In this case, ini‐
618 tialization for this context is executed to reserve the required
619 memory.
620 If an input port used up to now is not used, you may want to free
622 the memory reserved for the context ID assigned to this port. To
623 do so, call jrKanjiControl by specifying KC_CLOSEUICONTEXT as the
624 second argument.
625 Because this process causes a display change, specify jrKanjiSta‐
627 tusWithValue as the third structure.
628 (Example)
630 jrKanjiStatusWithValue ksv;
631 jrKanjiStatus ks;
632 unsigned char buf[SOMESIZE];
633 .....
634 ksv.ks = &ks;
635 ksv.buffer = buf;
636 ksv.bytes_buffer = SOMESIZE;
637 jrKanjiControl(0, KC_CLOSEUICONTEXT, &ksv);
639 .....
640 (13) KC_QUERYMAXMODESTR — Obtains the maximum length of mode display
643 character string.
644 The mode display character string can be customized using the
646 initialize file. It is necessary to examine the size of the dis‐
647 play area (in the customized resulting mode display character
648 string) that is to be reserved. Specify KC_QUERYMAXMODESTR as
649 the second argument, then call jrKanjiControl. As a result, the
650 number of columns necessary for the mode display character string
651 is returned. The number of columns is represented, defining that
652 the width of one half-wide alphanumeric character is 1.
653 The third argument is unused; dummy value 0 is assigned to it.
655 (Example)
657 int max_mode_columns;
658 .....
659 max_mode_columns = jrKanjiControl(0, KC_QUERYMAXMODESTR, 0);
660 .....
661XLookupKanjiString(3) Library Functions Manual XLookupKanjiString(3)
666
670 XLookupKanjiString — Converts the keyboard input into Kanji
671
673 #include <X11/Xlib.h>
674 #include <X11/kanji.h>
675 int
677 XLookupKanjiString(event_struct, buffer_return, bytes_buffer,
678 keysym_return, status_return, kanji_status_return)
679 XKeyEvent *event_struct;
680 char *buffer_return;
681 int bytes_buffer;
682 KeySym *keysym_return;
683 XComposeStatus *status_return;
684 XKanjiStatus *kanji_status_return;
685
687 event_struct Specifies the key event.
688 buffer_return Returns the resulting Kanji string.
690 bytes_buffer Specifies the buffer length.
692 keysym_return Returns the key symbol. NULL may be specified
694 status_return Specifies the pointer to the XCompose structure.
696 kanji_status_return
698 Returns the Kana-to-Kanji conversion status.
699
701 XLookupKanjiString is a convenient routine that associates a key event
702 with a Japanese character string. It uses the modifier key bit to pro‐
703 cesses such as shift, lock, and control.
704 XLookupKanjiString enables eight- and 16-bit Japanese characters to be
706 processed.
707 XLookupKanjiString processes alphabetical characters in the same way as
709 XLookupString.
710 For Japanese character processing, Romaji-to-Kana conversion and Kana-
712 to-Kanji conversion are done in this function. The XKanjiStatus,
713 defined below, is used during Japanese data input:
714 typedef struct _XKanjiStatus {
716 unsigned char *echoStr; /* local echo string */
717 int length; /* length of echo string */
718 int revPos; /* reverse position */
719 int revLen; /* reverse length */
720 unsigned long info; /* other informations */
721 unsigned char *mode; /* mode information */
722 struct {
723 unsigned char *line; /* a grance of Kanji characters */
724 int length; /* length of it */
725 int revPos; /* reverse position of it */
726 int revLen; /* reverse length of it */
727 } gline; /* a grancing line information */
728 } XKanjiStatus;
729 #define KanjiModeInfo 01
731 #define KanjiGLineInfo 02
732 When Kana-to-Kanji conversion is used during Japanese input, informa‐
734 tion such as the readings to be converted need to be echoed (local
735 echo). XLookupKanjiString does not perform display such as local echo.
736 Instead, it returns the character strings to be submitted to local
737 echo, to the application by using the XKanjiStatus structure.
738 The EUC character strings to be submitted to local echo include charac‐
740 ters already converted into Kana from Romaji and conversion candidate
741 characters. Until the conversion is fixed, they are returned by the
742 echoStr member. At this time, the length of local echo character
743 string is returned by the length member. Also, the starting position
744 and length (bytes) of reverse display are returned by the revPos and
745 revLen member, respectively. The buffer for local echo character
746 strings is reserved automatically by XLookupKanjiString. It should be
747 used only for reading. No character string must be written into this
748 buffer.
749 If no character string is to be submitted to local echo, 0 will return
751 to the length member.
752 The contents to be submitted to local echo may be the same as when
754 XLookupKanjiString was previously called. (This occurs, for example,
755 when the Shift key is pressed.) In this case, -1 returns to the length
756 member.
757 Mode changes and existence of information about the candidate list are
759 passed by the info member. If info member's KanjiModeInfo bit is on,
760 the character string indicating the new mode will return to mode. If
761 the info member's KanjiGLineInfo bit is on, the gline structure has
762 contained information such as the candidate list.
763 The character string for candidate list display returns to the gline
765 structure's line member. The length, reverse dispaly starting posi‐
766 tion, and reverse display duration of the candidate list character
767 string return to the gline structure's line, revPos, and revLen,
768 respectively.
769 If there is an EUC character string fixed during conversion, it will be
771 stored in buffer_return. In this case, the length (bytes) of this
772 character string will return as the return value of this function. If
773 there is no fixed character string, the return value will be 0.
774XKANJICONTROL(3) Library Functions Manual XKANJICONTROL(3)
778
782 XKanjiControl — Control the XLookupKanjiString mode and process.
783
785 #include <X11/kanji.h>
786 int XKanjiControl(dpy, win, request, arg)
787 Display dpy;
788 Window win;
789 int request;
790 char *arg;
791
793 XKanjiControl executes a process that relates to Japanese input within
794 the window defined by dpy and win. The process is specified in
795 request. Some processes are accompanied by the argument, specified in
796 arg.
797 XKanjiControl controls the following functions:
799 request name Function
801 KC_INITIALIZE Initializes Kana-to-Kanji conversion.
803 KC_CHANGEMODE Changes the input mode.
805 KC_SETWIDTH Specifies the width used to display the candidate
807 KC_FINALIZE Finalizes (terminates) Kana-to-Kanji conversion pro‐
809 cessing.
810 KC_SETUNDEFKEYFUNCTION
812 Sets a function for an undefined key.
813 KC_SETMODEINFOSTYLE
815 Specifies whether mode information is represented in
816 numeric form.
817 KC_KAKUTEI Fixes the currently entered character string.
819 KC_KILL Deletes the currently entered character string.
821 KC_QUERYMODE Queries about the current mode.
823 KC_SETSERVERNAME Specifies the server to be connected.
825 KC_SETINITFILENAME
827 Specifies the customize file.
828 KC_CLOSEUICONTEXT Closes the context.
830 KC_QUERYMAXMODESTR
832 Obtains the maximum length of mode display character
833 string.
834 Basically, XKanjiControl is enabled only for the window specified in
836 the dpy and win. This rule does not apply to the initialize and termi‐
837 nate processes.
838 The unfixed character string condition may change, or details of the
840 mode may vary, depending on the XKanjiControl operation. If this may
841 occur, pass the pointer to a structure that can contain the varied
842 information in the arg field. This structure is defined as follows:
843 typedef struct {
845 int val; /* The length of the character string in the
846 buffer returns. */
847 unsigned char *buffer; /* Specifies the buffer used to store the
848 fixed character string. */
849 int bytes_buffer; /* Specifies the size of the above buffer. */
850 XKanjiStatus *ks; /* Pointer to the structure that contains
851 information about the unfixed character string. */
852 } XKanjiStatusWithValue;
853 The XKanjiControl functions can be executed in the following ways:
856 (1) KC_INITIALIZE — Initializes Kana-to-Kanji conversion.
858 KC_INITIALIZE initializes Kana-to-Kanji conversion by specifying
860 KC_INITIALIZE in the request field. Specify one of the following
861 in arg: (1) the pointer to the char ** type variable used to
862 store the warning message and (2) NULL. The initialize process
863 is basically executed automatically when XLookupKanjiString(3) is
864 first called. This is skipped by using XKanjiControl for ini‐
865 tialization.
866 For example, when control about Kana-to-Kanji conversion is exe‐
868 cuted using XKanjiControl before use of XLookupKanjiString(3),
869 Kana-to-Kanji conversion must be initialized.
870 When the process terminates normally, 0 returns as the XKanjiCon‐
872 trol return value. When it terminates abnormally, -1 returns.
873 When KC_INITIALIZE is executed, a warning, rather than an error,
875 may occur. When it occurs, the pointer to the warning character
876 string array is stored in and returns to the variable specified
877 in arg. If no warning occurs, NULL is stored and returns.
878 (Example)
880 int res; /* Prepare for error return */
881 char **warning;
882 .....
883 res = XKanjiControl(dpy, win, KC_INITIALIZE, &warning);
884 if (warning) {
885 char **p;
886 for (p = warning ; *p ; p++) {
888 fprintf(stderr, "%s0, *p);
889 }
890 }
891 In the library, malloc is done for the warning message returning
894 to the fourth argument. This message is freed when KC_INITIALIZE
895 or KC_FINALIZE is executed next. The application programmer must
896 not free it. The maximum number of warning messages is
897 restricted to 64 now. The subsequent ones are discarded.
898 The following warnings may be included in a message:
900 - All customize files including those of the system are unavail‐
902 able.
903 - The customize file contains a syntax error.
905 - The Romaji-to-Kana conversion dictionary is unavailable.
907 - The Kana-to-Kanji conversion dictionary is unavailable.
909 - Connection to the Kana-to-Kanji conversion server is disabled.
911 If NULL is specified as the fourth argument, any warning message
913 will be discarded.
914 (2) KC_CHANGEMODE — Changes the input mode.
916 KC_CHANGEMODE changes the input mode from the application. Spec‐
918 ify KC_CHANGEMODE in the request field. Specify the XKanjiSta‐
919 tusWithValue structure in arg. The Japanese mode is changed by
920 specifying the mode number with the val member of XKanjiSta‐
921 tusWithValue structure. The mode number is indicated by the fol‐
922 lowing macros:
923 Macro number Mode
925 CANNA_MODE_AlphaMode Alphabet mode
927 CANNA_MODE_HenkanMode Conversion input mode
929 CANNA_MODE_KigoMode Symbol input mode
931 CANNA_MODE_ZenHiraKakuteiMode
933 Full-wide Hiragana fixed input mode
934 CANNA_MODE_ZenKataKakuteiMode
936 Full-wide Katakana fixed mode
937 CANNA_MODE_HanKataKakuteiMode
939 Half-wide Katakana fixed input mode
940 CANNA_MODE_ZenAlphaKakuteiMode
942 Full-wide alphabet fixed input mode
943 CANNA_MODE_HanAlphaKakuteiMode
945 Half-wide alphabet fixed input mode
946 CANNA_MODE_HexMode Hexadecimal code input mode
948 CANNA_MODE_BushuMode Bushu input mode
950 CANNA_MODE_TorokuMode Word register mode
952 This function causes much dispaly (mode name etc.) to vary in
954 response to a mode change. The display change is returned by the
955 XKanjiStatusWithValue structure specified as arg.
956 (Example)
958 XKanjiStatus ks;
959 XKanjiStatusWithValue ksv;
960 unsigned char buf[SOMESIZE];
961 .....
962 ksv.ks = &ks;
963 ksv.buffer = buf;
964 ksv.bytes_buffer = SOMESIZE;
965 ksv.val = CANNA_MODE_HexMode;
966 XKanjiControl(dpy, win, KC_CHANGEMODE, &ksv);
968 len = ksv.val;
969 .....
970 /* Information about the unfixed or fixed character string is
971 returned by ksv. */
972 (3) KC_SETWIDTH — Specifies the width used to display the candidate
975 list.
976 KC_SETWIDTH specifies the number of columns of the area on which
978 the candidate list is to be displayed. The width of one column
979 equals that of an alphabetical or half-wide Katakana character.
980 Each full-wide Kanji character occupies two columns. Using
981 KC_SETWIDTH, specify the width of candidate list display area to
982 be specified in the request field. At this time, specify the
983 number of columns in arg.
984 (Example)
986 XKanjiControl(dpy, win, KC_SETWIDTH, (char *)60);
987 (4) KC_FINALIZE — Finalizes (terminates) processing of Kana-to-Kanji
990 conversion
991 KC_FINALIZE specifies that Kana-to-Kanji conversion also final‐
993 izes (terminates) at the end of the program and in other cases.
994 Be sure to execute this process when terminating Kana-to-Kanji
995 conversion processing. All contents learned up to now are regis‐
996 tered in the file. Specify KC_FINALIZE in the request field.
997 When the process terminates normally, 0 returns. When it termi‐
999 nates abnormally, -1 returns.
1000 When KC_INITIALIZE is executed, a warning, rather than an error,
1002 may occur. When it occurs, the pointer to the warning character
1003 string array is stored in and returns to the variable specified
1004 in arg. If no warning occurs, NULL is stored and returns.
1005 (Example)
1007 int res; /* Prepare for error return */
1008 char **warning;
1009 .....
1010 res = XKanjiControl(dpy, win, KC_FINALIZE, &warning);
1011 if (warning) {
1012 char **p;
1013 for (p = warning ; *p ; p++) {
1015 fprintf(stderr, "%s0, *p);
1016 }
1017 }
1018 In the library, malloc is done for the warning message returning
1021 to the fourth argument. This message is freed when KC_INITIALIZE
1022 or KC_FINALIZE is executed next. The application programmer must
1023 not free it.
1024 The maximum number of warning messages is restricted to 64 now.
1026 The subsequent ones are discarded.
1027 The following warning may be included in a message:
1029 - The dictionary cannot be unmounted.
1031 If NULL is specified as the fourth argument, any warning message
1033 will be discarded.
1034 (5) KC_SETUNDEFKEYFUNCTION — Sets a function for an undefined key.
1036 For example, if you press CTRL-t during input of a reading, it is
1038 regarded as undefined key input. The following processes are
1039 executed, responding to undefined key input:
1040 Macro name Process
1042 kc_normal Beep
1044 kc_through Passes the input to the application program.
1046 kc_kakutei Fixes the input and passes it to the application pro‐
1048 gram.
1049 kc_kill Deletes the input and passes it to the application
1051 program.
1052 If kc_normal is specified, the function set in external variable
1054 jrBeepFunc is called automatically by the library when an unde‐
1055 fined key is input. If the value is not set in jrBeepFunc, noth‐
1056 ing occurs when "jrBeepFunc == NULL" appears.
1057 (Example)
1059 extern (*jrBeepFunc)(), beep();
1060 jrBeepFunc = beep;
1062 XKanjiControl(dpy, win, KC_SETUNDEFKEYFUNCTION, kc_normal);
1063 (6) KC_SETMODEINFOSTYLE — Specifies mode information representation.
1066 You may want to display mode information with data such as the
1068 bit map, rather than character strings. In this case, return of
1069 numeric data as mode information helps you execute the process.
1070 Specify KC_SETMODEINFOSTYLE in XKanjiControl, and pass 1 to arg.
1071 After this, one character representing the mode code (numeric)
1072 plus To convert the value into the mode code, subtract '@' (0x40)
1073 from the returned character string. For the mode codes, see the
1074 mode change description of Item (2) KC_CHANGEMODE.
1075 (7) KC_KAKUTEI, (8) KC_KILL — Kill the currently input character
1077 string.
1078 You may want to relinquish the currently entered character string
1080 for some reason. There are two relinquishing methods. One is to
1081 relinquish the character string after including the currently
1082 entered character string as a fixed one. The other is to discard
1083 the character string completely then relinquish it. For the
1084 first method, specify KC_KAKUTEI in jrKanjiControl. For the sec‐
1085 ond method, specify KC_KILL.
1086 Each of the above influences the display. The XKanjiStatusWith‐
1088 Value must thus be specified as the fourth argument.
1089 (Example)
1091 XKanjiStatusWithValue ksv;
1092 XKanjiStatus ks;
1093 unsigned char buf[SOMESIZE];
1094 .....
1095 ksv.ks = &ks;
1096 ksv.buffer = buf;
1097 ksv.bytes_buffer = SOMESIZE;
1098 XKanjiControl(dpy, win, KC_KAKUTEI, &ksv);
1100 len = ksv.val;
1101 .....
1102 (9) KC_QUERYMODE — Inquiry about the mode
1105 To inquire about the current mode, specify KC_QUERYMODE in XKan‐
1107 jiControl.
1108 Specify the pointer to the character array in which the mode
1110 character string is to be stored. The mode character string is a
1111 character string ending with a null character. To return a
1112 numeric here, specify KC_SETMODEINFOSTYLE in XKanjiControl to
1113 change the mode character string style.
1114 (Example)
1116 char currentMode[MAXMODELEN];
1117 .....
1118 XKanjiControl(dpy, win, KC_QUERYMODE, currentMode);
1119 .....
1120 (10) KC_SETSERVERNAME — Specifies the server to be connected.
1123 KC_SETSERVERNAME enables you to switch the Kana-to-Kanji conver‐
1125 sion server without terminating the application program. To set
1126 the server to connect as the Kana-to-Kanji conversion server,
1127 specify KC_SETSERVERNAME in XKanjiControl. In the fourth argu‐
1128 ment, specify the name of the server to be connected.
1129 (11) KC_SETINITFILENAME — Specifies the customize file.
1131 KC_SETINITFILENAM enables the application program to change the
1133 customize file. To change the customize file, specify
1134 KC_SETINITFILENAME as the third argument and the file name char‐
1135 acter string as the fourth argument. This process must be exe‐
1136 cuted before KC_INTIALIZE.
1137 (Example)
1139 char *inifile = "app-own.canna"
1140 .....
1141 XKanjiControl(dpy, win, KC_SETINITFILENAME, initfile);
1142 .....
1143 (12) KC_CLOSEUICONTEXT Closes the context.
1146 When XKanjiControl or XLookupKanjiString is called, one conver‐
1148 sion context is assigned to combination of dpy and win. Combina‐
1149 tion of dpy and win not used yet can be specified for XKanjiCon‐
1150 trol or XLookupKanjiString. When this is done, a new context is
1151 created for the window and the required memory is reserved.
1152 If a window used up to now is not used, you may want to free the
1154 context memory that has been assigned to this window. To do so,
1155 call XKanjiControl by specifying KC_CLOSEUICONTEXT as the third
1156 argument.
1157 Because this process causes a display change, specify XKanjiSta‐
1159 tusWithValue as the fourth structure.
1160 (Example)
1162 XKanjiStatusWithValue ksv;
1163 XKanjiStatus ks;
1164 unsigned char buf[SOMESIZE];
1165 .....
1166 ksv.ks = &ks;
1167 ksv.buffer = buf;
1168 ksv.bytes_buffer = SOMESIZE;
1169 XKanjiControl(dpy, win, KC_CLOSEUICONTEXT, &ksv);
1171 .....
1172 (13) KC_QUERYMAXMODESTR — Obtains the maximum length of mode display
1175 character string.
1176 The mode display character string can be customized using the
1178 initialize file. It is necessary to examine the size of the dis‐
1179 play area (in the customized resulting mode display character
1180 string) that is to be reserved. Specify KC_QUERYMAXMODESTR as
1181 the third argument, then call XKanjiControl. As a result, the
1182 number of columns necessary for the mode display character string
1183 is returned. (The number of columns is represented, defining
1184 that the width of one half-wide alphanumeric character is 1.
1185 The fourth argument is unused; dummy value 0 is assigned to it.
1187 (Example)
1189 int max_mode_columns;
1190 .....
1191 max_mode_columns = XKanjiControl(dpy, win, KC_QUERYMAXMODESTR, 0);
1192 .....
1193 XKANJICONTROL(3)