XKB: 関数

XkbIgnoreExtension	XKB の有効/無効をセット
XkbLibraryVersion	XKB ライブラリの互換性を確認する
XkbQueryExtension	拡張機能がサーバーに存在するか確認し、初期化する
XkbOpenDisplay	サーバーへの接続と、XKB 初期化を同時に行う
XkbRefreshKeyboardMapping	X ライブラリの内部にあるキーボード詳細を更新
イベント
XkbSelectEvents	XKB イベントの配信を選択または選択解除
XkbSelectEventDetails	イベントの詳細な条件を指定して選択/選択解除
修飾子・グループ
XkbLockModifiers	修飾子のロック/ロック解除
XkbLatchModifiers	修飾子のラッチとラッチ解除
XkbLockGroup	keysym グループをロックする
XkbLatchGroup	グループをラッチする
XkbGetState	キーボードの状態を取得
XkbVirtualModsToReal	仮想修飾子から実際の修飾子を取得
XkbDesc
XkbGetKeyboard	キーボードの詳細を取得
XkbAllocKeyboard	XkbDescRec を確保
XkbFreeKeyboard	XkbDescRec の全体または一部を解放
キー変換
XkbKeycodeToKeysym	指定したグループ＆シフトレベルで、特定のキーにバインドされている KeySym を検索
XkbKeysymToModifiers	コアキーボード上の特定の KeySym にバインドされた修飾子のセットを検索
XkbLookupKeySym	キーコードから KeySym を検索
XkbLookupKeyBinding	XRebindKeysym によってキーにバインドされた文字列を検索
XkbTranslateKeySym	KeySym に修飾子を適用して返す
XkbTranslateKeyCode	XkbDescRec を元に、キーコードから KeySym に変換する
ベル
XkbDeviceBell	ベルを鳴らす
XkbBell	デフォルトキーボードでベルを鳴らす
XkbDeviceBellEvent	ベルイベントを発生させる
XkbBellEvent	デフォルトキーボードでベルイベントを発生させる
XkbForceDeviceBell	強制的にベルを鳴らす
XkbForceBell	デフォルトキーボードで強制的にベルを鳴らす

#include <X11/XKBlib.h>

Bool XkbIgnoreExtension(Bool ignore);

コア X ライブラリのキーボード関数が、X キーボード拡張機能を使用しないようにします。
サーバー接続を開く前に、XkbIgnoreExtension を呼び出す必要があります。
(Xkb には、接続が確立された後に、拡張機能の使用を有効または無効にする方法はありません)

ignore

True の場合、ライブラリは新しいディスプレイを開くときに、Xkb 拡張機能を初期化しません。
これにより、X サーバーは互換モードを使用し、コアプロトコルのリクエストとイベントのみを使用して、クライアントと通信するようになります。

False の場合、ライブラリは後続の XOpenDisplay() を通常どおり処理し、Xkb のリクエスト、イベント、および状態を使用します。

戻り値

要求を適用できなかった場合、False

Bool XkbLibraryVersion(int *lib_major_in_out, int *lib_minor_in_out);

クライアント側の XKB ライブラリのバージョンを確認します。
動的にロードされる Xkb ライブラリのバージョンと、アプリケーションで使用されるバージョンとの間の互換性をチェックする必要があります。

lib_major_in_out,lib_minor_in_out

アプリケーションで使用するバージョンをセットしておく。
実際に使用できるライブラリのバージョンが返る。
ヘッダのバージョンを使用したい場合、XkbMajorVersion, XkbMinorVersion をセットする。

戻り値

ライブラリのバージョンに互換性がある場合、True が返る

Bool XkbQueryExtension(Display *dpy, int *opcode_rtrn, int *event_rtrn, int *error_rtrn, int *major_in_out, int *minor_in_out);

サーバー内の拡張機能の存在と互換性を確認し、拡張機能を初期化します。
(バージョンが一致しない可能性があるため、初期化などに XQueryExtension および XInitExtension を使用することはできません)

他の Xkb ライブラリインターフェイスを使用する前に、XkbQueryExtension または XkbOpenDisplay を呼び出す必要があります。
例外は、XkbIgnoreExtension、XkbLibraryVersion、およびいくつかのベル関数です。

拡張機能が存在しないか、初期化されていない場合は、他の Xkb 関数を使用しないでください。
一般に、Xkb 拡張機能を初期化する前に Xkb ライブラリ関数を呼び出すと、BadAccess プロトコルエラーが発生します。

event_rtrn

XKB イベントのタイプ値が返る

error_rtrn

XKB のエラーのベース値が返る

戻り値

拡張機能が存在し、互換性がある場合は、True が返る

Display *XkbOpenDisplay(char *display_name, int *event_rtrn, int *error_rtrn, int *major_in_out, int *minor_in_out, int *reason_rtrn);

X サーバーへの接続を開き、ライブラリとサーバーの両方で Xkb 拡張機能の互換性のあるバージョンを確認し、拡張機能を使用できるように初期化します。

major_in_out と minor_in_out が NULL でない場合、まず XkbLibraryVersion() を呼び出して、クライアントライブラリに互換性があるかどうかを判断し、major_in_out と minor_in_out にバージョンを返します。
ライブラリに互換性がない場合、major_in_out と minor_in_out に、使用されているライブラリのバージョンを返し、戻り値は NULL を返します。
互換性がある場合、次に、display_name を使用して XOpenDisplay を呼び出します。これが失敗した場合、関数は NULL を返します。
成功すると、次に XkbQueryExtension() を呼び出し、サーバーでサポートされている Xkb 拡張機能のバージョンを major_in_out および minor_in_out に返します。
サーバーとライブラリの拡張機能のバージョンが互換性がない場合、またはサーバーに拡張機能が存在しない場合、ディスプレイを閉じて NULL を返します。
成功すると、関数は Display * を返します。

reason_rtrn

結果のステータス。
XkbOD_BadLibraryVersion は、XkbLibraryVersion() が False を返したことを示します。
XkbOD_ConnectionRefused は、ディスプレイを開けなかったことを示します。
XkbOD_BadServerVersion は、ライブラリとサーバーの拡張バージョンに互換性がないことを示します。
XkbOD_NonXkbServer は、拡張機能が X サーバーに存在しないことを示します。
XkbOD_Success は、関数が成功したことを示します。

Status XkbRefreshKeyboardMapping(XkbMapNotifyEvent *event);

XRefreshKeyboardMapping 関数の XKB 版。
X サーバーに対して、現在のキーマッピング情報をこのクライアントに送信するように、要求します。
クライアントは通常、XkbMapNotify イベントを受信した後に XkbRefreshKeyboardMapping を呼び出します。

XkbMapNotify イベントは、一部のクライアントが XkbSetMap、XkbChangeMap、XkbGetKeyboardByName、またはキーボードマッピング、または修飾子のマッピングを変更する標準 X ライブラリ関数のいずれかを呼び出したときに生成できます。

戻り値

成功した場合は Success を返し、event が Xkb イベントでない場合は BadMatch を返します。

イベント

Bool XkbSelectEvents(Display *display, unsigned int device_spec, unsigned long int bits_to_change, unsigned long int values_for_bits);

1 つ以上の Xkb イベントの配信を選択または選択解除します (指定イベントのすべての条件下で配信)。
クライアントは、他のクライアントのイベント選択を設定できません。

Xkb 拡張機能を使用するクライアントは、初期状態ではすべてのイベントは選択されていません。

bits_to_change にビットが設定されていないが、values_for_bits に設定されている場合、BadMatch プロトコルエラーが発生します。
bits_to_change または value_for_bits のいずれかに、未定義のビットが設定されている場合、BadValue プロトコルエラーが発生します。

device_spec

イベントの選択を変更するキーボード。
XInput 拡張機能におけるデバイスID、または XkbUseCoreKbd (マスターキーボードデバイス)。

bits_to_change

選択/選択解除するイベントのマスク

#define XkbNewKeyboardNotifyMask    (1L << 0)
#define XkbMapNotifyMask            (1L << 1)
#define XkbStateNotifyMask          (1L << 2)
#define XkbControlsNotifyMask       (1L << 3)
#define XkbIndicatorStateNotifyMask (1L << 4)
#define XkbIndicatorMapNotifyMask   (1L << 5)
#define XkbNamesNotifyMask          (1L << 6)
#define XkbCompatMapNotifyMask      (1L << 7)
#define XkbBellNotifyMask           (1L << 8)
#define XkbActionMessageMask        (1L << 9)
#define XkbAccessXNotifyMask        (1L << 10)
#define XkbExtensionDeviceNotifyMask (1L << 11)
#define XkbAllEventsMask            (0xFFF)

values_for_bits

各イベントを選択するか、選択解除するか。
bits_to_change に対応するビット位置が ON で選択、OFF で選択解除になります。

戻り値

拡張機能が初期化されている場合は True

Bool XkbSelectEventDetails(Display *display, unsigned int device_spec, unsigned int event_type,
    unsigned long int bits_to_change, unsigned long int values_for_bits);

event_type で指定された XKB イベントの詳細な配信条件を選択します。
bits_to_change と value_for_bits の解釈は、XKB イベントタイプによって異なります。

無効なイベントタイプが指定された場合、BadValue プロトコルエラーが発生します。

event_type

XKB イベントタイプ

bits_to_change

指定したイベントの詳細な条件のマスク。ON の場合、設定が変更される。

values_for_bits

詳細な条件を選択するか解除するかのマスク。
対応するビットが ON で選択、OFF で解除。

修飾子・グループ

Bool XkbLockModifiers(Display *display, unsigned int device_spec, unsigned int affect, unsigned int values);

修飾子のロックと、ロック解除をする。
XkbLockModifiers はサーバーからの応答を待ちません。

affect

対象とする修飾子のマスク。
ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask

values

ロックさせる修飾子のマスク。
affect が ON で values が OFF の修飾子は、ロックが解除される。

戻り値

リクエストが送信された場合は True を返し、そうでない場合は False を返します。

Bool XkbLatchModifiers(Display *display, unsigned int device_spec, unsigned int affect, unsigned int values);

修飾子のラッチとラッチ解除。
ラッチが ON の場合、次のキーのみ修飾子を適用し、その後解除する。

Bool XkbLockGroup(Display *display, unsigned int device_spec, unsigned int group);

指定されたグループをロックするリクエストをサーバーに送信し、応答を待ちません。

group

XkbGroup1Index (0), XkbGroup2Index, XkbGroup3Index, XkbGroup4Index

戻り値

リクエストが送信された場合は True を返し、そうでない場合は False を返します。

Bool XkbLatchGroup(Display *display, unsigned int device_spec, unsigned int group);

指定されたグループをラッチするリクエストをサーバーに送信し、応答を待ちません。

戻り値

リクエストが送信された場合は True を返し、そうでない場合は False を返します。

Status XkbGetState(Display *display, unsigned int device_spec, XkbStatePtr state_return);

typedef struct {
    unsigned char      group;             /* effective group index */
    unsigned char      base_group;        /* base group index */
    unsigned char      latched_group;     /* latched group index */
    unsigned char      locked_group;      /* locked group index */
    unsigned char      mods;              /* effective modifiers */
    unsigned char      base_mods;         /* base modifiers */
    unsigned char      latched_mods;      /* latched modifiers */
    unsigned char      locked_mods;       /* locked modifiers */
    unsigned char      compat_state;      /* effective group -> modifiers */
    unsigned char      grab_mods;         /* modifiers used for grabs */
    unsigned char      compat_grab_mods;
    unsigned char      lookup_mods;        /* mods used to lookup symbols */
    unsigned char      compat_lookup_mods; /* mods used for compatibility lookup */
    unsigned short     ptr_buttons;        /* ポインタボタン */
} XkbStateRec, *XkbStatePtr;

サーバーに現在のキーボードの状態を問い合わせ、応答を待ってから、state_return に結果をセットします。

すべてのグループ値は、[0..3] の範囲のグループインデックスとして表されます。
修飾子と互換性修飾子の state 値は、コア X11 修飾子マスクのビット単位の結合として表現されます。
ポインタボタンの状態は、コア X11 プロトコルと同様に報告されます。

Bool XkbVirtualModsToReal(XkbDescPtr xkb, unsigned int virtual_mask, unsigned int *mask_rtrn);

xkb によって定義されたキーボード記述に、仮想修飾子のバインディングが含まれている場合、それらのバインディングを使用して、virtual_mask で指定された仮想修飾子のセットに対応する実際の修飾子のセットを決定します。

※X サーバーの対応する定義には仮想修飾子情報が含まれている可能性がありますが、ローカル (クライアント側) キーボード記述 (xkb パラメーター) には、仮想修飾子情報が含まれていない可能性があります (単にクライアントが要求していないため)。

virtual_mask

変換する仮想修飾子を指定するマスク。
マスクの i 番目のビットは、i 番目の仮想修飾子を表します。

mask_return

NULL 以外の場合、結果として得られる実際の修飾子マスクが返る。

戻り値

xkb のキーボード記述に仮想修飾子バインディングが含まれていない場合、False を返します。それ以外の場合は True を返します。

XkbDesc

XkbDescPtr XkbGetKeyboard(Display *display, unsigned int which, unsigned int device_spec);

XkbDescRec を確保して返す。
device_spec で指定されたキーボードのコンポーネントをサーバーに要求し、その結果を割り当てられた XkbDescRec にコピーします。
残りのフィールドは NULL に設定されます。

戻り値を解放するには、XkbFreeKeyboard を使用します。

which

必要なデータのマスク。
※All を指定しても、Controls は取得されません。

#define XkbClientMapMask        (1L << 0)
#define XkbServerMapMask        (1L << 1)
#define XkbCompatMapMask        (1L << 2)
#define XkbIndicatorMapMask     (1L << 3)
#define XkbNamesMask            (1L << 4)
#define XkbGeometryMask         (1L << 5)
#define XkbControlsMask         (1L << 6)
#define XkbAllComponentsMask    (0x7f)

device_spec

キーボードデバイスの ID、または XkbUseCoreKbd

XkbDescRec *XkbAllocKeyboard(void);

XkbDescRec を確保。

キーボードの説明の割り当てに失敗した場合は、NULL を返します。それ以外の場合は、空のキーボード記述構造体へのポインタを返します。
device_spec フィールドは XkbUseCoreKbd に初期化されています。
次に、構造コンポーネントを入力するか、Xkb 関数を使用してキーボードデバイスから構造コンポーネントの値を取得します。

アプリケーションがキーボード記述を直接割り当てる必要はほとんどありません。通常は XkbGetKeyboard を呼び出すだけで十分です。
ただし、キーボード記述を最初から作成する必要がある場合は、malloc または Xmalloc を直接呼び出すのではなく、XkbAllocKeyboard を使用します。

void XkbFreeKeyboard(XkbDescPtr xkb, unsigned int which, Bool free_all);

XkbDescRec 全体またはそのメンバーの一部だけを破棄する。
which で指定されたコンポーネントを解放し、対応する値を NULL に設定します。

which

解放したいコンポーネントのマスク

free_all

True の場合、NULL でないすべてのコンポーネントを解放し、xkb 自体を解放する。

キー変換

KeySym XkbKeycodeToKeysym(Display *dpy, KeyCode kc, unsigned int group, unsigned int level);

コアキーボードの特定のキーの、特定のグループとシフトレベルにバインドされた KeySym を返します。
kc がコアキーボードの有効なキーコードでない場合、またはグループやレベルが指定されたキーの範囲外である場合、NoSymbol を返します。

unsigned int XkbKeysymToModifiers(Display *dpy, KeySym ks);

コアキーボードの KeySym に現在バインドされている修飾子のセットを検索します。
返される値は、ks にバインドされた修飾子のマスクです。
修飾子が KeySym にバインドされていない場合、ゼロを返します。
それ以外の場合は、ShiftMask、ControlMask、LockMask、Mod1Mask 〜 Mod5Mask の 0 個以上の OR を返します。

Bool XkbLookupKeySym(Display *dpy, KeyCode key, unsigned int state, unsigned int *mods_rtrn, KeySym *sym_rtrn);

キーコードから KeySym を検索

state

修飾子の状態 (KeyPress/KeyRelease イベントから)

mods_rtrn

消費された修飾子が返る

sym_rtrn

KeySym が返る

戻り値

True で成功

int XkbLookupKeyBinding(Display *dpy, KeySym sym, unsigned int state, char *buf, int nbytes, int *extra_rtrn);

XLookupString と同等です。KeySym にバインドされた文字列を検索します。
※XRebindKeysym は、ASCII 文字列を、指定された KeySym にバインドします。これにより、キーと指定された修飾子が押されたときに、文字列と KeySym が返されます。

buf

関連付けられた文字列が返る。オーバーフローがない限り NULL で終了する。

nbytes

バッファのバイト数

extra_rtrn

返された文字列が nbytes より大きい場合、バッファに収まらないバイト数が extra_rtrn に返されます。

戻り値

buf にセットされたバイト数を返します。

int XkbTranslateKeySym(Display *dpy, KeySym *sym_inout, unsigned int mods, char *buf, int nbytes, int *extra_rtrn);

KeySym に修飾子を適用したものを返し、文字列があればそれも返す。

sym_inout

元の KeySym をセットする。mods によって変換された KeySym が返る。

mods

適用する修飾子

buf

現在のロケールで、KeySym に関連付けられている文字列があれば返す。

nbytes

バッファのバイト数

extra_rtrn

返された文字列が nbytes より大きい場合、バッファに収まらないバイト数が extra_rtrn に返されます。

戻り値

buf にセットされたバイト数を返します。

Bool XkbTranslateKeyCode(XkbDescPtr xkb, KeyCode key, unsigned int mods, unsigned int *mods_rtrn, KeySym *keysym_rtrn);

XkbDescRec 構造体の情報を元に、キーコードと修飾子から KeySym に変換する。
AlwaysConsumeShiftAndLock ライブラリコントロールが有効になっている場合、Shift と Lock を消費します。

mods

修飾子

mods_rtrn

消費された修飾子が返る

keysym_rtrn

変換された KeySym が返る。

戻り値

NoSymbol となった場合は False を返し、それ以外は True を返す。

ベル

Bool XkbDeviceBell(Display *display, Window window, unsigned int device_spec,
    unsigned int bell_class, unsigned int bell_id, int percent, Atom name);

キーボードベルを鳴らします。
AudibleBell を無効にしている場合、サーバーは XkbBellNotify イベントを生成しますが、システムベルを鳴らしません。

window

ベルが生成されるウィンドウ、または None

bell_class

鳴らす XInput 拡張機能のベルクラス

bell_id

鳴らす XInput 拡張機能のベル ID

percent

ベル音量 (基本音量に対する相対的な音量)。-100 〜 100

name

ベルの名前または NULL

戻り値

互換性のあるキーボード拡張機能が X サーバーに存在しない場合、すぐに False を返します。
それ以外の場合、ディスプレイおよびキーボードデバイスに指定されたとおりにベルを鳴らし、True を返します。

Bool XkbBell(Display *display, Window window, int percent, Atom name);

互換性のあるキーボード拡張機能が X サーバーに存在しない場合、指定された display と percent で XBell を呼び出し、False を返します。
それ以外の場合、指定されたディスプレイ、ウィンドウ、パーセント、および名前、XkbUseCoreKbd の device_spec、XkbDfltXIClass の bell_class、および XkbDfltXIId の bell_id を使用して、XkbDeviceBell を呼び出し、True を返します。

Bool XkbDeviceBellEvent(Display *display, Window window, unsigned int device_spec,
    unsigned int bell_class, unsigned int bell_id, int percent, Atom name);

対応するベルを鳴らさずに、XInput 拡張デバイスまたはキーボードのベルイベントを発生させます。

Xkb を使用すると、ベルを鳴らさない名前付きベルイベントを生成することもできます。
これにより、アプリケーションの起動時にイベントを生成するなどの作業が可能になります。

たとえば、オーディオクライアントがこれらの種類のベルをリッスンしている場合、名前付きベルイベントを受信すると、クライアントが開始されたばかりであることを示す「ヒュー」という音を生成できます。
このようにして、アプリケーションは起動フィードバックを生成できるため、オーディオサーバーが実行されていない場合に、迷惑なビープ音の発生を心配する必要がなくなります。

Bool XkbBellEvent(Display *display, Window window, int percent, Atom name);

指定されたディスプレイ、ウィンドウ、パーセント、および名前、XkbUseCoreKbd の device_spec、XkbDfltXIClass の bell_class、および XkbDfltXIId の bell_id を使用して、XkbDeviceBellEvent を呼び出し、XkbDeviceBellEvent が返すものを返します。

Bool XkbForceDeviceBell(Display *display, Window window, unsigned int device_spec,
    unsigned int bell_class, unsigned int bell_id, int percent);

AudibleBell のユーザー設定を無視して、強制的にベルを鳴らします。
XkbForceDeviceBell は XkbBellNotify イベントを引き起こさないため、name パラメーターはありません。

Bool XkbForceBell(Display *display, int percent);

デフォルトキーボードで強制的にベルを鳴らす