XKB: インディケータ

定義
struct XkbIndicatorRec	インディケータ
struct XkbIndicatorMapRec	インディケータのマップ
struct XkbIndicatorChangesRec	インディケータの変更情報
関数
XkbGetIndicatorState	インディケータの状態を取得
XkbGetIndicatorMap	インディケータマップを取得
XkbGetNamedDeviceIndicator	インディケータの名前から情報を取得
XkbGetNamedIndicator	デフォルトのデバイスで、インディケータの名前から情報を取得
XkbSetIndicatorMap	一つ以上のインディケータマップを変更
XkbSetNamedDeviceIndicator	インディケータ名を指定して、インディケータマップを変更
XkbSetNamedIndicator	デフォルトのデバイスでインディケータマップを変更
XkbChangeIndicators	XkbDescRec から、変更するインディケータのみの情報をセット
XkbNoteIndicatorChanges	インディケータ状態変化イベントによる変更の情報を取得
XkbGetIndicatorChanges	インディケータの変更データから XkbDescRec を取得
XkbAllocIndicatorMaps	インディケータマップを確保
XkbFreeIndicatorMaps	インディケータマップを解放

定義

typedef struct {
    unsigned long        phys_indicators; //LED の有無
    XkbIndicatorMapRec   maps[XkbNumIndicators]; //マップ
} XkbIndicatorRec, *XkbIndicatorPtr;

#define XkbNumIndicators 32

この構造体には、インジケーターと、キーボード上の物理 LED 間の対応関係に関する情報と、インジケーターごとに 1 つのマップを含むインジケーターマップの配列を関連付ける phys_indicators フィールドが含まれています。

各インジケーターには、クライアントがその状態を明示的に設定できるかどうか、およびキーボードの状態を追跡するかどうかを指定する独自の属性セットがあります。
各インジケーターの属性は、XkbIndicatorRec 構造体の配列であるマップ配列に保持されます。

phys_indicators

どのインジケーターがキーボード上の物理 LED にバインドされているかを示します。
ビットが phys_indicators に設定されている場合、関連するインジケーターには物理 LED が関連付けられています。
一部のインジケーターには、対応する物理 LED がキーボード上にない場合があるため、このフィールドは必要です。
たとえば、ほとんどのキーボードには、CapsLock の状態を示す LED がありますが、ほとんどのキーボードには現在のグループを示す LED がありません。

phys_indicators はキーボードの物理的特性を記述するため、プログラムの制御下で直接変更することはできません。
ただし、クライアントプログラムが XkbGetKeyboardByName を介して、まったく新しいキーボード記述をロードした場合、または、新しいキーボードが接続されて X 実装がそれを認識した場合、新しいキーボードのインジケーターが異なると、phys_indicators が変更されます。

typedef struct {
    unsigned char  flags;
    unsigned char  which_groups;  /* グループの一致基準 */
    unsigned char  groups;        /* インジケーターが監視するキーボード グループ */
    unsigned char  which_mods;    /* 修飾子の一致基準 */
    XkbModsRec     mods;          /* インジケーターが監視する修飾子 */
    unsigned int   ctrls;         /* インジケーターが監視するコントロール */
} XkbIndicatorMapRec, *XkbIndicatorMapPtr;

このインジケーターマップは、各インジケーターに対して次のことを指定します。

キーボード修飾子の状態がインジケーターに影響を与える条件
キーボードのグループの状態がインジケーターに影響を与える条件
ブール制御器の状態がインジケーターに影響を与える条件
関数 XkbSetControls または XChangeKeyboardControl を使用して、インジケーターの状態を明示的に変更しようとする試みの効果 (ある場合)

flags 以外のフィールドは、Xkb がインジケーターを自動的にオンまたはオフにする条件を指定します (XkbIM_NoAutomatic が設定されていない場合のみ)。
これらの条件がキーボードの状態と一致すると、Xkb はインジケーターをオンにします。条件が一致しない場合、Xkb はインジケーターをオフにします。

which_groups および groups フィールドは、キーボードグループの状態が、対応するインジケーターにどのような影響を与えるかを決定します。

flags

インジケーターを変更できる条件と、インジケーターの変更による影響を指定します。

XkbIM_NoExplicit	(1L<<7)	クライアントアプリケーションはインジケーターの状態を変更できません
XkbIM_NoAutomatic	(1L<<6)	Xkb は、インジケーターマップの他のフィールドの値に関係なく、キーボードの状態の変化に基づいてインジケーターの値を自動的に変更しません
XkbIM_LEDDrivesKB	(1L<<5)	クライアントアプリケーションがインジケーターの状態を変更すると、キーボードの状態も変化します

XkbIM_NoAutomatic が設定されていない場合、デフォルトでインジケーターはキーボードの状態に従います。

XkbIM_LEDDrivesKB が設定され、XkbIM_NoExplicit が設定されていない場合、およびインジケーターマップのサーバーのイメージを更新する関数 (XkbSetIndicatorMap や XkbSetNamedDeviceIndicator など) を呼び出すと、Xkb はキーボードの状態とコントロールを変更して、インジケーターマップの他のフィールドを反映します。
XkbIM_LEDDrivesKB が存在しない、または XkbIM_NoExplicit が存在するインジケーターの値を明示的に変更しようとしても、キーボードの状態やコントロールは影響を受けません。

たとえば、キーボード設計者は、CapsLock LED をサーバーのみで制御できるようにし、Scroll Lock LED はクライアントアプリケーションで制御できるようにしたい場合があります。
これを行うには、キーボード設計者は CapsLock LED に XkbIM_NoExplicit フラグを設定できますが、Scroll Lock LED には設定できません。
あるいは、キーボード設計者は、サーバーアプリケーションとクライアントアプリケーションの両方で CapsLock LED を制御できるようにし、クライアントアプリケーションが CapsLock LED を変更するたびに、サーバーが CapsLock 修飾子の状態を自動的に変更できるようにしたい場合もあります。
これを行うには、キーボード設計者は XkbIM_NoExplicit フラグを設定せず、代わりに XkbIM_LEDDrivesKB フラグを設定します。

which_groups

グループの解釈。

#define XkbIM_UseNone        0
#define XkbIM_UseBase        (1L << 0)
#define XkbIM_UseLatched     (1L << 1)
#define XkbIM_UseLocked      (1L << 2)
#define XkbIM_UseEffective   (1L << 3)
#define XkbIM_UseAnyGroup    XkbIM_UseLatched | XkbIM_UseLocked | XkbIM_UseEffective

■ XkbIM_NoAutomatic がセットされていない場合

XkbIM_UseNone	groups フィールドと現在のキーボードグループの状態は無視されます。
XkbIM_UseBase	groups が 0 以外の場合、ベースキーボードグループがゼロ以外の場合は常にインジケーターが点灯します。 groups が 0 の場合、ベースキーボードグループが 0 になるたびにインジケーターが点灯します。
XkbIM_UseLatched	groups が 0 以外の場合、latched キーボードグループが 0 以外の場合は常にインジケーターが点灯します。 groups が 0 の場合、latched キーボードグループが 0 になるたびにインジケーターが点灯します。
XkbIM_UseLocked	groups フィールドはマスクとして解釈されます。現在ロックされているキーボードグループが、groups に設定されているビットの 1 つと一致すると、インジケーターが点灯します。
XkbIM_UseEffective	groups フィールドはマスクとして解釈されます。現在の Effective キーボードグループが、groups に設定されているビットの 1 つと一致すると、インジケーターが点灯します。

■ XkbIM_LEDDrivesKB がセットされている場合

-	変化した状態	キーボードグループの状態への影響
XkbIM_UseNone	On or Off	なし
XkbIM_UseBase	On or Off	なし
XkbIM_UseLatched	On	groups フィールドはグループマスクとして扱われます。キーボードグループ Latched は、groups で指定された最も小さい番号のグループに変更されます。グループが空の場合、キーボードグループ Latched はゼロに変更されます。
XkbIM_UseLatched	Off	groups フィールドはグループマスクとして扱われます。インジケーターが明示的に消灯されている場合、キーボードグループ Latched は、groups 内で指定されていない最も小さい番号のグループに変更されます。 groups が 0 の場合、キーボードグループ Latched は、最も高い正当なキーボードグループのインデックスに設定されます。
XkbIM_UseLocked XkbIM_UseEffective	On	groups マスクが空の場合、グループは変更されません。それ以外の場合、Locked キーボードグループは、groups 内で指定された最も小さい番号のグループに変更されます。
XkbIM_UseEffective XkbIM_UseEffective	Off	Locked キーボードグループは、groups マスクで指定されていない最も小さい番号のグループに変更されるか、groups マスクにすべてのキーボードグループが含まれている場合は、Group1 に変更されます。

grouos

インジケーターが監視するキーボードグループ。

#define XkbGroup1Mask      (1<<0)
#define XkbGroup2Mask      (1<<1)
#define XkbGroup3Mask      (1<<2)
#define XkbGroup4Mask      (1<<3)
#define XkbAnyGroupMask    (1<<7)
#define XkbAllGroupsMask   (0xf)

mods

インジケーターが監視する修飾子を指定します。
mods で指定された仮想インジケーターの一部、またはすべてがバインドされていない場合でも有効です。
mods フィールドを指定するには、通常、対象の修飾子を mods.real_mods に割り当て、対象の仮想修飾子を mods.vmods に割り当てます。
アプリケーションがインジケーターマップを直接解釈する必要がない限り (つまり、自動インジケーターの動作を独自にシミュレートする必要がある場合)、mods.mask フィールドは無視できます。
これを行う必要があるアプリケーションは比較的少数ですが、必要があると判断した場合は、更新後にサーバーからインジケーターマップを読み取るか (修飾子定義で実修飾子または仮想修飾子のいずれかが変更されるたびに、サーバーが mask フィールドを自動的に更新します)、XkbDescRec に仮想修飾子定義が含まれていると仮定して、XkbVirtualModsToReal() を使用して mask フィールドの適切な内容を決定することができます。

which_mods

Xkb キーボード状態の 1 つ以上のコンポーネントを指定することによって、Xkb が対応する mods フィールドとの一致を決定するために使用する基準を指定します。
XkbIM_NoAutomatic が設定されていない場合 (キーボードがインジケーターを駆動する場合)、mods 修飾子定義の mask フィールドで指定された修飾子のいずれかが、which_mods で指定された現在のキーボード状態コンポーネントのいずれかにも設定されている場合は、常にインジケーターが点灯します。
mask フィールドは、定義で指定されたすべての実修飾子と、定義で指定された仮想修飾子にバインドされている実修飾子で構成されることに注意してください。

#define XkbIM_UseNone      0
#define XkbIM_UseBase      (1L << 0)
#define XkbIM_UseLatched   (1L << 1)
#define XkbIM_UseLocked    (1L << 2)
#define XkbIM_UseEffective (1L << 3)
#define XkbIM_UseCompat    (1L << 4)
#define XkbIM_UseAnyMods   XkbIM_UseBase | XkbIM_UseLatched |
    XkbIM_UseLocked | XkbIM_UseEffective | XkbIM_UseCompat

■ XkbIM_NoAutomatic がセットされていない場合

XkbIM_UseNone	mods フィールドと現在のキーボード修飾子の状態は無視されます。
XkbIM_UseBase	このインジケーターは、mods の mask フィールドで指定された修飾子のいずれかがキーボードのベース状態でオンになっているときに点灯します。 mods.real_mods と mods.vmods の両方が 0 の場合、ベースキーボード状態に修飾子が含まれていないときにインジケーターが点灯します。
XkbIM_UseLatched	mods の mask フィールドで指定された修飾子のいずれかがラッチされると、インジケーターが点灯します。 mods.real_mods と mods.vmods の両方が 0 の場合、どの修飾キーもラッチされていないときにインジケーターが点灯します。
XkbIM_UseLocked	mods の mask フィールドで指定された修飾子のいずれかがロックされている場合、インジケーターが点灯します。 mods.real_mods と mods.vmods の両方が 0 の場合、どの修飾キーもロックされていないときにインジケーターが点灯します。
XkbIM_UseEffective	このインジケーターは、mods の mask フィールドで指定された修飾子のいずれかが Effective キーボード状態にあるときに点灯します。 mods.real_mods と mods.vmods の両方が 0 の場合、Effective キーボード状態に修飾子が含まれていないときにインジケーターが点灯します。
XkbIM_UseCompat	このインジケーターは、mods の mask フィールドで指定された修飾子のいずれかがキーボード互換状態にある場合に点灯します。 mods.real_mods と mods.vmods の両方が 0 の場合、キーボードの互換性状態に修飾子が含まれていないときにインジケーターが点灯します。

■ XkbIM_LEDDrivesKB がセットされている場合

-	変化した状態	キーボードグループの状態への影響
XkbIM_UseNone XkbIM_UseBase	On or Off	なし
XkbIM_UseLatched	On	mods の mask フィールドで指定された修飾子はすべて、Latched 修飾子に追加されます。
XkbIM_UseLatched	Off	mods の mask フィールドで指定された修飾子は、Latched 修飾子から削除されます。
XkbIM_UseLocked XkbIM_UseCompat XkbIM_UseEffective	On	mods の mask フィールドで指定された修飾子はすべて、Locked 修飾子に追加されます。
XkbIM_UseLocked	Off	mods の mask フィールドで指定された修飾子は、Locked 修飾子から削除されます。
XkbIM_UseCompat XkbIM_UseEffective	Off	mods の mask フィールドで指定された修飾子は、Locked 修飾子と Latched 修飾子の両方から削除されます。

ctrl

インジケーターが監視する制御内容。
Xkb は、ctrl で指定されたブール制御のいずれかが有効になるたびにインジケーターを点灯します。

#define XkbRepeatKeysMask           (1L << 0)
#define XkbSlowKeysMask             (1L << 1)
#define XkbBounceKeysMask           (1L << 2)
#define XkbStickyKeysMask           (1L << 3)
#define XkbMouseKeysMask            (1L << 4)
#define XkbMouseKeysAccelMask       (1L << 5)
#define XkbAccessXKeysMask          (1L << 6)
#define XkbAccessXTimeoutMask       (1L << 7)
#define XkbAccessXFeedbackMask      (1L << 8)
#define XkbAudibleBellMask          (1L << 9)
#define XkbOverlay1Mask             (1L << 10)
#define XkbOverlay2Mask             (1L << 11)
#define XkbAllBooleanCtrlsMask      (0x00001FFF)

typedef struct _XkbIndicatorChanges {
    unsigned int state_changes;
    unsigned int map_changes;
} XkbIndicatorChangesRec,*XkbIndicatorChangesPtr;

インディケータの変更情報

state_changes

インディケータの状態を変更する場合、変更するインディケータのマスク。

map_changes

マップを変更するインディケータのマスク。

関数

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

device_spec で指定されたデバイス上のインジケーターの状態を取得します。
デバイス上で「オン」になっている各インジケーターについて、関連するビットが state_return に設定されます。

互換性のあるバージョンの Xkb 拡張機能がサーバーで利用できない場合、BadMatch エラーを返します。
それ以外の場合は、リクエストを X サーバーに送信し、インジケーターの状態を state_return に入れて、Success を返します。
したがって、XkbGetIndicatorState によって報告される値は、コアプロトコルによって報告される値と同じです。

Status XkbGetIndicatorMap(Display *dpy, unsigned int which, XkbDescPtr desc);

which マスクで指定されたインジケーターのみのマップをサーバーから取得し、その値を desc で指定されたキーボード記述にコピーします。
desc の indicators フィールドが NULL の場合、XkbGetIndicatorMap はそれを割り当てて初期化します。

BadAlloc、BadLength、BadMatch、BadImplementation エラーを生成する可能性があります。
インジケーターマップを解放するには、XkbFreeIndicatorMaps を使用します。

Bool XkbGetNamedDeviceIndicator(Display *dpy, unsigned int device_spec, unsigned int led_class, unsigned int led_id,
    Atom name, int *ndx_rtrn, Bool *state_rtrn, XkbIndicatorMapPtr map_rtrn, Bool *real_rtrn);

device_spec で指定され、led_class および led_id で指定されたフィードバックを持つデバイスに、name という名前のインジケーターがある場合、XkbGetNamedDeviceIndicator は True を返し、残りのパラメーターにインジケーターに関する情報を設定します。
それ以外の場合、XkbGetNamedDeviceIndicator は False を返します。

*_rtrn 引数はオプションです。NULL を渡すことができます。

led_class

クラス or XkbDfltXIClass

led_id

ID or XkbDfltXIId

name

インディケータの名前

ndx_rtrn

名前付きインジケーターの 0 から始まるインデックスを返します。
このインデックスは、インジケータービットのマスクを必要とする関数呼び出しで使用するビット位置、およびインジケーターマップの XkbIndicatorRec 配列へのインジケーターのインデックスです。

state_rtrn

名前付きインジケーターの現在の状態 (True = オン、False = オフ) を返します。

map_rtrn

指定されたインジケーターのインジケーターマップを返します。

real_rtrn

インジケーターが物理 LED にマップされている場合、True に設定されます。

Bool XkbGetNamedIndicator(Display *dpy, Atom name, int *ndx_rtrn, Bool *state_rtrn,
    XkbIndicatorMapPtr map_rtrn, Bool *real_rtrn);

device_spec = XkbUseCoreKbd、led_class = XkbDfltXIClass、led_id = XkbDfltXIId で XkbGetNamedDeviceIndicator を呼び出し、値を返す。

Bool XkbSetIndicatorMap(Display *dpy, unsigned int which, XkbDescPtr desc);

1 つ以上のインジケーターのマップを更新するには、まずキーボードの説明のローカルコピーを変更し、次に XkbSetIndicatorMap を使用して変更をサーバーにダウンロードします。

which

変更するインディケータのマスク

Bool XkbSetNamedDeviceIndicator(Display *dpy, unsigned int device_spec, unsigned int led_class, unsigned int led_id,
    Atom name, Bool change_state, Bool state, Bool create_new, XkbIndicatorMapPtr map);

互換性のあるバージョンの Xkb 拡張機能がサーバーで利用できない場合、XkbSetNamedDeviceIndicator は False を返します。
それ以外の場合は、名前で指定されたインジケーターを変更するリクエストを X サーバーに送信し、True を返します。

XkbIndicatorStateNotify、XkbIndicatorMapNotify、XkbNamesNotify イベントが生成される場合があります。

change_state

True の場合、サーバーに、名前付きインジケーターの状態を、state で指定された値に変更するように指示します。
False の場合、状態は使用されません。

state

設定するインディケータの状態

create_new

name で指定された名前のインジケーターがまだ存在しない場合、サーバーに新しい名前付きインジケーターを作成するかどうかを指示します。
True の場合、サーバーは名前のない最初のインジケーターを見つけて、name で指定された名前をそれに付けます。

map

NULL でない場合、サーバーにインジケーターのマップを map で指定された値に変更するように指示します。

Bool XkbSetNamedIndicator(Display *dpy, Atom name, Bool change_state, Bool state, Bool create_new, XkbIndicatorMapPtr map);

device_spec = XkbUseCoreKbd、led_class = XkbDfltXIClass、led_id = XkbDfltXIId で XkbSetNamedIndicator を呼び出す。

Bool XkbChangeIndicators(Display *dpy, XkbDescPtr xkb, XkbIndicatorChangesPtr changes, unsigned int state);

キーボード記述 xkb から、changes によって指定されたマップを、サーバーにコピーします。
XkbIndicatorStateNotify および XkbIndicatorMapNotify イベントが生成される場合があります。

changes

変更するインディケータの情報。

state

changes の state_changes のビットが設定されている場合、各インディケータの状態を変更する。
対応するビットが ON ならインディケータがオンになる。

void XkbNoteIndicatorChanges(XkbIndicatorChangesPtr old, XkbIndicatorNotifyEvent *new, unsigned int wanted);

インディケータ状態変化イベントによる変更の情報を取得。
new のイベントで報告され、want で指定されたすべての変更を、old にコピーします。

old

元の XkbIndicatorChanges 構造体。イベントによって更新されたインディケータの値が更新される。

new

イベント構造体

wanted

必要な値。XkbIndicatorMapMask と XkbIndicatorStateMask の OR

Status XkbGetIndicatorChanges(Display *dpy, XkbDescPtr xkb, XkbIndicatorChangesPtr changes, unsigned int *state);

キーボードの説明のローカルコピーを、実際の値で更新するには、XkbNoteIndicatorChanges への 1 つ以上の呼び出しの結果を XkbGetIndicatorChanges に渡します。

changes パラメータを調べ、サーバーから必要な情報を取得して、結果を xkb にコピーします。
changes の state_changes フィールドにビットが設定されている場合、それらのインジケーターの状態が state に設定されます。
xkb の indicators フィールドが NULL の場合、XkbGetIndicatorChanges はそれを割り当てて初期化します。
indicators フィールドを解放するには、XkbFreeIndicatorMaps を使用します。

Status XkbAllocIndicatorMaps(XkbDescPtr xkb);

インディケータマップを確保

戻り値

Success で成功、割り当てられなかった場合、BadAlloc エラー。

void XkbFreeIndicatorMaps(XkbDescPtr xkb);

xkb が指すキーボード記述レコードの indicators メンバーが NULL でない場合、関連付けられたメモリを解放します。