Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
UILIBINTRO(3)		   Library Functions Manual		 UILIBINTRO(3)

NAME
       UILib intro -- User interface library intro

DESCRIPTION
       User  interface libraries are responding	to one-chracter	or one-key in-
       put, return various kinds of information.   They	 include  the  unfixed
       character string, fixed character string, marked	segment	position, sta-
       tus display character string, and candidate list	character string.

       The application program displays	the data according to the returned in-
       formation.   It	can also control mode transition by triggering through
       something other than key	pressing (for example, selection  through  the
       mouse).

       The  user  interface  library provides jrKanjiString and	jrKanjiControl
       for the input through the TTY.  It also provides	XLookupKanjiString and
       XKanjiControl for the input through the X window.

       Use of the user interface library requires the following:

       -  Through the TTY:

	  Function	      jrKanjiString, jrKanjiControl

	  Header file	      canna/jrkanji.h

	  Library	      libcanna.a, libcanna.so

       -  Through the X	window:

	  Function	      XLookupKanjiString, XKanjiControl

	  Header file	      canna/kanji.h

	  Library	      libXn.a, libXn.so, libcanna.a, libcanna.so

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

       jrKanjiControl	   Executes the	control	with  jrKanjiString  according
			   to the specified parameters.

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

       XKanjiControl	   Executes the	control	 with  XLookupKanjiString  ac-
			   cording to the specified parameters.

JRKANJISTRING(3)	   Library Functions Manual	      JRKANJISTRING(3)

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 exe-
       cuted in	jrKanjiString.

       For a function or cursor	key, specify a special code (listed in ``FUNC-
       TION  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  re-
       turned 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, informa-
       tion such as the	readings to be converted  need	to  be	echoed	(local
       echo).  jrKanjiString does not perform display such as local echo.  In-
       stead, 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 charac-
       ters 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 buf-
       fer.

       If no character string is to be submitted to local echo,	0 will be  re-
       turned 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 re-
       turns 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 posi-
       tion, and reverse display duration  of  the  candidate  list  character
       string  return  to  the gline structure's line, revPos, and revLen, re-
       spectively.

       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	 (buf-
       fer_return).   If  the fixed character string is	longer than bytes_buf-
       fer, 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 re-
       turn 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)	   Library Functions Manual	     JRKANJICONTROL(3)

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 con-
       text_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 pro-
			 cessing.

       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  in-
       formation in the	arg field.  This structure is defined as follows:

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

       The jrKanjiControl functions can	be executed in the following ways:

       (1)   KC_INITIALIZE -- Initializes Kana-to-Kanji	conversion.

	     KC_INITIALIZE  initializes	Kana-to-Kanji conversion by specifying
	     KC_INITIALIZE in the request field.  Specify one of the following
	     in	 arg:  (1)  the	 pointer  to the char ** type variable used to
	     store the warning message and (2) NULL.

	     The initialize process is basically executed  automatically  when
	     jrKanjiString(3)  is  first  called.   This  is  skipped by using
	     jrKanjiControl for	initialization.

	     For example, when control about Kana-to-Kanji conversion is  exe-
	     cuted  using jrKanjiControl before	use of jrKanjiString(3), Kana-
	     to-Kanji conversion must be initialized.

	     When the process terminates normally, 0 returns as	 the  jrKanji-
	     Control return value.  When it terminates abnormally, -1 returns.

	     When  KC_INITIALIZE is executed, a	warning, rather	than an	error,
	     may occur.	 When it occurs, the pointer to	the warning  character
	     string  array  is stored in and returns to	the variable specified
	     in	arg.  If no warning occurs, NULL is stored and returns.

	     (Example)
	       int res;	/* Prepare for error return */
	       char **warning;
	       .....
	       res = jrKanjiControl(0, KC_INITIALIZE, &warning);
	       if (warning) {
		 char **p;

		 for (p	= warning ; *p ; p++) {
		   fprintf(stderr, "%s0, *p);
		 }
	       }

	     In	the library, malloc is done for	the warning message  returning
	     to	 the third argument.  This message is freed when KC_INITIALIZE
	     or	KC_FINALIZE is executed	next.  The application programmer must
	     not  free	it.   The  maximum  number  of warning messages	is re-
	     stricted to 64 now.  The subsequent ones are discarded.

	     The following warnings may	be included in a message:

	     -	All customize files including those of the system are unavail-
		able.

	     -	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.	 Spec-
	     ify  KC_CHANGEMODE	in the request field.  Specify the jrKanjiSta-
	     tusWithValue structure in arg.

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

	     Macro number	     Mode

	     CANNA_MODE_AlphaMode    Alphabet mode

	     CANNA_MODE_HenkanMode   Conversion	input mode

	     CANNA_MODE_KigoMode     Symbol input mode

	     CANNA_MODE_ZenHiraKakuteiMode
				     Full-wide Hiragana	fixed input mode

	     CANNA_MODE_ZenKataKakuteiMode
				     Full-wide Katakana	fixed mode

	     CANNA_MODE_HanKataKakuteiMode
				     Half-wide Katakana	fixed input mode

	     CANNA_MODE_ZenAlphaKakuteiMode
				     Full-wide alphabet	fixed input mode

	     CANNA_MODE_HanAlphaKakuteiMode
				     Half-wide alphabet	fixed input mode

	     CANNA_MODE_HexMode	     Hexadecimal code input mode

	     CANNA_MODE_BushuMode    Bushu input mode

	     CANNA_MODE_TorokuMode   Word register mode

	     This function causes much dispaly (mode name etc.)	to vary	in re-
	     sponse  to	 a mode	change.	 The display change is returned	by the
	     jrKanjiStatusWithValue structure specified	as arg.

	     (Example)
	       jrKanjiStatus ks;
	       jrKanjiStatusWithValue ksv;
	       unsigned	char buf[SOMESIZE];
	       .....
	       ksv.ks =	&ks;
	       ksv.buffer = buf;
	       ksv.bytes_buffer	= SOMESIZE;
	       ksv.val = CANNA_MODE_HexMode;

	       jrKanjiControl(context, KC_CHANGEMODE, &ksv);
	       len = ksv.val;
	       .....

	     /*	Information about the unfixed or fixed character string	is returned
		by ksv.	*/

       (3)   KC_SETWIDTH -- Specifies the width	used to	display	the  candidate
	     list.

	     KC_SETWIDTH  specifies the	number of columns of the area on which
	     the candidate list	is to be displayed.  The width of  one	column
	     equals  that  of an alphabetical or half-wide Katakana character.
	     Each full-wide  Kanji  character  occupies	 two  columns.	 Using
	     KC_SETWIDTH,  specify the width of	candidate list display area to
	     be	specified in the request field.	 At  this  time,  specify  the
	     number of columns in arg.

	     (Example)
	       jrKanjiControl(0, KC_SETWIDTH, (char *)60);

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

	     KC_FINALIZE specifies that	Kana-to-Kanji conversion  also	final-
	     izes (terminates) at the end of the program and in	other cases.
	      Be  sure	to execute this	process	when terminating Kana-to-Kanji
	     conversion	processing.  All contents learned up to	now are	regis-
	     tered in the file.	 Specify KC_FINALIZE in	the request field.

	     When  the process terminates normally, 0 returns.	When it	termi-
	     nates abnormally, -1 returns.

	     When KC_FINALIZE is executed, a warning, rather  than  an	error,
	     may  occur.  When it occurs, the pointer to the warning character
	     string array is stored in and returns to the  variable  specified
	     in	arg.  If no warning occurs, NULL is stored and returns.

	     (Example)
	       int res;	/* Prepare for error return */
	       char **warning;
	       .....
	       res = jrKanjiControl(0, KC_FINALIZE, &warning);
	       if (warning) {
		 char **p;

		 for (p	= warning ; *p ; p++) {
		   fprintf(stderr, "%s0, *p);
		 }
	       }

	     In	 the library, malloc is	done for the warning message returning
	     to	the third argument.  This message is freed when	 KC_INITIALIZE
	     or	KC_FINALIZE is executed	next.  The application programmer must
	     not free it.

	     The maximum number	of warning messages is restricted to  64  now.
	     The subsequent ones are discarded.

	     The following warning may be included in a	message:

	     -	The dictionary cannot be unmounted.

	     If	 NULL  is specified as the third argument, any warning message
	     will be discarded.

       (5)   KC_SETUNDEFKEYFUNCTION -- Sets a function for an undefined	key.

	     For example, if you press CTRL-t during input of a	reading, it is
	     regarded as undefined key input.  The following processes are ex-
	     ecuted, responding	to undefined key input:

	     Macro name	 Process

	     kc_normal	 Beep

	     kc_through	 Passes	the input to the application

	     kc_kakutei	 Fixes the input and passes it to the application pro-
			 gram.

	     kc_kill	 Deletes  the  input  and passes it to the application
			 program.

	     If	kc_normal is specified,	the function set in external  variable
	     jrBeepFunc	 is  called automatically by the library when an unde-
	     fined key is input.  If the value is not set in jrBeepFunc, noth-
	     ing occurs	when ``jrBeepFunc == NULL'' appears.

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

	       jrBeepFunc = beep;
	       jrKanjiControl(0, KC_SETUNDEFKEYFUNCTION, kc_normal);

       (6)   KC_SETMODEINFOSTYLE -- Specifies mode information representation.

	     You  may  want  to	display	mode information with data such	as the
	     bit map, rather than character strings.  In this case, return  of
	     numeric  data  as mode information	helps you execute the process.
	     Specify KC_SETMODEINFOSTYLE in jrKanjiControl, and	pass 1 to arg.
	     After  this,  one	character representing the mode	code (numeric)
	     plus 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 en-
	     tered 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 sec-
	     ond method, specify KC_KILL.

	     Each of the above influences the display.	The jrKanjiStatusWith-
	     Value must	thus be	specified as the third argument.

	     (Example)
	       jrKanjiStatusWithValue ksv;
	       jrKanjiStatus ks;
	       unsigned	char buf[SOMESIZE];
	       .....
	       ksv.ks =	&ks;
	       ksv.buffer = buf;
	       ksv.bytes_buffer	= SOMESIZE;

	       jrKanjiControl(context, KC_KAKUTEI, &ksv);
	       len = ksv.val;
	       .....

       (9)   KC_QUERYMODE -- Inquiry about the mode

	     To	inquire	about the current mode,	specify	KC_QUERYMODE in	jrKan-
	     jiControl.

	     Specify  the  pointer  to	the  character array in	which the mode
	     character string is to be stored.	The mode character string is a
	     character	string	ending with a null character.  To return a nu-
	     meric here,  specify  KC_SETMODEINFOSTYLE	in  jrKanjiControl  to
	     change the	mode character string style.

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

       (10)  KC_SETSERVERNAME	Specifies the server to	be connected.

	     KC_SETSERVERNAME  enables you to switch the Kana-to-Kanji conver-
	     sion server without terminating the application program.  To  set
	     the  server  to  connect  as the Kana-to-Kanji conversion server,
	     specify KC_SETSERVERNAME in jrKanjiControl.  In the  third	 argu-
	     ment, specify the name of the server to be	connected.

       (11)  KC_SETINITFILENAME	-- Specifies the customize file.

	     KC_SETINITFILENAM	enables	 the application program to change the
	     customize file.  To change	the  customize	file,  specify	KC_SE-
	     TINITFILENAME  as the second argument and the file	name character
	     string as the third argument.  This process must be executed  be-
	     fore KC_INTIALIZE.

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

       (12)  KC_CLOSEUICONTEXT	 Closes	the context.

	     Any integer may be	assigned as the	context	ID that	represents the
	     conversion	context.  A context ID that has	never been used	can be
	     assigned  to jrKanjiString	or jrKanjiControl.  In this case, ini-
	     tialization for this context is executed to reserve the  required
	     memory.

	     If	an input port used up to now is	not used, you may want to free
	     the memory	reserved for the context ID assigned to	this port.  To
	     do	so, call jrKanjiControl	by specifying KC_CLOSEUICONTEXT	as the
	     second argument.

	     Because this process causes a display change, specify jrKanjiSta-
	     tusWithValue as the third structure.

	     (Example)
	       jrKanjiStatusWithValue ksv;
	       jrKanjiStatus ks;
	       unsigned	char buf[SOMESIZE];
	       .....
	       ksv.ks =	&ks;
	       ksv.buffer = buf;
	       ksv.bytes_buffer	= SOMESIZE;

	       jrKanjiControl(0, KC_CLOSEUICONTEXT, &ksv);
	       .....

       (13)  KC_QUERYMAXMODESTR	 -- Obtains the	maximum	length of mode display
	     character string.

	     The mode display character	string can  be	customized  using  the
	     initialize	file.  It is necessary to examine the size of the dis-
	     play area (in the customized  resulting  mode  display  character
	     string)  that  is	to be reserved.	 Specify KC_QUERYMAXMODESTR as
	     the second	argument, then call jrKanjiControl.  As	a result,  the
	     number of columns necessary for the mode display character	string
	     is	returned.  The number of columns is represented, defining that
	     the width of one half-wide	alphanumeric character is 1.

	     The third argument	is unused; dummy value 0 is assigned to	it.

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

XLookupKanjiString(3)	   Library Functions Manual	 XLookupKanjiString(3)

NAME
       XLookupKanjiString -- Converts the keyboard input into Kanji

SYNOPSIS
       #include	<X11/Xlib.h>
       #include	<X11/kanji.h>

       int
       XLookupKanjiString(event_struct,	buffer_return, bytes_buffer,
			  keysym_return, status_return,	kanji_status_return)
	       XKeyEvent *event_struct;
	       char *buffer_return;
	       int bytes_buffer;
	       KeySym *keysym_return;
	       XComposeStatus *status_return;
	       XKanjiStatus *kanji_status_return;

ARGUMENTS
	      event_struct    Specifies	the key	event.

	      buffer_return   Returns the resulting Kanji string.

	      bytes_buffer    Specifies	the buffer length.

	      keysym_return   Returns the key symbol.  NULL may	be specified

	      status_return   Specifies	the pointer to the XCompose structure.

	      kanji_status_return
			      Returns the Kana-to-Kanji	conversion status.

DESCRIPTION
       XLookupKanjiString  is a	convenient routine that	associates a key event
       with a Japanese character string.  It uses the modifier key bit to pro-
       cesses 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,  de-
       fined 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 informations	*/
		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, informa-
       tion 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 charac-
       ters 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 posi-
       tion, and reverse display duration  of  the  candidate  list  character
       string  return  to  the gline structure's line, revPos, and revLen, re-
       spectively.

       If there	is an EUC character string fixed during	conversion, it will be
       stored  in  buffer_return.   In	this  case, the	length (bytes) of this
       character string	will return as the return value	of this	function.   If
       there is	no fixed character string, the return value will be 0.

XKANJICONTROL(3)	   Library Functions Manual	      XKANJICONTROL(3)

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  re-
       quest.	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  pro-
			 cessing.

       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	termi-
       nate 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 in-
       formation in the	arg field.  This structure is defined as follows:

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

       The XKanjiControl functions can be executed in the following ways:

       (1)   KC_INITIALIZE -- Initializes Kana-to-Kanji	conversion.

	     KC_INITIALIZE initializes Kana-to-Kanji conversion	by  specifying
	     KC_INITIALIZE in the request field.  Specify one of the following
	     in	arg: (1) the pointer to	the char  **  type  variable  used  to
	     store  the	 warning message and (2) NULL.	The initialize process
	     is	basically executed automatically when XLookupKanjiString(3) is
	     first  called.   This  is skipped by using	XKanjiControl for ini-
	     tialization.

	     For example, when control about Kana-to-Kanji conversion is  exe-
	     cuted  using  XKanjiControl  before use of	XLookupKanjiString(3),
	     Kana-to-Kanji conversion must be initialized.

	     When the process terminates normally, 0 returns as	the XKanjiCon-
	     trol return value.	 When it terminates abnormally,	-1 returns.

	     When  KC_INITIALIZE is executed, a	warning, rather	than an	error,
	     may occur.	 When it occurs, the pointer to	the warning  character
	     string  array  is stored in and returns to	the variable specified
	     in	arg.  If no warning occurs, NULL is stored and returns.

	     (Example)
	       int res;	/* Prepare for error return */
	       char **warning;
	       .....
	       res = XKanjiControl(dpy,	win, KC_INITIALIZE, &warning);
	       if (warning) {
		 char **p;

		 for (p	= warning ; *p ; p++) {
		   fprintf(stderr, "%s0, *p);
		 }
	       }

	     In	the library, malloc is done for	the warning message  returning
	     to	the fourth argument.  This message is freed when KC_INITIALIZE
	     or	KC_FINALIZE is executed	next.  The application programmer must
	     not  free	it.   The  maximum  number  of warning messages	is re-
	     stricted to 64 now.  The subsequent ones are discarded.

	     The following warnings may	be included in a message:

	     -	All customize files including those of the system are unavail-
		able.

	     -	The customize file contains a syntax error.

	     -	The Romaji-to-Kana conversion dictionary is unavailable.

	     -	The Kana-to-Kanji conversion dictionary	is unavailable.

	     -	Connection to the Kana-to-Kanji	conversion server is disabled.

	     If	 NULL is specified as the fourth argument, any warning message
	     will be discarded.

       (2)   KC_CHANGEMODE -- Changes the input	mode.

	     KC_CHANGEMODE changes the input mode from the application.	 Spec-
	     ify  KC_CHANGEMODE	 in the	request	field.	Specify	the XKanjiSta-
	     tusWithValue structure in arg.  The Japanese mode is  changed  by
	     specifying	 the  mode  number  with  the val member of XKanjiSta-
	     tusWithValue structure.  The mode number is indicated by the fol-
	     lowing macros:

	     Macro number	     Mode

	     CANNA_MODE_AlphaMode    Alphabet mode

	     CANNA_MODE_HenkanMode   Conversion	input mode

	     CANNA_MODE_KigoMode     Symbol input mode

	     CANNA_MODE_ZenHiraKakuteiMode
				     Full-wide Hiragana	fixed input mode

	     CANNA_MODE_ZenKataKakuteiMode
				     Full-wide Katakana	fixed mode

	     CANNA_MODE_HanKataKakuteiMode
				     Half-wide Katakana	fixed input mode

	     CANNA_MODE_ZenAlphaKakuteiMode
				     Full-wide alphabet	fixed input mode

	     CANNA_MODE_HanAlphaKakuteiMode
				     Half-wide alphabet	fixed input mode

	     CANNA_MODE_HexMode	     Hexadecimal code input mode

	     CANNA_MODE_BushuMode    Bushu input mode

	     CANNA_MODE_TorokuMode   Word register mode

	     This function causes much dispaly (mode name etc.)	to vary	in re-
	     sponse to a mode change.  The display change is returned  by  the
	     XKanjiStatusWithValue structure specified as arg.

	     (Example)
	       XKanjiStatus ks;
	       XKanjiStatusWithValue ksv;
	       unsigned	char buf[SOMESIZE];
	       .....
	       ksv.ks =	&ks;
	       ksv.buffer = buf;
	       ksv.bytes_buffer	= SOMESIZE;
	       ksv.val = CANNA_MODE_HexMode;

	       XKanjiControl(dpy, win, KC_CHANGEMODE, &ksv);
	       len = ksv.val;
	       .....
	       /* Information about the	unfixed	or fixed character string is
		  returned by ksv. */

       (3)   KC_SETWIDTH  -- Specifies the width used to display the candidate
	     list.

	     KC_SETWIDTH specifies the number of columns of the	area on	 which
	     the  candidate  list is to	be displayed.  The width of one	column
	     equals that of an alphabetical or half-wide  Katakana  character.
	     Each  full-wide  Kanji  character	occupies  two  columns.	 Using
	     KC_SETWIDTH, specify the width of candidate list display area  to
	     be	 specified  in	the  request field.  At	this time, specify the
	     number of columns in arg.

	     (Example)
	       XKanjiControl(dpy, win, KC_SETWIDTH, (char *)60);

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

	     KC_FINALIZE  specifies  that Kana-to-Kanji	conversion also	final-
	     izes (terminates) at the end of the program and in	 other	cases.
	     Be	 sure  to  execute this	process	when terminating Kana-to-Kanji
	     conversion	processing.  All contents learned up to	now are	regis-
	     tered in the file.	 Specify KC_FINALIZE in	the request field.

	     When  the process terminates normally, 0 returns.	When it	termi-
	     nates abnormally, -1 returns.

	     When KC_INITIALIZE	is executed, a warning,	rather than an	error,
	     may  occur.  When it occurs, the pointer to the warning character
	     string array is stored in and returns to the  variable  specified
	     in	arg.  If no warning occurs, NULL is stored and returns.

	     (Example)
	       int res;	/* Prepare for error return */
	       char **warning;
	       .....
	       res = XKanjiControl(dpy,	win, KC_FINALIZE, &warning);
	       if (warning) {
		 char **p;

		 for (p	= warning ; *p ; p++) {
		   fprintf(stderr, "%s0, *p);
		 }
	       }

	     In	 the library, malloc is	done for the warning message returning
	     to	the fourth argument.  This message is freed when KC_INITIALIZE
	     or	KC_FINALIZE is executed	next.  The application programmer must
	     not free it.

	     The maximum number	of warning messages is restricted to  64  now.
	     The subsequent ones are discarded.

	     The following warning may be included in a	message:

	     -	The dictionary cannot be unmounted.

	     If	 NULL is specified as the fourth argument, any warning message
	     will be discarded.

       (5)   KC_SETUNDEFKEYFUNCTION -- Sets a function for an undefined	key.

	     For example, if you press CTRL-t during input of a	reading, it is
	     regarded as undefined key input.  The following processes are ex-
	     ecuted, responding	to undefined key input:

	     Macro name	 Process

	     kc_normal	 Beep

	     kc_through	 Passes	the input to the application program.

	     kc_kakutei	 Fixes the input and passes it to the application pro-
			 gram.

	     kc_kill	 Deletes  the  input  and passes it to the application
			 program.

	     If	kc_normal is specified,	the function set in external  variable
	     jrBeepFunc	 is  called automatically by the library when an unde-
	     fined key is input.  If the value is not set in jrBeepFunc, noth-
	     ing occurs	when "jrBeepFunc == NULL" appears.

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

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

       (6)   KC_SETMODEINFOSTYLE -- Specifies mode information representation.

	     You  may  want  to	display	mode information with data such	as the
	     bit map, rather than character strings.  In this case, return  of
	     numeric  data  as mode information	helps you execute the process.
	     Specify KC_SETMODEINFOSTYLE in XKanjiControl, and pass 1 to  arg.
	     After  this,  one	character representing the mode	code (numeric)
	     plus 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 en-
	     tered 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 sec-
	     ond method, specify KC_KILL.

	     Each  of the above	influences the display.	 The XKanjiStatusWith-
	     Value must	thus be	specified as the fourth	argument.

	     (Example)
	       XKanjiStatusWithValue ksv;
	       XKanjiStatus ks;
	       unsigned	char buf[SOMESIZE];
	       .....
	       ksv.ks =	&ks;
	       ksv.buffer = buf;
	       ksv.bytes_buffer	= SOMESIZE;

	       XKanjiControl(dpy, win, KC_KAKUTEI, &ksv);
	       len = ksv.val;
	       .....

       (9)   KC_QUERYMODE -- Inquiry about the mode

	     To	inquire	about the current mode,	specify	KC_QUERYMODE in	 XKan-
	     jiControl.

	     Specify  the  pointer  to	the  character array in	which the mode
	     character string is to be stored.	The mode character string is a
	     character	string	ending with a null character.  To return a nu-
	     meric  here,  specify  KC_SETMODEINFOSTYLE	 in  XKanjiControl  to
	     change the	mode character string style.

	     (Example)
	       char currentMode[MAXMODELEN];
	       .....
	       XKanjiControl(dpy, win, KC_QUERYMODE, currentMode);
	       .....

       (10)  KC_SETSERVERNAME -- Specifies the server to be connected.

	     KC_SETSERVERNAME  enables you to switch the Kana-to-Kanji conver-
	     sion 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	 argu-
	     ment, specify the name of the server to be	connected.

       (11)  KC_SETINITFILENAME	-- Specifies the customize file.

	     KC_SETINITFILENAM	enables	 the application program to change the
	     customize file.  To change	the  customize	file,  specify	KC_SE-
	     TINITFILENAME  as	the third argument and the file	name character
	     string as the fourth argument.  This process must be executed be-
	     fore KC_INTIALIZE.

	     (Example)
	       char *inifile = "app-own.canna"
	       .....
	       XKanjiControl(dpy, win, KC_SETINITFILENAME, initfile);
	       .....

       (12)  KC_CLOSEUICONTEXT	 Closes	the context.

	     When  XKanjiControl  or XLookupKanjiString	is called, one conver-
	     sion context is assigned to combination of	dpy and	win.  Combina-
	     tion  of dpy and win not used yet can be specified	for XKanjiCon-
	     trol or XLookupKanjiString.  When this is done, a new context  is
	     created for the window and	the required memory is reserved.

	     If	 a window used up to now is not	used, you may want to free the
	     context memory that has been assigned to this window.  To do  so,
	     call  XKanjiControl  by specifying	KC_CLOSEUICONTEXT as the third
	     argument.

	     Because this process causes a display change, specify  XKanjiSta-
	     tusWithValue as the fourth	structure.

	     (Example)
	       XKanjiStatusWithValue ksv;
	       XKanjiStatus ks;
	       unsigned	char buf[SOMESIZE];
	       .....
	       ksv.ks =	&ks;
	       ksv.buffer = buf;
	       ksv.bytes_buffer	= SOMESIZE;

	       XKanjiControl(dpy, win, KC_CLOSEUICONTEXT, &ksv);
	       .....

       (13)  KC_QUERYMAXMODESTR	 -- Obtains the	maximum	length of mode display
	     character string.

	     The mode display character	string can  be	customized  using  the
	     initialize	file.  It is necessary to examine the size of the dis-
	     play area (in the customized  resulting  mode  display  character
	     string)  that  is	to be reserved.	 Specify KC_QUERYMAXMODESTR as
	     the third argument, then call XKanjiControl.  As  a  result,  the
	     number of columns necessary for the mode display character	string
	     is	returned.  (The	number of  columns  is	represented,  defining
	     that the width of one half-wide alphanumeric character is 1.

	     The fourth	argument is unused; dummy value	0 is assigned to it.

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

							      XKANJICONTROL(3)

NAME | DESCRIPTION | Outline | NAME | SYNOPSIS | DESCRIPTION | FUNCTION KEYS | SEE ALSO | RETURN VALUE | NAME | SYNOPSIS | DESCRIPTION | NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | NAME | SYNOPSIS | DESCRIPTION

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=XKanjiControl&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help