diff options
Diffstat (limited to 'specs/ch15.xml')
| -rw-r--r-- | specs/ch15.xml | 232 |
1 files changed, 232 insertions, 0 deletions
diff --git a/specs/ch15.xml b/specs/ch15.xml new file mode 100644 index 0000000..fb9472f --- /dev/null +++ b/specs/ch15.xml @@ -0,0 +1,232 @@ +<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='none'> +<tgroup cols='2'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Name</entry> + <entry>Capability</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>XI_Keyboards</entry> + <entry>If set, applications can use all XKB requests and events with +extension keyboards.</entry> + </row> + <row rowsep='0'> + <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 rowsep='0'> + <entry>XI_IndicatorNames</entry> + <entry>If set, clients can assign names to indicators on non-keyboard +extension devices.</entry> + </row> + <row rowsep='0'> + <entry>XI_IndicatorMaps</entry> + <entry>If set, clients can assign indicator maps to indicators on +non-keyboard extension devices. </entry> + </row> + <row rowsep='0'> + <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 +<ulink url="XKBproto.htm#50332257_15763">See Key Actions</ulink>) 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> |