XmbLookupString(3X11)

名前
XmbLookupString, XwcLookupString, Xutf8LookupString - 変換処理された入力を入力メソッドから得る

書式
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
    返されるデータの種類を示す値が返される。

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

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

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

と によって返された文字列は、ロケールのエンコーディングの初期状態で始まる (ロケールのエンコーディングが状態依存の場合)。 正しい入力処理を保証するためには、クライアントは イベントのみを に送ることが重要である。 クライアントが イベントを送った場合、これらの関数の動作は未定義である。

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

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

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

関連項目
XLookupKeysym(3X11)
Xlib - C Language X Interface