diff options
Diffstat (limited to 'libX11/specs/XKB/ch21.xml')
| -rw-r--r-- | libX11/specs/XKB/ch21.xml | 3076 |
1 files changed, 1545 insertions, 1531 deletions
diff --git a/libX11/specs/XKB/ch21.xml b/libX11/specs/XKB/ch21.xml index 7b2c653ba..7d122d92b 100644 --- a/libX11/specs/XKB/ch21.xml +++ b/libX11/specs/XKB/ch21.xml @@ -1,3 +1,6 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <chapter id='Attaching_Xkb_Actions_to_X_Input_Extension_Devices'> <title>Attaching Xkb Actions to X Input Extension Devices</title> @@ -10,8 +13,8 @@ input extension. Other types of devices supported by the input extension include, but are not limited to: mice, tablets, touchscreens, barcode readers, button boxes, trackballs, identifier devices, data gloves, and eye trackers. Xkb provides additional control over all X input extension devices, whether -they are <emphasis>KeyClass</emphasis> - devices or not, as well as the core keyboard and pointer. +they are <symbol>KeyClass</symbol> +devices or not, as well as the core keyboard and pointer. </para> @@ -58,16 +61,16 @@ the following additional access is provided: <itemizedlist> <listitem> <para> -If allowed, Xkb functionality for additional <emphasis> -KeyClass</emphasis> - devices supported by the input extension is accessed via those same functions. +If allowed, Xkb functionality for additional +<symbol>KeyClass</symbol> +devices supported by the input extension is accessed via those same functions. </para> </listitem> <listitem> <para> -If allowed, Xkb functionality for non-<emphasis> -KeyClass</emphasis> - devices supported by the input extension is also accessed via the +If allowed, Xkb functionality for non- +<symbol>KeyClass</symbol> +devices supported by the input extension is also accessed via the XkbGetDeviceInfo and XkbSetDeviceInfo functions described in this chapter. </para> </listitem> @@ -76,11 +79,11 @@ XkbGetDeviceInfo and XkbSetDeviceInfo functions described in this chapter. <para> Each device has an X Input Extension device ID. Each device may have several classes of feedback. For example, there are two types of feedbacks that can -generate bells: bell feedback and keyboard feedback (<emphasis> -BellFeedbackClass</emphasis> - and <emphasis> -KbdFeedbackClass</emphasis> -). A device can have more than one feedback of each type; the feedback ID +generate bells: bell feedback and keyboard feedback +(<symbol>BellFeedbackClass</symbol> +and +<symbol>KbdFeedbackClass</symbol>). +A device can have more than one feedback of each type; the feedback ID identifies the particular feedback within its class. </para> @@ -123,109 +126,107 @@ Up to 32 LEDs If the input extension is present and the server allows interaction between the input extension and Xkb, then the core keyboard, the core keyboard indicators, and the core keyboard bells may each be addressed using an appropriate device -spec, class, and ID. The constant <emphasis> -XkbXIDfltID</emphasis> - may be used as the device ID to specify the core keyboard indicators for the +spec, class, and ID. The constant +<symbol>XkbDfltXIId</symbol> +may be used as the device ID to specify the core keyboard indicators for the core indicator feedback. The particular device ID corresponding to the core keyboard feedback and the core indicator feedback may be obtained by calling -<emphasis> -XkbGetDeviceInfo</emphasis> - and specifying <emphasis> -XkbUseCoreKbd</emphasis> - as the <emphasis> -device_spec</emphasis> -; the values will be returned in <emphasis> -dflt_kbd_id</emphasis> - and <emphasis> -dflt_led_id</emphasis> -. -</para> - - -<para> -If the server does not allow Xkb access to input extension <emphasis> -KeyClass</emphasis> - devices, attempts to use Xkb requests with those devices fail with a -Bad<emphasis> -Keyboard</emphasis> - error. Attempts to access non-<emphasis> -KeyClass</emphasis> - input extension devices via XkbGetDeviceInfo and XkbSetDeviceInfo fail +<function>XkbGetDeviceInfo</function> +and specifying +<symbol>XkbUseCoreKbd</symbol> +as the +<parameter>device_spec</parameter>; +the values will be returned in +<structfield>dflt_kbd_fb</structfield> +and +<structfield>dflt_led_fb</structfield>. +</para> + + +<para> +If the server does not allow Xkb access to input extension +<symbol>KeyClass</symbol> +devices, attempts to use Xkb requests with those devices fail with a +<errorname>BadKeyboard</errorname> +error. Attempts to access non- +<symbol>KeyClass</symbol> +input extension devices via XkbGetDeviceInfo and XkbSetDeviceInfo fail silently if Xkb access to those devices is not supported by the X server. </para> <sect1 id='XkbDeviceInfoRec'> <title>XkbDeviceInfoRec</title> +<indexterm significance="preferred" zone="XkbDeviceInfoRec"> +<primary><structname>XkbDeviceInfoRec</structname></primary></indexterm> +<indexterm significance="preferred" zone="XkbDeviceInfoRec"> +<primary><structname>XkbDeviceLedInfoRec</structname></primary></indexterm> <para> Information about X Input Extension devices is transferred between a client -program and the Xkb extension in an <emphasis> -XkbDeviceInfoRec</emphasis> - structure: -</para> +program and the Xkb extension in an +<structname>XkbDeviceInfoRec</structname> +structure: -<para><programlisting> +<programlisting> typedef struct { - char * name; /* name for device */ - Atom type; /* name for class of devices */ - unsigned short device_spec; /* device of interest */ - Bool has_own_state; /* <emphasis> True</emphasis> =>this - device has its own state */ - unsigned short supported; /* bits indicating supported capabilities */ - unsigned short unsupported; /* bits indicating unsupported capabilities */ - unsigned short num_btns; /* number of entries in <emphasis> btn_acts</emphasis> */ - XkbAction * btn_acts; /* button actions */ - unsigned short sz_leds; /* total number of entries in LEDs vector */ - unsigned short num_leds; /* number of valid entries in LEDs vector */ - unsigned short dflt_kbd_fb; /* input extension ID of default (core kbd) indicator */ - unsigned short dflt_led_fb; /* input extension ID of default indicator feedback */ - XkbDeviceLedInfoPtr leds; /* LED descriptions */ -} <emphasis>XkbDeviceInfoRec</emphasis>, *XkbDeviceInfoPtr; -</programlisting></para> + char * name; /* name for device */ + Atom type; /* name for class of devices */ + unsigned short device_spec; /* device of interest */ + Bool has_own_state; /* <symbol>True</symbol> ⇒ this device has + its own state */ + unsigned short supported; /* bits indicating supported capabilities */ + unsigned short unsupported; /* bits indicating unsupported capabilities */ + unsigned short num_btns; /* number of entries in <structfield>btn_acts</structfield> */ + XkbAction * btn_acts; /* button actions */ + unsigned short sz_leds; /* total number of entries in LEDs vector */ + unsigned short num_leds; /* number of valid entries in LEDs vector */ + unsigned short dflt_kbd_fb; /* input extension ID of default + (core kbd) indicator */ + unsigned short dflt_led_fb; /* input extension ID of default + indicator feedback */ + XkbDeviceLedInfoPtr leds; /* LED descriptions */ +} <structname>XkbDeviceInfoRec</structname>, *XkbDeviceInfoPtr; -<para><programlisting> typedef struct { - unsigned short led_class; /* class for this LED device*/ - unsigned short led_id; /* ID for this LED device */ - unsigned int phys_indicators; /* bits for which LEDs physically - present */ - unsigned int maps_present; /* bits for which LEDs have maps in - <emphasis>maps</emphasis> */ - unsigned int names_present; /* bits for which LEDs are in - <emphasis> names</emphasis> */ - unsigned int state; /* 1 bit => corresponding LED is on */ - Atom names[XkbNumIndicators]; /* names for LEDs */ - XkbIndicatorMapRec maps; /* indicator maps for each LED */ -} <emphasis>XkbDeviceLedInfoRec</emphasis>, *XkbDeviceLedInfoPtr; + unsigned short led_class; /* class for this LED device */ + unsigned short led_id; /* ID for this LED device */ + unsigned int phys_indicators; /* bits for which LEDs physically present */ + unsigned int maps_present; /* bits for which LEDs have maps in <structfield>maps</structfield> */ + unsigned int names_present; /* bits for which LEDs are in <structfield>names</structfield> */ + unsigned int state; /* 1 bit ⇒ corresponding LED is on */ + Atom names[XkbNumIndicators]; /* names for LEDs */ + XkbIndicatorMapRec maps; /* indicator maps for each LED */ +} <structname>XkbDeviceLedInfoRec</structname>, *XkbDeviceLedInfoPtr; </programlisting></para> <para> -The <emphasis> -type</emphasis> - field is a registered symbolic name for a class of devices (for example, -"TABLET"). If a device is a keyboard (that is, is a member of <emphasis> -KeyClass</emphasis> -), it has its own state, and <emphasis> -has_own_state</emphasis> - is <emphasis> -True</emphasis> -. If <emphasis> -has_own_state</emphasis> - is <emphasis> -False</emphasis> -, the state of the core keyboard is used. The <emphasis> -supported</emphasis> - and <emphasis> -unsupported</emphasis> - fields are masks where each bit indicates a capability. The meaning of the -mask bits is listed in Table 21.1, together with the fields in the <emphasis> -XkbDeviceInfoRec</emphasis> - structure that are associated with the capability represented by each bit. The +The +<structfield>type</structfield> +field is a registered symbolic name for a class of devices (for example, +"TABLET"). If a device is a keyboard (that is, is a member of +<symbol>KeyClass</symbol>), +it has its own state, and +<structfield>has_own_state</structfield> +is +<symbol>True</symbol>. +If +<structfield>has_own_state</structfield> +is +<symbol>False</symbol>, +the state of the core keyboard is used. The +<structfield>supported</structfield> +and +<structfield>unsupported</structfield> +fields are masks where each bit indicates a capability. The meaning of the +mask bits is listed in <link linkend="table21.1">Table 21.1</link>, +together with the fields in the +<structname>XkbDeviceInfoRec</structname> +structure that are associated with the capability represented by each bit. The same bits are used to indicate the specific information desired in many of the functions described subsequently in this section. </para> -<table frame='topbot'> +<table id='table21.1' frame='topbot'> <title>XkbDeviceInfoRec Mask Bits</title> <?dbfo keep-together="always" ?> <tgroup cols='4' align='left' colsep='0' rowsep='0'> @@ -243,60 +244,60 @@ functions described subsequently in this section. </thead> <tbody> <row> - <entry>XkbXI_KeyboardsMask</entry> + <entry><symbol>XkbXI_KeyboardsMask</symbol></entry> <entry></entry> <entry>(1L << 0)</entry> <entry> Clients can use all Xkb requests and events with -<emphasis>KeyClass</emphasis> +<symbol>KeyClass</symbol> devices supported by the input device extension. </entry> </row> <row> - <entry>XkbXI_ButtonActionsMask</entry> + <entry><symbol>XkbXI_ButtonActionsMask</symbol></entry> <entry> <para>num_btns</para> <para>btn_acts</para> </entry> <entry>(1L <<1)</entry> <entry> -Clients can assign key actions to buttons on non-<emphasis> -KeyClass</emphasis> +Clients can assign key actions to buttons on non- +<symbol>KeyClass</symbol> input extension devices. </entry> </row> <row> - <entry>XkbXI_IndicatorNamesMask</entry> + <entry><symbol>XkbXI_IndicatorNamesMask</symbol></entry> <entry>leds->names</entry> <entry>(1L <<2)</entry> <entry> -Clients can assign names to indicators on non-<emphasis> -KeyClass</emphasis> - input extension devices. +Clients can assign names to indicators on non- +<symbol>KeyClass</symbol> +input extension devices. </entry> </row> <row> - <entry>XkbXI_IndicatorMapsMask</entry> + <entry><symbol>XkbXI_IndicatorMapsMask</symbol></entry> <entry>leds->maps</entry> <entry>(1L <<3)</entry> <entry> -Clients can assign indicator maps to indicators on non-<emphasis> -KeyClass</emphasis> - input extension devices. +Clients can assign indicator maps to indicators on non- +<symbol>KeyClass</symbol> +input extension devices. </entry> </row> <row> - <entry>XkbXI_IndicatorStateMask</entry> + <entry><symbol>XkbXI_IndicatorStateMask</symbol></entry> <entry>leds->state</entry> <entry>(1L <<4)</entry> <entry> -Clients can request the status of indicators on non-<emphasis> -KeyClass</emphasis> - input extension devices. +Clients can request the status of indicators on non- +<symbol>KeyClass</symbol> +input extension devices. </entry> </row> <row> - <entry>XkbXI_IndicatorsMask</entry> + <entry><symbol>XkbXI_IndicatorsMask</symbol></entry> <entry> <para>sz_leds</para> <para>num_leds</para> @@ -304,42 +305,42 @@ KeyClass</emphasis> </entry> <entry>(0x1c)</entry> <entry> -<para>XkbXI_IndicatorNames­Mask |</para> -<para>XkbXI_IndicatorMaps­Mask |</para> -<para>XkbXI_IndicatorState­Mask</para> +<para><symbol>XkbXI_IndicatorNames­Mask</symbol> |</para> +<para><symbol>XkbXI_IndicatorMaps­Mask</symbol> |</para> +<para><symbol>XkbXI_IndicatorState­Mask</symbol></para> </entry> </row> <row> - <entry>XkbXI_UnsupportedFeaturesMask</entry> + <entry><symbol>XkbXI_UnsupportedFeaturesMask</symbol></entry> <entry>unsupported</entry> <entry>(1L <<15)</entry> <entry></entry> </row> <row> - <entry>XkbXI_AllDeviceFeaturesMask</entry> + <entry><symbol>XkbXI_AllDeviceFeaturesMask</symbol></entry> <entry>Those selected by Value column masks</entry> <entry>(0x1e)</entry> <entry> -<para>XkbXI_Indicators­Mask | </para> -<para>XkbSI_ButtonActions­Mask</para> +<para><symbol>XkbXI_Indicators­Mask</symbol> | </para> +<para><symbol>XkbXI_ButtonActions­Mask</symbol> </para> </entry> </row> <row> - <entry>XkbXI_AllFeaturesMask</entry> + <entry><symbol>XkbXI_AllFeaturesMask</symbol></entry> <entry>Those selected by Value column masks</entry> <entry>(0x1f)</entry> <entry> -<para>XkbSI_AllDevice­FeaturesMask |</para> -<para>XkbSI_Keyboards­Mask</para> +<para><symbol>XkbXI_AllDevice­FeaturesMask</symbol> | </para> +<para><symbol>XkbXI_Keyboards­Mask</symbol> </para> </entry> </row> <row> - <entry>XkbXI_AllDetailsMask</entry> + <entry><symbol>XkbXI_AllDetailsMask</symbol></entry> <entry>Those selected by Value column masks</entry> <entry>(0x801f)</entry> <entry> -<para>XkbXI_AllFeatures­Mask | </para> -<para>XkbXI_Unsupported­FeaturesMask</para> +<para><symbol>XkbXI_AllFeatures­Mask</symbol> | </para> +<para><symbol>XkbXI_Unsupported­FeaturesMask</symbol></para> </entry> </row> </tbody> @@ -347,20 +348,17 @@ KeyClass</emphasis> </table> <para> -The <emphasis> -name</emphasis> -, <emphasis> -type</emphasis> -, <emphasis> -has_own_state</emphasis> -, <emphasis> -supported</emphasis> -, and <emphasis> -unsupported</emphasis> - fields are always filled in when a valid reply is returned from the server -involving an <emphasis> -XkbDeviceInfoRec</emphasis> -. All of the other fields are modified only if the particular function asks for +The +<structfield>name</structfield>, +<structfield>type</structfield>, +<structfield>has_own_state</structfield>, +<structfield>supported</structfield>, +and +<structfield>unsupported</structfield> +fields are always filled in when a valid reply is returned from the server +involving an +<structname>XkbDeviceInfoRec</structname>. +All of the other fields are modified only if the particular function asks for them. </para> @@ -371,235 +369,242 @@ them. <para> To determine whether the X server allows Xkb access to particular capabilities of input devices other than the core X keyboard, or to determine the status of -indicator maps, indicator names or button actions on a non-<emphasis> -KeyClass</emphasis> - extension device, use XkbGetDeviceInfo. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbDeviceInfoPtr <emphasis> -XkbGetDeviceInfo</emphasis> -(<emphasis> -dpy</emphasis> -, which, device_spec, ind_class, ind_id) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int which; /* mask indicating information to -return */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -ind_class</emphasis> -; /* feedback class for indicator requests */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -ind_id</emphasis> -; /* feedback ID for indicator requests */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetDeviceInfo</emphasis> - returns information about the input device specified by <emphasis> -device_spec</emphasis> -. Unlike the <emphasis> -device_spec</emphasis> - parameter of most Xkb functions, <emphasis> -device_spec</emphasis> - does not need to be a keyboard device. It must, however, indicate either the +indicator maps, indicator names or button actions on a non- +<symbol>KeyClass</symbol> +extension device, use XkbGetDeviceInfo. +</para> + +<indexterm significance="preferred" zone="XkbGetDeviceInfo"><primary><function>XkbGetDeviceInfo</function></primary></indexterm> +<funcsynopsis id="XkbGetDeviceInfo"> + <funcprototype> + <funcdef>XkbDeviceInfoPtr <function>XkbGetDeviceInfo</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +which, device_spec, ind_class, ind_id) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int <parameter>ind_class</parameter></paramdef> + <paramdef>unsigned int <parameter>ind_id</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask indicating information to return + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>ind_class</parameter> + </term> + <listitem> + <para> + feedback class for indicator requests + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>ind_id</parameter> + </term> + <listitem> + <para> + feedback ID for indicator requests + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetDeviceInfo</function> +returns information about the input device specified by +<parameter>device_spec</parameter>. +Unlike the +<parameter>device_spec</parameter> +parameter of most Xkb functions, +<parameter>device_spec</parameter> +does not need to be a keyboard device. It must, however, indicate either the core keyboard or a valid X Input Extension device. </para> <para> -The <emphasis> -which </emphasis> -parameter<emphasis> - </emphasis> +The +<parameter>which</parameter> +parameter is a mask specifying optional information to be returned. It is an inclusive OR -of one or more of the values from Table 21.1 and causes the returned <emphasis> -XkbDeviceInfoRec</emphasis> - to contain values for the corresponding fields specified in the table. +of one or more of the values from <link linkend="table21.1">Table 21.1</link> +and causes the returned +<structname>XkbDeviceInfoRec</structname> +to contain values for the corresponding fields specified in the table. </para> <para> -The <emphasis> -XkbDeviceInfoRec</emphasis> - returned by <emphasis> -XkbGetDeviceInfo</emphasis> - always has values for <emphasis> -name</emphasis> - (may be a null string, ""), <emphasis> -type</emphasis> -, <emphasis> -supported</emphasis> -, <emphasis> -unsupported</emphasis> -, <emphasis> -has_own_state</emphasis> -, <emphasis> -dflt_kbd_fd</emphasis> -, and <emphasis> -dflt_kbd_fb</emphasis> -. Other fields are filled in as specified by <emphasis> -which</emphasis> -. +The +<structname>XkbDeviceInfoRec</structname> +returned by +<function>XkbGetDeviceInfo</function> +always has values for +<structfield>name</structfield> +(may be a null string, ""), +<structfield>type</structfield>, +<structfield>supported</structfield>, +<structfield>unsupported</structfield>, +<structfield>has_own_state</structfield>, +<structfield>dflt_kbd_fb</structfield>, +and +<structfield>dflt_led_fb</structfield>. +Other fields are filled in as specified by +<parameter>which</parameter>. </para> <para> -Upon return, the <emphasis> -supported</emphasis> - field will be set to the inclusive OR of zero or more bits from Table 21.1; +Upon return, the +<structfield>supported</structfield> +field will be set to the inclusive OR of zero or more bits from +<link linkend="table21.1">Table 21.1</link>; each bit set indicates an optional Xkb extension device feature supported by the server implementation, and a client may modify the associated behavior. </para> <para> -If the <emphasis> -XkbButtonActionsMask</emphasis> - bit is set in <emphasis> -which</emphasis> -, the <emphasis> -XkbDeviceInfoRec</emphasis> - returned will have the button actions (<emphasis> -btn_acts</emphasis> - field) filled in for all buttons. +If the +<symbol>XkbXI_ButtonActionsMask</symbol> +bit is set in +<parameter>which</parameter>, +the +<structname>XkbDeviceInfoRec</structname> +returned will have the button actions +(<structfield>btn_acts</structfield> +field) filled in for all buttons. </para> <para> -If <emphasis> -which</emphasis> - includes one of the bits in XkbXI_IndicatorsMask, the feedback class of the +If +<parameter>which</parameter> +includes one of the bits in <symbol>XkbXI_IndicatorsMask</symbol>, +the feedback class of the indicators must be specified in ind_class, and the feedback ID of the indicators must be specified in ind_id. If the request does not include any of -the bits in XkbXI_IndicatorsMask, the ind_class and ind_id parameters are +the bits in <symbol>XkbXI_IndicatorsMask</symbol>, +the ind_class and ind_id parameters are ignored. The class and ID can be obtained via the input device extension XListInputDevices request. </para> <para> -If any of the <emphasis> -XkbXI_IndicatorsMask</emphasis> - bits are set in <emphasis> -which</emphasis> -, the <emphasis> -XkbDeviceInfoRec</emphasis> - returned will have filled in the portions of the <emphasis> -leds</emphasis> - structure corresponding to the indicator feedback identified by <emphasis> -ind_class</emphasis> - and <emphasis> -ind_id</emphasis> -. The <emphasis> -leds</emphasis> - vector of the <emphasis> -XkbDeviceInfoRec</emphasis> - is allocated if necessary and <emphasis> -sz_leds</emphasis> - and <emphasis> -num_leds</emphasis> - filled in. The <emphasis> -led_class</emphasis> -, <emphasis> -led_id</emphasis> - and <emphasis> -phys_indicators</emphasis> - fields of the <emphasis> -leds</emphasis> - entry corresponding to <emphasis> -ind_class</emphasis> - and <emphasis> -ind_id</emphasis> - are always filled in. If <emphasis> -which</emphasis> - contains <emphasis> -XkbXI_IndicatorNamesMask</emphasis> -, the <emphasis> -names_present</emphasis> - and <emphasis> -names</emphasis> - fields of the <emphasis> -leds</emphasis> - structure corresponding to <emphasis> -ind_class</emphasis> - and <emphasis> -ind_id</emphasis> - are returned.<emphasis> - </emphasis> -If <emphasis> -which</emphasis> - contains <emphasis> -XkbXI_IndicatorStateMask</emphasis> -<emphasis> -,</emphasis> - the corresponding <emphasis> -state</emphasis> - field is updated. If <emphasis> -which</emphasis> - contains <emphasis> -XkbXI_IndicatorMapsMask</emphasis> -, the <emphasis> -maps_present</emphasis> - and <emphasis> -maps</emphasis> - fields are updated. +If any of the +<symbol>XkbXI_IndicatorsMask</symbol> +bits are set in +<parameter>which</parameter>, +the +<structname>XkbDeviceInfoRec</structname> +returned will have filled in the portions of the +<structfield>leds</structfield> +structure corresponding to the indicator feedback identified by +<parameter>ind_class</parameter> +and +<parameter>ind_id</parameter>. +The +<structfield>leds</structfield> +vector of the +<structname>XkbDeviceInfoRec</structname> +is allocated if necessary and +<structfield>sz_leds</structfield> +and +<structfield>num_leds</structfield> +filled in. The +<structfield>led_class</structfield>, +<structfield>led_id</structfield> +and +<structfield>phys_indicators</structfield> +fields of the +<structfield>leds</structfield> +entry corresponding to +<parameter>ind_class</parameter> +and +<parameter>ind_id</parameter> +are always filled in. If +<parameter>which</parameter> +contains +<symbol>XkbXI_IndicatorNamesMask</symbol>, +the +<structfield>names_present</structfield> +and +<structfield>names</structfield> +fields of the +<structfield>leds</structfield> +structure corresponding to +<parameter>ind_class</parameter> +and +<parameter>ind_id</parameter> +are returned. +If +<parameter>which</parameter> +contains +<symbol>XkbXI_IndicatorStateMask</symbol>, +the corresponding +<structfield>state</structfield> +field is updated. If +<parameter>which</parameter> +contains +<symbol>XkbXI_IndicatorMapsMask</symbol>, +the +<structfield>maps_present</structfield> +and +<structfield>maps</structfield> +fields are updated. </para> <para> Xkb provides convenience functions to request subsets of the information -available via <emphasis> -XkbGetDeviceInfo</emphasis> -. These convenience functions mirror some of the mask bits. The functions all -take an <emphasis> -XkbDeviceInfoPtr</emphasis> - as an input argument and operate on the X Input Extension device specified by -the <emphasis> -device_spec</emphasis> - field of the structure. Only the parts of the structure indicated in the -function description are updated. The <emphasis> -XkbDeviceInfo</emphasis> -Rec structure used in the function call can be obtained by calling -XkbGetDeviceInfo or can be allocated by calling XkbAllocDeviceInfo (see section -21.3). +available via +<function>XkbGetDeviceInfo</function>. +These convenience functions mirror some of the mask bits. The functions all +take an +<type>XkbDeviceInfoPtr</type> +as an input argument and operate on the X Input Extension device specified by +the +<parameter>device_spec</parameter> +field of the structure. Only the parts of the structure indicated in the +function description are updated. The +<structname>XkbDeviceInfoRec</structname> +structure used in the function call can be obtained by calling +XkbGetDeviceInfo or can be allocated by calling XkbAllocDeviceInfo +(see <link linkend="Allocating_Initializing_and_Freeing_the_XkbDeviceInfoRecStructure">section 21.3</link>). </para> @@ -614,131 +619,137 @@ XkbGetDeviceButtonActions. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetDeviceButtonActions</emphasis> -(<emphasis> -dpy, device_info, all_buttons, first_button, num_buttons</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDeviceInfoPtr device_info; /* structure to update with -results */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> -all_buttons</emphasis> -; /* <emphasis> -True</emphasis> - => get information for all buttons */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int first_button; /* number of first button for -which info is desired */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int num_buttons; /* number of buttons for which -info is desired */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetDeviceButtonActions</emphasis> - queries the server for the desired button information for the device indicated -by the <emphasis> -device_spec</emphasis> - field of <emphasis> -device_info</emphasis> - and waits for a reply. If successful,<emphasis> - XkbGetDeviceButtonActions</emphasis> - backfills the button actions (<emphasis> -btn_acts</emphasis> - field of <emphasis> -device_info</emphasis> -) for only the requested buttons, updates the <emphasis> -name</emphasis> -, <emphasis> -type</emphasis> -, <emphasis> -supported</emphasis> -, and <emphasis> -unsupported</emphasis> - fields, and returns <emphasis> -Success</emphasis> -. -</para> - - -<para> -<emphasis> -all_buttons</emphasis> -, <emphasis> -first_button</emphasis> - and <emphasis> -num_buttons</emphasis> - specify the device buttons for which actions should be returned. Setting -<emphasis> -all_buttons</emphasis> - to <emphasis> -True</emphasis> - requests actions for all device buttons; if <emphasis> -all_buttons</emphasis> - is <emphasis> -False</emphasis> -, <emphasis> -first_button</emphasis> - and <emphasis> -num_buttons</emphasis> - specify a range of buttons for which actions are requested. +<indexterm significance="preferred" zone="XkbGetDeviceButtonActions"><primary><function>XkbGetDeviceButtonActions</function></primary></indexterm> +<funcsynopsis id="XkbGetDeviceButtonActions"> + <funcprototype> + <funcdef>Status <function>XkbGetDeviceButtonActions</function></funcdef> +<!-- ( +<parameter>dpy, device_info, all_buttons, first_button, num_buttons</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>XkbDeviceInfoPtr <parameter>device_info</parameter></paramdef> + <paramdef>Bool <parameter>all_buttons</parameter></paramdef> + <paramdef>unsigned int <parameter>first_button</parameter></paramdef> + <paramdef>unsigned int <parameter>num_buttons</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_info</parameter> + </term> + <listitem> + <para> + structure to update with results + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>all_buttons</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ get information for all buttons + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first_button</parameter> + </term> + <listitem> + <para> + number of first button for which info is desired + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num_buttons</parameter> + </term> + <listitem> + <para> + number of buttons for which info is desired + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetDeviceButtonActions</function> +queries the server for the desired button information for the device indicated +by the +<structfield>device_spec</structfield> +field of +<parameter>device_info</parameter> +and waits for a reply. If successful, +<function>XkbGetDeviceButtonActions</function> +backfills the button actions +(<structfield>btn_acts</structfield> +field of +<parameter>device_info</parameter>) +for only the requested buttons, updates the +<structfield>name</structfield>, +<structfield>type</structfield>, +<structfield>supported</structfield>, +and +<structfield>unsupported</structfield> +fields, and returns +<symbol>Success</symbol>. +</para> + + +<para> +<parameter>all_buttons</parameter>, +<parameter>first_button</parameter> +and +<parameter>num_buttons</parameter> +specify the device buttons for which actions should be returned. Setting +<parameter>all_buttons</parameter> +to +<symbol>True</symbol> +requests actions for all device buttons; if +<parameter>all_buttons</parameter> +is +<symbol>False</symbol>, +<parameter>first_button</parameter> +and +<parameter>num_buttons</parameter> +specify a range of buttons for which actions are requested. </para> <para> If a compatible version of Xkb is not available in the server or the Xkb extension has not been properly initialized, XkbGetDeviceButtonActions returns -<emphasis> -BadAccess</emphasis> -. If allocation errors occur, a <emphasis> -BadAlloc</emphasis> - status is returned. If the specified device (<emphasis> -device_info</emphasis> --><emphasis> -device_spec</emphasis> -) is invalid, a BadKeyboard status is returned. If the device has no buttons, a -Bad<emphasis> -Match</emphasis> - status is returned. If <emphasis> -first_button</emphasis> - and <emphasis> -num_buttons</emphasis> - specify illegal buttons, a Bad<emphasis> -Value</emphasis> - status is returned. +<errorname>BadAccess</errorname>. +If allocation errors occur, a +<errorname>BadAlloc</errorname> +status is returned. If the specified device +(<parameter>device_info</parameter>-><structfield>device_spec</structfield>) +is invalid, a +<errorname>BadKeyboard</errorname> +status is returned. If the device has no buttons, a +<errorname>BadMatch</errorname> +status is returned. If +<parameter>first_button</parameter> +and +<parameter>num_buttons</parameter> +specify illegal buttons, a +<errorname>BadValue</errorname> +status is returned. </para> @@ -748,181 +759,192 @@ of an input extension device, use XkbGetDeviceLedInfo. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetDeviceLedInfo</emphasis> -(<emphasis> -dpy, device_i</emphasis> -nfo, led_class, led_id, which) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDeviceInfoPtr device_info; /* structure to update with -results */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -led_class</emphasis> -; /* LED feedback class assigned by input extension */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int led_id; /* LED feedback ID assigned by input -extension */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int which; /* mask indicating desired -information */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetDeviceLedInfo</emphasis> - queries the server for the desired LED information for the feedback specified -by <emphasis> -led_class</emphasis> - and <emphasis> -led_id</emphasis> - for the X input extension device indicated by <emphasis> -device_spec</emphasis> --><emphasis> -device_info</emphasis> - and waits for a reply. If successful, <emphasis> -XkbGetDeviceLedInfo</emphasis> - backfills the relevant fields of <emphasis> -device_info</emphasis> - as determined by <emphasis> -which</emphasis> - with the results and returns <emphasis> -Success</emphasis> -. Valid values for <emphasis> -which</emphasis> - are the inclusive OR of any of <emphasis> -XkbXI_IndicatorNamesMask</emphasis> -, <emphasis> -XkbXI_IndicatorMapsMask</emphasis> -, and <emphasis> -XkbXI_IndicatorStateMask</emphasis> -. -</para> - - -<para> -The fields of <emphasis> -device_info</emphasis> - that are filled in when this request succeeds are <emphasis> -name, type, supported</emphasis> -, and <emphasis> -unsupported</emphasis> -, and portions of the <emphasis> -leds</emphasis> - structure corresponding to <emphasis> -led_class</emphasis> - and <emphasis> -led_id</emphasis> - as indicated by the bits set in <emphasis> -which</emphasis> -. The <emphasis> -device_info->leds</emphasis> - vector is allocated if necessary and <emphasis> -sz_leds</emphasis> - and <emphasis> -num_leds</emphasis> - filled in. The <emphasis> -led_class</emphasis> -, <emphasis> -led_id</emphasis> - and <emphasis> -phys_indicators</emphasis> - fields of the <emphasis> -device_info</emphasis> --><emphasis> -leds</emphasis> - entry corresponding to <emphasis> -led_class</emphasis> - and <emphasis> -led_id</emphasis> - are always filled in. -</para> - - -<para> -If <emphasis> -which</emphasis> - contains <emphasis> -XkbXI_IndicatorNamesMask</emphasis> -, the <emphasis> -names_present</emphasis> - and <emphasis> -names</emphasis> - fields of the <emphasis> -device_info</emphasis> --><emphasis> -leds</emphasis> - structure corresponding to <emphasis> -led_class</emphasis> - and <emphasis> -led_id</emphasis> - are updated, if <emphasis> -which</emphasis> - contains <emphasis> -XkbXI_IndicatorStateMask</emphasis> -<emphasis> -,</emphasis> - the corresponding <emphasis> -state</emphasis> - field is updated, and if <emphasis> -which</emphasis> - contains <emphasis> -XkbXI_IndicatorMapsMask</emphasis> -, the <emphasis> -maps_present</emphasis> - and <emphasis> -maps</emphasis> - fields are updated. +<indexterm significance="preferred" zone="XkbGetDeviceLedInfo"><primary><function>XkbGetDeviceLedInfo</function></primary></indexterm> +<funcsynopsis id="XkbGetDeviceLedInfo"> + <funcprototype> + <funcdef>Status <function>XkbGetDeviceLedInfo</function></funcdef> +<!-- ( +<parameter>dpy, device_i</parameter> +nfo, led_class, led_id, which) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>XkbDeviceInfoPtr <parameter>device_info</parameter></paramdef> + <paramdef>unsigned int <parameter>led_class</parameter></paramdef> + <paramdef>unsigned int <parameter>led_id</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_info</parameter> + </term> + <listitem> + <para> + structure to update with results + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>led_class</parameter> + </term> + <listitem> + <para> + LED feedback class assigned by input extension + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>led_id</parameter> + </term> + <listitem> + <para> + LED feedback ID assigned by input extension + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask indicating desired information + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetDeviceLedInfo</function> +queries the server for the desired LED information for the feedback specified +by +<parameter>led_class</parameter> +and +<parameter>led_id</parameter> +for the X input extension device indicated by +<structfield>device_spec</structfield>-><parameter>device_info</parameter> +and waits for a reply. If successful, +<function>XkbGetDeviceLedInfo</function> +backfills the relevant fields of +<parameter>device_info</parameter> +as determined by +<parameter>which</parameter> +with the results and returns +<symbol>Success</symbol>. +Valid values for +<parameter>which</parameter> +are the inclusive OR of any of +<symbol>XkbXI_IndicatorNamesMask</symbol>, +<symbol>XkbXI_IndicatorMapsMask</symbol>, +and +<symbol>XkbXI_IndicatorStateMask</symbol>. +</para> + + +<para> +The fields of +<parameter>device_info</parameter> +that are filled in when this request succeeds are +<structfield>name</structfield>, +<structfield>type</structfield>, +<structfield>supported</structfield>, +and +<structfield>unsupported</structfield>, +and portions of the +<structfield>leds</structfield> +structure corresponding to +<parameter>led_class</parameter> +and +<parameter>led_id</parameter> +as indicated by the bits set in +<parameter>which</parameter>. +The +<structfield>device_info->leds</structfield> +vector is allocated if necessary and +<structfield>sz_leds</structfield> +and +<structfield>num_leds</structfield> +filled in. The +<parameter>led_class</parameter>, +<parameter>led_id</parameter> +and +<structfield>phys_indicators</structfield> +fields of the +<parameter>device_info</parameter>-><structfield>leds</structfield> +entry corresponding to +<parameter>led_class</parameter> +and +<parameter>led_id</parameter> +are always filled in. +</para> + + +<para> +If +<parameter>which</parameter> +contains +<symbol>XkbXI_IndicatorNamesMask</symbol>, +the +<structfield>names_present</structfield> +and +<structfield>names</structfield> +fields of the +<parameter>device_info</parameter>-><structfield>leds</structfield> +structure corresponding to +<parameter>led_class</parameter> +and +<parameter>led_id</parameter> +are updated, if +<parameter>which</parameter> +contains +<symbol>XkbXI_IndicatorStateMask</symbol>, +the corresponding +<structfield>state</structfield> +field is updated, and if +<parameter>which</parameter> +contains +<symbol>XkbXI_IndicatorMapsMask</symbol>, +the +<structfield>maps_present</structfield> +and +<structfield>maps</structfield> +fields are updated. </para> <para> If a compatible version of Xkb is not available in the server or the Xkb -extension has not been properly initialized, <emphasis> -XkbGetDeviceLedInfo</emphasis> - returns <emphasis> -BadAccess</emphasis> -. If allocation errors occur, a BadAlloc status is returned. If the device has -no indicators, a BadMatch error is returned. If <emphasis> -ledClass</emphasis> - or <emphasis> -ledID</emphasis> - have illegal values, a Bad<emphasis> -Value</emphasis> - error is returned. If they have legal values but do not specify a feedback -that contains LEDs and is associated with the specified device, a Bad<emphasis> -Match</emphasis> - error is returned. +extension has not been properly initialized, +<function>XkbGetDeviceLedInfo</function> +returns +<errorname>BadAccess</errorname>. +If allocation errors occur, a +<errorname>BadAlloc</errorname> +status is returned. If the device has no indicators, a +<errorname>BadMatch</errorname> +error is returned. If +<structfield>ledClass</structfield> +or +<structfield>ledID</structfield> +have illegal values, a +<errorname>BadValue</errorname> +error is returned. If they have legal values but do not specify a feedback +that contains LEDs and is associated with the specified device, a +<errorname>BadMatch</errorname> +error is returned. </para> @@ -932,396 +954,396 @@ Match</emphasis> Structure</title> <para> -To obtain an <emphasis> -XkbDeviceInfoRec</emphasis> - structure, use XkbGetDeviceInfo or XkbAllocDeviceInfo. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbDeviceInfoPtr <emphasis> -XkbAllocDeviceInfo</emphasis> -(device_spec, n_buttons, sz_leds) - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int device_spec; /* device ID with which -structure will be used */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -n_buttons</emphasis> -; /* number of button actions to allocate space for*/ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -sz_leds</emphasis> -; /* number of LED feedbacks to allocate space for */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAllocDeviceInfo</emphasis> - allocates space for an <emphasis> -XkbDeviceInfoRec</emphasis> - structure and initializes that structure’s <emphasis> -device_spec</emphasis> - field with the device ID specified by device_spec. If <emphasis> -n_buttons</emphasis> - is nonzero, <emphasis> -n_buttons</emphasis> - <emphasis> -XkbActions</emphasis> - are linked into the <emphasis> -XkbDeviceInfoRec</emphasis> - structure and initialized to zero. If sz_leds is nonzero, <emphasis> -sz_leds</emphasis> - <emphasis> -XkbDeviceLedInfoRec</emphasis> - structures are also allocated and linked into the <emphasis> -XkbDeviceInfoRec</emphasis> - structure. If you request <emphasis> -XkbDeviceLedInfoRec</emphasis> - structures be allocated using this request, you must initialize them +To obtain an +<structname>XkbDeviceInfoRec</structname> +structure, use XkbGetDeviceInfo or XkbAllocDeviceInfo. +</para> + +<indexterm significance="preferred" zone="XkbAllocDeviceInfo"><primary><function>XkbAllocDeviceInfo</function></primary></indexterm> +<funcsynopsis id="XkbAllocDeviceInfo"> + <funcprototype> + <funcdef>XkbDeviceInfoPtr <function>XkbAllocDeviceInfo</function></funcdef> +<!-- (device_spec, n_buttons, sz_leds) --> + + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int <parameter>n_buttons</parameter></paramdef> + <paramdef>unsigned int <parameter>sz_leds</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID with which structure will be used + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>n_buttons</parameter> + </term> + <listitem> + <para> + number of button actions to allocate space for + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>sz_leds</parameter> + </term> + <listitem> + <para> + number of LED feedbacks to allocate space for + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAllocDeviceInfo</function> +allocates space for an +<structname>XkbDeviceInfoRec</structname> +structure and initializes that structure’s +<parameter>device_spec</parameter> +field with the device ID specified by device_spec. If +<parameter>n_buttons</parameter> +is nonzero, +<parameter>n_buttons</parameter> +<structname>XkbAction</structname>s +are linked into the +<structname>XkbDeviceInfoRec</structname> +structure and initialized to zero. If sz_leds is nonzero, +<parameter>sz_leds</parameter> +<structname>XkbDeviceLedInfoRec</structname> +structures are also allocated and linked into the +<structname>XkbDeviceInfoRec</structname> +structure. If you request +<structname>XkbDeviceLedInfoRec</structname> +structures be allocated using this request, you must initialize them explicitly. </para> <para> -To obtain an <emphasis> -XkbDeviceLedInfoRec</emphasis> - structure, use XkbAllocDeviceLedInfo. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbAllocDeviceLedInfo</emphasis> -(devi, num_needed) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDeviceInfoPtr <emphasis> -device_info</emphasis> -; /* structure in which to allocate LED space */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int <emphasis> -num_needed</emphasis> -; /* number of indicators to allocate space for */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAllocDeviceLedInfo</emphasis> - allocates space for an <emphasis> -XkbDeviceLedInfoRec</emphasis> - and places it in <emphasis> -device_info</emphasis> -. If num_needed is nonzero, <emphasis> -num_needed</emphasis> - <emphasis> -XkbIndicatorMapRec</emphasis> - structures are also allocated and linked into the <emphasis> -XkbDeviceLedInfoRec</emphasis> - structure. If you request <emphasis> -XkbIndicatorMapRec</emphasis> - structures be allocated using this request, you must initialize them +To obtain an +<structname>XkbDeviceLedInfoRec</structname> +structure, use XkbAllocDeviceLedInfo. +</para> + + +<indexterm significance="preferred" zone="XkbAllocDeviceLedInfo"><primary><function>XkbAllocDeviceLedInfo</function></primary></indexterm> +<funcsynopsis id="XkbAllocDeviceLedInfo"> + <funcprototype> + <funcdef>Status <function>XkbAllocDeviceLedInfo</function></funcdef> +<!-- (devi, num_needed) --> + + <paramdef>XkbDeviceInfoPtr <parameter>device_info</parameter></paramdef> + <paramdef>int <parameter>num_needed</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>device_info</parameter> + </term> + <listitem> + <para> + structure in which to allocate LED space + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num_needed</parameter> + </term> + <listitem> + <para> + number of indicators to allocate space for + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAllocDeviceLedInfo</function> +allocates space for an +<structname>XkbDeviceLedInfoRec</structname> +and places it in +<parameter>device_info</parameter>. +If num_needed is nonzero, +<parameter>num_needed</parameter> +<structname>XkbIndicatorMapRec</structname> +structures are also allocated and linked into the +<structname>XkbDeviceLedInfoRec</structname> +structure. If you request +<structname>XkbIndicatorMapRec</structname> +structures be allocated using this request, you must initialize them explicitly. All other fields are initialized to zero. </para> <para> -To initialize an <emphasis> -XkbDeviceLedInfoRec</emphasis> - structure, use XkbAddDeviceLedInfo. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -XkbDeviceLedInfoPtr <emphasis> -XkbAddDeviceLedInfo</emphasis> -(device_info, led_class, led_id) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDeviceInfoPtr device_info; /* structure in which to -add LED info */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -led_class</emphasis> -; /* input extension class for LED device of interest */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -led_id</emphasis> -; /* input extension ID for LED device of interest */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAddDeviceLedInfo</emphasis> - first checks to see whether an entry matching <emphasis> -led_class</emphasis> - and <emphasis> -led_id</emphasis> - already exists in the <emphasis> -device_info->leds</emphasis> - array. If it finds a matching entry, it returns a pointer to that entry. -Otherwise, it checks to be sure there is at least one empty entry in <emphasis> -device_info</emphasis> --><emphasis> -leds</emphasis> - and extends it if there is not enough room. It then increments <emphasis> -device_info</emphasis> --><emphasis> -num_leds</emphasis> - and fills in the next available entry in <emphasis> -device_info</emphasis> --><emphasis> -leds</emphasis> - with <emphasis> -led_class</emphasis> - and <emphasis> -led_id</emphasis> -. -</para> - - -<para> -If successful, <emphasis> -XkbAddDeviceLedInfo</emphasis> - returns a pointer to the <emphasis> -XkbDeviceLedInfoRec</emphasis> - structure that was initialized. If unable to allocate sufficient storage, or -if <emphasis> -device_info</emphasis> - points to an invalid <emphasis> -XkbDeviceInfoRec</emphasis> - structure, or if <emphasis> -led_class</emphasis> - or <emphasis> -led_id</emphasis> - are inappropriate, <emphasis> -XkbAddDeviceLedInfo</emphasis> - returns <emphasis> -NULL</emphasis> -. -</para> - - -<para> -To allocate additional space for button actions in an <emphasis> -XkbDeviceInfoRec</emphasis> - structure, use XkbResizeDeviceButtonActions. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbResizeDeviceButtonActions</emphasis> -(device_info, new_total) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDeviceInfoPtr device_info; /* structure in which to -allocate button actions */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -new_total</emphasis> -; /* new total number of button actions needed */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbResizeDeviceButton</emphasis> - reallocates space, if necessary, to make sure there is room for a total of -<emphasis> -new_total</emphasis> - button actions in the <emphasis> -device_info</emphasis> - structure. Any new entries allocated are zeroed. If successful, <emphasis> -XkbResizeDeviceButton</emphasis> - returns Success. If new_total is zero, all button actions are deleted, -<emphasis> -device_info</emphasis> --><emphasis> -num_btns</emphasis> - is set to zero, and <emphasis> -device_info</emphasis> --><emphasis> -btn_acts</emphasis> - is set to <emphasis> -NULL</emphasis> -. If device_info is invalid or new_total is greater than 255, BadValue is -returned. If a memory allocation failure occurs, a <emphasis> -BadAlloc</emphasis> - is returned. -</para> - - -<para> -To free an <emphasis> -XkbDeviceInfoRec</emphasis> - structure, use XkbFreeDeviceInfo. -</para> - - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeDeviceInfo</emphasis> -(device_info, which, free_all) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDeviceInfoPtr device_info; /* pointer to <emphasis> -XkbDeviceInfoRec</emphasis> - in which to free items */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -which</emphasis> -; /* mask of components of <emphasis> -device_info</emphasis> - to free */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> -free_all</emphasis> -; /* <emphasis> -True</emphasis> - => free everything, including device_info */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -If free_all is <emphasis> -True</emphasis> -, the <emphasis> -XkbFreeDeviceInfo</emphasis> - frees all components of <emphasis> -device_info</emphasis> - and the <emphasis> -XkbDeviceInfoRec</emphasis> - structure pointed to by <emphasis> -device_info</emphasis> - itself. If free_all is <emphasis> -False</emphasis> -, the value of which determines which subcomponents are freed. <emphasis> -which </emphasis> -is an inclusive OR of one or more of the values from Table 21.1. If which -contains XkbXI_ButtonActionsMask, all button actions associated with <emphasis> -device_info</emphasis> - are freed, <emphasis> -device_info</emphasis> --><emphasis> -btn_acts</emphasis> - is set to <emphasis> -NULL</emphasis> -, and <emphasis> -device_info</emphasis> --><emphasis> -num_btns</emphasis> - is set to zero. If which contains all bits in XkbXI_IndicatorsMask, all -<emphasis> -XkbDeviceLedInfoRec</emphasis> - structures associated with <emphasis> -device_info</emphasis> - are freed, <emphasis> -device_info</emphasis> --><emphasis> -leds</emphasis> - is set to <emphasis> -NULL</emphasis> -, and <emphasis> -device_info</emphasis> --><emphasis> -sz_leds</emphasis> - and <emphasis> -device_info</emphasis> --><emphasis> -num_leds</emphasis> - are set to zero. If which contains XkbXI_IndicatorMapsMask, all indicator maps -associated with <emphasis> -device_info</emphasis> - are cleared, but the number of LEDs and the leds structures themselves are -preserved. If which contains XkbXI_IndicatorNamesMask, all indicator names +To initialize an +<structname>XkbDeviceLedInfoRec</structname> +structure, use XkbAddDeviceLedInfo. +</para> + + +<indexterm significance="preferred" zone="XkbAddDeviceLedInfo"><primary><function>XkbAddDeviceLedInfo</function></primary></indexterm> +<funcsynopsis id="XkbAddDeviceLedInfo"> + <funcprototype> + <funcdef>XkbDeviceLedInfoPtr <function>XkbAddDeviceLedInfo</function></funcdef> +<!-- (device_info, led_class, led_id) --> + + <paramdef>XkbDeviceInfoPtr <parameter>device_info</parameter></paramdef> + <paramdef>unsigned int <parameter>led_class</parameter></paramdef> + <paramdef>unsigned int <parameter>led_id</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>device_info</parameter> + </term> + <listitem> + <para> + structure in which to add LED info + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>led_class</parameter> + </term> + <listitem> + <para> + input extension class for LED device of interest + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>led_id</parameter> + </term> + <listitem> + <para> + input extension ID for LED device of interest + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAddDeviceLedInfo</function> +first checks to see whether an entry matching +<parameter>led_class</parameter> +and +<parameter>led_id</parameter> +already exists in the +<structfield>device_info->leds</structfield> +array. If it finds a matching entry, it returns a pointer to that entry. +Otherwise, it checks to be sure there is at least one empty entry in +<parameter>device_info</parameter>-><structfield>leds</structfield> +and extends it if there is not enough room. It then increments +<parameter>device_info</parameter>-><structfield>num_leds</structfield> +and fills in the next available entry in +<parameter>device_info</parameter>-><structfield>leds</structfield> +with +<parameter>led_class</parameter> +and +<parameter>led_id</parameter>. +</para> + + +<para> +If successful, +<function>XkbAddDeviceLedInfo</function> +returns a pointer to the +<structname>XkbDeviceLedInfoRec</structname> +structure that was initialized. If unable to allocate sufficient storage, or +if +<parameter>device_info</parameter> +points to an invalid +<structname>XkbDeviceInfoRec</structname> +structure, or if +<parameter>led_class</parameter> +or +<parameter>led_id</parameter> +are inappropriate, +<function>XkbAddDeviceLedInfo</function> +returns +<symbol>NULL</symbol>. +</para> + + +<para> +To allocate additional space for button actions in an +<structname>XkbDeviceInfoRec</structname> +structure, use XkbResizeDeviceButtonActions. +</para> + + +<indexterm significance="preferred" zone="XkbResizeDeviceButtonActions"><primary><function>XkbResizeDeviceButtonActions</function></primary></indexterm> +<funcsynopsis id="XkbResizeDeviceButtonActions"> + <funcprototype> + <funcdef>Status <function>XkbResizeDeviceButtonActions</function></funcdef> +<!-- (device_info, new_total) --> + + <paramdef>XkbDeviceInfoPtr <parameter>device_info</parameter></paramdef> + <paramdef>unsigned int <parameter>new_total</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>device_info</parameter> + </term> + <listitem> + <para> + structure in which to allocate button actions + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>new_total</parameter> + </term> + <listitem> + <para> + new total number of button actions needed + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbResizeDeviceButtonActions</function> +reallocates space, if necessary, to make sure there is room for a total of +<parameter>new_total</parameter> +button actions in the +<parameter>device_info</parameter> +structure. Any new entries allocated are zeroed. If successful, +<function>XkbResizeDeviceButtonActions</function> +returns Success. If new_total is zero, all button actions are deleted, +<parameter>device_info</parameter>-><structfield>num_btns</structfield> +is set to zero, and +<parameter>device_info</parameter>-><structfield>btn_acts</structfield> +is set to +<symbol>NULL</symbol>. +If device_info is invalid or new_total is greater than 255, +<errorname>BadValue</errorname> +is returned. If a memory allocation failure occurs, a +<errorname>BadAlloc</errorname> +is returned. +</para> + + +<para> +To free an +<structname>XkbDeviceInfoRec</structname> +structure, use XkbFreeDeviceInfo. +</para> + + +<indexterm significance="preferred" zone="XkbFreeDeviceInfo"><primary><function>XkbFreeDeviceInfo</function></primary></indexterm> +<funcsynopsis id="XkbFreeDeviceInfo"> + <funcprototype> + <funcdef>void <function>XkbFreeDeviceInfo</function></funcdef> +<!-- (device_info, which, free_all) --> + + <paramdef>XkbDeviceInfoPtr <parameter>device_info</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>Bool <parameter>free_all</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>device_info</parameter> + </term> + <listitem> + <para> + pointer to <structname>XkbDeviceInfoRec</structname> in which to free items + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask of components of <parameter>device_info</parameter> to free + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>free_all</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ free everything, including device_info + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +If free_all is +<symbol>True</symbol>, +the +<function>XkbFreeDeviceInfo</function> +frees all components of +<parameter>device_info</parameter> +and the +<structname>XkbDeviceInfoRec</structname> +structure pointed to by +<parameter>device_info</parameter> +itself. If free_all is +<symbol>False</symbol>, +the value of which determines which subcomponents are freed. +<parameter>which</parameter> +is an inclusive OR of one or more of the values from +<link linkend="table21.1">Table 21.1</link>. If which +contains <symbol>XkbXI_ButtonActionsMask</symbol>, +all button actions associated with +<parameter>device_info</parameter> +are freed, +<parameter>device_info</parameter>-><structfield>btn_acts</structfield> +is set to +<symbol>NULL</symbol>, +and +<parameter>device_info</parameter>-><structfield>num_btns</structfield> +is set to zero. If which contains all bits in +<symbol>XkbXI_IndicatorsMask</symbol>, all +<structname>XkbDeviceLedInfoRec</structname> +structures associated with +<parameter>device_info</parameter> +are freed, +<parameter>device_info</parameter>-><structfield>leds</structfield> +is set to +<symbol>NULL</symbol>, +and +<parameter>device_info</parameter>-><structfield>sz_leds</structfield> +and +<parameter>device_info</parameter>-><structfield>num_leds</structfield> +are set to zero. If which contains <symbol>XkbXI_IndicatorMapsMask</symbol>, +all indicator maps associated with +<parameter>device_info</parameter> +are cleared, but the number of LEDs and the leds structures themselves are +preserved. If which contains <symbol>XkbXI_IndicatorNamesMask</symbol>, +all indicator names associated with device_info are cleared, but the number of LEDs and the leds structures themselves are preserved. If which contains -XkbXI_IndicatorStateMask, the indicator state associated with the <emphasis> -device_info</emphasis> - leds are set to zeros but the number of LEDs and the leds structures +<symbol>XkbXI_IndicatorStateMask</symbol>, +the indicator state associated with the +<parameter>device_info</parameter> +leds are set to zeros but the number of LEDs and the leds structures themselves are preserved. </para> @@ -1349,13 +1371,13 @@ core X keyboard. Xkb implementations are required to support key actions for the buttons of the core pointer device, but support for actions on extension devices is optional. Implementations that do not support button actions for extension devices must -not set the <emphasis> -XkbXI_ButtonActionsMask</emphasis> - bit in the <emphasis> -supported</emphasis> - field of an <emphasis> -XkbDeviceInfoRec</emphasis> - structure. +not set the +<symbol>XkbXI_ButtonActionsMask</symbol> +bit in the +<structfield>supported</structfield> +field of an +<structname>XkbDeviceInfoRec</structname> +structure. </para> @@ -1363,22 +1385,22 @@ XkbDeviceInfoRec</emphasis> If a client attempts to modify valid characteristics of a device using an implementation that does not support modification of those characteristics, no protocol error is generated. Instead, the server reports a failure for the -request; it also sends an <emphasis> -XkbExtensionDeviceNotify</emphasis> - event to the client that issued the request if the client has selected to +request; it also sends an +<symbol>XkbExtensionDeviceNotify</symbol> +event to the client that issued the request if the client has selected to receive these events. </para> <para> To change characteristics of an X Input Extension device in the server, first -modify a local copy of the device structure and then use either <emphasis> -XkbSetDeviceInfo,</emphasis> - or, to save network traffic, use an <emphasis> -XkbDeviceChangesRec</emphasis> - structure (see section 21.6) and call <emphasis> -XkbChangeDeviceInfo</emphasis> - to download the changes to the server. +modify a local copy of the device structure and then use either +<function>XkbSetDeviceInfo</function>, +or, to save network traffic, use an +<structname>XkbDeviceChangesRec</structname> +structure (see <link linkend="Tracking_Changes_to_Extension_Devices">section 21.6</link>) and call +<function>XkbChangeDeviceInfo</function> +to download the changes to the server. </para> @@ -1387,130 +1409,128 @@ To modify some or all of the characteristics of an X Input Extension device, use XkbSetDeviceInfo. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbSetDeviceInfo</emphasis> -(<emphasis> -dpy</emphasis> -, which, device_info) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -which</emphasis> -; /* mask indicating characteristics to modify */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDeviceInfoPtr device_info; /* structure defining the -device and modifications */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSetDeviceInfo</emphasis> - sends a request to the server to modify the characteristics of the device -specified in the <emphasis> -device_info</emphasis> - structure. The particular characteristics modified are identified by the bits -set in <emphasis> -which</emphasis> - and take their values from the relevant fields in <emphasis> -device_info</emphasis> - (see Table 21.1). <emphasis> -XkbSetDeviceInfo</emphasis> - returns <emphasis> -True</emphasis> - if the request was successfully sent to the server. If the X server +<indexterm significance="preferred" zone="XkbSetDeviceInfo"><primary><function>XkbSetDeviceInfo</function></primary></indexterm> +<funcsynopsis id="XkbSetDeviceInfo"> + <funcprototype> + <funcdef>Bool <function>XkbSetDeviceInfo</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +which, device_info) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>XkbDeviceInfoPtr <parameter>device_info</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask indicating characteristics to modify + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_info</parameter> + </term> + <listitem> + <para> + structure defining the device and modifications + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSetDeviceInfo</function> +sends a request to the server to modify the characteristics of the device +specified in the +<parameter>device_info</parameter> +structure. The particular characteristics modified are identified by the bits +set in +<parameter>which</parameter> +and take their values from the relevant fields in +<parameter>device_info</parameter> +(see <link linkend="table21.1">Table 21.1</link>). +<function>XkbSetDeviceInfo</function> +returns +<symbol>True</symbol> +if the request was successfully sent to the server. If the X server implementation does not allow interaction between the X input extension and the -Xkb Extension, the function does nothing and returns <emphasis> -False</emphasis> -. +Xkb Extension, the function does nothing and returns +<symbol>False</symbol>. </para> <para> -The <emphasis> -which</emphasis> - parameter specifies which aspects of the device should be changed and is a +The +<parameter>which</parameter> +parameter specifies which aspects of the device should be changed and is a bitmask composed of an inclusive OR or one or more of the following bits: -<emphasis> -XkbXI_ButtonActionsMask</emphasis> -, <emphasis> -XkbXI_IndicatorNamesMask</emphasis> -, <emphasis> -XkbXI_IndicatorMapsMask</emphasis> -. If the features requested to be manipulated in <emphasis> -which</emphasis> - are valid for the device, but the server does not support assignment of one or +<symbol>XkbXI_ButtonActionsMask</symbol>, +<symbol>XkbXI_IndicatorNamesMask</symbol>, +<symbol>XkbXI_IndicatorMapsMask</symbol>. +If the features requested to be manipulated in +<parameter>which</parameter> +are valid for the device, but the server does not support assignment of one or more of them, that particular portion of the request is ignored. </para> <para> -If the device specified in <emphasis> -device_info</emphasis> --><emphasis> -device_spec</emphasis> - does not contain buttons and a request affecting buttons is made, or the +If the device specified in +<parameter>device_info</parameter>-><structfield>device_spec</structfield> +does not contain buttons and a request affecting buttons is made, or the device does not contain indicators and a request affecting indicators is made, -a <emphasis> -BadMatch</emphasis> - protocol error results. +a +<errorname>BadMatch</errorname> +protocol error results. </para> <para> -If the <emphasis> -XkbXI_ButtonActionsMask</emphasis> - bit is set in the supported mask returned by XkbGetDeviceInfo, the Xkb +If the +<symbol>XkbXI_ButtonActionsMask</symbol> +bit is set in the supported mask returned by XkbGetDeviceInfo, the Xkb extension allows applications to assign key actions to buttons on input -extension devices other than the core keyboard device. If the <emphasis> -XkbXI_ButtonActionsMask</emphasis> - is set in <emphasis> -which</emphasis> -, the actions for all buttons specified in device_info are set to the <emphasis> -XkbAction</emphasis> -s specified in <emphasis> -device_info</emphasis> --><emphasis> -btn_acts</emphasis> -. If the number of buttons requested to be updated is not valid for the device, -<emphasis> -XkbSetDeviceInfo</emphasis> - returns <emphasis> -False</emphasis> - and a <emphasis> -BadValue</emphasis> - protocol error results. -</para> - - -<para> -If the <emphasis> -XkbXI_IndicatorMaps</emphasis> - and / or <emphasis> -XkbXI_IndicatorNamesMask</emphasis> - bit is set in the supported mask returned by XkbGetDeviceInfo, the Xkb +extension devices other than the core keyboard device. If the +<symbol>XkbXI_ButtonActionsMask</symbol> +is set in +<parameter>which</parameter>, +the actions for all buttons specified in device_info are set to the +<structname>XkbAction</structname>s +specified in +<parameter>device_info</parameter>-><structfield>btn_acts</structfield>. +If the number of buttons requested to be updated is not valid for the device, +<function>XkbSetDeviceInfo</function> +returns +<symbol>False</symbol> +and a +<errorname>BadValue</errorname> +protocol error results. +</para> + + +<para> +If the +<symbol>XkbXI_IndicatorMapsMask</symbol> +and / or +<symbol>XkbXI_IndicatorNamesMask</symbol> +bit is set in the supported mask returned by XkbGetDeviceInfo, the Xkb extension allows applications to assign maps and / or names to the indicators of nonkeyboard extension devices. If supported, maps and / or names can be assigned to all extension device indicators, whether they are part of a @@ -1519,63 +1539,46 @@ keyboard feedback or part of an indicator feedback. <para> -If the <emphasis> -XkbXI_IndicatorMapsMask</emphasis> - and / or <emphasis> -XkbXI_IndicatorNamesMask</emphasis> - flag is set in <emphasis> -which</emphasis> -, the indicator maps and / or names for all <emphasis> -device_info</emphasis> --><emphasis> -num_leds</emphasis> - indicator devices specified in <emphasis> -device_info</emphasis> --><emphasis> -leds</emphasis> - are set to the maps and / or names specified in <emphasis> -device_info</emphasis> --><emphasis> -leds</emphasis> -. <emphasis> -device_info</emphasis> --><emphasis> -leds</emphasis> --><emphasis> -led_class</emphasis> - and <emphasis> -led_id</emphasis> - specify the input extension class and device ID for each indicator device to -modify; if they have invalid values, a <emphasis> -BadValue</emphasis> - protocol error results and <emphasis> -XkbSetDeviceInfo</emphasis> - returns <emphasis> -False</emphasis> -. If they have legal values but do not specify a keyboard or indicator class -feedback for the device in question, a <emphasis> -BadMatch</emphasis> - error results. If any of the values in <emphasis> -device_info</emphasis> --><emphasis> -leds</emphasis> -<emphasis> --></emphasis> -<emphasis> -names</emphasis> - are not a valid Atom or <emphasis> -None</emphasis> -, a <emphasis> -BadAtom</emphasis> - protocol error results. +If the +<symbol>XkbXI_IndicatorMapsMask</symbol> +and / or +<symbol>XkbXI_IndicatorNamesMask</symbol> +flag is set in +<parameter>which</parameter>, +the indicator maps and / or names for all +<parameter>device_info</parameter>-><structfield>num_leds</structfield> +indicator devices specified in +<parameter>device_info</parameter>-><structfield>leds</structfield> +are set to the maps and / or names specified in +<parameter>device_info</parameter>-><structfield>leds</structfield>. +<parameter>device_info</parameter>-><structfield>leds</structfield>-><structfield>led_class</structfield> +and +<structfield>led_id</structfield> +specify the input extension class and device ID for each indicator device to +modify; if they have invalid values, a +<errorname>BadValue</errorname> +protocol error results and +<function>XkbSetDeviceInfo</function> +returns +<symbol>False</symbol>. +If they have legal values but do not specify a keyboard or indicator class +feedback for the device in question, a +<errorname>BadMatch</errorname> +error results. If any of the values in +<parameter>device_info</parameter>-><structfield>leds->names</structfield> +are not a valid Atom or +<symbol>None</symbol>, +a +<errorname>BadAtom</errorname> +protocol error results. </para> <para> Xkb provides convenience functions to modify subsets of the information -accessible via <emphasis> -XkbSetDeviceInfo</emphasis> -. Only the parts of the structure indicated in the function description are +accessible via +<function>XkbSetDeviceInfo</function>. +Only the parts of the structure indicated in the function description are modified. These convenience functions are described as follows. </para> @@ -1586,118 +1589,124 @@ XkbSetDeviceButtonActions. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbSetDeviceButtonActions</emphasis> -(<emphasis> -dpy</emphasis> -, device, first_button, num_buttons, actions) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDeviceInfoPtr device_info; /* structure defining the -device and modifications */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int first_button; /* number of first button to -update, 0 relative */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int num_buttons; /* number of buttons to update -*/ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSetDeviceButtonActions</emphasis> - assigns actions to the buttons of the device specified in -device_info-><emphasis> -device_spec</emphasis> -. Actions are assigned to <emphasis> -num_buttons</emphasis> - buttons beginning with <emphasis> -first_button</emphasis> - and are taken from the actions specified in <emphasis> -device_info</emphasis> --><emphasis> -btn_acts</emphasis> -. +<indexterm significance="preferred" zone="XkbSetDeviceButtonActions"><primary><function>XkbSetDeviceButtonActions</function></primary></indexterm> +<funcsynopsis id="XkbSetDeviceButtonActions"> + <funcprototype> + <funcdef>Bool <function>XkbSetDeviceButtonActions</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +device, first_button, num_buttons, actions) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>XkbDeviceInfoPtr <parameter>device_info</parameter></paramdef> + <paramdef>unsigned int <parameter>first_button</parameter></paramdef> + <paramdef>unsigned int <parameter>num_buttons</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_info</parameter> + </term> + <listitem> + <para> + structure defining the device and modifications + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>first_button</parameter> + </term> + <listitem> + <para> + number of first button to update, 0 relative + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>num_buttons</parameter> + </term> + <listitem> + <para> + number of buttons to update + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSetDeviceButtonActions</function> +assigns actions to the buttons of the device specified in +device_info-><structfield>device_spec</structfield>. +Actions are assigned to +<parameter>num_buttons</parameter> +buttons beginning with +<parameter>first_button</parameter> +and are taken from the actions specified in +<parameter>device_info</parameter>-><structfield>btn_acts</structfield>. </para> <para> If the server does not support assignment of Xkb actions to extension device -buttons, <emphasis> -XkbSetDeviceButtonActions</emphasis> - has no effect and returns <emphasis> -False</emphasis> -. If the device has no buttons or if <emphasis> -first_button</emphasis> - or <emphasis> -num_buttons</emphasis> - specify buttons outside of the valid range as determined by <emphasis> -device_info</emphasis> --><emphasis> -num_btns</emphasis> -, the function has no effect and returns <emphasis> -False</emphasis> -. Otherwise, <emphasis> -XkbSetDeviceButtonActions</emphasis> - sends a request to the server to change the actions for the specified buttons -and returns <emphasis> -True</emphasis> -. +buttons, +<function>XkbSetDeviceButtonActions</function> +has no effect and returns +<symbol>False</symbol>. +If the device has no buttons or if +<parameter>first_button</parameter> +or +<parameter>num_buttons</parameter> +specify buttons outside of the valid range as determined by +<parameter>device_info</parameter>-><structfield>num_btns</structfield>, +the function has no effect and returns +<symbol>False</symbol>. +Otherwise, +<function>XkbSetDeviceButtonActions</function> +sends a request to the server to change the actions for the specified buttons +and returns +<symbol>True</symbol>. </para> <para> If the actual request sent to the server involved illegal button numbers, a -<emphasis> -BadValue</emphasis> - protocol error is generated. If an invalid device identifier is specified in -device_info-><emphasis> -device_spec</emphasis> -, a BadKeyboard protocol error results. If the actual device specified in -<emphasis> -device_info</emphasis> --><emphasis> -device_spec</emphasis> - does not contain buttons and a request affecting buttons is made, a <emphasis> -BadMatch</emphasis> - protocol error is generated. +<errorname>BadValue</errorname> +protocol error is generated. If an invalid device identifier is specified in +device_info-><structfield>device_spec</structfield>, +a <errorname>BadKeyboard</errorname> +protocol error results. If the actual device specified in +<parameter>device_info</parameter>-><structfield>device_spec</structfield> +does not contain buttons and a request affecting buttons is made, a +<errorname>BadMatch</errorname> +protocol error is generated. </para> </sect1> <sect1 id='XkbExtensionDeviceNotify_Event'> <title>XkbExtensionDeviceNotify Event</title> +<indexterm significance="preferred" zone="XkbExtensionDeviceNotify_Event"> +<primary>events</primary><secondary><symbol>XkbExtensionDeviceNotify</symbol></secondary></indexterm> +<indexterm significance="preferred" zone="XkbExtensionDeviceNotify_Event"> +<primary><structname>XkbExtensionDeviceNotifyEvent</structname></primary></indexterm> <para> -The Xkb extension generates <emphasis> -XkbExtensionDeviceNotify</emphasis> - events when the status of an input extension device changes or when an attempt +The Xkb extension generates +<symbol>XkbExtensionDeviceNotify</symbol> +events when the status of an input extension device changes or when an attempt is made to use an Xkb feature that is not supported by a particular device. </para> @@ -1706,86 +1715,81 @@ delivered only to the client requesting the event.</para></note> <para> To track changes to the status of input extension devices or attempts to use -unsupported features of a device, select to receive <emphasis> -XkbExtensionDeviceNotify</emphasis> - events by calling either <emphasis> -XkbSelectEvents</emphasis> - or <emphasis> -XkbSelectEventDetails</emphasis> - (see section 4.3). +unsupported features of a device, select to receive +<symbol>XkbExtensionDeviceNotify</symbol> +events by calling either +<function>XkbSelectEvents</function> +or +<function>XkbSelectEventDetails</function> +(see <link linkend="Selecting_Xkb_Events">section 4.3</link>). </para> <para> -To receive <emphasis> -XkbExtensionDeviceNotify</emphasis> - events under all possible conditions, call <emphasis> -XkbSelectEvents</emphasis> - and pass <emphasis> -XkbExtensionDeviceNotifyMask</emphasis> - in both <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits</emphasis> -. +To receive +<symbol>XkbExtensionDeviceNotify</symbol> +events under all possible conditions, call +<function>XkbSelectEvents</function> +and pass +<symbol>XkbExtensionDeviceNotifyMask</symbol> +in both +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter>. </para> <para> -The <emphasis> -XkbExtensionDeviceNotify</emphasis> - event has no event details. However, you can call <emphasis> -XkbSelectEventDetails</emphasis> - using <emphasis> -XkbExtensionDeviceNotify</emphasis> - as the <emphasis> -event_type</emphasis> - and specifying <emphasis> -XkbAllExtensionDeviceMask</emphasis> - in <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits.</emphasis> - This has the same effect as a call to <emphasis> -XkbSelectEvents</emphasis> -. +The +<symbol>XkbExtensionDeviceNotify</symbol> +event has no event details. However, you can call +<function>XkbSelectEventDetails</function> +using +<symbol>XkbExtensionDeviceNotify</symbol> +as the +<structfield>event_type</structfield> +and specifying +<symbol>XkbAllExtensionDeviceEventsMask</symbol> +in +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter>. +This has the same effect as a call to +<function>XkbSelectEvents</function>. </para> <para> -The structure for <emphasis> -XkbExtensionDeviceNotify</emphasis> - events is: -</para> +The structure for +<symbol>XkbExtensionDeviceNotify</symbol> +events is: -<para><programlisting> +<programlisting> typedef struct { - int type; /* Xkb extension base event code */ - unsigned long serial; /* X server serial number for event */ - Bool send_event; /* <emphasis>True</emphasis> - => synthetically generated*/ - Display * display; /* server connection where event generated */ - Time time; /* server time when event generated */ - int xkb_type; /* <emphasis>XkbExtensionDeviceNotifyEvent</emphasis> */ - int device; /* Xkb device ID, will not be - <emphasis>XkbUseCoreKbd</emphasis> */ - unsigned int reason; /* reason for the event */ - unsigned int supported; /* mask of supported features */ - unsigned int unsupported; /* unsupported features this client + int type; /* Xkb extension base event code */ + unsigned long serial; /* X server serial number for event */ + Bool send_event; /* <symbol>True</symbol> ⇒ synthetically generated */ + Display * display; /* server connection where event generated */ + Time time; /* server time when event generated */ + int xkb_type; /* <structname>XkbExtensionDeviceNotifyEvent</structname> */ + int device; /* Xkb device ID, will not be <symbol>XkbUseCoreKbd</symbol> */ + unsigned int reason; /* reason for the event */ + unsigned int supported; /* mask of supported features */ + unsigned int unsupported; /* unsupported features this client attempted to use */ - int first_btn; /* first button that changed */ - int num_btns; /* number of buttons that changed */ - unsigned int leds_defined; /* indicators with names or maps */ - unsigned int led_state; /* current state of the indicators */ - int led_class; /* feedback class for LED changes */ - int led_id; /* feedback ID for LED changes */ -} <emphasis>XkbExtensionDeviceNotifyEvent</emphasis>; + int first_btn; /* first button that changed */ + int num_btns; /* number of buttons that changed */ + unsigned int leds_defined; /* indicators with names or maps */ + unsigned int led_state; /* current state of the indicators */ + int led_class; /* feedback class for LED changes */ + int led_id; /* feedback ID for LED changes */ +} <structname>XkbExtensionDeviceNotifyEvent</structname>; </programlisting></para> <para> -The <emphasis> -XkbExtensionDeviceNotify</emphasis> - event has fields enabling it to report changes in the state (on/off) of all of +The +<symbol>XkbExtensionDeviceNotify</symbol> +event has fields enabling it to report changes in the state (on/off) of all of the buttons for a device, but only for one LED feedback associated with a device. You will get multiple events when more than one LED feedback changes state or configuration. @@ -1795,43 +1799,44 @@ state or configuration. </sect1> <sect1 id='Tracking_Changes_to_Extension_Devices'> <title>Tracking Changes to Extension Devices</title> +<indexterm significance="preferred" zone="Tracking_Changes_to_Extension_Devices"> +<primary><structname>XkbDeviceChangesRec</structname></primary></indexterm> +<indexterm significance="preferred" zone="Tracking_Changes_to_Extension_Devices"> +<primary><structname>XkbDeviceLedChangesRec</structname></primary></indexterm> <para> -Changes to an Xkb extension device may be tracked by listening to <emphasis> -XkbDeviceExtensionNotify</emphasis> - events and accumulating the changes in an <emphasis> -XkbDeviceChangesRec</emphasis> - structure. The changes noted in the structure may then be used in subsequent +Changes to an Xkb extension device may be tracked by listening to +<symbol>XkbExtensionDeviceNotify</symbol> +events and accumulating the changes in an +<structname>XkbDeviceChangesRec</structname> +structure. The changes noted in the structure may then be used in subsequent operations to update either a server configuration or a local copy of an Xkb extension device configuration. The changes structure is defined as follows: -</para> -<para><programlisting> +<programlisting> typedef struct _XkbDeviceChanges { - unsigned int changed; /* bits indicating what has changed */ - unsigned short first_btn; /* number of first button which changed, - if any */ - unsigned short num_btns; /* number of buttons that have changed */ - XkbDeviceLedChangesRec leds; -} <emphasis>XkbDeviceChangesRec</emphasis>,*XkbDeviceChangesPtr; -</programlisting></para> + unsigned int changed; /* bits indicating what has changed */ + unsigned short first_btn; /* number of first button which changed, + if any */ + unsigned short num_btns; /* number of buttons that have changed */ + XkbDeviceLedChangesRec leds; +} <structname>XkbDeviceChangesRec</structname>, *XkbDeviceChangesPtr; -<para><programlisting> typedef struct _XkbDeviceLedChanges { - unsigned short led_class; /* class of this indicator feedback bundle */ - unsigned short led_id; /* ID of this indicator feedback bundle */ - unsigned int names; /* bits indicating which names have changed */ - unsigned int maps; /* bits indicating which maps have changed */ - struct _XkbDeviceLedChanges *next; /* link to indicator change record - for next set */ -} <emphasis>XkbDeviceLedChangesRec</emphasis>,*XkbDeviceLedChangesPtr; + unsigned short led_class; /* class of this indicator feedback bundle */ + unsigned short led_id; /* ID of this indicator feedback bundle */ + unsigned int names; /* bits indicating which names have changed */ + unsigned int maps; /* bits indicating which maps have changed */ + struct _XkbDeviceLedChanges *next; /* link to indicator change record + for next set */ +} <structname>XkbDeviceLedChangesRec</structname>, *XkbDeviceLedChangesPtr; </programlisting></para> <para> A local description of the configuration and state of a device may be kept in -an <emphasis> -XkbDeviceInfoRec</emphasis> - structure. The actual state or configuration of the device may change because +an +<structname>XkbDeviceInfoRec</structname> +structure. The actual state or configuration of the device may change because of XkbSetDeviceInfo and XkbSetButtonActions requests made by clients or by user interaction with the device. The X server sends an XkbExtensionDeviceNotify event to all interested clients when the state of any buttons or indicators or @@ -1847,81 +1852,84 @@ server. <para> -To note device changes reported in an <emphasis> -XkbExtensionDeviceNotify</emphasis> - event, use XkbNoteDeviceChanges. -</para> - -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbNoteDeviceChanges</emphasis> - (<emphasis> -old, new, wanted</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDeviceChangesPtr <emphasis> -old</emphasis> -; /* structure tracking state changes */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbExtensionDeviceNotifyEvent * <emphasis> -new</emphasis> -; /* event indicating state changes */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -wanted</emphasis> -; /* mask indicating changes to note */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -The wanted field specifies the changes that should be noted in <emphasis> -old</emphasis> -, and is composed of the bitwise inclusive OR of one or more of the masks from -Table 21.1<emphasis> -.</emphasis> - The <emphasis> -reason</emphasis> - field of the event in <emphasis> -new</emphasis> - indicates the types of changes the event is reporting. <emphasis> -XkbNoteDeviceChanges</emphasis> - updates the <emphasis> -XkbDeviceChangesRec</emphasis> - specified by <emphasis> -old</emphasis> - with the changes that are both specified in <emphasis> -wanted</emphasis> - and contained in <emphasis> -new</emphasis> --><emphasis> -reason</emphasis> -. +To note device changes reported in an +<symbol>XkbExtensionDeviceNotify</symbol> +event, use XkbNoteDeviceChanges. +</para> + +<indexterm significance="preferred" zone="XkbNoteDeviceChanges"><primary><function>XkbNoteDeviceChanges</function></primary></indexterm> +<funcsynopsis id="XkbNoteDeviceChanges"> + <funcprototype> + <funcdef>void <function>XkbNoteDeviceChanges</function></funcdef> +<!-- ( +<parameter>old, new, wanted</parameter> +) --> + + <paramdef>XkbDeviceChangesPtr <parameter>old</parameter></paramdef> + <paramdef>XkbExtensionDeviceNotifyEvent *<parameter>new</parameter></paramdef> + <paramdef>unsigned int <parameter>wanted</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>old</parameter> + </term> + <listitem> + <para> + structure tracking state changes + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>new</parameter> + </term> + <listitem> + <para> + event indicating state changes + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>wanted</parameter> + </term> + <listitem> + <para> + mask indicating changes to note + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The wanted field specifies the changes that should be noted in +<parameter>old</parameter>, +and is composed of the bitwise inclusive OR of one or more of the masks from +<link linkend="table21.1">Table 21.1</link>. +The +<structfield>reason</structfield> +field of the event in +<parameter>new</parameter> +indicates the types of changes the event is reporting. +<function>XkbNoteDeviceChanges</function> +updates the +<structname>XkbDeviceChangesRec</structname> +specified by +<parameter>old</parameter> +with the changes that are both specified in +<parameter>wanted</parameter> +and contained in +<parameter>new</parameter>-><structfield>reason</structfield>. </para> <para> To update a local copy of the state and configuration of an X input extension -device with the changes previously noted in an <emphasis> -XkbDeviceChangesRec</emphasis> - structure, use XkbGetDeviceInfoChanges. +device with the changes previously noted in an +<structname>XkbDeviceChangesRec</structname> +structure, use XkbGetDeviceInfoChanges. </para> @@ -1932,62 +1940,66 @@ XkbGetDeviceInfoChanges. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetDeviceInfoChanges</emphasis> -(<emphasis> -dpy</emphasis> -, <emphasis> -device_info</emphasis> -, changes) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDeviceInfoPtr device_info; /* structure to update with -results */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDeviceChangesPtr <emphasis> -changes</emphasis> -; /* contains notes of changes that have occurred */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbGetDeviceInfoChanges"><primary><function>XkbGetDeviceInfoChanges</function></primary></indexterm> +<funcsynopsis id="XkbGetDeviceInfoChanges"> + <funcprototype> + <funcdef>Status <function>XkbGetDeviceInfoChanges</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>device_info</parameter>, +changes) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>XkbDeviceInfoPtr <parameter>device_info</parameter></paramdef> + <paramdef>XkbDeviceChangesPtr <parameter>changes</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_info</parameter> + </term> + <listitem> + <para> + structure to update with results + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>changes</parameter> + </term> + <listitem> + <para> + contains notes of changes that have occurred + </para> + </listitem> + </varlistentry> +</variablelist> <para> The changes->changed field indicates which attributes of the device -specified in <emphasis> -changes</emphasis> --><emphasis> -device</emphasis> - have changed. The parameters describing the changes are contained in the other -fields of <emphasis> -changes</emphasis> -. <emphasis> -XkbGetDeviceInfoChanges</emphasis> - uses that information to call XkbGetDeviceInfo to obtain the current status of +specified in +<parameter>changes</parameter>-><structfield>device</structfield> +have changed. The parameters describing the changes are contained in the other +fields of +<parameter>changes</parameter>. +<function>XkbGetDeviceInfoChanges</function> +uses that information to call XkbGetDeviceInfo to obtain the current status of those attributes that have changed. It then updates the local description of -the device in <emphasis> -device_info</emphasis> - with the new information. +the device in +<parameter>device_info</parameter> +with the new information. </para> @@ -1997,59 +2009,61 @@ XkbDeviceChangesRec, use XkbChangeDeviceInfo. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbChangeDeviceInfo</emphasis> - (<emphasis> -dpy, device_info, changes</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDeviceInfoPtr <emphasis> -device_info</emphasis> -; /* local copy of device state and configuration */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDeviceChangesPtr <emphasis> -changes</emphasis> -; /* note specifying changes in <emphasis> -device_info</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbChangeDeviceInfo</emphasis> - updates the server’s description of the device specified in <emphasis> -device_info</emphasis> --><emphasis> -device_spec</emphasis> - with the changes specified in <emphasis> -changes</emphasis> - and contained in <emphasis> -device_info</emphasis> -. The update is made by an XkbSetDeviceInfo request. +<indexterm significance="preferred" zone="XkbChangeDeviceInfo"><primary><function>XkbChangeDeviceInfo</function></primary></indexterm> +<funcsynopsis id="XkbChangeDeviceInfo"> + <funcprototype> + <funcdef>Bool <function>XkbChangeDeviceInfo</function></funcdef> +<!-- ( +<parameter>dpy, device_info, changes</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>XkbDeviceInfoPtr <parameter>device_info</parameter></paramdef> + <paramdef>XkbDeviceChangesPtr <parameter>changes</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_info</parameter> + </term> + <listitem> + <para> + local copy of device state and configuration + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>changes</parameter> + </term> + <listitem> + <para> + note specifying changes in <parameter>device_info</parameter> + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbChangeDeviceInfo</function> +updates the server’s description of the device specified in +<parameter>device_info</parameter>-><structfield>device_spec</structfield> +with the changes specified in +<parameter>changes</parameter> +and contained in +<parameter>device_info</parameter>. +The update is made by an XkbSetDeviceInfo request. </para> </sect1> |