% Copyright 1994 NEC Corporation, Tokyo, Japan.
%
% Permission to use, copy, modify, distribute and sell this software
% and its documentation for any purpose is hereby granted without
% fee, provided that the above copyright notice appear in all copies
% and that both that copyright notice and this permission notice
% appear in supporting documentation, and that the name of NEC
% Corporation not be used in advertising or publicity pertaining to
% distribution of the software without specific, written prior
% permission.  NEC Corporation makes no representations about the
% suitability of this software for any purpose.  It is provided "as
% is" without express or implied warranty.
%
% NEC CORPORATION DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
% INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN 
% NO EVENT SHALL NEC CORPORATION BE LIABLE FOR ANY SPECIAL, INDIRECT OR
% CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF 
% USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR 
% OTHER TORTUOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 
% PERFORMANCE OF THIS SOFTWARE. 
%
%

\chapter{かな漢字変換ライブラリ}
\label{5かな漢字変換ライブラリ}

\section{ライブラリ概説}

\subsection{ライブラリと階層}

『かんな』では、
\HIDX{かな漢字変換ライブラリ}{かなかんしへんかんらいふらり}{H0.9.0.0.0}
として以下の 2 つのライブラリを提供しています。

\begin{itemize}

\item {ユーザインタフェースライブラリ}

1 文字の入力、1 キーの入力に対応して、未確定文字列、確定文字列、注目文節
位置、ステータス表示のための文字列、候補一覧のための文字列などを返還す
るライブラリです。低レベルかな漢字変換ライブラリに見られるような辞書
のメンテナンスや、学習の制御などに関する機能は、このライブラリ
では提供しません。日本語入力ユーザインタフェースの大まかなラインは規定
されますが、表示部分に若干の工夫をする余地は残ります。X ウィ
ンドウにおいて、図形と文字を同じウィンドウ内で入力/表示したいアプリケー
ションはこのアプリケーションインタフェースを用いることをお勧めします。

\item {RKライブラリ}

辞書のアクセスや候補の選択を直接制御したいときに用います。このレベルのか
な漢字変換ライブラリでは、かな漢字変換システムの利用開始、読みから漢字
への変換、文節の切り分けの変更、次候補/前候補の取り出し、学習の制御、
辞書のメンテナンスなどの処理に対する関数インタフェースを提供します。低
レベルライブラリは中レベルアプリケーションインタフェースや高レベルアプ
リケーションインタフェースを構築するために用いられています。一般のユー
ザは用いないほうが良いでしょう。

\end{itemize}

\subsection{ライブラリとヘッダファイルについて}
\label{5.1.1ライブラリとヘッダファイルについて}

本システムは、ライブラリ 1 つとヘッダファイル 2 つを提供しています。
それぞれの詳細を以下に示します。

\begin{itemize}
\item {\dg\bf ライブラリ}

\begin{tabular}{lp{1.7cm}p{12.8cm}}
(1) & libcanna.$\ast$          & 日本語入力のためのライブラリです。\\
\end{tabular}
\HIDXAS{libcanna.$\ast$\/}{ＬＩＢＣＡＮＮＡ．＊}{H0.9.1.2.0}

\item {\dg\bf ヘッダファイル}

\begin{tabular}{lp{1.7cm}p{12.8cm}}
(1) & \HIDX{jrkanji.h}{ＪＲＫＡＮＪＩ．Ｈ}{H0.9.1.2.0.a}\hptar{label=H0.9.1.2.0.a}  & (\CANNAINCLUDEDIR) TTYレベルの日本語の入出力を行うときに必要なヘッダファイルです。\\
(2) & \HIDX{RK.h}{ＲＫ．Ｈ}{H0.9.1.2.0.b}\hptar{label=H0.9.1.2.0.b}  & (\CANNAINCLUDEDIR) RKライブラリを使用するとき必要なヘッダファイルです。\\
\end{tabular}

\end{itemize}

下表の関数を利用する場合は、表に示すライブラリをリンクし、
ヘッダファイルをインクルードしてください。

\vspace{10mm}
\begin{center}
\begin{tabular}{|c|c|c|}
\hline
関　　　　　数            &  ライブラリ                   & ヘッダファイル\\
\hline
jrKanjiString             &  libcanna.$\ast$              & canna/jrkanji.h\\
\hline
RKライブラリ              &  libcanna.$\ast$              & canna/RK.h\\
\hline
\end{tabular}
\end{center}
\vspace{10mm}

{
\begin{nquote}{1em}
\begin{namelist}{注}
\item [注意] ライブラリ名の ".$\ast$" は、".a"、".so" などを表します。
\end{namelist}
\end{nquote}
}

\subsection{\HIDX{libcanna 使用時の注意}
{ＬＩＢＣＡＮＮＡしようしのちゆうい}{H0.9.1.3.0}事項}

libcanna.$\ast$ をリンクするアプリケーションを作成する際には、
以下の点に注意してください。

\begin{itemize}
\item libucb と libcanna は同時にリンクすることはできません。

したがって、\verb+/usr/ucb/cc+ を用いてコンパイルするようなアプリケーション
や、libucb を明示的にリンクするようなアプリケーションでは、
libcanna をリンクしないでください。

\item libcanna の提供する関数はマルチスレッドに対応していません。

したがって、EWS-UX/V(Rel4.2MP), UP-UX/V(Rel4.2MP) においてマルチスレッド機能を
用いる場合、libcanna で提供する関数は単一のスレッドからのみ呼び出してください。

\end{itemize}

\newpage

\section{ユーザインタフェースライブラリ}
\label{5.2中レベルのライブラリ}

\HIDX{ユーザインタフェースライブラリ}{ゆーさいんたふえーすらいふらり}
{H0.9.2.0.0}は、
1 文字の入力、1 キーの入力に対応して、未確定文字列、確定文字列、
注目文節位置、ステータス表示のための文字列、候補一覧のための
文字列などを返還するライブラリです。
アプリケーションプログラムは、返還された情報によって表示します。
アプリケーションプログラムは、キー入力以外のトリガー
(たとえばマウスによる選択など)によってモードの遷移を制御することもできます。
 
ユーザインタフェースライブラリは、jrKanjiString などの汎用ベースの関数を
提供します。

ユーザインタフェースライブラリの関数と、その関数を使用する際に必要なファイルを
表\ref{ユーザインタフェースライブラリ関数およびそのファイル一覧}に示します。

{\small
\begin{table}[hbtp]
\begin{center}
\caption{ユーザインタフェースライブラリ関数およびそのファイル一覧}
\label{ユーザインタフェースライブラリ関数およびそのファイル一覧}
\begin{tabular}{|c|c|c|c|c|}
\hline
用　　途    & 文字コード       & 関　　　数           & ライブラリ      & ヘッダファイル\\
\hline
            &                  & jrKanjiString        & & \\
\cline{3-3}
            & EUC              & jrKanjiControl       & & \\
\cline{3-3}
            &                  & jrCloseKanjiContext  & & \\
\cline{2-3}
            & ワイド           & wcKanjiString        & & \\
\cline{3-3}
汎　　用    & キャラクタ       & wcKanjiControl       & libcanna.$\ast$      & canna/jrkanji.h\\
\cline{3-3}
            &                  & wcCloseKanjiContext  & & \\
\cline{2-3}
            &                  & kanjiInitialize      & & \\
\cline{3-3}
            & 共　通           & kanjiFinalize        & & \\
\cline{3-3}
            &                  & createKanjiContext   & & \\
\hline
\end{tabular}
\end{center}
\end{table}
}

\begin{nquote}{1em}
\begin{namelist}{注}
\item [注意] ライブラリ名の ".$\ast$" は、".a"、".so" などを表します。
\end{namelist}
\end{nquote}

% 9.2.1
\subsection{提供機能}
\HIDXAS{ユーザインタフェースライブラリの機能}{ゆーさいんたふえーすらいふらりのきのう}{H0.9.2.1.0}
\label{5.2.1提供機能}

\begin{namelist}{XwcLookupKanjiString}
\item [{\rm jrKanjiString}]
TTYからの入力、Xでの入力、基本ウィンドウでの入力など一般的なキーボード
入力に対して漢字文字列への変換を行います。漢字文字列はEUCコード扱いで
す。

\item [{\rm jrKanjiControl}]
指定されたパラメータにより、jiKanjiString での制御を行います。

\item [{\rm wcKanjiStirng}]
jrKanjiString と基本的な機能は同じです。
ほとんどの文字列の扱いがワイドキャラクタになっています。

\item [{\rm wcKanjiControl}]
wcKanjiString での制御を指定されたパラメータにより行います。

\item [{\rm kanjiInitialize}]
かな漢字変換の初期化を行います。

\item [{\rm kanjiFinalize}]
プログラム終了などに伴うかな漢字変換終了処理を行います。

\item [{\rm createKanjiContext}]
かな漢字変換に使用するコンテクストを作成します。

\item [{\rm jrCloseKanjiContext}]
jrKanjiString でかな漢字変換に使用したコンテクストをクローズします。

\item [{\rm wcCloseKanjiContext}]
wcKanjiString でかな漢字変換に使用したコンテクストをクローズします。

\end{namelist}

% 9.2.2
\subsection{利用ガイド}
\label{5.2.2利用ガイド}

ここでは\HIDX{ユーザインタフェースライブラリの使用法}{ゆーさいんたふぇー
すらいふらりのしようほう}{H0.9.2.2.0}について説明します。

% 9.2.2.1
\subsubsection{簡単な例}
\label{5.2.2.1簡単な例}

以下にユーザインタフェースライブラリを用いた簡単な例を示します。\\

\begin{tabular}{|p{15cm}|}
\hline
\ \verb- 1  #include <stdio.h>-\\
\ \verb- 2  #include <canna/jrkanji.h>-\\
\ \verb- 3-\\
\ \verb- 4  #define MAX_SIZE 1024-\\
\ \verb- 5-\\
\ \verb- 6  main()-\\
\ \verb- 7  {-\\
\ \verb- 8    int c, nbytes;-\\
\ \verb- 9    unsigned char workbuf[MAX_SIZE];-\\
\ \verb-10    jrKanjiStatus ks;-\\
\ \verb-11-\\
\ \verb-12    jrKanjiControl(0, KC_INITIALIZE, 0);-\\
\ \verb-13    {-\\
\ \verb-14      jrKanjiStatusWithValue ksv;-\\
\ \verb-15-\\
\ \verb-16      ksv.ks = &ks;-\\
\ \verb-17      ksv.buffer = workbuf;-\\
\ \verb-18      ksv.bytes_buffer = MAX_SIZE;-\\
\ \verb-19      ksv.val = CANNA_MODE_HenkanMode;-\\
\ \verb-20      jrKanjiControl(0, KC_CHANGEMODE, &ksv);-\\
\ \verb-21    }-\\
\ \verb-22    c = getchar();-\\
\ \verb-23    while (c != EOF) {-\\
\ \verb-24      nbytes = jrKanjiString(0, c, workbuf, MAX_SIZE, &ks);-\\
\ \verb-25      if (nbytes > 0) {-\\
\ \verb-26        workbuf[nbytes] = '\0';-\\
\ \verb-27        printf("%s\n", workbuf);-\\
\ \verb-28      }-\\
\ \verb-29      c = getchar();-\\
\ \verb-30    }-\\
\ \verb-31    jrKanjiControl(0, KC_FINALIZE, 0);-\\
\ \verb-32    exit(0);-\\
\ \verb-33  }-\\
\hline
\end{tabular}
\\

このプログラムをコンパイルし、実行した結果は以下のようになります。
以下の例で \verb*/ / は半角のスペース文字を表します。

\begin{nquote}{3em}
\begin{tabular}{|l|}
\hline
\verb+% cc sample1.c -lcanna -o sample1+ \\
\verb+% sample1+\\
\verb*+koreha kantannna puroguramudesu. +\\
これは\\
簡単な\\
プログラムです。\\
\verb+% + \CURSOR \\
\hline
\end{tabular}
\end{nquote}

\begin{nquote}{3em}
ただし、SVR4 系マシンでは、-lsocket、-lnsl を指定してください。
\end{nquote}

上記プログラムでは、12 行目 〜 21 行目で初期化処理、22 行目 〜 30 行目で
ローマ字かな変換/かな漢字変換処理をしています。31 行目は終了処理です。
上記プログラムの詳細について以下で説明します。

% 9.2.2.2
\subsubsection{ユーザインタフェースライブラリ}
\label{5.2.2.2ユーザインタフェースライブラリ}

ユーザインタフェースライブラリでは、個々の入力に対して表示すべき文字列と
確定した文字列を返します。たとえば、
「kanjini$<$space$>$shimasu$<$return$>$」のような入力があったときに、ユー
ザインタフェースライブラリに対する入出力は以下のようになります。

\vspace{10mm}
\begin{center}
\begin{tabular}{|c|l|l|c|l|l|}
\hline
入　力  & \multicolumn{2}{|c|}{出　　　力}  \\
\cline{2-3}
        & 表　　示   & 確定文字\\
\hline
k       & k          & \\
a       & か         & \\
n       & かn        & \\
j       & かんj      & \\
i       & かんじ     & \\
n       & かんじn    & \\
i       & かんじに   & \\
$<$space$>$ & 漢字に     & \\
\hline
\end{tabular}
\begin{tabular}{|c|l|l|}
\hline
入　力  & \multicolumn{2}{|c|}{出　　　力}  \\
\cline{2-3}
        & 表　　示   & 確定文字\\
\hline
s       & s          & 漢字に\\
h       & sh         & \\
i       & し         & \\
m       & しm        & \\
a       & しま       & \\
s       & しまs      & \\
u       & します     & \\
$<$return$> $ &      & します\\
\hline
\end{tabular}
\end{center}
\vspace{10mm}

\HIDX{アプリケーションプログラムの処理}
{あふりけーしよんふろくらむのしより}{H0.9.2.2.2}は以下の 3 つから構成されます。

\begin{nquote}{2em}
\begin{enumerate}
\item 1 文字ごとの入力をユーザインタフェースライブラリに与える。

\item その結果ユーザインタフェースライブラリが返す中間表示文字列を表示する。

\item 確定文字列として返ってきた文字列を入力して取り扱う。
\end{enumerate}
\end{nquote}

すなわち、アプリケーションプログラムは何らかの入力を 1 文字ごとに
ライブラリに与え、その結果得られる中間結果文字列を表示する処理を行います。
もちろん、確定文字列として得られる文字列は自分の入力として扱います。

スペースキーが変換キーであるとか、矢印キーが右移動であるなどの
ユーザインタフェースにかかわる処理はライブラリ内部で行われるので、
アプリケーションプログラムはそのような煩わしいことに関知することなく
日本語入力が行えます。

上記で説明した中間結果および確定文字列を返す関数は
jrKanjiString という関数です。前述のプログラムでは 24 行目に使われ
ており、プログラム中で中心的な役割を行っています。

この関数を使うためには、まず、次のようにヘッダファイルをインクルードしなければ
なりません。

\vspace{10mm}
\begin{nquote}{3em}
\begin{tabular}{|l|}
\hline
\ \verb+#include <canna/jrkanji.h>+\\
\hline
\end{tabular}
\end{nquote}
\vspace{10mm}

jrKanjiString は以下のような関数仕様になっています。

\vspace{10mm}
\begin{nquote}{3em}
\begin{tabular}{|l|}
\hline
\ \verb+jrkanjiString(context_id, ch, buffer_return,+\\
\ \verb+              bytes_buffer, kanji_status_return)+\\
\ \verb+int context_id;+\\
\ \verb+int ch;+\\
\ \verb+char *buffer_return;+\\
\ \verb+int bytes_buffer;+\\
\ \verb+jrKanjiStatus *kanji_status_return;+\\
\hline
\end{tabular}
\end{nquote}
\vspace{10mm}

引数には {\it context\_id、ch、buffer\_return、
bytes\_buffer、kanji\_status\_re\-turn} があります。

{\it context\_id} にはコンテクスト識別子を指定します。\\
コンテクストに関しては、
{\dg\bf \ref{5.2.2.3コンテクスト} \hpref{count=6,label=H0.9.2.2.3} コンテクスト} を参照してください。

{\it ch} は入力された文字です。

{\it buffer\_return} には確定した文字列を返すためのバッファを指定します。
このバッファはアプリケーションプログラムが準備します。
確定文字列ができると jrKanjiString は確定文字列を
このバッファに格納して返します。

{\it bytes\_buffer} は {\it buffer\_return} のバッファ長です。
jrKanjiString は、どんなに長い文字列が確定文字列として発生した場合においても
 {\it bytes\_buffer} で与えられた長さ以上の文字を返すことはありません。

{\it kanji\_status\_return} は中間表示のための情報、
その他が入っている jrKanjiStatus 型の構造体です。
jrKanjiStatus 型については、
{\dg\bf \ref{5.2.2.6中間表示} \hpref{count=4,label=H0.9.2.2.6} 中間表示} を
参照してください。

\subsubsection{\HIDX{コンテクスト}{こんてくすと}{H0.9.2.2.3}}
\label{5.2.2.3コンテクスト}

ユーザインタフェースライブラリの呼び出しには必ず {\it context\_id} を指
定します。

さて、{\it context\_id} とは何でしょうか。

アプリケーションプログラムが 2 つのウィンドウを同時に表示しており、それ
ぞれのウィンドウにおいて入力を受け付けている状況を考えてください。

% --------------------
% 図形
\begin{figure}[htbp]
\caption{コンテクスト説明図}\label{コンテクスト説明図}
\begin{center}
%\epsfile{file=../zukei/context.eps,scale=0.7}
\includegraphics[scale=0.7]{../zukei/context.eps}
\end{center}
\end{figure}
% --------------------

2 つのウィンドウでの入力は独立して行われると考えるのが自然です。

すなわち、1 つのウィンドウで『わたしの$<$変換$>$』まで入力したときに
他のウィンドウで入力を始めても、最初のウィンドウでは『わたしの
$<$変換$>$』の状態のままであるのが望ましいわけです。

このような処理はかな漢字変換を行っているプロセスがウィンドウごとに別々
であれば自然に行える処理ですが、単一のプロセスで複数の入力部を持つ
場合には入力の切り分けをうまく行わなければなりません。

上記の場合、キーの入力がどちらのウィンドウのものであるかを区別する
識別子が必要になります。
その識別子が {\it context\_id} です。
{\it context\_id} はユーザインタフェースライブラリを呼び出すときに、
どの入力ポートに関するものであるかを表すものです。
すなわち、かな漢字変換の処理単位を示す識別子なのです。

{\it context\_id} には、int 型の値であり、
複数の入力部間で重複することのない値であれば、
どのような値を与えてもかまいません。
たとえば、open で返されるファイル記述子や fopen で返されるファイルポイ
ンタを int 型にキャストしたものでも良いのです。
特に X ウィンドウのプログラミングでは Widget 構造体へのポインタを int 型
にキャストして用いると良いでしょう。

コンテクストを切り分ける必要がない場合には {\it context\_id} として 0 を指
定します。

\subsubsection{初期化処理}
\label{5.2.2.4初期化処理}

きちんとした初期化処理を行わずに jrKanjiString を呼び出した場合でも、
jrKanji\-String の最初の呼び出し時に自動的に初期化処理が行われます。
しかし、明示的に初期化処理を行う方が望ましいプログラミングスタイルといえ
ます。

かな漢字変換処理を初期化するためには以下の処理を行います。
\HIDXAS{かな漢字変換の初期化処理}{かなかんしへんかんのしよきかしより}{H0.9.2.2.4}

\vspace{10mm}
\begin{nquote}{3em}
\begin{tabular}{|l|}
\hline
\ \verb+char **warn;+\\
\\
\ \verb+jrKanjiControl(context_id, KC_INITIALIZE, &warn);+\\
\hline
\end{tabular}
\end{nquote}
\vspace{10mm}

jrKanjiControl はかな漢字変換処理に関する制御を行うための関数
です。第 1 引数には {\it context\_id} を与え、第 2 引
数にはどのような制御を行うかを表すコントロールキーワードを与えます。
第 3 引数には警告メッセージのポインタの格納場所を与えます。

初期化を行う場合には、第 2 引数に KC\_INITIALIZE を指定します。
前述のサンプルプログラムでは 12 行目で呼び出しています。

初期化時には以下の 4 つの処理が行われます。

\begin{nquote}{2em}
\begin{enumerate}
\item カスタマイズファイルの読み込み

\item ローマ字かな変換テーブルの読み込み

\item かな漢字変換サーバとの接続

\item 辞書のマウント処理
\end{enumerate}
\end{nquote}

初期化処理にはコンテクストは関係しないので、
{\it context\_id} としては 0 を与えます。

第 3 引数には警告メッセージが返されます。初期化処理において
警告が発生した場合、第 3 引数で指定された変数に警告
メッセージへのポインタが格納されます。警告メッセージを標
準エラー出力に表示したい場合には以下のような処理を行います。

\vspace{10mm}
\begin{nquote}{3em}
\begin{tabular}{|l|}
\hline
\ \verb+char **warn;+\\
\\
\ \verb+jrKanjiControl(0, KC_INITIALIZE, &warn);+\\
\ \verb+if (warn) {+\\
\ \verb+  char **p;+\\
\\
\ \verb-  for (p = warn ; *p ; p++) {-\\
\ \verb+    fprintf(stderr, "%s\n", *p);+\\
\ \verb+  }+\\
\ \verb+}+\\
\hline
\end{tabular}
\end{nquote}
\vspace{10mm}

警告メッセージが必要でない場合は第 3 引数に 0 を指定します。

\subsubsection{終了処理}
\label{5.2.2.5終了処理}

\HIDX{かな漢字変換の終了処理}{かなかんしへんかんのしゆうりようしより}{H0.9.2.2.5}を行う場合は、
jrKanjiControl の第 2 引数に KC\_FINELIZE を指定します。
前述のサンプルプログラムでは 31 行目で呼び出しています。

終了時には以下の処理が行われます。

\begin{nquote}{2em}
\begin{enumerate}
\item 学習情報の辞書への書き込み

\item 辞書のアンマウント

\item かな漢字変換サーバとの接続の切断

\item ローマ字かな変換テーブルの解放

\item 各種カスタマイズ設定のリセット

\item かな漢字変換に使われていたメモリの解放
\end{enumerate}
\end{nquote}

終了処理時の第 3 引数の取扱いは初期化処理時と同じになります。

終了処理は、プログラム終了時およびかな漢字変換終了時には
必ず呼び出してください。

\subsubsection{\HIDX{中間表示}{ちゆうかんひようし}{H0.9.2.2.6}}
\label{5.2.2.6中間表示}

中間表示情報は jrKanjiStatus 構造体で返されます。
jrKanjiStatus について説明する前に、中間表示にはどのようなものがあるかについて
以下で説明します。

% -------------------
% 図形
\begin{figure}[htbp]
\caption{中間表示図}\label{中間表示図}
\begin{center}
%\epsfile{file=../zukei/interdpy.eps,scale=0.7}
\includegraphics[scale=0.7]{../zukei/interdpy.eps}
\end{center}
\end{figure}
% -------------------

図\ref{中間表示図}に示されるように
中間表示としては以下の 3 つがあります。

\begin{nquote}{2em}
\begin{enumerate}

\item 変換の様子を示す入力部

\item モードを表すモード表示部

\item 候補一覧など、その他の情報を表すガイドライン表示部
\end{enumerate}
\end{nquote}

入力部およびガイドライン表示部は表示の一部が反転するといった強調表示が
行われることがあります(図\ref{中間表示図} において四角で囲まれている部分)。
jrKanjiStatus 構造体では、
このような強調表示される部分がどこであるのかといった情報も返されます。

中間表示のための情報は以下の構造体により返されます。

\vspace{10mm}
\begin{nquote}{3em}
\begin{tabular}{|l|}
\hline
\ \verb-typedef struct {-\\
\ \verb-  unsigned char *echoStr;  /*- {\dg 入力部分の文字列} \verb-*/-\\
\ \verb-  int           length;    /*- {\dg その長さ} \verb-*/-\\
\ \verb-  int           revPos;    /*- {\dg 強調表示の開始位置} \verb-*/-\\
\ \verb-  int           revLen;    /*- {\dg 強調表示の長さ} \verb-*/-\\
\ \verb-  int           info;      /*- {\dg その他の情報。下を見よ} \verb-*/-\\
\ \verb-  unsigned char *mode;     /*- {\dg モード情報} \verb-*/-\\
\ \verb-  struct {-\\
\ \verb-    unsigned char *line;   /*- {\dg ガイドライン部分の文字列} \verb-*/-\\
\ \verb-    int           length;  /*- {\dg その長さ} \verb-*/-\\
\ \verb-    int           revPos;  /*- {\dg 強調表示の開始位置} \verb-*/-\\
\ \verb-    int           revLen;  /*- {\dg 強調表示の長さ} \verb-*/-\\
\ \verb-  } gline;-\\
\ \verb-} jrKanjiStatus;-\\
\\
\ \verb-/* information flags */-\\
\ \verb-#define KanjiModeInfo   01-\\
\ \verb-#define KanjiGLineInfo  02-\\
\hline
\end{tabular}
\end{nquote}
\vspace{10mm}

\begin{enumerate}

\item {\dg\bf 入力部の情報}

入力部の情報は jrKanjiStatus 構造体の echoStr、length、revPos、revLen の
各メンバに返されます。それぞれの意味は上記の構造体の定義中にコメン
トで表されています。

\begin{itemize}

\item {\dg\bf lengthが$-$1のとき−入力部に変化がない}

length が $-$1 のときは、入力部に変化がなかったことを表します。たと
えば、かな漢字変換入力中にシフトキーなどの単発的な入力があってもかな漢
字変換入力操作に影響を与えません。このような場合には length メンバに $-$1 
が返ります。

\item {\dg\bf lengthが0のとき−入力部がない}

length メンバが 0 である場合には入力部がなくなったということを表しま
す。$-$1 の場合と混同しないようにしてください。

\item {\dg\bf revPos、revLen−強調表示部}

revPos、revLen メンバは強調表示部の範囲を表します。入力部の表示
に関しては、入力部全体に下線をほどこし、強調部のみを反転するという
表示で良いでしょう。あるいは、入力部全体の色を確定している
テキストの色とは別の色にし、さらに強調部については別の色にするなども
考えられます。表示の方法についてはアプリケーションプログ
ラムの自由ですので、いろいろと工夫してみてください。

\item {\dg\bf echoStr−入力部文字列}

echoStr には中間表示文字列へのポインタが格納されますが、
この文字列を格納するためのメモリ領域はライブラリ内部に取られています。この文
字列バッファをアプリケーションプログラムが書き換えたり、 free したり
しないでください。
そのような場合には予測されない結果を生じることがあります。

\end{itemize}

\item {\dg\bf モード表示}

モード表示に変化が生じた場合(すなわちモードが変わった場合)には info メン
バの KanjiModeInfo ビットが立ちます。したがって、モード表示に変
化があったかどうかは以下のように判断することができます。

\vspace{10mm}
\begin{nquote}{3em}
\begin{tabular}{|l|}
\hline
\ \verb+jrKanjiStatus ks;+\\
\ \verb+int nbytes, ch;+\\
\ \verb+.....+\\
\ \verb+nbytes = jrKanjiString(0, ch, buf, bufsize, &ks);+\\
\ \verb+.....+\\
\\
\ \verb+if (ks.info & KanjiModeInfo) { /* +{\dg モードに変化がある} \verb+*/+\\
\ \verb+  +{\dg モード表示を変更する処理} \verb+;+\\
\ \verb+}+\\
\hline
\end{tabular}
\end{nquote}
\vspace{10mm}

\begin{itemize}
\item {\dg\bf info−モードが変化したかどうか}

info メンバに対して KanjiModeInfo ビットが立っている場合には、mode メ
ンバにモードを表す文字列が格納されています。アプリケーションプログラム
は、このモード文字列をしかるべきモード表示領域に表示する必要があります。

\item {\dg\bf mode−モード文字列}

mode メンバで返される文字列用の領域もユーザインタフェースライブラリ内
部で確保されていますので、文字列の内容を勝手に書き換えたり、free したり
しないでください。

\end{itemize}

\item {\dg\bf ガイドライン表示部の情報}

ガイドラインの表示に変化が生じた場合には info メンバの KanjiGLineInfo ビッ
トが立ちます。
したがって、ガイドラインの表示に変化が生じたかどうかは、
モード表示の変化と同様の方法で調べることができます。
唯一の違いは、調べるビットが KanjiModeInfo ではなく、
KanjiGLineInfo であることです。

\begin{itemize}
\item {\dg\bf info−ガイドライン表示に変化があるかどうか}

info メンバの KanjiGLineInfo ビットが立っていた場合にはガイドラインの情報
が jrKanjiStatus 構造体を介して返されます。jrKanjiStatus 構造体の gline メ
ンバがそれに当たります。gline メンバはさらに構造体の形になっており、内
部メンバとして、line、length、revPos、revLen を持っています。これは、
line が echoStr に対応していると考えれば、jrKanjiStatus 構造体の入力部分の
情報を表している echoStr、length、revPos、revLen と同じ意味を持ちます。

すなわち、以下のようになります。

\begin{itemize}
\item {\dg\bf line−ガイドライン文字列}

line にはガイドラインに表示する文字列のポインタが返ります。

\item {\dg\bf length−ガイドライン文字列の長さ}

length には line の長さ(バイト単位)が返ります。

\item {\dg\bf revPos、revLen−強調表示部分}

revPos、revLen にはそれぞれ、line のうち、
強調表示する部分の位置と長さが返ります。
\end{itemize}

入力部とは違い、ガイドライン情報については、length として $-1$ が
返ることはありません。

入力部では、表示に変化がない場合には length に $-$1 が返りましたが、
ガイドラインに関しては表示に変化がないことは、単に info メンバの
 KanjiGLineInfo が立たないことによって表されます。

KanjiGLineInfo が立っていないということは、ガイドラインに表示する情報が
変化していないということであり、ガイドラインに表示する情報が
存在しないという意味ではありません。

\end{itemize}
\end{enumerate}

% misao %
% この先が妙に語り口調で気になりますが、ちょっと面倒なので後回しにします。
% 初期化ふたたび と 再初期化 の違いは読む人にはわからないんじゃないかな。
\subsubsection{初期化ふたたび}
\HIDXAS{かな漢字変換の初期化処理}{かなかんしへんかんのしよきかしより}{H0.9.2.2.7}
\label{5.2.2.7初期化ふたたび}

さて、ここまでの説明でひととおりかな漢字変換を伴うアプリケーションプログラ
ムが記述できるようになったことと思います。

これより以降では、実使用に耐えるアプリケーションプログラムを作成するとき
に必ず守ってもらいたい事項や、このことを知っていればさらにいろいろな機能を
活用できるようになる、といった事項について説明します。

まず始めは初期化のときの処理です。

初期化のときに初期化ファイルを読み込んだりかな漢字変換サーバに接続したり
する処理が行われますが、どの初期化ファイルを読み込むかとか、どのかな漢
字変換サーバに接続するかなどがアプリケーションプログラムから制御するこ
とができます。

また、初期化直後にアプリケーションの名前をサーバに通知する必要があります。

さらに、かな漢字変換を始めるに当たってモード表示領域やガイドライン表示
領域を設けなければなりませんが、それがどのくらい必要であるかをあらかじ
め知っておく必要があります。

典型的な初期化の処理は次のようになります。

\vspace{10mm}
\begin{center}
\begin{tabular}{|l|l|l|l|}
\hline
  & \multicolumn{1}{|c|}{キ　ー　ワ　ー　ド} & \multicolumn{1}{|c|}{処　　理　　内　　容} & \multicolumn{1}{|c|}{備　考}\\
\hline
1 & KC\_SETINITFILENAME      & 初期化ファイルの指定               & オプション\\
  & \multicolumn{1}{|c|}{↓} &                                    & \\
2 & KC\_SETSERVERNAME        & 接続するかな漢字変換サーバの指定   & オプション\\
  & \multicolumn{1}{|c|}{↓} &                                    & \\
3 & KC\_INITIALIZE           & かな漢字変換の初期化               & \\
  & \multicolumn{1}{|c|}{↓} &                                    & \\
4 & KC\_SETAPPNAME           & アプリケーション名の通知           & \\
  & \multicolumn{1}{|c|}{↓} &                                    & \\
5 & KC\_QUERYMAXMODESTR      & モード表示文字列の最大長の取得     & \\
  & \multicolumn{1}{|c|}{↓} &                                    & \\
6 & KC\_QUERYMODE            & モード文字列の取得                 & \\
  & \multicolumn{1}{|c|}{↓} &                                    & \\
7 & KC\_SETWIDTH             & ガイドライン表示部分の大きさの設定 & \\
\hline
\end{tabular}
\end{center}
\vspace{10mm}

上記の表でオプションとあるものについては実行してもしなくても構いません。
オプションとあるもの以外(3〜7)に関しては必ず実行しておくことを強くお勧
めいたします。

以下では上記の各々について説明します。

\paragraph{初期化ファイルの指定}
\label{5.2.2.7.1初期化ファイルの指定}

初期化ファイルとして、アプリケーション固有のファイルを用いるようにすることが、
\hpref{count=14,label=jrKanjiControl} jrKanjiControl を用いてできます。
それには \\
KC\_SETINITFILENAME を用います。
KC\_SETINITFILENAMEの詳しい仕様についてはマニュアルページの方を参照し
てもらうことにして、ここではその使用例を示します。

KC\_SETINITFILENAMEはKC\_INITIALIZEを行う前に設定します。なぜなら初期
化ファイルの読み込みはKC\_INITIALIZEときに行われるからです。
KC\_SETINITFILENAMEを行うと、環境変数CANNAFILEにいかなる値が設定されて
いようともKC\_SETINITFILENAMEで指定されたものの方が優先されることにな
ります。

\vspace{10mm}
\begin{center}
\begin{tabular}{|l|}
\hline
\ \verb+{+\\
\ \verb+  char *initfile = "app-own.canna";+\\
\ \verb+  .....+\\
\\
\ \verb+  nbytes = jrKanjiControl(0, KC_SETINITFILENAME, initfile);+\\
\ \verb+  .....+\\
\\
\ \verb+  jrKanjiControl(0, KC_INITIALIZE, &warn);+\\
\ \verb+}+\\
\hline
\end{tabular}
\end{center}
\vspace{10mm}

\paragraph{接続するかな漢字変換サーバの指定}
\label{5.2.2.7.2接続するかな漢字変換サーバの指定}

接続するかな漢字変換サーバをアプリケーションプログラムから指定すること
ができます。指定にはKC\_SETSERVERNAMEを用います。この指定は環境変数
CANNAHOSTよりも優先されます。

たとえばこれにより、アプリケーションプログラムのオプションとしてかな漢字
変換サーバの指定を含めることができます。本日本語入力に関して提供されて
いる多くのシステムコマンド(lsdic など)では接続するかな漢字変換サーバを接
続するオプションが準備されており、"$-$cs {\it server\ $-$name}"で指定
することができるようになっています。

本ライブラリを用いるアプリケーションプログラムで、かな漢字変換サーバを
指定するオプションを備える場合、"$-$cs"オプションにするようお勧めいた
します。

KC\_SETSERVERNAMEはKC\_SETINITFILENAMEと同様KC\_INITIALIZEよりも前に呼
び出さなければなりません。次のようなイメージになります。

\vspace{10mm}
\begin{nquote}{3em}
\begin{tabular}{|l|}
\hline
\ \verb+{+\\
\ \verb+  char *servername = "app-own-server";+\\
\ \verb+  .....+\\
\\
\ \verb+  nbytes = jrKanjiControl(0, SETSERVERNAME, servername);+\\
\ \verb+  .....+\\
\\
\ \verb+  jrKanjiControl(0, KC_INITIALIZE, &warn);+\\
\ \verb+}+\\
\hline
\end{tabular}
\end{nquote}
\vspace{10mm}

\paragraph{アプリケーション名の通知}

初期化処理が成功したときには、KC\_SETAPPNAMEを用い、接続しているかな漢字変換サーバにアプリケーション名を通知します。

KC\_SETAPPNAMEで設定したアプリケーション名はKC\_FINALIZEを行うまで有効
です。したがって、KC\_INITIALIZEを行った場合には、そのつど実行する必要
があります。

\vspace{10mm}
\begin{nquote}{3em}
\begin{tabular}{|l|}
\hline
\ \verb+{+\\
\ \verb+  char appname[CANNA_MAXAPPNAME];+\\
\ \verb+  .....+\\
\ \verb+  strcpy(appname, "cannad");+\\
\ \verb+  .....+\\
\ \verb+  jrKanjiControl(0, KC_INITIALIZE, &warn);+\\
\ \verb+  .....+\\
\ \verb+  jrKanjiControl(0, KC_SETAPPNAME, appname);+\\
\ \verb+  .....+\\
\ \verb+}+\\
\hline
\end{tabular}
\end{nquote}
\vspace{10mm}

\paragraph{モード表示文字列の最大長の取得}
\label{5.2.2.7.3モード表示文字列の最大長の取得}

モード表示文字列は利用者の初期化ファイルの設定にしたがって長さが大きく
変わります。

KC\_QUERYMAXMODESTRを用いればモード文字列のうち最大のコラム長を持つ文
字列のコラム長を得ることができます。ここで、コラム長とは半角英数文字の
文字幅を1としたときの文字幅になります。たとえば全角文字は2コラムとなります。

KC\_INITIALIZEを呼び出したら、モード文字列表示領域としてどれだけの大き
さが必要であるかを、KC\_QUERYMAXMODESTRを呼び出して確認してください。

\vspace{10mm}
\begin{nquote}{3em}
\begin{tabular}{|l|}
\hline
\ \verb+{+\\
\ \verb+  int max_mode_columns;+\\
\ \verb+  .....+\\
\ \verb+  jrKanjiControl(0, KC_INITIALIZE, &warn);+\\
\ \verb+  .....+\\
\ \verb+  max_mode_columns = jrKanjiControl(0, KC_QUERYMAXMODESTR, 0);+\\
\ \verb+  .....+\\
\ \verb+}+\\
\hline
\end{tabular}
\end{nquote}
\vspace{10mm}

\paragraph{モード文字列の取得}
\label{5.2.2.7.4モード文字列の取得}

モード表示のための領域の幅を取得したら、次は最初に表示しておくべき文字
列を取得します。

システムで提供しているデフォルトのユーザインタフェースでは、最初のモー
ドはアルファベットモードであり、表示されるモード文字列は半角空白文字6
文字となります。したがって真っ白い表示にしておけば良いことになります。

ただしユーザのカスタマイズのやり方しだいでいろいろなモードが最初のモードとな
ることがあり、モード文字列としても""以外のものになることがあります。

アプリケーションプログラムはユーザのカスタマイズによってどのようなモー
ドが最初のモードになっているかを、jrKanjiControlのKC\_QUERYMODEによっ
て入手し、表示する必要があります。

それには、以下のような処理をすることになります。

\vspace{10mm}
\begin{nquote}{3em}
\begin{tabular}{|l|}
\hline
\ \verb+{+\\
\ \verb+  unsigned char currentMode[MAXMODEELEN];+\\
\ \verb+  .....+\\
\ \verb+  jrKanjiControl(0, KC_QUERYMODE, currentMode);+\\
\ \verb+  .....+\\
\ \verb+}+\\
\hline
\end{tabular}
\end{nquote}
\vspace{10mm}

この処理により文字配列currentModeに初期モード文字列が返されますので、
アプリケーションプログラムはこのモード文字列をモード表示領域に表示して
ください。

\paragraph{ガイドライン表示部分の大きさの設定}
\label{5.2.2.7.5ガイドライン表示部分の大きさの設定}

ガイドラインには候補一覧などが表示されますが、アプリケーションプログラム
の都合にしたがって、ガイドライン領域の幅を調整することができます。ユー
ザインタフェースライブラリはアプリケーションプログラムから指示された幅
に収まるようにガイドライン表示を行います。たとえば候補一覧を表示する場合
にはガイドラインに入る範囲で候補を表示します。

ガイドラインの幅を指定するにはjrKanjiControlをKC\_SETWIDTHを伴って呼び
出します。

\vspace{10mm}
\begin{nquote}{3em}
\begin{tabular}{|l|}
\hline
\ \verb+.....+\\
\ \verb+jrKanjiControl(0, KC_INITIALIZE, &warn);+\\
\ \verb+.....+\\
\ \verb+jrKanjiControl(0, KC_SETWIDTH, 72);+\\
\ \verb+.....+\\
\hline
\end{tabular}
\end{nquote}
\vspace{10mm}

もし、ガイドラインがあまりにも小さすぎてユーザインタフェースでどう調整
しても入り切らない場合には次のいずれかの処理が行われます。

\begin{nquote}{2em}
\begin{enumerate}
\item ガイドラインに表示し切れなかった文字列を入力部分に表示する。
\item 表示を行わない。
\end{enumerate}
\end{nquote}

KC\_SETWIDTHは入力コンテクストごとに別々の値を設定することができます。

逆に言うと入力コンテクストを複数持っているアプリケーションプログラムは
それぞれのコンテクストに対してKC\_SETWIDTHを行わなければならないことに
なります。

複数の入力コンテクストを利用されるかたはご注意ください。

\subsubsection{再初期化}
\HIDXAS{かな漢字変換の再初期化}{かなかんしへんかんのさいしよきか}{H0.9.2.2.8}
\label{5.2.2.8再初期化}

カスタマイズファイルを修正したとき、その修正を即座に反映させるために、再初
期化処理が行えると便利です。もしアプリケーションプログラムが再初期化処
理を備えていれば、ユーザがカスタマイズファイルを書き換えたときに、アプリ
ケーションプログラムを再起動しなくてもカスタマイズの結果をアプリケーショ
ンプログラムに反映させることができます。

以下の項目を満たすようなアプリケーションプログラムでは再初期化処理を備
えておくことをお勧め致します。

\begin{nquote}{2em}
\begin{enumerate}
\item 一度起動したらかなり長い間起動しておく
\item 起動や終了の処理が比較的たいへん
\item 日本語入力をよく使う
\end{enumerate}
\end{nquote}

たとえば Nemacs などが上を満たす良い例になります。

このようなアプリケーションプログラムではプルダウンメニューなどに``かな
漢字変換の再初期化''の項目を入れておくことをお勧めします。

再初期化処理は、KC\_FINALIZEを行った後、前節で説明した初期化関連の一連
の処理を行うことによって達成されます。

\subsubsection{\HIDX{かな漢字変換処理中の機能}
{かなかんしへんかんしよりちゆうのきのう}{H0.9.2.2.9}}
\label{5.2.2.9かな漢字変換処理中の機能}

かな漢字変換処理中にも、必要に応じて現在のモードを調べたり、かな漢字変
換中の文字を強制的にアプリケーションプログラム側から確定させたりするこ
とが可能です。

それぞれの機能はjrKanjiControlを対応するコントロールキーワードを伴って
呼び出すことにより実行されます。実行できる機能には以下のものがあります。

\begin{table}[hbtp]
\begin{center}
\caption{jrKanjiControl実現機能}\label{jrKanjiControl実現機能}
\begin{tabular}{|l|l|l|l|}
\hline
  &  \multicolumn{1}{|c|}{キ　ー　ワ　ー　ド} & \multicolumn{1}{|c|}{内　容　処　理} & 備考\\
\hline
1 &  KC\_QUERYMODE           & モードの調査               & \\
2 &  KC\_CHANGEMODE          & モードの変更               & \\
3 &  KC\_KAKUTEI             & 入力中の文字列の確定       & \\
4 &  KC\_KILL                & 入力中の文字列の消去       & \\
5 &  KC\_SETUNDEFKEYFUNCTION & 未定義キーの処理           & \\
6 &  KC\_CLOSEUICONTEXT      & 入力コンテクストのクローズ & \\
\hline
\end{tabular}
\end{center}
\end{table}

以下ではそれぞれの機能に対応するコントロールキーワードと、その使い方な
どについて説明します。詳細なアプリケーションインタフェース仕様について
は \hpref{count=14,label=jrKanjiControl} jrKanjiControl の説明の項を
参照してください。

\paragraph{モードの調査}
\label{5.2.2.9.1モードの調査}

現在の入力モードが何であるのかを前述したKC\_QUERYMODEで調べることがで
きます。ただし、以下の理由からKC\_QUERYMODEの呼び出しだけでは今どのよ
うなモードであるのか断定することができません。

\begin{nquote}{2em}
\begin{enumerate}
\item KC\_QUERYMODEの返す値はデフォルトではモード文字列の形である
\item モード文字列はユーザのカスタマイズにより変更できる。
\end{enumerate}
\end{nquote}

実は、KC\_SETMODEINFOSTYLEによってKC\_QUERYMODEの返す値を調査用に少し
変更することができます。KC\_SETMODEINFOSTYLEではモードとしてどのよう
なものを採用するかを制御できます。

\vspace{10mm}
\begin{center}
\begin{tabular}{|c||c|c|}
\hline
SETMODEINFOSTYLEに与える値 &    0   &       1       \\
\hline
表示されるモード           & 文字列 & 数値+'@'(0x40)\\
\hline
\end{tabular}
\end{center}
\vspace{10mm}

KC\_SETMODEINFOSTYLEでモードスタイルを1にすることによりKC\_QUERYMODEで
返される値はモードを表す数値に'@'(0x40)を足した値が1文字長の文字列とし
て返されるようになります。この値はユーザによるカスタマイズの影響を受け
ません。モードを表す数値とはヘッダファイル$<$canna/jrkanji.h$>$から間
接的にインクルードされる$<$canna/mfdef.h$>$の中で、CANNA\_MODE\_xxxと
してマクロ定義されている値です。たとえば、アルファベットモードは
CANNA\_MODE\_AlphaModeというマクロで定義される値を持ちます。

KC\_QUERYMODEによって返される値から'@'を引いたものを
CANNA\_MODE\_Alpha\-Modeなどと比較することにより現在のモードを明確に判
断することができます。\\

\paragraph{モードの変更}
\label{5.2.2.9.2モードの変更}

アプリケーションプログラムの都合でかな漢字変換のモードをたとえばカタカナ
入力モードなどに強制的に変更する場合にはKC\_CHANGEMODEを用います。\\

\paragraph{入力中の文字列の確定/消去}
\label{5.2.2.9.3入力中の文字列の確定/消去}

何らかの都合で入力中の文字列をアプリケーションプログラム側から消去した
り確定したりしたいことがあると思います。

たとえば、ダイアログボックスを表示していた場合、Cancelボタンなどがクリッ
クされたときはそのダイアログボックス中のすべての入力ポートに対して入力状態
をクリアする処理を行う必要があります。

このような場合にはKC\_KAKUTEIあるいはKC\_KILLを行います。

それぞれの意味は以下のようになります。

\vspace{10mm}
\begin{center}
\begin{tabular}{|l|l|}
\hline
KC\_KAKUTEI & 入力中の文字を強制的に確定させる\\
KC\_KILL    & 入力中の文字を強制的に消去する\\
\hline
\end{tabular}
\end{center}
\vspace{10mm}

いずれの場合もかな漢字変換の状態は基底状態(何も入力されていない状態)に
なります。

\paragraph{未定義キーの処理}
\label{5.2.2.9.4未定義キーの処理}

かな漢字変換中にかな漢字変換には用いられないキー(未定義キー)が入力され
たときの処理を指定することができます。デフォルトでは未定義キーは無視され
るだけですが、以下のように設定することができます。

\begin{enumerate}
\item ビープ音を鳴らす
\item 未定義キーをアプリケーションプログラムに渡す。

この場合、以下の3つのうちいずれかを選択できます。
\begin{enumerate}
\item 入力中の文字列を確定する。
\item 入力中の文字列を消去する。
\item 入力中の文字列は入力中のままにしておく。\\
\end{enumerate}
\end{enumerate}

\paragraph{入力中のコンテクストのクローズ}
\label{5.2.2.9.5入力中のコンテクストのクローズ}

ユーザインタフェースライブラリを用いてかな漢字変換を行う上ではさまざま
な形でメモリを消費します。

たとえば入力ポートが増えればその分だけ余分にメモリを消費することになりま
す。

入力にウィンドウを用いるアプリケーションプログラムによっては入力のため
のウィンドウを次々と作っては壊していく場合があります。このような場合に
jrKanjiStringに対して次々と新しいコンテクストを与えて行くとどんどんメ
モリを消費してしまうことになります。

入力に用いられたウィンドウを破壊する場合にはそのウィンドウからの入力を
jrKanjiStringに与えるときに用いていたコンテクストをクローズした方が良い
でしょう。

コンテクストをクローズすることにより、その入力コンテクストのために確保
されていたメモリが解放されます。

コンテクストの解放にはKC\_CLOSEUICONTEXTを用います。


