summaryrefslogtreecommitdiff
path: root/specs/ch15.xml
blob: d3e47d0f75742dc6de6a0c47e578345391e488cc (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
<chapter id='Interactions_Between_XKB_and_the_X_Input_Extension'>
<title>Interactions Between XKB and the X Input Extension</title>

<para>
All XKB interactions with the input extension are optional; implementors are
free to restrict the effects of the X Keyboard Extension to the core keyboard
device. The <emphasis>
XkbGetExtensionDeviceInfo</emphasis>
 request reports whether or not an XKB implementation supports a particular
capability for input extension devices.
</para>


<para>
XKB recognizes the following interactions with the X Input Extension:
</para>

<informaltable frame='topbot'>
<?dbfo keep-together="always" ?>
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
<colspec colname='c1' colwidth='1.0*'/>
<colspec colname='c2' colwidth='3.0*'/>
<thead>
  <row rowsep='1'>
    <entry>Name</entry>
    <entry>Capability</entry>
  </row>
</thead>
<tbody>
  <row>
    <entry>XI_Keyboards</entry>
    <entry>If set, applications can use all XKB requests and events with
extension keyboards.</entry>
  </row>
  <row>
    <entry>XI_ButtonActions</entry>
    <entry>If set, clients can assign key actions to buttons, even on input
extension devices that are not keyboards.</entry>
  </row>
  <row>
    <entry>XI_IndicatorNames</entry>
    <entry>If set, clients can assign names to indicators on non-keyboard
extension devices.</entry>
  </row>
  <row>
    <entry>XI_IndicatorMaps</entry>
    <entry>If set, clients can assign indicator maps to indicators on
non-keyboard extension devices. </entry>
  </row>
  <row>
    <entry>XI_IndicatorState</entry>
    <entry>If set, clients can change the state of device indicators using the
<emphasis>
XkbSetExtensionDeviceInfo</emphasis>
 request.</entry>
  </row>
</tbody>
</tgroup>
</informaltable>

<para>
Attempts to use an XKB feature with an extension device fail with a <emphasis>
Keyboard</emphasis>
 error if the server does not support the <emphasis>
XkbXI_Keyboards</emphasis>
 optional feature. If a capability particular capability other than <emphasis>
XkbXI_Keyboards</emphasis>
 is not supported, attempts to use it fail silently. The replies for most
requests that can use one of the other optional features include a field to
report whether or not the request was successful, but such requests do not
cause an error condition.
</para>


<para>
Clients can also request an <emphasis>
XkbExtensionDeviceNotify</emphasis>
 event. This event notifies interested clients of changes to any of the
supported XKB features for extension devices, or if a request from the client
that is receiving the event attempted to use an unsupported feature.
</para>

<sect1 id='Using_XKB_Functions_with_Input_Extension_Keyboards'>
<title>Using XKB Functions with Input Extension Keyboards</title>

<para>
All XKB requests and events include a device identifier which can refer to an
input extension <emphasis>
KeyClass</emphasis>
 device, if the implementation allows XKB to control extension devices. If the
implementation does not support XKB manipulation of extension devices, the
device identifier is ignored but it must be either <emphasis>
0</emphasis>
 or <emphasis>
UseCoreKbd</emphasis>
.
</para>


<para>
Implementations which do not support the use of XKB functions with extension
keyboards must not set the <emphasis>
XkbXI_Keyboards</emphasis>
 flag. Attempts to use XKB features on an extension keyboard with an
implementation that does not support this feature yield a <emphasis>
Keyboard</emphasis>
 error.
</para>


</sect1>
<sect1 id='Pointer_and_Device_Button_Actions'>
<title>Pointer and Device Button Actions</title>

<para>
The XKB extension optionally allows clients to assign any key action (see
<link linkend='Key_Actions'>Key Actions</link>) to core
pointer or input extension device buttons. This makes it possible to control
the keyboard or generate keyboard key events from extension devices or from the
core pointer.
</para>


<para>
XKB implementations are required to support actions for the buttons of the core
pointer device, but support for actions on extension devices is optional.
Implementations which do not support button actions for extension devices must
not set the <emphasis>
XkbXI_ButtonActions</emphasis>
 flag.
</para>


<para>
Attempts to query or assign button actions with an implementation that does not
support this feature report failure in the request reply and might cause the
server to send an <emphasis>
XkbExtensionDeviceNotify</emphasis>
 event to the client which issued the request that failed. Such requests never
cause an error condition.
</para>


</sect1>
<sect1 id='Indicator_Maps_for_Extension_Devices'>
<title>Indicator Maps for Extension Devices</title>

<para>
The XKB extension allows applications to assign indicator maps to the
indicators of non-keyboard extension devices. If supported, maps can be
assigned to all extension device indicators, whether they are part of a
keyboard feedback or part of an indicator feedback.
</para>


<para>
Implementations which do not support indicator maps for extension devices must
not set the <emphasis>
XkbXI_IndicatorMaps</emphasis>
 flag.
</para>


<para>
Attempts to query or assign indicator maps with an implementation that does not
support this feature report failure in the request reply and might cause the
server to send an <emphasis>
XkbExtensionDeviceNotify</emphasis>
 event to the client which issued the request that failed. Such requests never
cause an error condition.
</para>


<para>
If this feature is supported, the maps for the default indicators on the core
keyboard device are visible both as extension indicators and as the core
indicators. Changes made with <emphasis>
XkbSetDeviceInfo</emphasis>
 are visible via <emphasis>
XkbGetIndicatorMap</emphasis>
 and changes made with <emphasis>
XkbSetIndicatorMap</emphasis>
 are visible via <emphasis>
XkbGetDeviceInfo</emphasis>
.
</para>


</sect1>
<sect1 id='Indicator_Names_for_Extension_Devices'>
<title>Indicator Names for Extension Devices</title>

<para>
The XKB extension allows applications to assign symbolic names to the
indicators of non-keyboard extension devices. If supported, symbolic names can
be assigned to all extension device indicators, whether they are part of a
keyboard feedback or part of an indicator feedback.
</para>


<para>
Implementations which do not support indicator maps for extension devices must
not set the <emphasis>
XkbXI_IndicatorMaps</emphasis>
 flag.
</para>


<para>
Attempts to query or assign indicator names with an implementation that does
not support this feature report failure in the request reply and might cause
the server to send an <emphasis>
XkbExtensionDeviceNotify</emphasis>
 event to the client which issued the request that failed. Such requests never
cause an error condition.
</para>


<para>
If this feature is supported, the names for the default indicators on the core
keyboard device are visible both as extension indicators and as the core
indicators. Changes made with <emphasis>
XkbSetDeviceInfo</emphasis>
 are visible via <emphasis>
XkbGetNames</emphasis>
 and changes made with <emphasis>
XkbSetNames</emphasis>
 are visible via <emphasis>
XkbGetDeviceInfo</emphasis>
.
</para>
</sect1>
</chapter>