1<chapter id='Interactions_Between_XKB_and_the_X_Input_Extension'>
2<title>Interactions Between XKB and the X Input Extension</title>
3
4<para>
5All XKB interactions with the input extension are optional; implementors are
6free to restrict the effects of the X Keyboard Extension to the core keyboard
7device. The <emphasis>
8XkbGetExtensionDeviceInfo</emphasis>
9 request reports whether or not an XKB implementation supports a particular
10capability for input extension devices.
11</para>
12
13
14<para>
15XKB recognizes the following interactions with the X Input Extension:
16</para>
17
18<informaltable frame='topbot'>
19<?dbfo keep-together="always" ?>
20<tgroup cols='2' align='left' colsep='0' rowsep='0'>
21<colspec colname='c1' colwidth='1.0*'/>
22<colspec colname='c2' colwidth='3.0*'/>
23<thead>
24  <row rowsep='1'>
25    <entry>Name</entry>
26    <entry>Capability</entry>
27  </row>
28</thead>
29<tbody>
30  <row>
31    <entry>XI_Keyboards</entry>
32    <entry>If set, applications can use all XKB requests and events with
33extension keyboards.</entry>
34  </row>
35  <row>
36    <entry>XI_ButtonActions</entry>
37    <entry>If set, clients can assign key actions to buttons, even on input
38extension devices that are not keyboards.</entry>
39  </row>
40  <row>
41    <entry>XI_IndicatorNames</entry>
42    <entry>If set, clients can assign names to indicators on non-keyboard
43extension devices.</entry>
44  </row>
45  <row>
46    <entry>XI_IndicatorMaps</entry>
47    <entry>If set, clients can assign indicator maps to indicators on
48non-keyboard extension devices. </entry>
49  </row>
50  <row>
51    <entry>XI_IndicatorState</entry>
52    <entry>If set, clients can change the state of device indicators using the
53<emphasis>
54XkbSetExtensionDeviceInfo</emphasis>
55 request.</entry>
56  </row>
57</tbody>
58</tgroup>
59</informaltable>
60
61<para>
62Attempts to use an XKB feature with an extension device fail with a <emphasis>
63Keyboard</emphasis>
64 error if the server does not support the <emphasis>
65XkbXI_Keyboards</emphasis>
66 optional feature. If a capability particular capability other than <emphasis>
67XkbXI_Keyboards</emphasis>
68 is not supported, attempts to use it fail silently. The replies for most
69requests that can use one of the other optional features include a field to
70report whether or not the request was successful, but such requests do not
71cause an error condition.
72</para>
73
74
75<para>
76Clients can also request an <emphasis>
77XkbExtensionDeviceNotify</emphasis>
78 event. This event notifies interested clients of changes to any of the
79supported XKB features for extension devices, or if a request from the client
80that is receiving the event attempted to use an unsupported feature.
81</para>
82
83<sect1 id='Using_XKB_Functions_with_Input_Extension_Keyboards'>
84<title>Using XKB Functions with Input Extension Keyboards</title>
85
86<para>
87All XKB requests and events include a device identifier which can refer to an
88input extension <emphasis>
89KeyClass</emphasis>
90 device, if the implementation allows XKB to control extension devices. If the
91implementation does not support XKB manipulation of extension devices, the
92device identifier is ignored but it must be either <emphasis>
930</emphasis>
94 or <emphasis>
95UseCoreKbd</emphasis>
96.
97</para>
98
99
100<para>
101Implementations which do not support the use of XKB functions with extension
102keyboards must not set the <emphasis>
103XkbXI_Keyboards</emphasis>
104 flag. Attempts to use XKB features on an extension keyboard with an
105implementation that does not support this feature yield a <emphasis>
106Keyboard</emphasis>
107 error.
108</para>
109
110
111</sect1>
112<sect1 id='Pointer_and_Device_Button_Actions'>
113<title>Pointer and Device Button Actions</title>
114
115<para>
116The XKB extension optionally allows clients to assign any key action (see
117<link linkend='Key_Actions'>Key Actions</link>) to core
118pointer or input extension device buttons. This makes it possible to control
119the keyboard or generate keyboard key events from extension devices or from the
120core pointer.
121</para>
122
123
124<para>
125XKB implementations are required to support actions for the buttons of the core
126pointer device, but support for actions on extension devices is optional.
127Implementations which do not support button actions for extension devices must
128not set the <emphasis>
129XkbXI_ButtonActions</emphasis>
130 flag.
131</para>
132
133
134<para>
135Attempts to query or assign button actions with an implementation that does not
136support this feature report failure in the request reply and might cause the
137server to send an <emphasis>
138XkbExtensionDeviceNotify</emphasis>
139 event to the client which issued the request that failed. Such requests never
140cause an error condition.
141</para>
142
143
144</sect1>
145<sect1 id='Indicator_Maps_for_Extension_Devices'>
146<title>Indicator Maps for Extension Devices</title>
147
148<para>
149The XKB extension allows applications to assign indicator maps to the
150indicators of non-keyboard extension devices. If supported, maps can be
151assigned to all extension device indicators, whether they are part of a
152keyboard feedback or part of an indicator feedback.
153</para>
154
155
156<para>
157Implementations which do not support indicator maps for extension devices must
158not set the <emphasis>
159XkbXI_IndicatorMaps</emphasis>
160 flag.
161</para>
162
163
164<para>
165Attempts to query or assign indicator maps with an implementation that does not
166support this feature report failure in the request reply and might cause the
167server to send an <emphasis>
168XkbExtensionDeviceNotify</emphasis>
169 event to the client which issued the request that failed. Such requests never
170cause an error condition.
171</para>
172
173
174<para>
175If this feature is supported, the maps for the default indicators on the core
176keyboard device are visible both as extension indicators and as the core
177indicators. Changes made with <emphasis>
178XkbSetDeviceInfo</emphasis>
179 are visible via <emphasis>
180XkbGetIndicatorMap</emphasis>
181 and changes made with <emphasis>
182XkbSetIndicatorMap</emphasis>
183 are visible via <emphasis>
184XkbGetDeviceInfo</emphasis>
185.
186</para>
187
188
189</sect1>
190<sect1 id='Indicator_Names_for_Extension_Devices'>
191<title>Indicator Names for Extension Devices</title>
192
193<para>
194The XKB extension allows applications to assign symbolic names to the
195indicators of non-keyboard extension devices. If supported, symbolic names can
196be assigned to all extension device indicators, whether they are part of a
197keyboard feedback or part of an indicator feedback.
198</para>
199
200
201<para>
202Implementations which do not support indicator maps for extension devices must
203not set the <emphasis>
204XkbXI_IndicatorMaps</emphasis>
205 flag.
206</para>
207
208
209<para>
210Attempts to query or assign indicator names with an implementation that does
211not support this feature report failure in the request reply and might cause
212the server to send an <emphasis>
213XkbExtensionDeviceNotify</emphasis>
214 event to the client which issued the request that failed. Such requests never
215cause an error condition.
216</para>
217
218
219<para>
220If this feature is supported, the names for the default indicators on the core
221keyboard device are visible both as extension indicators and as the core
222indicators. Changes made with <emphasis>
223XkbSetDeviceInfo</emphasis>
224 are visible via <emphasis>
225XkbGetNames</emphasis>
226 and changes made with <emphasis>
227XkbSetNames</emphasis>
228 are visible via <emphasis>
229XkbGetDeviceInfo</emphasis>
230.
231</para>
232</sect1>
233</chapter>
234