書式

int XmbLookupString(ic, event, buffer_return, bytes_buffer, keysym_return, status_return)

      XIC ic;

      XKeyPressedEvent *event;

      char *buffer_return;

      int bytes_buffer;

      KeySym *keysym_return;

      Status *status_return;

int XwcLookupString(ic, event, buffer_return, bytes_buffer, keysym_return, status_return)

      XIC ic;

      XKeyPressedEvent *event;

      wchar_t *buffer_return;

      int wchars_buffer;

      KeySym *keysym_return;

      Status *status_return;

int Xutf8LookupString(ic, event, buffer_return, bytes_buffer, keysym_return, status_return)

      XIC ic;

      XKeyPressedEvent *event;

      char *buffer_return;

      int bytes_buffer;

      KeySym *keysym_return;

      Status *status_return;

引き数

buffer_return

(存在するならば)マルチバイト文字列かワイド文字文字列が 入力メソッドから返される。

bytes_buffer

wchars_buffer

返却バッファの容量を指定する。

event

使われるキーイベントを指定する。

ic

入力コンテクストを指定する。

keysym_return

この引き数が NULL でない場合には、イベントから計算したキーシンボルが返される。

status_return

返されるデータの種類を示す値が返される。

説明

関数 XmbLookupString, XwcLookupString, Xutf8LookupString は、指定した入力メソッドから返された文字列を引き数 buffer_return に与え る。文字列が返されなければ、引き数 buffer_return の内容は変化しない。

引き数 keysym_return が NULL でなく、かつ、引き数 status_return が キーシンボルが返されたことを示している場合には、引き数 keysym_return にはキーシンボルが返され、そのキーシンボルにはイベントから得られた キーコードがマッピングされている。 文字列とキーシンボルの両方が返されている場合、キーシンボルの値が必ず 文字列に対応しているとは限らない。

XmbLookupString と Xutf8LookupString は文字列の長さをバイト数で返し、 XwcLookupString は文字列の長さを文字数で返す。 XmbLookupString と XwcLookupString は指定した入力コンテクストの入力メソッドに割り当てられた ロケールのエンコーディングで文字列を返し、 Xutf8LookupString は UTF-8 エンコーディングで文字列を返す。

XmbLookupString と XwcLookupString によって返された文字列は、ロケールのエンコーディングの初期状態で始まる (ロケールのエンコーディングが状態依存の場合)。

Note

正しい入力処理を保証するためには、クライアントは KeyPress イベントのみを XmbLookupString, XwcLookupString, Xutf8LookupString に送ることが重要である。 クライアントが KeyRelease イベントを送った場合、これらの関数の動作は未定義である。

クライアントは、まず引き数 status_return をチェックしてから他の返り値を 使用すべきである。 どの関数も、他の引き数に何が返されたかを示す引き数 status_return に値 を返す。 返される可能性がある値を以下に示す:

XBufferOverflow	返されるべき入力文字列が、与えられた buffer_return よりも大きい。 必要なサイズ( XmbLookupString, Xutf8LookupString の場合はバイト数、 XwcLookupString の場合は文字数)は、関数の値として返され、buffer_return および keysym_return の内容は変更されない。 文字列を得るためには、クライアントは適切な大きさのバッファを用意してか ら、同じイベントに対してこれらの関数を再び呼び出さなければならない。
XLookupNone	正しい入力が今のところ構成されていない。 buffer_return および keysym_return の内容は変更されず、関数は 0 を返す。
XLookupChars	入力文字列が構成されている。 これらは引き数 buffer_return に格納される。 使われるエンコーディングは前述の通りで、文字列の長さが関数の値として返 される。 引き数 keysym_return の内容は変更されない。
XLookupKeySym	文字列ではなく KeySym が返され、この KeySym は keysym_return に返され る。 引き数 buffer_return の内容は変更されず、関数は 0 を返す。
XLookupBoth	KeySym と文字列の両方が返された。 XLookupChars と XLookupKeySym が同時に起こる。

XmbLookupString, XwcLookupString, Xutf8LookupString に引き数として渡された入力コンテクストが現在フォーカスを所有していても、 あるいはそうでなくても、結果に違いは生じない。 入力はフォーカスを失った時点では既に入力コンテクストの内部に構築 されているので、キーボードフォーカスが失われてしまっても、後から XmbLookupString, XwcLookupString, Xutf8LookupString を呼び出して入力を受け取ることができる。

関数 Xutf8LookupString は XFree86 4.0.2 から導入された XFree86 独自の拡張である。 この関数が存在するかどうかはマクロ X_HAVE_UTF8_STRING で判定できる。