Chapter 12 Input Device Functions

12 章: 入力デバイス関数

Xlib 入力デバイス関数は以下の目的に使用できる:

ポインタのグラブ

Xlib にはポインタ(普通はマウス)からの入力の制御に使える関数が用意され ている。 普通は、キーボードやマウスのイベントが起きるとすぐに X サーバはこれらのイベントを適切なクライアントに配送する。 配送先はウィンドウや入力フォーカスによって決められる。 X サーバは、ウィンドウマネージャがマウスや他の種類の様々なスタイルの ユーザインタフェースに対応できるようにイベント配送を十分に制御できる。 これらのユーザインタフェースの多くはイベントの発生と配送が同期している ことに依存している。 ポインタイベントとキーボードイベントの配送は独立に制御できる。

マウスのボタンやキーボードのキーがグラブされると、イベントは そのイベントが通常行くはずのクライアントではなく、グラブを行っている クライアントに送られる。 キーボードやポインタが非同期モードならば、以降のマウスイベントや キーボードイベントは処理が続けられる。 キーボードやポインタが同期モードならば、グラブを行っているクライアント が許可するまでは( XAllowEvents を参照)イベントは全く処理されない。 キーボードやイベントはこの間、止まっていると見なされる。 グラブを引き起こしたイベントも再生される。

デバイスのイベント処理が止まっていると、デバイスの論理的状態(クライア ント側から見える)と物理的状態にずれが出るかもしれない点に注意すること。

グラブには種類が 2 つある。 すなわちアクティブグラブとパッシブグラブである。 アクティブグラブは 1 つのクライアントがキーボードやポインタを明示的に グラブしたときに起こる( XGrabPointerXGrabKeyboard を参照すること)。 パッシブグラブは複数のクライアントがある特定のキーボードのキーや ポインタボタンをウィンドウ内でグラブしたときに起こる。 グラブはキーやボタンが実際に押されたときに有効になる。 パッシブグラブは信頼性の高いポップアップメニューを実装するときに便利で ある。 例えば、ボタンをグラブして動作が同期するようにしておけば、 ポインタボタンアップのイベントが起こる前に ポップアップがマップされることを保証できる。 つまりポインタボタンダウンのイベントがグラブを引き起こし、 ポップアップウィンドウをマップできるまでポインタボタンのイベント処理を 止めることができる。 その後で、以降のイベントを処理できる。 したがって、ポインタボタンアップのイベントはポップアップウィンドウに対 して正しく処理される。

多くの操作について、 時刻を引数にとる関数がある。 X サーバは多くのイベントにタイムスタンプを入れる。 CurrentTimeという特別な時刻は現在のサーバ時刻を表す。 X サーバは入力フォーカスが最後に変化した時刻、 キーボードが最後にグラブされた時刻、 ポインタが最後にグラブされた時刻、 セレクションが最後に変化した時刻のいずれかを管理している。 アプリケーションはイベントに反応すると遅くなるかもしれない。 他のアプリケーションがキーボードやポインタ、セレクションを制御している ならば、自分はリクエストを出さないことを指定する何らかの方法が必要なこ とも多い。 リクエスト中のイベントからタイムスタンプを与えることにより、 他の誰かが操作を行っていたら自分の操作が効果を持たないようにすることが できる。

タイムスタンプは時刻を表す値であり、ミリ秒単位で表現される。 この時刻は最後にサーバがリセットされてからの時間である。 タイムスタンプはある間隔で一回りする(約 49.7 日間隔)。 したがってサーバが持つ現在時刻がタイムスタンプ T であるとすると、 クライアントから得たタイムスタンプの解釈の際、タイムスタンプ空間の半分 は必ず T より遅い時刻として扱われ、半分は T より早い時刻として表される。 CurrentTimeという特別なタイムスタンプ値をサーバが生成することはない。 この値は現在のサーバ時刻を表すリクエストで使うために予約されている。

この節で説明する多くの関数にはポインタイベントマスクビットを渡すこと。 有効なポインタイベントマスクは ButtonPressMask ,ButtonReleaseMask ,EnterWindowMask ,LeaveWindowMask ,PointerMotionMask ,PointerMotionHintMask ,Button1MotionMask ,Button2MotionMask ,Button3MotionMask ,Button4MotionMask ,Button5MotionMask ,ButtonMotionMask ,KeyMapStateMaskである。 この節の他の関数に対してはキーマスクビットを渡すこと。 有効なキーマスクビットは ShiftMask ,LockMask ,ControlMask ,Mod1Mask ,Mod2Mask ,Mod3Mask ,Mod4Mask ,Mod5Maskである。

ポインタをグラブするには XGrabPointerを用いる。

int XGrabPointer(display, grab_window, owner_events, event_mask, pointer_mode, keyboard_mode, confine_to, cursor, time)
Display *display;
Window grab_window;
Bool owner_events;
unsigned int event_mask;
int pointer_mode, keyboard_mode;
Window confine_to;
Cursor cursor;
Time time;
display
X サーバへの接続を指定する。
grab_window
グラブするウィンドウを指定する。
owner_events
イベントマスクによって選択されていた場合、ポインタイベントを通常通り 報告するか、またはグラブウィンドウについて報告するかどうかを示す真偽値 を指定する。
event_mask
どのポインタイベントがクライアントに報告されるかを指定する。 マスクは有効なポインタイベントマスクのビット値のビットごとの論理和を取っ て求める。
pointer_mode
ポインタイベントのさらなる処理を指定する。 GrabModeSync または GrabModeAsync を指定できる。
keyboard_mode
キーボードイベントのさらなる処理を指定する。 GrabModeSync または GrabModeAsync を指定できる。
confine_to
ポインタを閉じ込めるウィンドウを指定するか Noneを指定する。
cursor
グラブの間に表示されるカーソルか Noneを指定する。
time
時刻を指定する。 タイムスタンプか CurrentTimeを指定する。

関数 XGrabPointerはポインタの制御をアクティブにグラブし、これに成功した場合に GrabSuccessを返す。 以降のポインタイベントはグラブを行ったクライアントに対してのみ報告され る。 XGrabPointerはこのクライアントが行ったアクティブなポインタのグラブを全て無視する。 owner_events が Falseならば、生成された全てのポインタイベントは、イベントマスクによって選択 されている場合に限って grab_window に関して報告される。 owner_events が Trueであり、ポインタイベントが通常はこのクライアントに報告されるはずならば、 このイベントは通常通り報告される。 そうでない場合は、このイベントはイベントマスクによって選択されている場 合に限って grab_window に関して報告される。 owner_events のそれぞれの値について、報告されなかったイベントは破棄さ れる。

the pointer_mode が GrabModeAsyncならば、ポインタイベントの処理は通常通り継続される。 このクライアントがポインタを凍結している場合、ポインタに関する イベントの処理は再開される。 pointer_mode が GrabModeSyncならば、ポインタの状態(クライアントアプリケーションが見る)は凍結されて いると考えられ、グラブを行っているクライアントが XAllowEventsを呼び出すか、ポインタのグラブが解除されるまでは X サーバはこれ以上の ポインタイベントを生成しない。 ポインタの実際の変化はポインタが凍結されている間も失われない。これらは 単にサーバのキューに入れられ、後で処理される。

keyboard_mode が GrabModeAsyncならば、キーボードイベントの処理はグラブのアクティブ化による影響は受け ない。 keyboard_mode が GrabModeSyncならば、キーボードの状態(クライアントアプリケーションが見る)は凍結され ていると考えられ、グラブを行っているクライアントが XAllowEventsを呼び出すか、ポインタのグラブが解除されるまでは X サーバはこれ以上の キーボードイベントを生成しない。 実際のキーボードイベントの変化はポインタが凍結されている間も失われない。 これらは後で処理するために、単にサーバのキューに入れられるだけである。

cursor が指定された場合、このカーソルはポインタがどのウィンドウに入っ ていても表示される。 Noneが指定された場合は、ポインタが grab_window やそのサブウィンドウの1つに 入った時にそのウィンドウの通常のカーソルが表示される。 それ以外の場合には、grab_window のカーソルが表示される。

confine_window が指定された場合は、ポインタはそのウィンドウ内に閉じ込 められる。 confine_to は grab_window と関係を持っている必要はない。 最初の状態でポインタが confine_window に入っていない場合は、 グラブがアクティブ化される直前にポインタがこのウィンドウの最も近い辺へ と自動的に移動する。この時、enter/leave イベントは通常通りに生成される。 その後に confine_to ウィンドウの構成が変えられた場合は、ポインタはこの ウィンドウに含まれたままになるように、必要に応じて自動的に移動する。

引き数 time を利用して、クライアントはアプリケーションが応答するまでに長 い間がかかる場合や、ネットワークの遅延が大きい場合に生じる不具合を避け ることができる。 例として、2つのアプリケーションがあり、そのいずれもクリックされた時に ポインタのグラブを普通に行うという状況を考える。 どちらのアプリケーションもイベントから得たタイムスタンプを指定していれ ば、2番目のアプリケーションは最初のアプリケーションよりも速く立ち上が り、ポインタをうまくグラブできる。 最初のアプリケーションは、自分のリクエストが処理される前に他の アプリケーションがポインタをグラブしたことを知らされる。

XGrabPointerEnterNotify イベントと LeaveNotify を生成する。

grab_window ウィンドウか confine_to ウィンドウが表示不可能である場合か、 confine_to ウィンドウがルートウィンドウの境界から完全に外に出ている場 合には XGrabPointerは失敗し、 GrabNotViewableを返す。 他のクライアントがポインタをアクティブにグラブしている場合、この関数は 失敗し、 AlreadyGrabbedを返す。 ポインタが他のクライアントのアクティブなグラブによって凍結されている場 合は、この関数は失敗して GrabFrozenを返す。 指定した時間が最終ポインタグラブ時刻より早い場合や X サーバの現在時刻よ り遅い場合には、この関数は失敗して GrabInvalidTimeを返す。 これ以外の場合には、最終ポインタグラブ時刻には指定した時間がセットされる (CurrentTimeは X サーバの現在時刻に置き換えられる)。

XGrabPointerはエラー BadCursor ,BadValue ,BadWindow を起こすことがある。

ポインタのグラブを解除するには XUngrabPointerを使う。

XUngrabPointer(display, time)
Display *display;
Time time;
display
X サーバへの接続を指定する。
time
時刻を指定する。 タイムスタンプか CurrentTimeを指定できる。

関数 XUngrabPointerは、このクライアントが XGrabPointer ,XGrabButton関数の呼び出しや普通にボタンを押したことによってポインタをアクティブに グラブしている場合、ポインタとキューに入っているイベントを解放する。 指定した時刻が最終ポインタグラブ時刻より早い場合や、X サーバの現在時刻 よりも遅い場合には、 XUngrabPointerはポインタを解放しない。 この関数は EnterNotify イベントと LeaveNotify イベントを生成する。 ポインタのアクティブなグラブに対応するイベントウィンドウや confine_to ウィンドウが表示不能になった場合や、ウィンドウの構成の変化によって confine_to ウィンドウがルートウィンドウの境界から完全に外に出てしまっ た場合には、X サーバは UngrabPointer リクエストを自動的に実行する。

ポインタのアクティブなグラブを変更するには XChangeActivePointerGrabを使う。

XChangeActivePointerGrab(display, event_mask, cursor, time)
Display *display;
unsigned int event_mask;
Cursor cursor;
Time time;
display
event_mask
cursor
time

関数 XChangeActivePointerGrabは、クライアントがポインタをアクティブにグラブしていて、指定した時刻が 最終ポインタグラブ時刻よりも早くなく、かつ X サーバの現在時刻よりも遅 くない場合に指定された動的パラメータを変更する。 この関数は XGrabButtonのパッシブなパラメータに対しては無効である。 引き数 event_mask と cursor の解釈は XGrabPointerの項目で説明した通りである。

XChangeActivePointerGrabはエラー BadCursor ,BadValueを起こすことがある。

ポインタのボタンをグラブするには XGrabButtonを用いる。

XGrabButton(display, button, modifiers, grab_window, owner_events, event_mask,
pointer_mode, keyboard_mode, confine_to, cursor)
Display *display;
unsigned int button;
unsigned int modifiers;
Window grab_window;
Bool owner_events;
unsigned int event_mask;
int pointer_mode, keyboard_mode;
Window confine_to;
Cursor cursor;
display
X サーバへの接続を指定する。
button
グラブするポインタのボタンまたは AnyButtonを指定する。
modifiers
キーマスクの集合か AnyModifierを指定する。 このマスクは、有効なキーマスクビットのビットごとの論理和を取ってもので ある。
grab_window
グラブウィンドウを指定する。
owner_events
イベントマスクで選択されている場合、ポインタイベントを通常通り報告する のか、あるいはグラブウィンドウについて報告するのかを示す真偽値を指定する。
event_mask
クライアントに報告するポインタイベントを指定する。 このマスクは、有効なポインタイベントのマスクビットのビットごとの論理和 を取ったものである。
pointer_mode
後で行うポインタイベントの処理を指定する。 GrabModeSync または GrabModeAsyncを指定できる。
keyboard_mode
後で行うキーボードイベントの処理を指定する。 GrabModeSync または GrabModeAsyncを指定できる。
confine_to
ポインタを閉じ込めるウィンドウ、または Noneを指定する。
cursor
表示するカーソル、または Noneを指定する。

関数 XGrabButtonはパッシブなグラブを作る。 将来、以下の条件が全て真になった場合にポインタはアクティブにグラブされ( XGrabPointerによる)、ボタンが押された時刻が最終ポインタグラブ時刻にセットされ( ButtonPressイベントで送られる)、 ButtonPressが報告される。

残りの引き数の解釈は XGrabPointerと同じである。 ポインタの論理状態が全てのボタンが離された状態になったとき、アクティブ なグラブは自動的に終了する(論理的なモディファイアキーの状態には依存し ない)。

デバイスのイベント処理が凍結されている場合、デバイスの論理状態(クライ アントが受け取る)が物理的な状態とずれることがある。

同じクライアントの同じウィンドウの同じボタン/キーの組合せを使うことで、 このリクエストは以前の全てのグラブを上書きする。 引き数 modifiers に AnyModifierを指定することは、モディファイアの可能な組合せ全てに対してグラブの リクエストを発行することと等価である(モディファイアを使わないことも組 合せに含まれる)。 指定された全てのモディファイアがこの時点でキーコードを割り当てられてい る必要はない。 引き数 button に AnyButton を指定することは、可能なボタン全てに対してリクエストを発行することと 等価である。 これ以外の場合は、指定されたボタンが現在物理ボタンに割り当てられている 必要はない。

同じウィンドウ上の同じボタン/キーの組合せに対して他のクライアントが既に XGrabButtonを発行している場合は、エラー BadAccessとなる。 グラブが干渉する何らかの組合せがある場合、 AnyModifierAnyButtonは必ず失敗し、エラー BadAccessとなる(グラブは確立されない)。 XGrabButtonはアクティブなグラブに対しては無効である。

XGrabButtonはエラー BadCursor ,BadValue ,BadWindow を起こすことがある。

ポインタボタンのグラブを解除するには XUngrabButtonを用いる。

XUngrabButton(display, button, modifiers, grab_window)
Display *display;
unsigned int button;
unsigned int modifiers;
Window grab_window;
display
X サーバへの接続を指定する。
button
グラブまたは解放するポインタのボタン、または AnyButtonを指定する。
modifiers
キーマスクの集合または AnyModifierを指定する。 このマスクは、有効なキーマスクビットのビットごとの論理和を取ったもので ある。 グラブウィンドウを指定する。

関数 XUngrabButtonは、指定したウィンドウのパッシブなボタン/キーの組合せがクライアントに よってグラブされている時、これを解放する。 引き数 modifiers に AnyModifier を指定することは、モディファイアの可能な組合せ全てに対してグラブ解放の リクエストを発行することと等価である。この組合せはモディファイアを使わ ない組合せも含む。 引き数 button に AnyButton を指定することは、可能なボタン全てに対してリクエストを発行することと等 価である。 XUngrabButtonはアクティブなグラブに対しては無効である。

XUngrabButtonはエラー BadValue ,BadWindow を起こすことがある。

キーボードのグラブ

Xlib にはキーボードのグラブとグラブ解除やイベントの許可に使える関数が 用意されている。

この節の関数の多くにはキーマスクビットを渡す。 有効なキーマスクは ShiftMask ,LockMask ,ControlMask ,Mod1Mask ,Mod2Mask ,Mod3Mask ,Mod4Mask ,Mod5Maskである。

キーボードをグラブするには XGrabKeyboardを使う。

int XGrabKeyboard(display, grab_window, owner_events, pointer_mode, keyboard_mode, time)
Display *display;
Window grab_window;
Bool owner_events;
int pointer_mode, keyboard_mode;
Time time;
display
X サーバへの接続を指定する。
grab_window
グラブウィンドウを指定する。
owner_events
キーボードイベントを通常通り報告するのかどうかを示す真偽値を指定する。
pointer_mode
ポインタイベントの後処理を指定する。 GrabModeSync または GrabModeAsyncを指定する。
keyboard_mode
キーボードイベントの後処理を指定する。 GrabModeSync あるいは GrabModeAsyncを指定できる。
time
時刻を指定する。 タイムスタンプか CurrentTimeを渡せる。

関数 XGrabKeyboardはキーボードの制御をアクティブにグラブし、 FocusInイベントと FocusOutイベントを生成する。 以降のキーイベントはグラブを行っているクライアントにのみに報告される。 XGrabKeyboardはこのクライアントによる全てのアクティブなグラブを上書きする。 owner_events が Falseならば、生成された全てのキーイベントは grab_window について報告される。 owner_events が True の場合は、生成されたキーイベントが通常はこのクライアントに報告されるは ずならば、このイベントは通常通りに報告される。そうでないならば、このイ ベントは grab_window について報告される。 KeyPress イベントと KeyRelease イベントのいずれも、クライアントによるイベント選択とは関係なく常に報告 される。

引き数 keyboard_mode が GrabModeAsyncならば、キーボードイベント処理は通常通り続けられる。 キーボードがこのクライアントによって現在凍結されているならば、キーボー ドイベントの処理は再開される。 引き数 keyboard_mode が GrabModeSyncならば、キーボードの状態(クライアントアプリケーションが見る)は凍結され ていると考えられる。この場合は、グラブを行っているクライアントが解放を行う XAllowEventsの呼び出しを行うか、キーボードのグラブが解放されるまでは、X サーバは以 降のキーボードイベントを生成しない。 キーボードが凍結されている間もキーボードの実際の変化は失われない。これ らは単にサーバのキューに入れられており、後で処理される。

pointer_mode が GrabModeAsyncならば、ポインタイベントの処理はグラブのアクティブ化の影響は受けない。 pointer_mode が GrabModeSyncならば、ポインタの状態(クライアントアプリケーションが見る)は凍結されて いると考えられる。この場合は、グラブを行っているクライアントが XAllowEventsを呼び出して解放を行うか、キーボードのグラブが解放されるまでは、X サーバは以降のポインタイベントを生成しない。 ポインタが凍結されている間もポインタの実際の変化は失われない。これらは 単にサーバのキューに入れられており、後で処理される。

キーボードが他のクライアントによってアクティブにグラブされている場合、 XGrabKeyboardは失敗し、 AlreadyGrabbedを返す。 grab_window が表示可能でない場合、この関数は失敗して GrabNotViewableを返す。 キーボードが他のクライアントのアクティブなグラブによって凍結されている 場合、関数は失敗して GrabFrozenを返す。 指定した時刻が最終キーボードグラブ時刻よりも早い場合や X サーバの現在 時刻よりも遅い場合には、関数は失敗して GrabInvalidTimeを返す。 そうでない場合は、最終キーボードグラブ時刻には指定した時刻 (CurrentTime は X サーバの現在時刻に置き換えられる)がセットされる。

XGrabKeyboardはエラー BadValue ,BadWindow を起こすことがある。

キーボードのグラブを解放するには XUngrabKeyboard を使う。

XUngrabKeyboard(display, time)
Display *display;
Time time;
display
X サーバへの接続を指定する。
time
時刻を指定する。 タイムスタンプか CurrentTimeを渡せる。

関数 XUngrabKeyboardは、このクライアントが XGrabKeyboardXGrabKeyによってアクティブなグラブを行っているならば、キーボードとキューに入っ ているイベントを解放する。 指定した時刻が最終キーボードグラブ時刻より早い場合や X サーバの 現在時刻よりも遅い場合には、 XUngrabKeyboardはキーボードとキューに入っているイベントの解放を行わない。 また、この関数は FocusIn イベントと FocusOut を生成する。 アクティブなキーボードグラブに対するイベントウィンドウが表示不可能にな ると、X サーバは自動的に UngrabKeyboard リクエストを行う。

キーボードのキー 1 つのパッシブなグラブを行うには XGrabKeyを使う。

XGrabKey(display, keycode, modifiers, grab_window, owner_events, pointer_mode,
keyboard_mode)
Display *display;
int keycode;
unsigned int modifiers;
Window grab_window;
Bool owner_events;
int pointer_mode, keyboard_mode;
display
X サーバへの接続を指定する。
keycode
KeyCode あるいは AnyKeyを指定する。
modifiers
キーマスクの集合か AnyModifierを指定する。 このマスクは正しいキーマスクのビット値のビットごとの論理和を取ったもの である。
grab_window
グラブウィンドウを指定する。
owner_events
キーボードイベントを通常通り報告するかどうかを示す真偽値を指定する。
pointer_mode
ポインタイベントの後処理を指定する。 GrabModeSync あるいは GrabModeAsyncを指定する。
keyboard_mode
キーボードイベントの後処理を指定する。 GrabModeSync あるいは GrabModeAsyncを渡せる。

関数 XGrabKeyはキーボードのパッシブなグラブを確立する。 将来に以下の条件が全て真になった場合、キーボードはアクティブにグラブされ( XGrabKeyboardによって)、最終キーボードグラブ時刻にキーが押された時刻がセットされ( KeyPressイベントで送られるように)、 KeyPressイベントが報告される。

残りの引き数の解釈は XGrabKeyboardと同じである。 キーボードの論理的状態で、指定したキーが離された状態になった時、アクティ ブなグラブは自動的に終了する(モディファイアキーの論理的状態とは独立)。

デバイスのイベント処理が凍結されている時、デバイスの論理状態(クライア ントアプリケーションが見る)が物理状態とずれてしまうことがある。

引き数 modifiers が AnyModifierである場合は、可能なモディファイアの組み合わせ全てに対してリクエストを 発行することと等価である(モディファイアが無い組み合わせも含む)。 指定された全てのモディファイアが現在 KeyCode を割り当てられている必要 はない。 引き数 keycode が AnyKeyである場合は、可能な全てのキーコードに対してリクエストを発行することと 等価である。 これ以外の場合は、指定したキーコードは接続のセットアップ時に min_keycode と max_keycode で指定された範囲に入っている必要があり、 そうでなければエラー BadValueとなる。

他のクライアントが同じウィンドウの同じキーの組み合わせに対して XGrabKeyを発行している場合は、エラー BadAccess となる。 グラブが衝突する組み合わせが 1 つでもある場合に AnyModifierAnyKey ,を使用するとリクエストは必ず失敗し、エラー BadAccess となる(グラブは確立されない)。

XGrabKeyはエラー BadAccess ,BadValue ,BadWindow を起こすことがある。

キーのグラブを解放するには XUngrabKeyを使う。

XUngrabKey(display, keycode, modifiers, grab_window)
Display *display;
int keycode;
unsigned int modifiers;
Window grab_window;
display
X サーバへの接続を指定する。
keycode
KeyCode あるいは AnyKeyを指定する。
modifiers
キーマスクの集合か AnyModifierを指定する。 このマスクは正しいキーマスクのビット値のビットごとの論理和を取ったもの である。
grab_window
グラブウィンドウを指定する。

関数 XUngrabKeyは、このクライアントが指定したウィンドウをグラブしている場合、このウィ ンドウ上でのキーの組み合わせを解放する。 この関数はアクティブなグラブに対しては無意味である。 引き数 modifiers が AnyModifierである場合は、可能なモディファイアの組み合わせ全てに対してリクエストを 発行することと等価である(モディファイアが無いことも組み合わせに含まれる)。 引き数 keycode が AnyKeyである場合は、可能な全てのキーコードに対してリクエストを発行することと 等価である。

XUngrabKeyはエラー BadValue ,BadWindow を起こすことがある。

イベント処理の再開

前の節ではサーバによるイベント処理を一時的に訂正させるグラブ機構につい て説明した。この節ではイベント処理を再開させる機構について説明する。

デバイスが凍結されている時にそれ以降のイベントを処理できるようにするには XAllowEventsを使う。

XAllowEvents(display, event_mode, time)
Display *display;
int event_mode;
Time time;
display
X サーバへの接続を指定する。
event_mode
イベントモードを指定する。 AsyncPointer , SyncPointer , AsyncKeyboard , SyncKeyboard ,ReplayPointer , ReplayKeyboard ,AsyncBoth ,SyncBothのいずれかを指定できる。
time
時刻を指定する。 タイムスタンプか CurrentTimeを指定できる。

XAllowEventsはクライアントがデバイスを凍結したている場合に、キューに入っている イベントを解放する。 指定した時刻がクライアントについて最も近くに起きたアクティブなグラブの 最終グラブ時刻より早い場合や、指定した時刻が現在のサーバ時刻より遅い場 合には、この関数は無効である。 引き数 event_mode の値によって、以下の処理が行われる:
AsyncPointer クライアントがポインタを凍結している場合、ポインタイベントの処理は通常通り継続される。2 回の別々のグラブの間にクラアントがポインタを 2 回凍結している場合は、AsyncPointer は両方の凍結を解除する。クライアントがポインタを凍結していない場合にはAsyncPointerは効果がないが、ポインタはクライアントにグラブされる必要がない。
SyncPointer クライアントがポインタを凍結しており、かつアクティブにグラブしている場合、そのクライアントに対してButtonPress イベントやButtonRelease イベントが報告されるまでポインタイベント処理は通常通り続けられる。このとき、ポインタは再び凍結されているように見える。しかし、送られたイベントによってポインタのグラブが解放された場合はポインタは凍結されない。SyncPointer はクライアントがポインタを凍結していない場合やクライアントがポインタをグラブしていない場合には無効である。
ReplayPointer クライアントがポインタをアクティブにグラブしており、クライアントに送られているイベントの結果として凍結されている場合には(アクティブになったXGrabButton や、モードがSyncPointerである以前のXAllowEvents から送られる。ただし、XGrabPointer からは送られない)、ポインタのグラブは解放され、そのイベントは完全に再処理される。しかしこの時、この関数は解放されたばかりのグラブの grab_windows とそれより上の(ルートに近い)ウィンドウの全てのパッシブグラブを全て無視する。クライントがポインタをグラブしていない場合やポインタがイベントの結果として凍結されていない場合には、このリクエストは無効である。
AsyncKeyboard クライアントがキーボードを凍結していると、キーボードイベントの処理は通常通り継続される。2 回の別々のグラブの間にクライアントがキーボードを 2 回凍結している場合は、AsyncKeyboard は両方の凍結を解除する。クライアントがキーボードを凍結していないとAsyncKeyboard は効果が無いが、クライアントがキーボードをグラブしている必要はない。
SyncKeyboard クライアントがキーボードを凍結し、かつアクティブにグラブしている場合、次のKeyPress イベントかKeyRelease イベントがクライアントに報告されるまでキーボードイベントの処理は通常通り続けられる。この時、キーボードは再び凍結されているように見える。しかし、イベントが報告されるとキーボードのグラブは解放されるならば、キーボードは凍結されていない。SyncKeyboard はクライアントがキーボードを凍結していない場合や、クライアントがキーボードをグラブしていない場合には効果がない。
ReplayKeyboard クライアントに送られたイベントの結果(アクティブになったXGrabKey や、モードがSyncKeyboard である以前のXAllowEvents から送られる。ただしXGrabKeyboardからは送られない)としてクライアントがアクティブにキーボードをグラブしている場合、キーボードのグラブは解放され、そのイベントは完全に再処理される。しかしこの時、この関数は解放されたばかりのグラブの grab_window とそれより上の(ルートに近い)ウィンドウの全てのパッシブグラブを無視する。クライントがキーボードをグラブしていない場合やキーボードがイベントの結果として凍結されていない場合には、このリクエストは無効である。
SyncBoth クライアントがポインタとキーボードの両方をグラブしている場合は、このクライアントにグラブされているデバイスについての(ポインタの場合はボタンイベント、キーボードの場合はキーイベント)次のButtonPress , ButtonRelease , KeyPress , KeyRelease が報告されるまでは両方のデバイスに対するイベント処理は通常通り継続される。しかし、報告されたイベントによってグラブが解放されると、これらのデバイスは凍結されない(しかし、他のデバイスがまだグラブされていると、そのデバイスに対するこれ以降のイベントによって両方のデバイスが凍結される)。クライアントがポインタとキーボードの両方を凍結していなければ、SyncBothは無効である。クライアントがポインタとキーボードを 2 回の別々にグラブする間に凍結が2 回行われた場合、SyncBoth は両方のデバイスを解放する(ただし、SyncBoth に対する以降の凍結ではそれぞれのデバイスの凍結は一度しか行われない)。
AsyncBoth クライアントがポインタとキーボードを凍結していれば、両方のデバイスに対するイベント処理は通常通り継続される。もしクライアントが 2 回の別々のグラブの間にデバイスを 2 回凍結した場合、AsyncBoth は両方のデバイスを解凍する。クライアントがポインタとキーボードの両方を凍結していなければ、AsyncBoth は無効である。

AsyncPointer , SyncPointer , ReplayPointer はキーボードイベントの処理に影響を与えない。 AsyncKeyboard , SyncKeyboard , ReplayKeyboard はポインタイベントの処理に影響を与えない。 ポインタグラブとキーボードグラブを(同じクライアントまたは異なる クライアントが)同時にアクティブにすることは可能である。 あるデバイスがグラブとグラブの間に凍結された場合、 そのデバイスに対するイベント処理は行われない。 両方のグラブによって 1 つのデバイスを凍結することは可能である。 この場合、凍結は両方のグラブの間で、イベントが再び処理できるようになる 前に解放されなければならない。 1 つのクライアントがデバイスを 2 回凍結しても、1 回の AllowEventsで両方とも解凍される。

XAllowEventsはエラー BadValue を起こすことがある。

ポインタの移動

ポインタの移動は普通はエンドユーザの操作に任されているが、場合によって はプログラムの制御下でポインタを別の位置に移動させることが必要なことも ある。

ポインタをウィンドウ内の任意の位置に移動させるには XWarpPointerを使う。

XWarpPointer(display, src_w, dest_w, src_x, src_y, src_width, src_height, dest_x,
dest_y)
Display *display;
Window src_w, dest_w;
int src_x, src_y;
unsigned int src_width, src_height;
int dest_x, dest_y;
display
X サーバへの接続を指定する。
src_w
移動元のウィンドウか Noneを指定する。
dest_w
移動先のウィンドウか Noneを指定する。
src_x

src_y

src_width

src_height
移動元ウィンドウ内部の長方形を指定する。
dest_x

dest_y
移動先ウィンドウ内部での x, y 座標を指定する。

引き数 dest_w が Noneの場合、 XWarpPointerはポインタを現在の位置から相対的にオフセット(dest_x, dest_y)だけ移動さ せる。 dest_w がウィンドウの場合、 XWarpPointerは dest_w の原点からオフセット(dest_x, dest_y)の位置にポインタを移動させる。 しかし src_w がウィンドウの場合は、移動が行われるのはウィンドウ src_w 内にポインタがあり、かつ src_w 内の指定した長方形の内部にポインタがあ る場合だけである。

座標 src_x と src_y は src_w の原点からの相対座標である。 src_height が 0 の場合、これは現在の src_w の高さから src_y を引いた 値に置き換えられる。 src_width が 0 の場合、これは現在の src_w の幅から src_x を引いた値に 置き換えられる。

この関数を使うべき場合はほとんどない。 ポインタ操作は通常はユーザに委ねられるべきである。 それにもかかわらずこの関数を使う場合、ユーザがポインタをある位置から他 の位置に瞬間的に移動させたようなイベントが生成される。 XWarpPointerを使っても、ポインタをポインタのアクティブなグラブの confine_to ウィンドウ の外に移動させることはできない点に注意すること。 これを試みても、confine_to ウィンドウのもっとも近い外辺にポインタが 移動するだけである。

XWarpPointerはエラー BadWindowを起こすことがある。

入力フォーカスの制御

Xlib には入力フォーカスの設定と取得のための関数が用意されている。 入力フォーカスは共有されるリソースであり、正しく対話を行うためには クライアント間での協調動作が必要である。 入力フォーカスのポリシーについては Inter-Client Communication Conventions Manual を参照すること。

入力フォーカスを設定するには Inter-Client Communication Conventions Manual を参照すること。

を使う。

XSetInputFocus(display, focus, revert_to, time)
Display *display;
Window focus;
int revert_to;
Time time;
display
X サーバへの接続を指定する。
focus
ウィンドウ、 PointerRoot ,Noneのいずれかを指定する。
revert_to
ウィンドウが表示不能になったときに入力フォーカスがどこに戻るかを指定する。 RevertToParent , RevertToPointerRoot , RevertToNoneのいずれかを指定できる。
time
時刻を指定する。 タイムスタンプか CurrentTimeを指定できる。

関数 XSetInputFocusは入力フォーカスと最終フォーカス変更時刻(last-focus-change time)を変更 する。 指定した時刻が最終フォーカス変更時刻より早い場合や X サーバの現在時刻よ りも遅い場合には、この関数は何も行わない。 そうでない場合には、最終フォーカス変更時刻は指定した時刻にセットされる (CurrentTime は X サーバの現在時刻で置き換えられる)。 XSetInputFocusにより X サーバは FocusInイベントと FocusOutイベントを生成する。

引き数 focus の値により関数の動作は以下のようになる。

指定したフォーカスウィンドウは、 XSetInputFocusが呼び出されたときに表示可能でなければならない。 表示可能でなければ関数は BadMatchエラーとなる。 フォーカスウィンドウが後で表示可能でなくなった場合、 X サーバは引き数 revert_to を評価し、以下のようにして新しいフォーカスウィ ンドウを決定する。

XSetInputFocusはエラー BadMatch ,BadValue ,BadWindow を起こすことがある。

現在の入力フォーカスを得るには XGetInputFocus を使う。

XGetInputFocus(display, focus_return, revert_to_return)
Display *display;
Window *focus_return;
int *revert_to_return;
display
X サーバへの接続を指定する。
focus_return
フォーカスウィンドウ、 PointerRoot ,Noneのいずれかが返される。
revert_to_return
現在のフォーカス状態 (RevertToParent , RevertToPointerRoot , RevertToNoneのいずれか)を返す。

関数 XGetInputFocusはフォーカスウィンドウと現在のフォーカス状態を返す。

キーボードとポインタの設定の操作

Xlib には、キーボードの制御の変更、自動リピートするキーのリストの取得、 キーボードの自動リピートのオン/オフの設定、ベルを鳴らすこと、 ポインタのボタンとキーボードのマッピングの設定と取得、 キーボードのビットベクトルの取得を行う関数が用意されている。

この節ではユーザの好みに合わせたベル、キークリック、ポインタの動作等を 設定するオプションについて説明する。 これらのオプションのデフォルト値の多くはサーバに依存する。 実際には、どんな実装でもこれらのパラメータの全てを設定することはできな いかもしれない。

関数 XChangeKeyboardControlはキーボードの制御を変更し、以下に示す XKeyboardControl構造体を操作する:

/* ChangeKeyboardControl に対するマスクビット値 */

#define KBKeyClickPercent (1L<<0)
#define KBBellPercent (1L<<1)
#define KBBellPitch (1L<<2)
#define KBBellDuration (1L<<3)
#define KBLed (1L<<4)
#define KBLedMode (1L<<5)
#define KBKey (1L<<6)
#define KBAutoRepeatMode (1L<<7)
/* Values */
typedef struct {
	int key_click_percent;
	int bell_percent;
	int bell_pitch;
	int bell_duration;
	int led;
	int led_mode;	/* LedModeOn, LedModeOff */
	int key;
	int auto_repeat_mode;	/* AutoRepeatModeOff, AutoRepeatModeOn, 
                            	AutoRepeatModeDefault */
} XKeyboardControl;

key_click_percent メンバは、可能ならばキークリック音の音量を 0 (無音) 以上 100 (最大音量)以下の値で設定する。 -1 を指定するとデフォルト値が復元される。 これ以外の負の値を指定した場合は、エラー BadValueとなる。

bell_percent メンバは、可能ならば 0 (無音)以上 100 (最大音量)の間でベルの 基本音量を設定する。 -1 を指定するとデフォルト値が復元される。 これ以外の負の値を指定した場合は、エラー BadValueとなる。 bell_pitch メンバは、可能ならばベルの音調(Hz で指定)を設定する。 -1 を指定するとデフォルト値が復元される。 これ以外の負の値を指定した場合は、エラー BadValueとなる。 bell_duration メンバは、可能ならばベルの鳴る時間をミリ秒単位で設定する。 -1 を指定するとデフォルト値が復元される。 これ以外の負の値を指定した場合は、エラー BadValueとなる。

led_mode メンバと led_mode メンバの両方が指定された場合、可能ならばそ の LED の状態が変更される。 led_mode メンバには LedModeOnあるいは LedModeOffが設定できる。 led_mode だけが指定されている場合、可能ならば全ての LED の状態が変更さ れる。 1 から数えて最大 32 個までの LED がサポートされている。 LED の標準的な実装は定義されていない。 led_mode メンバ無しで led メンバが指定された場合は、エラー BadMatchとなる。

auto_repeat_mode メンバと key メンバの両方が設定されている場合、可能な らばそのキーに対する auto_repeat_mode モードが変更される(変更は AutoRepeatModeOn ,AutoRepeatModeOff ,AutoRepeatModeDefaultのいずれかに従って行われる)。 auto_repeat_mode だけが指定された場合、可能ならばキーボード全体につい ての大域的な auto_repeat_mode が変更されるが、個別のキーについての設定 は影響を受けない。 auto_repeat_mode 無しでキーが指定された場合、エラー BadMatchとなる。 それぞれのキーはオートリピートすべきかどうかを示す個別のモードと、この モードのデフォルトの設定を持っている。 さらに、オートリピートを有効にすべきかどうかを示す大域的なモードと、こ のモードのデフォルトの設定がある。 大域的なモードが AutoRepeatModeOnならば、キーは個別のオートリピートモードに従う。 大域的なモードが AutoRepeatModeOffならば、全てのキーはオートリピートしてはならない。 オートリピートしているキーは KeyPressイベントと KeyReleaseイベントを交互に生成する。 あるキーをモディファイアとして使う場合は、オートリピートの設定に関わら ず、そのキーはオートリピートさせないことが望ましい。

コンソールに接続されているがキーボードに直接は接続されていない ベル発生器は、キーボードの一部として扱われる。 制御が検査され、変更される順序はサーバ依存である。 エラーが生成された場合は、制御の一部が変更されているかもしれない。

XChangeKeyboardControl(display, value_mask, values)
Display *display;
unsigned long value_mask;
XKeyboardControl *values;
display
X サーバへの接続を指定する。
value_mask
どの制御を変更するか指定する。 このマスクは有効な制御マスクビット値のビットごとの論理和を取ったもので ある。
values
マスクで 1 にセットされている各ビットに対して値を 1 つずつ指定する。

関数 XChangeKeyboardControlは、 XKeyboardControl構造体で定義されるキーボード特性を制御する。 変更する値は引き数 value_mask を使って指定する。

XChangeKeyboardControlはエラー BadMatch ,BadValue を起こすことがある。

キーボードの現在の制御値を得るには XGetKeyboardControlを使う。

XGetKeyboardControl(display, values_return)
Display *display;
XKeyboardState *values_return;
display
X サーバへの接続を指定する。
values_return
指定した XKeyboardState 構造体に現在のキーボード制御が返される。

関数 XGetKeyboardControlはキーボードの現在の制御値を XKeyboardState構造体に返す。

typedef struct {
	int key_click_percent;
	int bell_percent;
	unsigned int bell_pitch, bell_duration;
	unsigned long led_mask;
	int global_auto_repeat;
	char auto_repeats[32];
} XKeyboardState;

LED の場合、led_mask の最小位ビットが LED 1 に対応し、 led_mask のそれぞれのビットを 1 にすることによってその LED の点灯を 指示する。 global_auto_repeat メンバには AutoRepeatModeOnまたは AutoRepeatModeOffを設定できる。 auto_repeats メンバはビットのベクトルである。 それぞれのビットに 1 が設定されていると、対応するキーのオートリピート が有効であることを示す。 このベクトルは 32 バイトで表される。 バイト N (0から数える)は、キー 8N から 8N + 7 に対応するビットを持つ。 ここでバイト中の最下位ビットがキー 8N を表す。

キーボードのオートリピートを有効にするには XAutoRepeatOnを使う。

XAutoRepeatOn(display)
Display *display;
display
X サーバへの接続を指定する。

関数 XAutoRepeatOnは、指定したディスプレイのキーボードのオートリピートを有効にする。

キーボードのオートリピートを無効にするには XAutoRepeatOffを使う。

XAutoRepeatOff(display)
Display *display;
display
X サーバへの接続を指定する。

関数 XAutoRepeatOffは、指定したディスプレイのキーボードのオートリピートを無効にする。

ベルを慣らすには XBellを使う。

XBell(display, percent)
Display *display;
int percent;
display
X サーバへの接続を指定する。
percent
ベルの音量を指定する。 これは -100 以上 100 以下の範囲である。

関数 XBellは可能ならば、指定したディスプレイのキーボードのベルを鳴らす。 指定する音量はキーボードの基本音量に対する相対値である。 引き数 percent の値が -100 から 100 の範囲でない場合には、エラー BadValueとなる。 引き数 percent の値が負でない場合には、ベルが鳴る音量は次のようになる。 .IP base - [(base * percent) / 100] + percent

引き数 percent の値が負の場合には、ベルが鳴る音量は次のようになる。 .IP base + [(base * percent) / 100]

ベルの基本音量を変更するには XChangeKeyboardControlを使う。

XBellはエラー BadValue を起こすことがある。

キーボードの状態を示すビットのベクトルを得るには XQueryKeymapを使う。

XQueryKeymap(display, keys_return)
Display *display;
char keys_return[32];
display
X サーバへの接続を指定する。
keys_return
どのキーが押されたかを示すバイト配列が返される。 それぞれのビットはキーボードの 1 つのキーを表す。

関数 XQueryKeymapは、キーボードの論理的状態を表すビットのベクトルを返す。 1 がセットされているビットは、対応するキーが現在押されていることを示す。 このベクトルは 32 バイトで表される。 バイト N (0から数える)は、キー 8N から 8N + 7 に対応するビットを持つ。 ここでバイト中の最下位ビットがキー 8N を表す。

デバイスのイベントが凍結されている場合、デバイスの論理的状態(クライア ントアプリケーションが見る)が物理的状態とずれることがある。

ポインタボタンのマッピングを設定するには XSetPointerMappingを使う。

int XSetPointerMapping(display, map, nmap)
Display *display;
unsigned char map[];
int nmap;
display
X サーバへの接続を指定する。
map
マッピングのリストを指定する。
nmap
マッピングリスト内の要素数を指定する。

関数 XSetPointerMappingはポインタのマッピングを設定する。 成功した場合には X サーバは MappingNotifyイベントを生成し、 XSetPointerMappingMappingSuccessを返す。 要素 map[i] は物理ボタン i+1 に対する論理的なボタン番号を定義する。 リストの長さは XGetPointerMappingが返す値と同じでなければならない。そうでない場合には、エラー BadValueとなる。 要素の値が 0 ならばボタンは使えなくなる。要素の値は物理的なボタン数に は制限されない。 しかし、2 つの要素は 0 でない同じ値を持つことはできない。同じ値になっ た場合には BadValueエラーとなる。 設定を変えようとしているボタンのいずれかが論理的に押された状態にあった場合、 XSetPointerMappingMappingBusyを返し、マッピングは変化しない。

XSetPointerMappingはエラー BadValue を起こすことがある。

ポインタのマッピングを得るには XGetPointerMappingを使う。

int XGetPointerMapping(display, map_return, nmap)
Display *display;
unsigned char map_return[];
int nmap;
display
X サーバへの接続を指定する。
map_return
マッピングのリストが返される。
nmap
マッピングのリストに含まれる要素数を指定する。

関数 XGetPointerMappingはポインタの現在のマッピングを返す。 ポインタのボタンには 1 から始まる番号が付けられる。 XGetPointerMappingはポインタに実際に付いている物理的なボタンの数を返す。 ポインタに対する名目的なマッピングは map[i]=i+1 である。 引き数 nmap はポインタのマッピングが返される配列の長さを指定する。 最初の nmap 個の要素だけが map_return に返される。

ポインタの対話的な操作感覚を制御するには XChangePointerControlを使う。

XChangePointerControl(display, do_accel, do_threshold, accel_numerator,
accel_denominator, threshold)
Display *display;
Bool do_accel, do_threshold;
int accel_numerator, accel_denominator;
int threshold;
display
X サーバへの接続を指定する。
do_accel
引き数 accel_numerator や accel_denominator の値を使うかどうか制御する真 偽値を指定する。
do_threshold
引き数 threshold の値を使うかどうか制御する真偽値を指定する。
accel_numerator
アクセラレーションの倍率の分子を指定する。
accel_denominator
アクセラレーションの倍率の分母を指定する。
threshold
アクセラレーションの閾値を指定する。

関数 XChangePointerControlは、ポインティングデバイスがどのように動くか定義する。 分母で表現されるアクセラレーションは移動量にかける倍率である。 例えば 3/1 を指定すると、ポインタは通常の 3 倍の速さで移動する。 X サーバによって、端数は任意に丸められることがある。 ポインタが一度に閾値の個数以上のピクセル移動し、引き数 threshold の値を 越える量を移動しようとした場合に限って、アクセラレーションは有効となる。 値に -1 を指定するとデフォルト値に戻る。 ポインタの値をセットするには、引き数 do_accel と do_threshold は Trueでなければならない。そうでない場合には、パラメータは変化しない。 負の値(-1 を除く)の場合には、エラー BadValueとなる。 引き数 accel_denominator が 0 の場合も同じエラーになる。

XChangePointerControlはエラー BadValue を起こすことがある。

ポインタに関する現在のパラメータを得るには XGetPointerControlを使う。

XGetPointerControl(display, accel_numerator_return, accel_denominator_return,
threshold_return)
Display *display;
int *accel_numerator_return, *accel_denominator_return;
int *threshold_return;
display
X サーバへの接続を指定する。
accel_numerator_return
アクセラレーションの倍率の分子が返される。
accel_denominator_return
アクセラレーションの倍率の分母が返される。
threshold_return
アクセラレーションの閾値が返される。

関数 XGetPointerControlは、ポインタのアクセラレーションの倍率と閾値の現在の値を返す。

キーボードのエンコーディングの操作

KeyCode は物理的(または論理的)なキーを表現する。 KeyCode は 8 以上 255 以下の範囲の値を持つ。 KeyCode の値は内在的な情報は持っていないが、サーバの実装者はジオメトリ (例えば行列)情報を何らかのやり方でエンコードして、この情報がサーバ依存 のやり方で解釈できるようにしてもよい。 キーと KeyCode のマッピングを変えることはできない。

KeySym はキートップのシンボルをエンコードしたものである。 定義済みの KeySym の集合には ISO Latin 文字集合 (1-4)、カタカナ、 アラビア文字、キリル文字、ギリシャ文字、技術記号、特殊記号、出版記号、 APL, ヘブライ文字、タイ文字、韓国文字、それからキーボードのキーに書か れている雑多なシンボル(Return, Help, Tab 等)が含まれる。 ある程度は、これらのシンボル集合は国際標準を基にしている。 標準がない部分に付いては、これらのシンボル集合の一部は DEC 社の標準を基に している。 定義されているシンボル集合は <X11/keysymdef.h>に書かれている。 残念ながら、C プリプロセッサの中には定義シンボルの数が制限されているも のがある。 Latin 1-4, Greek, 雑多クラス以外の KeySym を使わなければならない場合 は、これらの集合に対してシンボルを定義しなければならないかもしれない。 ほとんどのアプリケーションは普通は <X11/keysym.h>しかインクルードしない。このインクルードファイルで定義されているのは ISO Latin 1-4, ギリシャ文字シンボル、雑多シンボルである。

KeySym のリストはそれぞれの KeyCode に対応する。 このリストはシンボルの集合をこれに対応するキーに変えるためのものである。 もしリスト(末尾に付く NoSymbolエントリは無視する)が単一の KeySym ``K'' ならば、このリストは ``K NoSymbol K NoSymbol'' のように扱われる。 もしリスト(末尾に付く NoSymbolエントリは無視する)が KeySym の組 ``K1 K2'' ならば、このリストは ``K1 K2 K1 K2'' のように扱われる。 もしリスト(末尾に付く NoSymbolエントリは無視する)が KeySym 3 つの組 ``K1 K2 K3'' ならば、この リストは ``K1 K2 K3 NoSymbol'' のように扱われる。 明示的な「空の」要素がリスト内で必要な時は、 VoidSymbolという値を使える。

リストの最初の 4 つの要素は 2 グループの KeySym に分割される。 グループ 1 は最初と 2 番目の KeySym であり、 グループ 1 は3 番目と 4 番目の KeySym である。 それぞれのグループ内では、もしグループの 2 番目の要素が NoSymbol ならばそのグループは 2 番目の要素が最初の要素と同じであるかのように扱 わなければならない。ただし最初の要素がアルファベットの KeySym ``K'' であり、これに対して小文字と大文字の形式が定義されている時 は例外である。 この場合のグループは、最初の要素は小文字の形式の ``K'' を持ち、2 番目の要素が大文字の形式の ``K'' を持っているものとして扱わなけ ればならない。

KeyPressから KeySym を取得する標準的な規則はグループ 1 とグループ 2 の KeySym しか使わない。 リストに含まれる他の KeySym の解釈は与えられない。 使われるグループはモディファイアの状態によって決まる。 グループの切り替えは「モードスイッチ(MODE SWITCH)」という名前の KeySym と、その KeySym に何らかの KeyCode を割り付けてその KeyCode に Mod1から Mod5までのモディファイアの任意のひとつを割り付けることによって制御される。 このモディファイアはグループモディファイアと呼ばれる。 任意の KeyCode について、グループ 1 はグループモディファイアがオフの時 に使われ、グループ 2 はグループモディファイアがオンの時に使われる。

Lockモディファイアは、XK_Caps_Lock という名前の KeySym が何らかの KeyCode に割り付けられており、その KeyCode が Lockモディファイアに割り付けられている時に CapsLock と解釈される。 Lockモディファイアは、XK_Shift_Lock という名前の KeySym が何らかの KeyCode に割り付けられており、その KeyCode が Lockモディファイアに割り付けられている時に ShiftLock と解釈される。 Lock モディファイアが CapsLock と ShiftLock のどちらにでも解釈できる場合は、 CapsLock として解釈される。

テンキーの操作は XK_Num_Lock という名前の KeySym と、その KeySym に何 らかの KeyCode を割り付けてその KeyCode に Mod1から Mod5までのモディファイアの任意のひとつを割り付けることによって制御される。 このモディファイアは numlock モディファイアと呼ばれる。 名前に ``XK_KP_'' というプレフィックスが含まれる標準の KeySym はテンキー の KeySym と呼ばれる。これらは 16 進値で 0xFF80 以上 0xFFBD 以下の値を 持つ。これに加えて、16 進値で 0x11000000 以上 0x1100FFFF 以下の範囲を 持つベンダー固有の KeySym もテンキーの KeySym である。

あるグループの中での KeySym の選択は、以下のリストのうち最初に条件を満 たした規則によって行われる。

キー上のシンボルの空間的なジオメトリはどれも KeySym リスト内の順番によっ て定義されることはないが、ジオメトリはサーバ固有の方法に基づいて定義し ても構わない。 X サーバは KeyCode と KeySym のマッピングは使わない。 ただクライアントの読み書きのために格納することがあるだけである。

XDisplayKeycodes(display, min_keycodes_return, max_keycodes_return)
Display *display;
int *min_keycodes_return, *max_keycodes_return;
display
X サーバへの接続を指定する。
min_keycodes_return
KeyCode の最小数が返される。
max_keycodes_return
KeyCode の最大数が返される。

関数 XDisplayKeycodesは、指定したディスプレイがサポートしている最小のキーコードと最大のキー コードを返す。 返される最小の KeyCode の数は 8 より小さいことはなく、返される最大の KeyCode の数は 255 より大きいことはない。 この範囲の全ての KeyCode が対応するキーを持つ必要はない。

指定された KeyCode に対応するシンボルを得るには XGetKeyboardMappingを取得する。

KeySym *XGetKeyboardMapping(display, first_keycode, keycode_count,
keysyms_per_keycode_return)
Display *display;
KeyCode first_keycode;
int keycode_count;
int *keysyms_per_keycode_return;
display
X サーバへの接続を指定する。
first_keycode
返される最初の KeyCode を指定する。
keycode_count
返される KeyCode の数を指定する。
keysyms_per_keycode_return
KeyCode あたりの KeySym の数が返される。

関数 XGetKeyboardMappingは、first_keycode 番目から始まる指定した数の KeyCode に対するシンボル を返す。 first_keycode で指定する値は、 XDisplayKeycodesが返す min_keycode 以上でなければならない。 そうでない場合は、エラー BadValue となる。 さらに次に示す式は XDisplayKeycodesが返す max_keycode 以下でなければならない。

first_keycode + keycode_count - 1

そうでない場合には、エラー BadValueとなる。 KeySym リスト中の要素数は次の式で表される。

keycode_count * keysyms_per_keycode_return

0 から数えて番号 N である、KeyCode K に対する KeySym は、keysym リスト内で 以下の式のインデックスを持つ。このインデックスは 0 から数える。

(K - first_code) * keysyms_per_code_return + N

X サーバは、全ての必要なシンボルを報告するために十分な大きさである任意 の keysyms_per_keycode を選択する。 特別な KeySym 値である NoSymbol は、個別の KeyCode の未使用の要素を埋めるために使う。 XGetKeyboardMappingが返すメモリを解放するには、 XFreeを使用すること。.LP XGetKeyboardMappingはエラー BadValue を起こすことがある。

キーボードのマッピングを変更するには XChangeKeyboardMappingを使う。

XChangeKeyboardMapping(display, first_keycode, keysyms_per_keycode, keysyms, num_codes)
Display *display;
int first_keycode;
int keysyms_per_keycode;
KeySym *keysyms;
int num_codes;
display
X サーバへの接続を指定する。
first_keycode
変更される最初の KeyCode を指定する。
keysyms_per_keycode
KeyCode あたりの KeySym の数を指定する。
keysyms
KeySym の配列を指定する。
num_codes
変更される KeyCode の数を指定する。

関数 XChangeKeyboardMappingは、 first_keycode から始まる指定した数の KeyCode に対するシンボルを定 義する。 範囲外の KeyCode に対するシンボルは変更されない。 keysym 中の要素数は次の数でなければならない。

num_codes * keysyms_per_keycode

指定した first_keycode は XDisplayKeycodesが返す min_keycode 以上でなければならない。そうでない場合はエラー BadValue となる。 さらに、以下の式は XDisplayKeycodesが返す max_keycode 以下でなければならない。そうでない場合はエラー BadValue となる。

first_keycode + num_codes - 1

0 から数えて番号 N である、KeyCode K に対するKeySym は、keysym 内で 以下の式のインデックスを持つ。このインデックスは 0 から数える。

(K - first_keycode) * keysyms_per_keycode + N

全ての必要なシンボルを保持する十分な大きさであれば、クライアントは指定 した keysyms_per_keycode の数を任意に選択できる。 特別な KeySym 値である NoSymbol は、個別の KeyCode の未使用の要素を埋めるために使う。 NoSymbolは、実際に有効な KeyCode リストの最後でない位置に現われてもよい。 XChangeKeyboardMappingMappingNotifyイベントを生成する。

X サーバがこのマッピングを解釈する必要はない。 これはクライアントに読み書きさせるために保存しているだけである。

XChangeKeyboardMappingはエラー BadAlloc ,BadValue を起こすことがある。

以下の 6 つの関数は XModifierKeymap構造体を使う。構造体の内容は以下の通りである:

typedef struct {
	int max_keypermod;	/* このサーバにおける、モディファイア当たりのキーの最大個数 */
	KeyCode *modifiermap;	/* 8 * max_keypermod 個のモディファイアの配列 */
} XModifierKeymap;

XModifierKeymap構造体を作るには XNewModifiermapを使う。

XModifierKeymap *XNewModifiermap(max_keys_per_mod)
int max_keys_per_mod;
max_keys_per_mod
マップ中で予めモディファイアに割り当てられた KeyCode のエントリ数を指 定する。

関数 XNewModifiermapは、後で利用するための XModifierKeymap構造体へのポインタを返す。

XModifierKeymap構造体にエントリを追加するには XInsertModifiermapEntryを使う。

XModifierKeymap *XInsertModifiermapEntry(modmap, keycode_entry, modifier)
XModifierKeymap *modmap;
KeyCode keycode_entry;
int modifier;
modmap
XModifierKeymap構造体を指定する。
keycode_entry
KeyCode を指定する。 モディファイアを指定する。

関数 XInsertModifiermapEntryは指定したモディファイアを制御する集合に指定された KeyCode を追加し、 その結果得られた XModifierKeymap構造体(必要に応じて拡張される)を返す。

XModifierKeymap構造体からエントリを削除するには XDeleteModifiermapEntryを使う。

XModifierKeymap *XDeleteModifiermapEntry(modmap, keycode_entry, modifier)
XModifierKeymap *modmap;
KeyCode keycode_entry;
int modifier;
modmap
XModifierKeymap構造体を指定する。
keycode_entry
KeyCode を指定する。
modifier
モディファイアを指定する。

関数 XDeleteModifiermapEntryは指定したモディファイアを制御する集合から指定された KeyCode を削除し、 その結果得られた XModifierKeymap構造体へのポインタを返す。

XModifierKeymap構造体を破棄するには XFreeModifiermapを使う。

XFreeModifiermap(modmap)
XModifierKeymap *modmap;
modmap
XModifierKeymap構造体を指定する。

関数 XFreeModifiermapは指定された XModifierKeymap構造体を解放する。

モディファイアとして使われる KeyCode を設定するには XSetModifierMappingを使う。

int XSetModifierMapping(display, modmap)
Display *display;
XModifierKeymap *modmap;
display
X サーバへの接続を指定する。
modmap
XModifierKeymap構造体を指定する。

関数 XSetModifierMappingはモディファイアとして使うキー(もしあれば)の KeyCode を指定する。 成功した場合、X サーバは MappingNotifyイベントを生成し、 XSetModifierMappingMappingSuccessを返す。 X サーバは多くても 8 つのモディファイアキーしか認めない。 XModifierKeymap構造体で 8 個より多いモディファイアキーが指定されている場合、エラー BadLengthとなる。

XModifierKeymap構造体の modifiermap メンバは、max_keypermod 個の KeyCode を 8 組持ち、 各モディファイアに対するキーコードは Shift , Lock , Control , Mod1 , Mod2 , Mod3 , Mod4 , Mod5の順に並んでいる。 それぞれの集合のうち、0 でない KeyCode だけが意味を持ち、KeyCode が 0 で あるものは無視される。 さらに、0 でない全ての KeyCode は Display 構造体の min_keycode と max_keycode で指定される範囲でなければならない。 そうでない場合は、エラー BadValue となる。

X サーバはモディファイアの変更の仕方を制限することができる。 このような制限は例えば、あるキーが離された状態変化をハードウェア的に 生成できない場合、あるキーについてオートリピートを無効にできない場合、 複数個のモディファイアキーがサポートされていない場合等に行われる。 このような制限が破られた場合は、返されるステータスは MappingFailedであり、どのモディファイアも変更されない。 モディファイアに対して指定された新しい KeyCode が 現在定義されているモディファイアと異なり、そのモディファイアに対する (現在の、あるいは新しい)キーのいずれかが論理的に押された状態にある場合 は、 XSetModifierMappingMappingBusyを返し、どのモディファイアも変更されない。

XSetModifierMappingはエラー BadAlloc ,BadValueを起こすことがある。

モディファイアとして使う KeyCode を取得するには XGetModifierMappingを使う。

XModifierKeymap *XGetModifierMapping(display)
Display *display;
display
X サーバへの接続を指定する。

関数 XGetModifierMappingは新しく生成された XModifierKeymap構造体へのポインタを返す。この構造体はモディファイアとして使用されるキー を含む。 この構造体を使い終わったら XFreeModifiermapを呼び出して解放しなければならない。 集合内でいずれかのモディファイアに対する値として 0 が現われた場合、そ のモディファイアは無効となる。
目次に戻る