diff options
Diffstat (limited to 'libX11/specs/XKB/ch10.xml')
| -rw-r--r-- | libX11/specs/XKB/ch10.xml | 7419 |
1 files changed, 3708 insertions, 3711 deletions
diff --git a/libX11/specs/XKB/ch10.xml b/libX11/specs/XKB/ch10.xml index b7f306938..72727f224 100644 --- a/libX11/specs/XKB/ch10.xml +++ b/libX11/specs/XKB/ch10.xml @@ -1,11 +1,21 @@ +<?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='Keyboard_Controls'> <title>Keyboard Controls</title> +<indexterm significance="preferred" zone="Keyboard_Controls"> +<primary>controls</primary></indexterm> +<indexterm significance="preferred" zone="Keyboard_Controls"> +<primary>server controls</primary></indexterm> +<indexterm significance="preferred" zone="Keyboard_Controls"> +<primary>controls</primary><secondary>server</secondary></indexterm> + <para> The Xkb extension is composed of two parts: a server extension, and a client-side X library extension. This chapter discusses functions used to modify controls effecting the behavior of the server portion of the Xkb -extension. Chapter 11 discusses functions used to modify controls that affect +extension. <xref linkend="X_Library_Controls" /> discusses functions used to modify controls that affect only the behavior of the client portion of the extension; those controls are known as Library Controls. </para> @@ -14,15 +24,23 @@ known as Library Controls. <para> Xkb contains control features that affect the entire keyboard, known as global keyboard controls. Some of the controls may be selectively enabled and -disabled; these controls are known as the <emphasis> -Boolean Controls</emphasis> -. Boolean Controls can be turned on or off under program control and can also +disabled; these controls are known as the +<firstterm>Boolean Controls</firstterm>. +<indexterm significance="preferred" zone="Keyboard_Controls"> +<primary>boolean controls</primary></indexterm> +<indexterm significance="preferred" zone="Keyboard_Controls"> +<primary>controls</primary><secondary>boolean</secondary></indexterm> +Boolean Controls can be turned on or off under program control and can also be automatically set to an on or off condition when a client program exits. The -remaining controls, known as the <emphasis> -Non-Boolean Controls</emphasis> -, are always active. The<emphasis> - XkbControlsRec</emphasis> - structure describes the current state of most of the global controls and the +remaining controls, known as the +<firstterm>Non-Boolean Controls</firstterm>, +<indexterm significance="preferred" zone="Keyboard_Controls"> +<primary>non-boolean controls</primary></indexterm> +<indexterm significance="preferred" zone="Keyboard_Controls"> +<primary>controls</primary><secondary>non-boolean</secondary></indexterm> +are always active. The +<structname>XkbControlsRec</structname> +structure describes the current state of most of the global controls and the attributes effecting the behavior of each of these Xkb features. This chapter describes the Xkb controls and how to manipulate them. </para> @@ -32,31 +50,32 @@ describes the Xkb controls and how to manipulate them. There are two possible components for each of the Boolean Controls: attributes describing how the control should work, and a state describing whether the behavior as a whole is enabled or disabled. The attributes and state for most -of these controls are held in the <emphasis> -XkbControlsRec</emphasis> - structure (see section 10.8). +of these controls are held in the +<structname>XkbControlsRec</structname> +structure (see <link linkend="The_XkbControlsRec_Structure">section 10.8</link>). </para> <para> You can manipulate the Xkb controls individually, via convenience functions, or -as a whole. To treat them as a group, modify an <emphasis> -XkbControlsRec</emphasis> - structure to describe all of the changes to be made, and then pass that -structure and appropriate flags to an Xkb library function, or use a <emphasis> -XkbControlsChangesRec</emphasis> - (see section 10.10.1) to reduce network traffic. When using a convenience -function to manipulate one control individually, you do not use an <emphasis> -XkbControlsRec</emphasis> - structure directly. +as a whole. To treat them as a group, modify an +<structname>XkbControlsRec</structname> +structure to describe all of the changes to be made, and then pass that +structure and appropriate flags to an Xkb library function, or use a +<structname>XkbControlsChangesRec</structname> +(see <link linkend="The_XkbControlsChangesRec_Structure">section 10.10.1</link>) to reduce network traffic. When using a convenience +function to manipulate one control individually, you do not use an +<structname>XkbControlsRec</structname> +structure directly. </para> <para> -The Xkb controls are grouped as shown in Table 10.1. <!-- xref --> +The Xkb controls are grouped as shown in +<link linkend="table10.1">Table 10.1</link>. </para> -<table frame='topbot'> +<table id='table10.1' frame='topbot'> <title>Xkb Keyboard Controls</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -192,9 +211,9 @@ The Xkb controls are grouped as shown in Table 10.1. <!-- xref --> <para> The individual categories and controls are described first, together with -functions for manipulating them. A description of the <emphasis> -XkbControlsRec</emphasis> - structure and the general functions for dealing with all of the controls at +functions for manipulating them. A description of the +<structname>XkbControlsRec</structname> +structure and the general functions for dealing with all of the controls at once follow at the end of the chapter. </para> @@ -203,12 +222,10 @@ once follow at the end of the chapter. <para> Enable and disable the boolean controls under program control by using the -<emphasis> -EnabledControls</emphasis> - control; enable and disable them upon program exit by configuring the -<emphasis> -AutoReset</emphasis> - control. +<emphasis>EnabledControls</emphasis> +control; enable and disable them upon program exit by configuring the +<emphasis>AutoReset</emphasis> +control. </para> @@ -216,124 +233,130 @@ AutoReset</emphasis> <title>The EnabledControls Control</title> <para> -The <emphasis> -EnabledControls</emphasis> - control is a bit mask where each bit that is turned on means the corresponding +The +<emphasis>EnabledControls</emphasis> +control is a bit mask where each bit that is turned on means the corresponding control is enabled, and when turned off, disabled. It corresponds to the -<emphasis> -enabled_ctrls</emphasis> - field of an <emphasis> -XkbControlsRec</emphasis> - structure (see section 10.8). The bits describing which controls are turned on -or off are defined in Table 10.7. <!-- xref --> -</para> - - -<para> -Use <emphasis> -XkbChangeEnabledControls</emphasis> - to manipulate the <emphasis> -EnabledControls</emphasis> - control. -</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> -XkbChangeEnabledControls</emphasis> -(<emphasis> -dpy</emphasis> -, <emphasis> -device_spec</emphasis> -, <emphasis> -mask</emphasis> -,<emphasis> - values</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* keyboard device to modify */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -mask</emphasis> -; /* 1 bit -> controls to enable / disable */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -values</emphasis> -; /* 1 bit => enable, 0 bit => disable */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -The <emphasis> -mask</emphasis> - parameter specifies the boolean controls to be enabled or disabled, and the -<emphasis> -values</emphasis> - mask specifies the new state for those controls. Valid values for both of +<structfield>enabled_ctrls</structfield> +field of an +<structname>XkbControlsRec</structname> +structure (see <link linkend="The_XkbControlsRec_Structure">section 10.8</link>). The bits describing which controls are turned on +or off are defined in <link linkend="table10.7">Table 10.7</link>. +</para> + + +<para> +Use +<function>XkbChangeEnabledControls</function> +to manipulate the +<emphasis>EnabledControls</emphasis> +control. +</para> + +<indexterm significance="preferred" zone="XkbChangeEnabledControls"><primary><function>XkbChangeEnabledControls</function></primary></indexterm> +<funcsynopsis id="XkbChangeEnabledControls"> + <funcprototype> + <funcdef>Bool <function>XkbChangeEnabledControls</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>device_spec</parameter>, +<parameter>mask</parameter>, +<parameter>values</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int <parameter>mask</parameter></paramdef> + <paramdef>unsigned int <parameter>values</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + keyboard device to modify + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>mask</parameter> + </term> + <listitem> + <para> + 1 bit → controls to enable / disable + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>values</parameter> + </term> + <listitem> + <para> + 1 bit ⇒ enable, 0 bit ⇒ disable + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<parameter>mask</parameter> +parameter specifies the boolean controls to be enabled or disabled, and the +<parameter>values</parameter> +mask specifies the new state for those controls. Valid values for both of these masks are composed of a bitwise inclusive OR of bits taken from the set -of mask bits in Table 10.7, using only those masks with "ok" in the <emphasis> -enabled_ctrls</emphasis> - column. +of mask bits in <link linkend="table10.7">Table 10.7</link>, +using only those masks with <quote>ok</quote> in the +<structfield>enabled_ctrls</structfield> +column. </para> <para> If the X server does not support a compatible version of Xkb or the Xkb -extension has not been properly initialized, <emphasis> -XkbChangeEnabledControls</emphasis> - returns <emphasis> -False</emphasis> -; otherwise, it sends the request to the X server and returns <emphasis> -True</emphasis> -. +extension has not been properly initialized, +<function>XkbChangeEnabledControls</function> +returns +<symbol>False</symbol>; +otherwise, it sends the request to the X server and returns +<symbol>True</symbol>. </para> <para> -Note that the <emphasis> -EnabledControls</emphasis> - control only enables and disables controls; it does not configure them. Some -controls, such as the <emphasis> -AudibleBell</emphasis> - control, have no configuration attributes and are therefore manipulated solely +Note that the +<emphasis>EnabledControls</emphasis> +control only enables and disables controls; it does not configure them. Some +controls, such as the +<emphasis>AudibleBell</emphasis> +control, have no configuration attributes and are therefore manipulated solely by enabling and disabling them. Others, however, have additional attributes to -configure their behavior. For example, the <emphasis> -RepeatControl</emphasis> - control uses <emphasis> -repeat_delay</emphasis> - and <emphasis> -repeat_interval</emphasis> - fields to describe the timing behavior of keys that repeat. The <emphasis> -RepeatControl</emphasis> - behavior is turned on or off depending on the value of the <emphasis> -XkbRepeatKeysMask</emphasis> - bit, but you must use other means, as described in this chapter, to configure +configure their behavior. For example, the +<emphasis>RepeatControl</emphasis> +control uses +<structfield>repeat_delay</structfield> +and +<structfield>repeat_interval</structfield> +fields to describe the timing behavior of keys that repeat. The +<emphasis>RepeatControl</emphasis> +behavior is turned on or off depending on the value of the +<symbol>XkbRepeatKeysMask</symbol> +bit, but you must use other means, as described in this chapter, to configure its behavior in detail. </para> @@ -347,255 +370,242 @@ You can configure the boolean controls to automatically be enabled or disabled when a program exits. This capability is controlled via two masks maintained in the X server on a per-client basis. There is no client-side Xkb data structure corresponding to these masks. Whenever the client exits for any reason, any -boolean controls specified in the <emphasis> -auto-reset mask</emphasis> - are set to the corresponding value from the <emphasis> -auto-reset values</emphasis> - mask. This makes it possible for clients to "clean up after themselves" +boolean controls specified in the +<firstterm>auto-reset mask</firstterm> +<indexterm significance="preferred" zone="The_AutoReset_Control"> +<primary>auto-reset mask</primary></indexterm> +<indexterm significance="preferred" zone="The_AutoReset_Control"> +<primary>mask</primary><secondary>auto-reset</secondary></indexterm> +are set to the corresponding value from the +<firstterm>auto-reset values</firstterm> +mask. This makes it possible for clients to "clean up after themselves" automatically, even if abnormally terminated. The bits used in the masks -correspond to the <emphasis> -EnabledControls</emphasis> - control bits. +correspond to the +<emphasis>EnabledControls</emphasis> +control bits. </para> <para> For example, a client that replaces the keyboard bell with some other audible -cue might want to turn off the <emphasis> -AudibleBell</emphasis> - control to prevent the server from also generating a sound and avoid -cacophony. If the client were to exit without resetting the <emphasis> -AudibleBell </emphasis> -control, the user would be left without any feedback at all. Setting <emphasis> -AudibleBell</emphasis> - in both the auto-reset mask and auto-reset values guarantees that the audible +cue might want to turn off the +<emphasis>AudibleBell</emphasis> +control to prevent the server from also generating a sound and avoid +cacophony. If the client were to exit without resetting the +<emphasis>AudibleBell</emphasis> +control, the user would be left without any feedback at all. Setting +<emphasis>AudibleBell</emphasis> +in both the auto-reset mask and auto-reset values guarantees that the audible bell will be turned back on when the client exits. </para> <para> -To get the current values of the auto-reset controls, use <emphasis> -XkbGetAutoResetControls</emphasis> -. -</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> -XkbGetAutoResetControls</emphasis> -(<emphasis> -dpy</emphasis> -, <emphasis> -auto_ctrls</emphasis> -, <emphasis> -auto_values</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> -auto_ctrls</emphasis> -; /* specifies which bits in <emphasis> -auto_values</emphasis> - are relevant */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> -auto_values</emphasis> -; /* 1 bit => corresponding control has auto-reset on */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetAutoResetControls</emphasis> - backfills <emphasis> -auto_ctrls</emphasis> - and <emphasis> -auto_values</emphasis> - with the <emphasis> -AutoReset</emphasis> - control attributes for this particular client. It returns <emphasis> -True</emphasis> - if successful, and <emphasis> -False</emphasis> - otherwise. -</para> - - -<para> -To change the current values of the <emphasis> -AutoReset</emphasis> - control attributes, use <emphasis> -XkbSetAutoResetControls.</emphasis> -</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> -XkbSetAutoResetControls</emphasis> -(<emphasis> -dpy</emphasis> -, <emphasis> -changes</emphasis> -,<emphasis> - auto_ctrls</emphasis> -, <emphasis> -auto_values</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -changes</emphasis> -; /* controls for which to change auto-reset values */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> -auto_ctrls</emphasis> -; /* controls from changes that should auto reset */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> -auto_values</emphasis> -; /* 1 bit => auto-reset on */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSetAutoResetControls changes the auto-reset status and associated auto-reset -values for the controls selected by </emphasis> -<emphasis> -changes</emphasis> -<emphasis> -. For any control selected by </emphasis> -<emphasis> -changes</emphasis> -<emphasis> -, if the corresponding bit is set in </emphasis> -<emphasis> -auto_ctrls</emphasis> -<emphasis> -, the control is configured to auto-reset when the client exits. If the -corresponding bit in </emphasis> -<emphasis> -auto_values</emphasis> -<emphasis> - is on, the control is turned on when the client exits; if zero, the control is -turned off when the client exits.</emphasis> - For any control selected by <emphasis> -changes</emphasis> -, if the corresponding bit is not set in <emphasis> -auto_ctrls</emphasis> -, the control is configured to not reset when the client exits. For example: -</para> - - -<para> -<emphasis> -To leave the auto-reset controls for </emphasis> -<emphasis> -StickyKeys</emphasis> -<emphasis> - the way they are:</emphasis> -</para> +To get the current values of the auto-reset controls, use +<function>XkbGetAutoResetControls</function>. +</para> + +<indexterm significance="preferred" zone="XkbGetAutoResetControls"><primary><function>XkbGetAutoResetControls</function></primary></indexterm> +<funcsynopsis id="XkbGetAutoResetControls"> + <funcprototype> + <funcdef>Bool <function>XkbGetAutoResetControls</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>auto_ctrls</parameter>, +<parameter>auto_values</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int *<parameter>auto_ctrls</parameter></paramdef> + <paramdef>unsigned int *<parameter>auto_values</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>auto_ctrls</parameter> + </term> + <listitem> + <para> + specifies which bits in <parameter>auto_values</parameter> are relevant + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>auto_values</parameter> + </term> + <listitem> + <para> + 1 bit ⇒ corresponding control has auto-reset on + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetAutoResetControls</function> +backfills +<parameter>auto_ctrls</parameter> +and +<parameter>auto_values</parameter> +with the +<emphasis>AutoReset</emphasis> +control attributes for this particular client. It returns +<symbol>True</symbol> +if successful, and +<symbol>False</symbol> +otherwise. +</para> + + +<para> +To change the current values of the +<emphasis>AutoReset</emphasis> +control attributes, use +<function>XkbSetAutoResetControls</function>. +</para> + + +<indexterm significance="preferred" zone="XkbSetAutoResetControls"><primary><function>XkbSetAutoResetControls</function></primary></indexterm> +<funcsynopsis id="XkbSetAutoResetControls"> + <funcprototype> + <funcdef>Bool <function>XkbSetAutoResetControls</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>changes</parameter>, +<parameter>auto_ctrls</parameter>, +<parameter>auto_values</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>changes</parameter></paramdef> + <paramdef>unsigned int *<parameter>auto_ctrls</parameter></paramdef> + <paramdef>unsigned int *<parameter>auto_values</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>changes</parameter> + </term> + <listitem> + <para> + controls for which to change auto-reset values + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>auto_ctrls</parameter> + </term> + <listitem> + <para> + controls from changes that should auto reset + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>auto_values</parameter> + </term> + <listitem> + <para> + 1 bit ⇒ auto-reset on + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSetAutoResetControls</function> +changes the auto-reset status and associated auto-reset +values for the controls selected by +<parameter>changes</parameter>. +For any control selected by +<parameter>changes</parameter>, +if the corresponding bit is set in +<parameter>auto_ctrls</parameter>, +the control is configured to auto-reset when the client exits. If the +corresponding bit in +<parameter>auto_values</parameter> +is on, the control is turned on when the client exits; +if zero, the control is turned off when the client exits. +For any control selected by +<parameter>changes</parameter>, +if the corresponding bit is not set in +<parameter>auto_ctrls</parameter>, +the control is configured to not reset when the client exits. For example: +</para> + + +<para> +To leave the auto-reset controls for +<emphasis>StickyKeys</emphasis> +the way they are: -<para><programlisting> -ok = XkbSetAutoResetControls(dpy, 0, 0, 0); +<programlisting> + ok = XkbSetAutoResetControls(dpy, 0, 0, 0); </programlisting></para> <para> -<emphasis> -To change the auto-reset controls so that </emphasis> -<emphasis> -StickyKeys</emphasis> -<emphasis> - are unaffected when the client exits:</emphasis> -</para> +To change the auto-reset controls so that +<emphasis>StickyKeys</emphasis> +are unaffected when the client exits: -<para><programlisting> -ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, 0, 0); +<programlisting> + ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, 0, 0); </programlisting></para> <para> -<emphasis> -To change the auto-reset controls so that </emphasis> -<emphasis> -StickyKeys</emphasis> -<emphasis> - are turned off when the client exits:</emphasis> -</para> +To change the auto-reset controls so that +<emphasis>StickyKeys</emphasis> +are turned off when the client exits: -<para><programlisting> -ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, XkbStickyKeysMask, 0); +<programlisting> + ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, XkbStickyKeysMask, 0); </programlisting></para> <para> -<emphasis> -To change the auto-reset controls so that </emphasis> -<emphasis> -StickyKeys</emphasis> -<emphasis> - are turned on when the client exits:</emphasis> -</para> +To change the auto-reset controls so that +<emphasis>StickyKeys</emphasis> +are turned on when the client exits: -<para><programlisting> -ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, XkbStickyKeysMask, -XkbStickyKeysMask); +<programlisting> + ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, XkbStickyKeysMask, + XkbStickyKeysMask); </programlisting></para> <para> -<emphasis> -XkbSetAutoResetControls</emphasis> - backfills <emphasis> -auto_ctrls</emphasis> - and <emphasis> -auto_values</emphasis> - with the auto-reset controls for this particular client. Note that all of the +<function>XkbSetAutoResetControls</function> +backfills +<parameter>auto_ctrls</parameter> +and +<parameter>auto_values</parameter> +with the auto-reset controls for this particular client. Note that all of the bits are valid in the returned values, not just the ones selected in the -<emphasis> -changes</emphasis> - mask. +<parameter>changes</parameter> +mask. </para> @@ -605,9 +615,9 @@ changes</emphasis> <title>Control for Bell Behavior</title> <para> -The X server’s generation of sounds is controlled by the <emphasis> -AudibleBell</emphasis> - control. Configuration of different bell sounds is discussed in Chapter 9. +The X server’s generation of sounds is controlled by the +<emphasis>AudibleBell</emphasis> +control. Configuration of different bell sounds is discussed in <xref linkend="Bells" />. </para> @@ -615,17 +625,17 @@ AudibleBell</emphasis> <title>The AudibleBell Control</title> <para> -The <emphasis> -AudibleBell</emphasis> - control is a boolean control that has no attributes. As such, you may enable -and disable it using either the <emphasis> -EnabledControls</emphasis> - control or the <emphasis> -AutoReset</emphasis> - control discussed in section 10.1.1. When enabled, protocol requests to <!-- xref --> +The +<emphasis>AudibleBell</emphasis> +control is a boolean control that has no attributes. As such, you may enable +and disable it using either the +<emphasis>EnabledControls</emphasis> +control or the +<emphasis>AutoReset</emphasis> +control discussed in <link linkend="The_EnabledControls_Control">section 10.1.1</link>. When enabled, protocol requests to generate a sound result in the X server actually producing a real sound; when disabled, requests to the server to generate a sound are ignored unless the -sound is forced. See section 9.2. <!-- xref --> +sound is forced. See <link linkend="Audible_Bells">section 9.2</link>. </para> @@ -634,22 +644,23 @@ sound is forced. See section 9.2. <!-- xref --> <sect1 id='Controls_for_Repeat_Key_Behavior'> <title>Controls for Repeat Key Behavior</title> +<indexterm significance="preferred" zone="Controls_for_Repeat_Key_Behavior"> +<primary>auto-repeat</primary><secondary>controls</secondary></indexterm> + <para> The repeating behavior of keyboard keys is governed by three controls, the -<emphasis> -PerKeyRepeat</emphasis> - control, which is always active, and the <emphasis> -RepeatKeys</emphasis> - and <emphasis> -DetectableAutorepeat</emphasis> - controls, which are boolean controls that may be enabled and disabled. -<emphasis> -PerKeyRepeat</emphasis> - determines which keys are allowed to repeat. <emphasis> -RepeatKeys</emphasis> - governs the behavior of an individual key when it is repeating. <emphasis> -DetectableAutorepeat</emphasis> - allows a client to detect when a key is repeating as a result of being held +<emphasis>PerKeyRepeat</emphasis> +control, which is always active, and the +<emphasis>RepeatKeys</emphasis> +and +<emphasis>DetectableAutorepeat</emphasis> +controls, which are boolean controls that may be enabled and disabled. +<emphasis>PerKeyRepeat</emphasis> +determines which keys are allowed to repeat. +<emphasis>RepeatKeys</emphasis> +governs the behavior of an individual key when it is repeating. +<emphasis>DetectableAutorepeat</emphasis> +allows a client to detect when a key is repeating as a result of being held down. </para> @@ -658,20 +669,20 @@ down. <title>The PerKeyRepeat Control</title> <para> -The <emphasis> -PerKeyRepeat</emphasis> - control is a bitmask long enough to contain a bit for each key on the device; -it determines which individual keys are allowed to repeat. The Xkb <emphasis> -PerKeyRepeat</emphasis> - control provides no functionality different from that available via the core X +The +<emphasis>PerKeyRepeat</emphasis> +control is a bitmask long enough to contain a bit for each key on the device; +it determines which individual keys are allowed to repeat. The Xkb +<emphasis>PerKeyRepeat</emphasis> +control provides no functionality different from that available via the core X protocol. There are no convenience functions in Xkb for manipulating this -control. The <emphasis> -PerKeyRepeat</emphasis> - control settings are carried in the <emphasis> -per_key_repeat</emphasis> - field of an <emphasis> -XkbControlsRec</emphasis> - structure, discussed in section 10.8. <!-- xref --> +control. The +<emphasis>PerKeyRepeat</emphasis> +control settings are carried in the +<structfield>per_key_repeat</structfield> +field of an +<structname>XkbControlsRec</structname> +structure, discussed in <link linkend="The_XkbControlsRec_Structure">section 10.8</link>. </para> @@ -681,192 +692,200 @@ XkbControlsRec</emphasis> <para> The core protocol allows only control over whether or not the entire keyboard -or individual keys should auto-repeat when held down. <emphasis> -RepeatKeys</emphasis> - is a boolean control that extends this capability by adding control over the -delay until a key begins to repeat and the rate at which it repeats. <emphasis> -RepeatKeys</emphasis> - is coupled with the core auto-repeat control: when <emphasis> -RepeatKeys</emphasis> - is enabled or disabled, the core auto-repeat is enabled or disabled and vice +or individual keys should auto-repeat when held down. +<emphasis>RepeatKeys</emphasis> +is a boolean control that extends this capability by adding control over the +delay until a key begins to repeat and the rate at which it repeats. +<emphasis>RepeatKeys</emphasis> +is coupled with the core auto-repeat control: when +<emphasis>RepeatKeys</emphasis> +is enabled or disabled, the core auto-repeat is enabled or disabled and vice versa. </para> <para> -Auto-repeating keys are controlled by two attributes. The first, <emphasis> -timeout</emphasis> -, is the delay after the initial press of an auto-repeating key and the first -generated repeat event. The second, <emphasis> -interval</emphasis> -, is the delay between all subsequent generated repeat events. As with all +Auto-repeating keys are controlled by two attributes. The first, +<firstterm>timeout</firstterm>, +is the delay after the initial press of an auto-repeating key and the first +generated repeat event. The second, +<firstterm>interval</firstterm>, +is the delay between all subsequent generated repeat events. As with all boolean controls, configuring the attributes that determine how the control -operates does not automatically enable the control as a whole; see section 10.1. -</para> - - -<para> -To get the current attributes of the <emphasis> -RepeatKeys</emphasis> - control for a keyboard device, use <emphasis> -XkbGetAutoRepeatRate</emphasis> -. -</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> -XkbGetAutoRepeatRate</emphasis> -(<emphasis> -display, device_spec, timeout_rtrn, interval_rtrn</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - device_spec</emphasis> -; /* desired device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -* timeout_rtrn</emphasis> -; /* backfilled with initial repeat delay, ms */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -* interval_rtrn</emphasis> -; /* backfilled with subsequent repeat delay, ms */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetAutoRepeatRate</emphasis> - queries the server for the current values of the <emphasis> -RepeatControls</emphasis> - control attributes, backfills <emphasis> -timeout_rtrn</emphasis> - and <emphasis> -interval_rtrn</emphasis> - with them, and returns <emphasis> -True</emphasis> -. If a compatible version of the Xkb extension is not available in the server -<emphasis> -XkbGetAutoRepeatRate</emphasis> - returns <emphasis> -False</emphasis> -. +operates does not automatically enable the control as a whole; see <link linkend="Controls_that_Enable_and_Disable_Other_Controls">section 10.1</link>. +</para> + + +<para> +To get the current attributes of the +<emphasis>RepeatKeys</emphasis> +control for a keyboard device, use +<function>XkbGetAutoRepeatRate</function>. +</para> + +<indexterm significance="preferred" zone="XkbGetAutoRepeatRate"><primary><function>XkbGetAutoRepeatRate</function></primary></indexterm> +<funcsynopsis id="XkbGetAutoRepeatRate"> + <funcprototype> + <funcdef>Bool <function>XkbGetAutoRepeatRate</function></funcdef> +<!-- ( +<parameter>display, device_spec, timeout_rtrn, interval_rtrn</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int *<parameter>timeout_rtrn</parameter></paramdef> + <paramdef>unsigned int *<parameter>interval_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + desired device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>timeout_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with initial repeat delay, ms + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>interval_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with subsequent repeat delay, ms + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetAutoRepeatRate</function> +queries the server for the current values of the +<emphasis>RepeatControls</emphasis> +control attributes, backfills +<parameter>timeout_rtrn</parameter> +and +<parameter>interval_rtrn</parameter> +with them, and returns +<symbol>True</symbol>. +If a compatible version of the Xkb extension is not available in the server +<function>XkbGetAutoRepeatRate</function> +returns +<symbol>False</symbol>. </para> <para> To set the attributes of the RepeatKeys control for a keyboard device, use -<emphasis> -XkbSetAutoRepeatRate</emphasis> -. -</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> -XkbSetAutoRepeatRate</emphasis> -(<emphasis> -display, device_spec, timeout, interval</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device to configure, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - timeout</emphasis> -; /* initial delay, ms */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - interval</emphasis> -; /* delay between repeats, ms */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSetAutoRepeatRate</emphasis> - sends a request to the X server to configure the <emphasis> -AutoRepeat</emphasis> - control attributes to the values specified in <emphasis> -timeout</emphasis> - and <emphasis> -interval</emphasis> -. -</para> - - -<para> -<emphasis> -XkbSetAutoRepeatRate</emphasis> - does not wait for a reply; it normally returns <emphasis> -True</emphasis> -. Specifying a zero value for either <emphasis> -timeout</emphasis> - or <emphasis> -interval</emphasis> - causes the server to generate a <emphasis> -BadValue</emphasis> - protocol error. If a compatible version of the Xkb extension is not available -in the server, <emphasis> -XkbSetAutoRepeatRate</emphasis> - returns <emphasis> -False</emphasis> -. +<function>XkbSetAutoRepeatRate</function>. +</para> + + +<indexterm significance="preferred" zone="XkbSetAutoRepeatRate"><primary><function>XkbSetAutoRepeatRate</function></primary></indexterm> +<funcsynopsis id="XkbSetAutoRepeatRate"> + <funcprototype> + <funcdef>Bool <function>XkbSetAutoRepeatRate</function></funcdef> +<!-- ( +<parameter>display, device_spec, timeout, interval</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int <parameter>timeout</parameter></paramdef> + <paramdef>unsigned int <parameter>interval</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device to configure, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>timeout</parameter> + </term> + <listitem> + <para> + initial delay, ms + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>interval</parameter> + </term> + <listitem> + <para> + delay between repeats, ms + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSetAutoRepeatRate</function> +sends a request to the X server to configure the +<emphasis>AutoRepeat</emphasis> +control attributes to the values specified in +<parameter>timeout</parameter> +and +<parameter>interval</parameter>. +</para> + + +<para> +<function>XkbSetAutoRepeatRate</function> +does not wait for a reply; it normally returns +<symbol>True</symbol>. +Specifying a zero value for either +<parameter>timeout</parameter> +or +<parameter>interval</parameter> +causes the server to generate a +<errorname>BadValue</errorname> +protocol error. If a compatible version of the Xkb extension is not available +in the server, +<function>XkbSetAutoRepeatRate</function> +returns +<symbol>False</symbol>. </para> @@ -877,242 +896,242 @@ False</emphasis> <para> Auto-repeat is the generation of multiple key events by a keyboard when the user presses a key and holds it down. Keyboard hardware and device-dependent X -server software often implement auto-repeat by generating multiple <emphasis> -KeyPress</emphasis> - events with no intervening <emphasis> -KeyRelease</emphasis> - event. The standard behavior of the X server is to generate a <emphasis> -KeyRelease</emphasis> - event for every <emphasis> -KeyPress</emphasis> - event. If the keyboard hardware and device-dependent software of the X server -implement auto-repeat by generating multiple <emphasis> -KeyPress</emphasis> - events, the device-independent part of the X server by default synthetically -generates a <emphasis> -KeyRelease</emphasis> - event after each <emphasis> -KeyPress</emphasis> - event. This provides predictable behavior for X clients, but does not allow +server software often implement auto-repeat by generating multiple +<symbol>KeyPress</symbol> +events with no intervening +<symbol>KeyRelease</symbol> +event. The standard behavior of the X server is to generate a +<symbol>KeyRelease</symbol> +event for every +<symbol>KeyPress</symbol> +event. If the keyboard hardware and device-dependent software of the X server +implement auto-repeat by generating multiple +<symbol>KeyPress</symbol> +events, the device-independent part of the X server by default synthetically +generates a +<symbol>KeyRelease</symbol> +event after each +<symbol>KeyPress</symbol> +event. This provides predictable behavior for X clients, but does not allow those clients to detect the fact that a key is auto-repeating. </para> <para> -Xkb allows clients to request <emphasis> -detectable auto-repeat</emphasis> -. If a client requests and the server supports <emphasis> -DetectableAutorepeat</emphasis> -, Xkb generates <emphasis> -KeyRelease</emphasis> - events only when the key is physically released. If <emphasis> -DetectableAutorepeat</emphasis> - is not supported or has not been requested, the server synthesizes a <emphasis> -KeyRelease</emphasis> - event for each repeating <emphasis> -KeyPress</emphasis> - event it generates. +Xkb allows clients to request +<firstterm>detectable auto-repeat</firstterm>. +<indexterm significance="preferred" zone="The_DetectableAutorepeat_Control"> +<primary>detectable auto-repeat</primary></indexterm> +<indexterm significance="preferred" zone="The_DetectableAutorepeat_Control"> +<primary>auto-repeat</primary><secondary>detectable</secondary></indexterm> +If a client requests and the server supports +<emphasis>DetectableAutorepeat</emphasis>, +Xkb generates +<symbol>KeyRelease</symbol> +events only when the key is physically released. If +<emphasis>DetectableAutorepeat</emphasis> +is not supported or has not been requested, the server synthesizes a +<symbol>KeyRelease</symbol> +event for each repeating +<symbol>KeyPress</symbol> +event it generates. </para> <para> -<emphasis> -DetectableAutorepeat</emphasis> -, unlike the other controls in this chapter, is not contained in the <emphasis> -XkbControlsRec</emphasis> - structure, nor can it be enabled or disabled via the <emphasis> -EnabledControls</emphasis> - control. Instead, query and set <emphasis> -DetectableAutorepeat</emphasis> - using <emphasis> -XkbGetDetectableAutorepeat</emphasis> - and <emphasis> -XkbSetDetectableAutorepeat</emphasis> -. +<emphasis>DetectableAutorepeat</emphasis>, +unlike the other controls in this chapter, is not contained in the +<structname>XkbControlsRec</structname> +structure, nor can it be enabled or disabled via the +<emphasis>EnabledControls</emphasis> +control. Instead, query and set +<emphasis>DetectableAutorepeat</emphasis> +using +<function>XkbGetDetectableAutorepeat</function> +and +<function>XkbSetDetectableAutorepeat</function>. </para> <para> -<emphasis> -DetectableAutorepeat</emphasis> - is a condition that applies to all keyboard devices for a client’s +<emphasis>DetectableAutorepeat</emphasis> +is a condition that applies to all keyboard devices for a client’s connection to a given X server; it cannot be selectively set for some devices and not for others. For this reason, none of the Xkb library functions -involving <emphasis> -DetectableAutorepeat</emphasis> - involve a device specifier. -</para> - - -<para> -To determine whether or not the server supports <emphasis> -DetectableAutorepeat</emphasis> -, use <emphasis> -XkbGetDetectableAutorepeat</emphasis> -. -</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> -XkbGetDetectableAutorepeat</emphasis> -(<emphasis> -display, supported_rtrn</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool *<emphasis> - supported_rtrn</emphasis> -; /* backfilled <emphasis> -True</emphasis> - if <emphasis> -DetectableAutorepeat</emphasis> - supported */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetDetectableAutorepeat</emphasis> - queries the server for the current state of <emphasis> -DetectableAutorepeat</emphasis> - and waits for a reply. If <emphasis> -supported_rtrn</emphasis> - is not <emphasis> -NULL</emphasis> -, it backfills supported_rtrn with <emphasis> -True</emphasis> - if the server supports <emphasis> -DetectableAutorepeat</emphasis> -, and <emphasis> -False</emphasis> - otherwise. <emphasis> -XkbGetDetectableAutorepeat</emphasis> - returns the current state of <emphasis> -DetectableAutorepeat</emphasis> - for the requesting client: <emphasis> -True</emphasis> - if <emphasis> -DetectableAutorepeat</emphasis> - is set, and <emphasis> -False</emphasis> - otherwise. -</para> - - -<para> -To set <emphasis> -DetectableAutorepeat</emphasis> -, use <emphasis> -XkbSetDetectableAutorepeat</emphasis> -. This request affects all keyboard activity for the requesting client only; +involving +<emphasis>DetectableAutorepeat</emphasis> +involve a device specifier. +</para> + + +<para> +To determine whether or not the server supports +<emphasis>DetectableAutorepeat</emphasis>, +use +<function>XkbGetDetectableAutorepeat</function>. +</para> + +<indexterm significance="preferred" zone="XkbGetDetectableAutorepeat"><primary><function>XkbGetDetectableAutorepeat</function></primary></indexterm> +<funcsynopsis id="XkbGetDetectableAutorepeat"> + <funcprototype> + <funcdef>Bool <function>XkbGetDetectableAutorepeat</function></funcdef> +<!-- ( +<parameter>display, supported_rtrn</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>Bool *<parameter>supported_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>supported_rtrn</parameter> + </term> + <listitem> + <para> + backfilled <symbol>True</symbol> if +<emphasis>DetectableAutorepeat</emphasis> + supported + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetDetectableAutorepeat</function> +queries the server for the current state of +<emphasis>DetectableAutorepeat</emphasis> +and waits for a reply. If +<parameter>supported_rtrn</parameter> +is not +<symbol>NULL</symbol>, +it backfills supported_rtrn with +<symbol>True</symbol> +if the server supports +<emphasis>DetectableAutorepeat</emphasis>, +and +<symbol>False</symbol> +otherwise. +<function>XkbGetDetectableAutorepeat</function> +returns the current state of +<emphasis>DetectableAutorepeat</emphasis> +for the requesting client: +<symbol>True</symbol> +if +<emphasis>DetectableAutorepeat</emphasis> +is set, and +<symbol>False</symbol> +otherwise. +</para> + + +<para> +To set +<emphasis>DetectableAutorepeat</emphasis>, +use +<function>XkbSetDetectableAutorepeat</function>. +This request affects all keyboard activity for the requesting client only; other clients still see the expected nondetectable auto-repeat behavior, unless they have requested otherwise. </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> -XkbSetDetectableAutorepeat</emphasis> -(<emphasis> -display, detectable, supported_rtrn</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool<emphasis> - detectable</emphasis> -; /* <emphasis> -True</emphasis> - => set <emphasis> -DetectableAutorepeat</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool *<emphasis> - supported_rtrn</emphasis> -; /* backfilled <emphasis> -True</emphasis> - if <emphasis> -DetectableAutorepeat</emphasis> - supported */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSetDetectableAutorepeat</emphasis> - sends a request to the server to set <emphasis> -DetectableAutorepeat</emphasis> - on for the current client if <emphasis> -detectable</emphasis> - is <emphasis> -True</emphasis> -, and off it <emphasis> -detectable</emphasis> - is <emphasis> -False</emphasis> -; it then waits for a reply. If <emphasis> -supported_rtrn</emphasis> - is not <emphasis> -NULL</emphasis> -, <emphasis> -XkbSetDetectableAutorepeat</emphasis> - backfills <emphasis> -supported_rtrn</emphasis> - with <emphasis> -True</emphasis> - if the server supports <emphasis> -DetectableAutorepeat</emphasis> -, and <emphasis> -False</emphasis> - if it does not. <emphasis> -XkbSetDetectableAutorepeat</emphasis> - returns the current state of <emphasis> -DetectableAutorepeat</emphasis> - for the requesting client: <emphasis> -True</emphasis> - if <emphasis> -DetectableAutorepeat</emphasis> - is set, and <emphasis> -False</emphasis> - otherwise. +<indexterm significance="preferred" zone="XkbSetDetectableAutorepeat"><primary><function>XkbSetDetectableAutorepeat</function></primary></indexterm> +<funcsynopsis id="XkbSetDetectableAutorepeat"> + <funcprototype> + <funcdef>Bool <function>XkbSetDetectableAutorepeat</function></funcdef> +<!-- ( +<parameter>display, detectable, supported_rtrn</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>Bool <parameter>detectable</parameter></paramdef> + <paramdef>Bool *<parameter>supported_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>detectable</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ set +<emphasis>DetectableAutorepeat</emphasis> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>supported_rtrn</parameter> + </term> + <listitem> + <para> + backfilled <symbol>True</symbol> if +<emphasis>DetectableAutorepeat</emphasis> + supported + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSetDetectableAutorepeat</function> +sends a request to the server to set +<emphasis>DetectableAutorepeat</emphasis> +on for the current client if +<parameter>detectable</parameter> +is +<symbol>True</symbol>, +and off it +<parameter>detectable</parameter> +is +<symbol>False</symbol>; +it then waits for a reply. If +<parameter>supported_rtrn</parameter> +is not +<symbol>NULL</symbol>, +<function>XkbSetDetectableAutorepeat</function> +backfills +<parameter>supported_rtrn</parameter> +with +<symbol>True</symbol> +if the server supports +<emphasis>DetectableAutorepeat</emphasis>, +and +<symbol>False</symbol> +if it does not. +<function>XkbSetDetectableAutorepeat</function> +returns the current state of +<emphasis>DetectableAutorepeat</emphasis> +for the requesting client: +<symbol>True</symbol> +if +<emphasis>DetectableAutorepeat</emphasis> +is set, and +<symbol>False</symbol> +otherwise. </para> @@ -1132,37 +1151,37 @@ keyboards. <para> -Xkb includes direct support for two keyboard overlays, using the <emphasis> -Overlay1</emphasis> - and <emphasis> -Overlay2</emphasis> - controls. When <emphasis> -Overlay1</emphasis> - is enabled, all of the keys that are members of the first keyboard overlay -generate an alternate keycode. When <emphasis> -Overlay2</emphasis> - is enabled, all of the keys that are members of the second keyboard overlay +Xkb includes direct support for two keyboard overlays, using the +<emphasis>Overlay1</emphasis> +and +<emphasis>Overlay2</emphasis> +controls. When +<emphasis>Overlay1</emphasis> +is enabled, all of the keys that are members of the first keyboard overlay +generate an alternate keycode. When +<emphasis>Overlay2</emphasis> +is enabled, all of the keys that are members of the second keyboard overlay generate an alternate keycode. The two overlays are mutually exclusive; any -particular key may be in at most one overlay. <emphasis> -Overlay1</emphasis> - and <emphasis> -Overlay2</emphasis> - are boolean controls. As such, you may enable and disable them using either -the <emphasis> -EnabledControls</emphasis> - control or the <emphasis> -AutoReset</emphasis> - control discussed in section 10.1.1. <!-- xref --> +particular key may be in at most one overlay. +<emphasis>Overlay1</emphasis> +and +<emphasis>Overlay2</emphasis> +are boolean controls. As such, you may enable and disable them using either +the +<emphasis>EnabledControls</emphasis> +control or the +<emphasis>AutoReset</emphasis> +control discussed in <link linkend="The_EnabledControls_Control">section 10.1.1</link>. </para> <para> To specify the overlay to which a key belongs and the alternate keycode it -should generate when that overlay is enabled, assign it either the <emphasis> -XkbKB_Overlay1</emphasis> - or <emphasis> -XkbKB_Overlay2</emphasis> - key behaviors, as described in section 16.2. <!-- xref --> +should generate when that overlay is enabled, assign it either the +<symbol>XkbKB_Overlay1</symbol> +or +<symbol>XkbKB_Overlay2</symbol> +key behaviors, as described in <link linkend="Key_Behavior">section 16.2</link>. </para> @@ -1174,20 +1193,20 @@ XkbKB_Overlay2</emphasis> Using Xkb, it is possible to configure the keyboard to allow simulation of the X pointer device. This simulation includes both movement of the pointer itself and press and release events associated with the buttons on the pointer. Two -controls affect this behavior: the <emphasis> -MouseKeys</emphasis> - control determines whether or not simulation of the pointer device is active, -as well as configuring the default button; the <emphasis> -MouseKeysAccel</emphasis> - control determines the movement characteristics of the pointer when simulated +controls affect this behavior: the +<emphasis>MouseKeys</emphasis> +control determines whether or not simulation of the pointer device is active, +as well as configuring the default button; the +<emphasis>MouseKeysAccel</emphasis> +control determines the movement characteristics of the pointer when simulated via the keyboard. Both of them are boolean controls; as such, you may enable -and disable them using either the <emphasis> -EnabledControls</emphasis> - control or the <emphasis> -AutoReset</emphasis> - control discussed in section 10.1.1. The individual keys that simulate <!-- xref --> +and disable them using either the +<emphasis>EnabledControls</emphasis> +control or the +<emphasis>AutoReset</emphasis> +control discussed in <link linkend="The_EnabledControls_Control">section 10.1.1</link>. The individual keys that simulate different aspects of the pointer device are determined by the keyboard mapping, -discussed in Chapter 16. <!-- xref --> +discussed in <xref linkend="Xkb_Server_Keyboard_Mapping" />. </para> @@ -1195,64 +1214,63 @@ discussed in Chapter 16. <!-- xref --> <title>The MouseKeys Control</title> <para> -The <emphasis> -MouseKeys</emphasis> - control allows a user to control all the mouse functions from the keyboard. -When <emphasis> -MouseKeys</emphasis> - are enabled, all keys with <emphasis> -MouseKeys</emphasis> - actions bound to them generate core pointer events instead of normal <emphasis> -KeyPress</emphasis> - and <emphasis> -KeyRelease</emphasis> - events. +The +<emphasis>MouseKeys</emphasis> +control allows a user to control all the mouse functions from the keyboard. +When +<emphasis>MouseKeys</emphasis> +are enabled, all keys with +<emphasis>MouseKeys</emphasis> +actions bound to them generate core pointer events instead of normal +<symbol>KeyPress</symbol> +and +<symbol>KeyRelease</symbol> +events. </para> <para> -The <emphasis> -MouseKeys</emphasis> - control has a single attribute, <emphasis> -mk_dflt_btn</emphasis> - that specifies the core button number to be used by mouse keys actions that do +The +<emphasis>MouseKeys</emphasis> +control has a single attribute, +<structfield>mk_dflt_btn</structfield> +that specifies the core button number to be used by mouse keys actions that do not explicitly specify a button. There is no convenience function for getting -or setting the attribute; instead use <emphasis> -XkbGetControls</emphasis> - and <emphasis> -XkbSetControls</emphasis> - (see sections 10.9 and 10.10). <!-- xref --> -</para> - -<note><para><emphasis> -MouseKeys</emphasis> - can also be turned on and off by pressing the key combination necessary to -produce an <emphasis> -XK_Pointer_EnableKeys</emphasis> - keysym. The de facto default standard for this is <emphasis> -Shift+Alt+NumLock</emphasis> -, but this may vary depending on the keymap.</para></note> +or setting the attribute; instead use +<function>XkbGetControls</function> +and +<function>XkbSetControls</function> +(see <link linkend="Querying_Controls">section 10.9</link> and <link linkend="Changing_Controls">section 10.10</link>). +</para> + +<note><para> +<emphasis>MouseKeys</emphasis> +can also be turned on and off by pressing the key combination necessary to +produce an +<keysym>XK_Pointer_EnableKeys</keysym> +keysym. The de facto default standard for this is +<keycombo><keycap>Shift</keycap><keycap>Alt</keycap><keycap>NumLock</keycap></keycombo>, +but this may vary depending on the keymap.</para></note> </sect2> <sect2 id='The_MouseKeysAccel_Control'> <title>The MouseKeysAccel Control</title> <para> -When the <emphasis> -MouseKeysAccel</emphasis> - control is enabled, the effect of a key-activated pointer motion action +When the +<emphasis>MouseKeysAccel</emphasis> +control is enabled, the effect of a key-activated pointer motion action changes as a key is held down. If the control is disabled, pressing a -mouse-pointer key yields one mouse event. When <emphasis> -MouseKeysAccel</emphasis> - is enabled, mouse movement is defined by an initial distance specified in the -<emphasis> -XkbSA_MovePtr</emphasis> - action and the following fields in the <emphasis> -XkbControlsRec</emphasis> - structure (see section 10.8). <!-- xref --> +mouse-pointer key yields one mouse event. When +<emphasis>MouseKeysAccel</emphasis> +is enabled, mouse movement is defined by an initial distance specified in the +<symbol>XkbSA_MovePtr</symbol> +action and the following fields in the +<structname>XkbControlsRec</structname> +structure (see <link linkend="The_XkbControlsRec_Structure">section 10.8</link>). </para> -<table frame='topbot'> +<table id='table10.2' frame='topbot'> <title>MouseKeysAccel Fields</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -1293,35 +1311,34 @@ speed</entry> <para> There are no convenience functions to query or change the attributes of the -<emphasis> -MouseKeysAccel</emphasis> - control; instead use <emphasis> -XkbGetControls</emphasis> - and <emphasis> -XkbSetControls</emphasis> - (see sections 10.9 and 10.10). <!-- xref --> +<emphasis>MouseKeysAccel</emphasis> +control; instead use +<function>XkbGetControls</function> +and +<function>XkbSetControls</function> +(see <link linkend="Querying_Controls">section 10.9</link> and <link linkend="Changing_Controls">section 10.10</link>). </para> <para> -The effects of the attributes of the <emphasis> -MouseKeysAccel</emphasis> - control depend on whether the <emphasis> -XkbSA_MovePtr</emphasis> - action (see section 16.1) specifies relative or absolute pointer motion. <!-- xref --> +The effects of the attributes of the +<emphasis>MouseKeysAccel</emphasis> +control depend on whether the +<symbol>XkbSA_MovePtr</symbol> +action (see <link linkend="Key_Actions">section 16.1</link>) specifies relative or absolute pointer motion. </para> <sect3 id='Absolute_Pointer_Motion'> <title>Absolute Pointer Motion</title> <para> -If an <emphasis> -XkbSA_MovePtr</emphasis> - action specifies an absolute position for one of the coordinates but still +If an +<symbol>XkbSA_MovePtr</symbol> +action specifies an absolute position for one of the coordinates but still allows acceleration, all repeated events contain any absolute coordinates -specified in the action. For example, if the <emphasis> -XkbSA_MovePtr</emphasis> - action specifies an absolute position for the X direction, but a relative +specified in the action. For example, if the +<symbol>XkbSA_MovePtr</symbol> +action specifies an absolute position for the X direction, but a relative motion for the Y direction, the pointer accelerates in the Y direction, but stays at the same X position. </para> @@ -1332,43 +1349,41 @@ stays at the same X position. <title>Relative Pointer Motion</title> <para> -If the <emphasis> -XkbSA_MovePtr</emphasis> - action specifies relative motion, the initial event always moves the cursor -the distance specified in the action. After <emphasis> -mk_delay</emphasis> - milliseconds, a second motion event is generated, and another occurs every -<emphasis> -mk_interval</emphasis> - milliseconds until the user releases the key. +If the +<symbol>XkbSA_MovePtr</symbol> +action specifies relative motion, the initial event always moves the cursor +the distance specified in the action. After +<structfield>mk_delay</structfield> +milliseconds, a second motion event is generated, and another occurs every +<structfield>mk_interval</structfield> +milliseconds until the user releases the key. </para> <para> -Between the time of the second motion event and <emphasis> -mk_time_to_max</emphasis> - intervals, the change in pointer distance per interval increases with each -interval. After <emphasis> -mk_time_to_max</emphasis> - intervals have elapsed, the change in pointer distance per interval remains +Between the time of the second motion event and +<structfield>mk_time_to_max</structfield> +intervals, the change in pointer distance per interval increases with each +interval. After +<structfield>mk_time_to_max</structfield> +intervals have elapsed, the change in pointer distance per interval remains the same and is calculated by multiplying the original distance specified in -the action by <emphasis> -mk_max_speed</emphasis> -. +the action by +<structfield>mk_max_speed</structfield>. </para> <para> -For example, if the <emphasis> -XkbSA_MovePtr</emphasis> - action specifies a relative motion in the X direction of 5, <emphasis> -mk_delay</emphasis> -=160, <emphasis> -mk_interval</emphasis> -=40, <emphasis> -mk_time_to_max</emphasis> -=30, and <emphasis> -mk_max_speed</emphasis> +For example, if the +<symbol>XkbSA_MovePtr</symbol> +action specifies a relative motion in the X direction of 5, +<structfield>mk_delay</structfield> +=160, +<structfield>mk_interval</structfield> +=40, +<structfield>mk_time_to_max</structfield> +=30, and +<structfield>mk_max_speed</structfield> =30, the following happens when the user presses the key: </para> @@ -1381,100 +1396,101 @@ pressed. </listitem> <listitem> <para> -After 160 milliseconds (<emphasis> -mk_delay</emphasis> -), and every 40 milliseconds thereafter (<emphasis> -mk_interval</emphasis> -), the pointer moves in the X direction. +After 160 milliseconds +(<structfield>mk_delay</structfield>), +and every 40 milliseconds thereafter +(<structfield>mk_interval</structfield>), +the pointer moves in the X direction. </para> </listitem> <listitem> <para> The distance in the X direction increases with each interval until 30 intervals -(<emphasis> -mk_time_to_max</emphasis> -) have elapsed. +( +<structfield>mk_time_to_max</structfield>) +have elapsed. </para> </listitem> <listitem> <para> After 30 intervals, the pointer stops accelerating, and moves 150 pixels -(<emphasis> -mk_max_speed</emphasis> - * the original distance) every interval thereafter, until the key is released. +( +<structfield>mk_max_speed</structfield> +* the original distance) every interval thereafter, until the key is released. </para> </listitem> </itemizedlist> <para> -The increase in pointer difference for each interval is a function of<emphasis> - mk_curve.</emphasis> - Events after the first but before maximum acceleration has been achieved are +The increase in pointer difference for each interval is a function of +<structfield>mk_curve</structfield>. +Events after the first but before maximum acceleration has been achieved are accelerated according to the formula: </para> <mediaobject> - <imageobject> <imagedata format="SVG" fileref="XKBlib-3.svg"/> - </imageobject> - </mediaobject> +<imageobject> <imagedata format="SVG" fileref="XKBlib-3.svg"/> +</imageobject> +</mediaobject> <para> -Where <emphasis> -action_delta</emphasis> - is the relative motion specified by the <emphasis> -XkbSA_MovePtr</emphasis> - action, <emphasis> -mk_max_speed </emphasis> -and <emphasis> -mk_time_to_max</emphasis> - are parameters to the <emphasis> -MouseKeysAccel</emphasis> - control, and the curveFactor is computed using the <emphasis> -MouseKeysAccel</emphasis> - <emphasis> -mk_curve</emphasis> - parameter as follows: +Where +<emphasis>action_delta</emphasis> +is the relative motion specified by the +<symbol>XkbSA_MovePtr</symbol> +action, +<structfield>mk_max_speed</structfield> +and +<structfield>mk_time_to_max</structfield> +are parameters to the +<emphasis>MouseKeysAccel</emphasis> +control, and the curveFactor is computed using the +<emphasis>MouseKeysAccel</emphasis> +<structfield>mk_curve</structfield> +parameter as follows: </para> <mediaobject> - <imageobject> <imagedata format="SVG" fileref="XKBlib-4.svg"/> - </imageobject> - </mediaobject> - - -<para> -With the result that a <emphasis> -mk_curve</emphasis> - of zero causes the distance moved to increase linearly from <emphasis> -action_delta</emphasis> - to <mediaobject> - <imageobject> <imagedata format="SVG" fileref="XKBlib-5.svg"/> - </imageobject> - </mediaobject> - -. A negative <emphasis> -mk_curve</emphasis> - causes an initial sharp increase in acceleration that tapers off, and a +<imageobject> <imagedata format="SVG" fileref="XKBlib-4.svg"/> +</imageobject> +</mediaobject> + + +<para> +With the result that a +<structfield>mk_curve</structfield> +of zero causes the distance moved to increase linearly from +<emphasis>action_delta</emphasis> +to <mediaobject> +<imageobject> <imagedata format="SVG" fileref="XKBlib-5.svg"/> +</imageobject> +</mediaobject>. +A negative +<structfield>mk_curve</structfield> +causes an initial sharp increase in acceleration that tapers off, and a positive curve yields a slower initial increase in acceleration followed by a sharp increase as the number of pointer events generated by the action -approaches <emphasis> -mk_time_to_max</emphasis> -. The legal values for <emphasis> -mk_curve</emphasis> - are between -1000 and 1000. +approaches +<structfield>mk_time_to_max</structfield>. +The legal values for +<structfield>mk_curve</structfield> +are between −1000 and 1000. </para> <para> -A distance vs. time graph of the pointer motion is shown in Figure 10.1. <!-- xref --> +A distance vs. time graph of the pointer motion is shown in +<link linkend="figure10.1">Figure 10.1</link>. </para> -<mediaobject> - <imageobject> <imagedata format="SVG" fileref="XKBlib-6.svg"/> - </imageobject> -<caption>MouseKeys Acceleration</caption> - </mediaobject> +<figure id='figure10.1'> + <title>MouseKeys Acceleration</title> + <mediaobject> + <imageobject> <imagedata format="SVG" fileref="XKBlib-6.svg"/> + </imageobject> + </mediaobject> +</figure> <!-- <H5 CLASS="Figure"> @@ -1508,65 +1524,65 @@ Wisconsin-Madison WI 53705-2280. Phone: 608-262-6966. e-mail: info@trace.wisc.ed <para> Enabling or disabling the keyboard controls through a graphical user interface may be impossible for people who need to use the controls. For example, a user -who needs <emphasis> -SlowKeys</emphasis> - (see section 10.6.6) may not even be able to start the graphical application, <!-- xref --> -let alone use it, if <emphasis> -SlowKeys</emphasis> - is not enabled. To allow easier access to some of the controls, the <emphasis> -AccessXKeys</emphasis> - control provides a set of special key sequences similar to those available in +who needs +<emphasis>SlowKeys</emphasis> +(see <link linkend="The_SlowKeys_Control">section 10.6.6</link>) may not even be able to start the graphical application, +let alone use it, if +<emphasis>SlowKeys</emphasis> +is not enabled. To allow easier access to some of the controls, the +<emphasis>AccessXKeys</emphasis> +control provides a set of special key sequences similar to those available in AccessDOS. </para> <para> -When the <emphasis> -AccessXKeys</emphasis> - control is enabled, the user can turn controls on or off from the keyboard by +When the +<emphasis>AccessXKeys</emphasis> +control is enabled, the user can turn controls on or off from the keyboard by entering the following standard key sequences: </para> <itemizedlist> <listitem> <para> -Holding down a shift key by itself for eight seconds toggles the <emphasis> -SlowKeys</emphasis> - control. +Holding down a <keycap>Shift</keycap> key by itself for eight seconds +toggles the +<emphasis>SlowKeys</emphasis> +control. </para> </listitem> <listitem> <para> -Pressing and releasing the left or right <emphasis> -Shift</emphasis> - key five times in a row, without any intervening key events and with less than +Pressing and releasing the left or right +<keycap>Shift</keycap> +key five times in a row, without any intervening key events and with less than 30 seconds delay between consecutive presses, toggles the state of the -<emphasis> -StickyKeys</emphasis> - control. +<emphasis>StickyKeys</emphasis> +control. </para> </listitem> <listitem> <para> -Simultaneously operating two or more modifier keys deactivates the <emphasis> -StickyKeys</emphasis> - control. +Simultaneously operating two or more modifier keys deactivates the +<emphasis>StickyKeys</emphasis> +control. </para> </listitem> </itemizedlist> <para> -When the <emphasis> -AccessXKeys</emphasis> - control is disabled, Xkb does not look for the above special key sequences. +When the +<emphasis>AccessXKeys</emphasis> +control is disabled, Xkb does not look for the above special key sequences. </para> <para> Some of these key sequences optionally generate audible feedback of the change -in state, as described in section 10.6.3, or <!-- xref --> -<emphasis>XkbControlsNotify</emphasis> - events, described in section 10.11. <!-- xref --> +in state, as described in <link linkend="The_AccessXFeedback_Control">section 10.6.3</link>, or +<symbol>XkbControlsNotify</symbol> +events, described in <link linkend="Tracking_Changes_to_Keyboard_Controls">section 10.11</link>. </para> </sect2> @@ -1574,288 +1590,300 @@ in state, as described in section 10.6.3, or <!-- xref --> <title>The AccessXTimeout Control</title> <para> -In environments where computers are shared, features such as <emphasis> -SlowKeys</emphasis> - present a problem: if <emphasis> -SlowKeys</emphasis> - is on, the keyboard can appear to be unresponsive because keys are not +In environments where computers are shared, features such as +<emphasis>SlowKeys</emphasis> +present a problem: if +<emphasis>SlowKeys</emphasis> +is on, the keyboard can appear to be unresponsive because keys are not accepted until they are held for a certain period of time. To help solve this -problem, Xkb provides an <emphasis> -AccessXTimeout</emphasis> - control to automatically change the enabled/disabled state of any boolean -controls and to change the value of the <emphasis> -AccessXKeys</emphasis> - and <emphasis> -AccessXFeedback</emphasis> - control attributes if the keyboard is idle for a specified period of time. -</para> - - -<para> -When a timeout as specified by <emphasis> -AccessXTimeout</emphasis> - occurs and a control is consequently modified, Xkb generates an <emphasis> -XkbControlsNotify</emphasis> - event. For more information on <emphasis> -XkbControlsNotify</emphasis> - events, refer to section 10.11. <!-- xref --> -</para> - - -<para> -Use <emphasis> -XkbGetAccessXTimeout</emphasis> - to query the current <emphasis> -AccessXTimeout</emphasis> - options for a keyboard device. -</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> -XkbGetAccessXTimeout</emphasis> -(<emphasis> -display</emphasis> -,<emphasis> - device_spec</emphasis> -,<emphasis> - timeout_rtrn</emphasis> -,<emphasis> - ctrls_mask_rtrn</emphasis> -,<emphasis> - ctrls_values_rtrn</emphasis> -,<emphasis> - options_mask_rtrn, options_values_rtrn</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device to query, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned short * <emphasis> -timeout_rtrn</emphasis> -; /* delay until AccessXTimeout, seconds */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int *<emphasis> - ctrls_mask_rtrn</emphasis> -; /* backfilled with controls to modify */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> -ctrls_values_rtrn</emphasis> -; /* backfilled with on/off status for controls */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned short * <emphasis> -opts_mask_rtrn</emphasis> -; /* backfilled with <emphasis> -ax_options</emphasis> - to modify */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned short * <emphasis> -opts_values_rtrn</emphasis> -; /* backfilled with values for <emphasis> -ax_options</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetAccessXTimeout</emphasis> - sends a request to the X server to obtain the current values for the <emphasis> -AccessXTimeout</emphasis> - attributes, waits for a reply, and backfills the values into the appropriate -arguments.<emphasis> - </emphasis> -The parameters <emphasis> -opts_mask_rtrn</emphasis> - and <emphasis> -opts_values_rtrn</emphasis> - are backfilled with the options to modify and the values for <emphasis> -ax_options</emphasis> -, which is a field in the -<emphasis>XkbControlsRec</emphasis> - structure (see section 10.8). <!-- xref --> -<emphasis> -XkbGetAccessXTimeout </emphasis> -returns<emphasis> - </emphasis> -<emphasis> -True</emphasis> - if successful; if a compatible version of the Xkb extension is not available -in the server, <emphasis> -XkbGetAccessXTimeout</emphasis> - returns <emphasis> -False</emphasis> -. -</para> - - -<para> -To configure the <emphasis> -AccessXTimeout</emphasis> - options for a keyboard device, use <emphasis> -XkbSetAccessXTimeout</emphasis> -. -</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> -XkbSetAccessXTimeout</emphasis> -(<emphasis> -display</emphasis> -,<emphasis> - device_spec, timeout, ctrls_mask, ctrls_values, opts_mask, -opts_values</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - device_spec</emphasis> -; /* device to configure, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned short <emphasis> -timeout</emphasis> -; /* seconds idle until AccessXTimeout occurs */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - ctrls_mask</emphasis> -; /* boolean controls to modify */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - ctrls_values</emphasis> -; /* new bits for controls selected by <emphasis> -ctrls_mask</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned short <emphasis> -opts_mask</emphasis> -; /* <emphasis> -ax_options</emphasis> - to change */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned short <emphasis> -opts_values</emphasis> -; /* new bits for <emphasis> -ax_options</emphasis> - selected by <emphasis> -opts_mask</emphasis> - */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -timeout</emphasis> - specifies the number of seconds the keyboard must be idle before the controls -are modified. <emphasis> -ctrls_mask</emphasis> - specifies what controls are to be enabled or disabled, and <emphasis> -ctrls_values</emphasis> - specifies whether those controls are to be enabled or disabled. The bit values -correspond to those for enabling and disabling boolean controls (see section -10.1.1). The <emphasis> -opts_mask</emphasis> - field specifies which attributes of the <emphasis> -AccessXKeys</emphasis> - and <emphasis> -AccessXFeedback</emphasis> - controls are to be changed, and <emphasis> -opts_values</emphasis> - specifies the new values for those options. The bit values correspond to those -for the <emphasis> -ax_options</emphasis> - field of an <emphasis> -XkbDescRec</emphasis> - (see section 10.8). <!-- xref --> -</para> - - -<para> -<emphasis> -XkbSetAccessXTimeout</emphasis> - sends a request to configure the <emphasis> -AccessXTimeout</emphasis> - control to the server.<emphasis> - </emphasis> -It does not wait for a reply, and normally returns <emphasis> -True</emphasis> -. If a compatible version of the Xkb extension is not available in the server, -<emphasis> -XkbSetAccessXTimeout</emphasis> - returns <emphasis> -False</emphasis> -. +problem, Xkb provides an +<emphasis>AccessXTimeout</emphasis> +control to automatically change the enabled/disabled state of any boolean +controls and to change the value of the +<emphasis>AccessXKeys</emphasis> +and +<emphasis>AccessXFeedback</emphasis> +control attributes if the keyboard is idle for a specified period of time. +</para> + + +<para> +When a timeout as specified by +<emphasis>AccessXTimeout</emphasis> +occurs and a control is consequently modified, Xkb generates an +<symbol>XkbControlsNotify</symbol> +event. For more information on +<symbol>XkbControlsNotify</symbol> +events, refer to <link linkend="Tracking_Changes_to_Keyboard_Controls">section 10.11</link>. +</para> + + +<para> +Use +<function>XkbGetAccessXTimeout</function> +to query the current +<emphasis>AccessXTimeout</emphasis> +options for a keyboard device. +</para> + +<indexterm significance="preferred" zone="XkbGetAccessXTimeout"><primary><function>XkbGetAccessXTimeout</function></primary></indexterm> +<funcsynopsis id="XkbGetAccessXTimeout"> + <funcprototype> + <funcdef>Bool <function>XkbGetAccessXTimeout</function></funcdef> +<!-- ( +<parameter>display</parameter>, +<parameter>device_spec</parameter>, +<parameter>timeout_rtrn</parameter>, +<parameter>ctrls_mask_rtrn</parameter>, +<parameter>ctrls_values_rtrn</parameter>, +<parameter>options_mask_rtrn, options_values_rtrn</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned short *<parameter>timeout_rtrn</parameter></paramdef> + <paramdef>unsigned int *<parameter>ctrls_mask_rtrn</parameter></paramdef> + <paramdef>unsigned int *<parameter>ctrls_values_rtrn</parameter></paramdef> + <paramdef>unsigned short *<parameter>opts_mask_rtrn</parameter></paramdef> + <paramdef>unsigned short *<parameter>opts_values_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device to query, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>timeout_rtrn</parameter> + </term> + <listitem> + <para> + delay until AccessXTimeout, seconds + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>ctrls_mask_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with controls to modify + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>ctrls_values_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with on/off status for controls + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>opts_mask_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with <structfield>ax_options</structfield> to modify + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>opts_values_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with values for <structfield>ax_options</structfield> + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetAccessXTimeout</function> +sends a request to the X server to obtain the current values for the +<emphasis>AccessXTimeout</emphasis> +attributes, waits for a reply, and backfills the values into the appropriate +arguments. +The parameters +<parameter>opts_mask_rtrn</parameter> +and +<parameter>opts_values_rtrn</parameter> +are backfilled with the options to modify and the values for +<structfield>ax_options</structfield>, +which is a field in the +<structname>XkbControlsRec</structname> +structure (see <link linkend="The_XkbControlsRec_Structure">section 10.8</link>). +<function>XkbGetAccessXTimeout</function> +returns +<symbol>True</symbol> +if successful; if a compatible version of the Xkb extension is not available +in the server, +<function>XkbGetAccessXTimeout</function> +returns +<symbol>False</symbol>. +</para> + + +<para> +To configure the +<emphasis>AccessXTimeout</emphasis> +options for a keyboard device, use +<function>XkbSetAccessXTimeout</function>. +</para> + + +<indexterm significance="preferred" zone="XkbSetAccessXTimeout"><primary><function>XkbSetAccessXTimeout</function></primary></indexterm> +<funcsynopsis id="XkbSetAccessXTimeout"> + <funcprototype> + <funcdef>Bool <function>XkbSetAccessXTimeout</function></funcdef> +<!-- ( +<parameter>display</parameter>, +<parameter>device_spec, timeout, ctrls_mask, ctrls_values, opts_mask, +opts_values</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned short <parameter>timeout</parameter></paramdef> + <paramdef>unsigned int <parameter>ctrls_mask</parameter></paramdef> + <paramdef>unsigned int <parameter>ctrls_values</parameter></paramdef> + <paramdef>unsigned short <parameter>opts_mask</parameter></paramdef> + <paramdef>unsigned short <parameter>opts_values</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device to configure, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>timeout</parameter> + </term> + <listitem> + <para> + seconds idle until AccessXTimeout occurs + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>ctrls_mask</parameter> + </term> + <listitem> + <para> + boolean controls to modify + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>ctrls_values</parameter> + </term> + <listitem> + <para> + new bits for controls selected by <parameter>ctrls_mask</parameter> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>opts_mask</parameter> + </term> + <listitem> + <para> + <structfield>ax_options</structfield> to change + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>opts_values</parameter> + </term> + <listitem> + <para> + new bits for <structfield>ax_options</structfield> selected by <parameter>opts_mask</parameter> + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<parameter>timeout</parameter> +specifies the number of seconds the keyboard must be idle before the controls +are modified. +<parameter>ctrls_mask</parameter> +specifies what controls are to be enabled or disabled, and +<parameter>ctrls_values</parameter> +specifies whether those controls are to be enabled or disabled. The bit values +correspond to those for enabling and disabling boolean controls +(see <link linkend="The_EnabledControls_Control">section 10.1.1</link>). The +<parameter>opts_mask</parameter> +field specifies which attributes of the +<emphasis>AccessXKeys</emphasis> +and +<emphasis>AccessXFeedback</emphasis> +controls are to be changed, and +<parameter>opts_values</parameter> +specifies the new values for those options. The bit values correspond to those +for the +<structfield>ax_options</structfield> +field of an +<structname>XkbDescRec</structname> +(see <link linkend="The_XkbControlsRec_Structure">section 10.8</link>). +</para> + + +<para> +<function>XkbSetAccessXTimeout</function> +sends a request to configure the +<emphasis>AccessXTimeout</emphasis> +control to the server. +It does not wait for a reply, and normally returns +<symbol>True</symbol>. +If a compatible version of the Xkb extension is not available in the server, +<function>XkbSetAccessXTimeout</function> +returns +<symbol>False</symbol>. </para> @@ -1866,27 +1894,27 @@ False</emphasis> <para> Just as some keyboards can produce keyclicks to indicate when a key is pressed or repeating, Xkb can provide feedback for the controls by using special beep -codes. Use the <emphasis> -AccessXFeedback</emphasis> - control to configure the specific types of operations that generate feedback. +codes. Use the +<emphasis>AccessXFeedback</emphasis> +control to configure the specific types of operations that generate feedback. </para> <para> -There is no convenience function for modifying the <emphasis> -AccessXFeedback</emphasis> - control, although the feedback as a whole can be enabled or disabled just as -other boolean controls are (see section 10.1). Individual beep codes are turned -on or off by modifying the following bits in the <emphasis> -ax_options</emphasis> - field of an <emphasis> -XkbControlsRec</emphasis> - structure and using <emphasis> -XkbSetControls</emphasis> - (see section 10.10): <!-- xref --> +There is no convenience function for modifying the +<emphasis>AccessXFeedback</emphasis> +control, although the feedback as a whole can be enabled or disabled just as +other boolean controls are (see <link linkend="Controls_that_Enable_and_Disable_Other_Controls">section 10.1</link>). Individual beep codes are turned +on or off by modifying the following bits in the +<structfield>ax_options</structfield> +field of an +<structname>XkbControlsRec</structname> +structure and using +<function>XkbSetControls</function> +(see <link linkend="Changing_Controls">section 10.10</link>): </para> -<table frame='topbot'> +<table id='table10.3' frame='topbot'> <title>AccessXFeedback Masks</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -1904,77 +1932,77 @@ XkbSetControls</emphasis> <row> <entry>LED turned on</entry> <entry>High-pitched beep</entry> - <entry>XkbAX_IndicatorFBMask</entry> + <entry><symbol>XkbAX_IndicatorFBMask</symbol></entry> </row> <row> <entry>LED turned off</entry> <entry>Low-pitched beep</entry> - <entry>XkbAX_IndicatorFBMask</entry> + <entry><symbol>XkbAX_IndicatorFBMask</symbol></entry> </row> <row> <entry>More than one LED changed state</entry> <entry>Two high-pitched beeps</entry> - <entry>XkbAX_IndicatorFBMask</entry> + <entry><symbol>XkbAX_IndicatorFBMask</symbol></entry> </row> <row> <entry>Control turned on</entry> <entry>Rising tone</entry> - <entry>XkbAX_FeatureFBMask</entry> + <entry><symbol>XkbAX_FeatureFBMask</symbol></entry> </row> <row> <entry>Control turned off</entry> <entry>Falling tone</entry> - <entry>XkbAX_FeatureFBMask</entry> + <entry><symbol>XkbAX_FeatureFBMask</symbol></entry> </row> <row> <entry>More than one control changed state</entry> <entry>Two high-pitched beeps</entry> - <entry>XkbAX_FeatureFBMask</entry> + <entry><symbol>XkbAX_FeatureFBMask</symbol></entry> </row> <row> <entry>SlowKeys and BounceKeys about to be turned on or off</entry> <entry>Three high-pitched beeps</entry> - <entry>XkbAX_SlowWarnFBMask</entry> + <entry><symbol>XkbAX_SlowWarnFBMask</symbol></entry> </row> <row> <entry>SlowKeys key pressed</entry> <entry>Medium-pitched beep</entry> - <entry>XkbAX_SKPressFBMask</entry> + <entry><symbol>XkbAX_SKPressFBMask</symbol></entry> </row> <row> <entry>SlowKeys key accepted</entry> <entry>Medium-pitched beep</entry> - <entry>XkbAX_SKAcceptFBMask</entry> + <entry><symbol>XkbAX_SKAcceptFBMask</symbol></entry> </row> <row> <entry>SlowKeys key rejected</entry> <entry>Low-pitched beep</entry> - <entry>XkbAX_SKRejectFBMask</entry> + <entry><symbol>XkbAX_SKRejectFBMask</symbol></entry> </row> <row> <entry>Accepted SlowKeys key released</entry> <entry>Medium-pitched beep</entry> - <entry>XkbAX_SKReleaseFBMask</entry> + <entry><symbol>XkbAX_SKReleaseFBMask</symbol></entry> </row> <row> <entry>BounceKeys key rejected</entry> <entry>Low-pitched beep</entry> - <entry>XkbAX_BKRejectFBMask</entry> + <entry><symbol>XkbAX_BKRejectFBMask</symbol></entry> </row> <row> <entry>StickyKeys key latched</entry> <entry>Low-pitched beep followed by high-pitched beep</entry> - <entry>XkbAX_StickyKeysFBMask</entry> + <entry><symbol>XkbAX_StickyKeysFBMask</symbol></entry> </row> <row> <entry>StickyKeys key locked</entry> <entry>High-pitched beep</entry> - <entry>XkbAX_StickyKeysFBMask</entry> + <entry><symbol>XkbAX_StickyKeysFBMask</symbol></entry> </row> <row> <entry>StickyKeys key unlocked</entry> <entry>Low-pitched beep</entry> - <entry>XkbAX_StickyKeysFBMask</entry> + <entry><symbol>XkbAX_StickyKeysFBMask</symbol></entry> </row> </tbody> </tgroup> @@ -1985,18 +2013,18 @@ Implementations that cannot generate continuous tones may generate multiple beeps instead of falling and rising tones; for example, they can generate a high-pitched beep followed by a low-pitched beep instead of a continuous falling tone. Other implementations can only ring the bell with one fixed -pitch. In these cases, use the <emphasis> -XkbAX_DumbBellFBMask</emphasis> - bit of <emphasis> -ax_options</emphasis> - to indicate that the bell can only ring with a fixed pitch. +pitch. In these cases, use the +<symbol>XkbAX_DumbBellFBMask</symbol> +bit of +<structfield>ax_options</structfield> +to indicate that the bell can only ring with a fixed pitch. </para> <para> -When any of the above feedbacks occur, Xkb may generate a <emphasis> -XkbBellNotify</emphasis> - event (see section 9.4). <!-- xref --> +When any of the above feedbacks occur, Xkb may generate a +<symbol>XkbBellNotify</symbol> +event (see <link linkend="Detecting_Bells">section 9.4</link>). </para> @@ -2004,39 +2032,42 @@ XkbBellNotify</emphasis> <sect2 id='AccessXNotify_Events'> <title>AccessXNotify Events</title> +<indexterm significance="preferred" zone="AccessXNotify_Events"> +<primary>events</primary><secondary><symbol>XkbAccessXNotify</symbol></secondary></indexterm> +<indexterm significance="preferred" zone="AccessXNotify_Events"> +<primary><structname>XkbAccessXNotifyEvent</structname></primary></indexterm> + <para> -The server can generate <emphasis> -XkbAccessXNotify</emphasis> - events for some of the global keyboard controls. The structure for the -<emphasis> -XkbAccessXNotify</emphasis> - event type is as follows: -</para> +The server can generate +<symbol>XkbAccessXNotify</symbol> +events for some of the global keyboard controls. The structure for the +<symbol>XkbAccessXNotify</symbol> +event type is as follows: -<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> XkbAccessXNotify</emphasis> */ - int device; /* Xkb device ID, will not be <emphasis> XkbUseCoreKbd</emphasis> */ - int detail; /* XkbAXN_* */ - KeyCode keycode; /* key of event */ - int slowKeysDelay; /* current SlowKeys delay */ - int debounceDelay; /* current debounce delay */ -} <emphasis>XkbAccessXNotifyEvent</emphasis>; + 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; /* <symbol>XkbAccessXNotify</symbol> */ + int device; /* Xkb device ID, will not be <symbol>XkbUseCoreKbd</symbol> */ + int detail; /* XkbAXN_* */ + KeyCode keycode; /* key of event */ + int slowKeysDelay; /* current SlowKeys delay */ + int debounceDelay; /* current debounce delay */ +} <structname>XkbAccessXNotifyEvent</structname>; </programlisting></para> <para> -The <emphasis> -detail</emphasis> - field describes what AccessX event just occurred and can be any of the values -in Table 10.4. <!-- xref --> +The +<structfield>detail</structfield> +field describes what AccessX event just occurred and can be any of the values +in <link linkend="table10.4">Table 10.4</link>. </para> -<table frame='topbot'> +<table id='table10.4' frame='topbot'> <title>AccessXNotify Events</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -2050,33 +2081,33 @@ in Table 10.4. <!-- xref --> </thead> <tbody> <row> - <entry>XkbAXN_SKPress</entry> + <entry><symbol>XkbAXN_SKPress</symbol></entry> <entry>A key was pressed when SlowKeys was enabled.</entry> </row> <row> - <entry>XkbAXN_SKAccept</entry> + <entry><symbol>XkbAXN_SKAccept</symbol></entry> <entry>A key was accepted (held longer than the SlowKeys delay).</entry> </row> <row> - <entry>XkbAXN_SKRelease</entry> + <entry><symbol>XkbAXN_SKRelease</symbol></entry> <entry>An accepted SlowKeys key was released.</entry> </row> <row> - <entry>XkbAXN_SKReject</entry> + <entry><symbol>XkbAXN_SKReject</symbol></entry> <entry>A key was rejected (released before the SlowKeys delay expired).</entry> </row> <row> - <entry>XkbAXN_BKAccept</entry> + <entry><symbol>XkbAXN_BKAccept</symbol></entry> <entry>A key was accepted by BounceKeys.</entry> </row> <row> - <entry>XkbAXN_BKReject</entry> + <entry><symbol>XkbAXN_BKReject</symbol></entry> <entry>A key was rejected (pressed before the BounceKeys delay expired).</entry> </row> <row> - <entry>XkbAXN_AXKWarning</entry> + <entry><symbol>XkbAXN_AXKWarning</symbol></entry> <entry>AccessXKeys is about to turn on/off StickyKeys or BounceKeys.</entry> </row> </tbody> @@ -2084,59 +2115,58 @@ expired).</entry> </table> <para> -The <emphasis> -keycode</emphasis> - field reports the keycode of the key for which the event occurred. If the -action is related to <emphasis> -SlowKeys</emphasis> -, the <emphasis> -slowKeysDelay</emphasis> - field contains the current <emphasis> -SlowKeys</emphasis> - acceptance delay. If the action is related to <emphasis> -BounceKeys</emphasis> -, the <emphasis> -debounceDelay</emphasis> - field contains the current <emphasis> -BounceKeys</emphasis> - debounce delay. +The +<structfield>keycode</structfield> +field reports the keycode of the key for which the event occurred. If the +action is related to +<emphasis>SlowKeys</emphasis>, +the +<structfield>slowKeysDelay</structfield> +field contains the current +<emphasis>SlowKeys</emphasis> +acceptance delay. If the action is related to +<emphasis>BounceKeys</emphasis>, +the +<structfield>debounceDelay</structfield> +field contains the current +<emphasis>BounceKeys</emphasis> +debounce delay. </para> <sect3 id='Selecting_for_AccessX_Events'> <title>Selecting for AccessX Events</title> <para> -To receive <emphasis> -XkbAccessXNotify</emphasis> - events under all possible conditions, use <emphasis> -XkbSelectEvents</emphasis> - (see section 4.3) and pass <emphasis> <!-- xref --> -XkbAccesXNotifyMask</emphasis> - in both <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits</emphasis> -. +To receive +<symbol>XkbAccessXNotify</symbol> +events under all possible conditions, use +<function>XkbSelectEvents</function> +(see <link linkend="Selecting_Xkb_Events">section 4.3</link>) and pass +<symbol>XkbAccessXNotifyMask</symbol> +in both +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter>. </para> <para> -To receive <emphasis> -XkbStateNotify</emphasis> - events only under certain conditions, use <emphasis> -XkbSelectEventDetails</emphasis> - using <emphasis> -XkbAccessXNotify</emphasis> - as the <emphasis> -event_type</emphasis> - and specifying the desired state changes in <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits</emphasis> - using mask bits from Table 10.5. <!-- xref --> +To receive +<symbol>XkbStateNotify</symbol> +events only under certain conditions, use +<function>XkbSelectEventDetails</function> +using +<symbol>XkbAccessXNotify</symbol> +as the +<structfield>event_type</structfield> +and specifying the desired state changes in +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter> +using mask bits from <link linkend="table10.5">Table 10.5</link>. </para> -<table frame='topbot'> +<table id='table10.5' frame='topbot'> <title>AccessXNotify Event Details</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -2152,37 +2182,37 @@ values_for_bits</emphasis> </thead> <tbody> <row> - <entry>XkbAXN_SKPressMask</entry> + <entry><symbol>XkbAXN_SKPressMask</symbol></entry> <entry>(1<<0)</entry> <entry>Slow key press notification wanted</entry> </row> <row> - <entry>XkbAXN_SKAcceptMask</entry> + <entry><symbol>XkbAXN_SKAcceptMask</symbol></entry> <entry>(1<<1)</entry> <entry>Slow key accept notification wanted</entry> </row> <row> - <entry>XkbAXN_SKRejectMask</entry> + <entry><symbol>XkbAXN_SKRejectMask</symbol></entry> <entry>(1<<2)</entry> <entry>Slow key reject notification wanted</entry> </row> <row> - <entry>XkbAXN_SKReleaseMask</entry> + <entry><symbol>XkbAXN_SKReleaseMask</symbol></entry> <entry>(1<<3)</entry> <entry>Slow key release notification wanted</entry> </row> <row> - <entry>XkbAXN_BKAcceptMask</entry> + <entry><symbol>XkbAXN_BKAcceptMask</symbol></entry> <entry>(1<<4)</entry> <entry>Bounce key accept notification wanted</entry> </row> <row> - <entry>XkbAXN_BKRejectMask</entry> + <entry><symbol>XkbAXN_BKRejectMask</symbol></entry> <entry>(1<<5)</entry> <entry>Bounce key reject notification wanted</entry> </row> <row> - <entry>XkbAXN_AXKWarningMask</entry> + <entry><symbol>XkbAXN_AXKWarningMask</symbol></entry> <entry>(1<<6)</entry> <entry>AccessX warning notification wanted</entry> </row> @@ -2201,26 +2231,25 @@ values_for_bits</emphasis> <title>StickyKeys, RepeatKeys, and MouseKeys Events</title> <para> -The <emphasis> -StickyKeys</emphasis> -, <emphasis> -RepeatKeys</emphasis> -, and <emphasis> -MouseKeys</emphasis> - controls do not generate specific events. Instead, the latching, unlatching, -locking, or unlocking of modifiers using <emphasis> -StickyKeys</emphasis> - generates <emphasis> -XkbStateNotify</emphasis> - events as described in section 5.4. Repeating keys generate normal <emphasis> <!-- xref --> -KeyPress</emphasis> - and <emphasis> -KeyRelease</emphasis> - events, though the auto-repeat can be detected using <emphasis> -DetectableAutorepeat</emphasis> - (see section 10.3.3). Finally, <emphasis> <!-- xref --> -MouseKeys</emphasis> - generates pointer events identical to those of the core pointer device. +The +<emphasis>StickyKeys</emphasis>, +<emphasis>RepeatKeys</emphasis>, +and +<emphasis>MouseKeys</emphasis> +controls do not generate specific events. Instead, the latching, unlatching, +locking, or unlocking of modifiers using +<emphasis>StickyKeys</emphasis> +generates +<symbol>XkbStateNotify</symbol> +events as described in <link linkend="Tracking_Keyboard_State">section 5.4</link>. Repeating keys generate normal +<symbol>KeyPress</symbol> +and +<symbol>KeyRelease</symbol> +events, though the auto-repeat can be detected using +<emphasis>DetectableAutorepeat</emphasis> +(see <link linkend="The_DetectableAutorepeat_Control">section 10.3.3</link>). Finally, +<emphasis>MouseKeys</emphasis> +generates pointer events identical to those of the core pointer device. </para> @@ -2231,186 +2260,181 @@ MouseKeys</emphasis> <para> Some users may accidentally bump keys while moving a hand or typing stick toward the key they want. Usually, the keys that are accidentally bumped are -just hit for a very short period of time. The <emphasis> -SlowKeys</emphasis> - control helps filter these accidental bumps by telling the server to wait a -specified period, called the <emphasis> -SlowKeys acceptance delay</emphasis> -, before delivering key events. If the key is released before this period +just hit for a very short period of time. The +<emphasis>SlowKeys</emphasis> +control helps filter these accidental bumps by telling the server to wait a +specified period, called the +<firstterm>SlowKeys acceptance delay</firstterm>, +before delivering key events. If the key is released before this period elapses, no key events are generated. Users can then bump any number of keys on their way to the one they want without accidentally getting those characters. Once they have reached the key they want, they can then hold the desired key -long enough for the computer to accept it. <emphasis> -SlowKeys</emphasis> - is a boolean control with one configurable attribute. +long enough for the computer to accept it. +<emphasis>SlowKeys</emphasis> +is a boolean control with one configurable attribute. </para> <para> -When the <emphasis> -SlowKeys</emphasis> - control is active, the server reports the initial key press, subsequent +When the +<emphasis>SlowKeys</emphasis> +control is active, the server reports the initial key press, subsequent acceptance or rejection, and release of any key to interested clients by -sending an appropriate <emphasis> -AccessXNotify</emphasis> - event (see section 10.6.4). <!-- xref --> -</para> - -<para> -To get the <emphasis> -SlowKeys</emphasis> - acceptance delay for a keyboard device, use <emphasis> -XkbGetSlowKeysDelay</emphasis> -. -</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> -XkbGetSlowKeysDelay</emphasis> -(<emphasis> -display</emphasis> -,<emphasis> - device_spec</emphasis> -,<emphasis> - delay_rtrn</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </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> -delay_rtrn</emphasis> -; /* backfilled with <emphasis> -SlowKeys</emphasis> - delay, ms */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetSlowKeysDelay </emphasis> -requests the attributes of the <emphasis> -SlowKeys</emphasis> - control from the server, waits for a reply and backfills <emphasis> -delay_rtrn </emphasis> -with the <emphasis> -SlowKeys</emphasis> - delay attribute. <emphasis> -XkbGetSlowKeysDelay </emphasis> -returns <emphasis> -True</emphasis> - if successful; if a compatible version of the Xkb extension is not available -in the server, <emphasis> -XkbGetSlowKeysDelay</emphasis> - returns <emphasis> -False</emphasis> -. -</para> - - -<para> -To set the <emphasis> -SlowKeys</emphasis> - acceptance delay for a keyboard device, use <emphasis> -XkbSetSlowKeysDelay</emphasis> -. -</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> -XkbSetSlowKeysDelay</emphasis> -(<emphasis> -display</emphasis> -,<emphasis> - device_spec</emphasis> -,<emphasis> - delay</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device to configure, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -delay</emphasis> -; /* <emphasis> -SlowKeys</emphasis> - delay, ms */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSetSlowKeysDelay</emphasis> - sends a request to configure the <emphasis> -SlowKeys</emphasis> - control to the server.<emphasis> - </emphasis> -It does not wait for a reply, and normally returns <emphasis> -True</emphasis> -. Specifying a value of <emphasis> -0</emphasis> - for the <emphasis> -delay </emphasis> -parameter causes <emphasis> -XkbSetSlowKeys</emphasis> - to generate a <emphasis> -BadValue</emphasis> - protocol error. If a compatible version of the Xkb extension is not available -in the server <emphasis> -XkbSetSlowKeysDelay</emphasis> - returns <emphasis> -False</emphasis> -. +sending an appropriate +<emphasis>AccessXNotify</emphasis> +event (see <link linkend="AccessXNotify_Events">section 10.6.4</link>). +</para> + +<para> +To get the +<emphasis>SlowKeys</emphasis> +acceptance delay for a keyboard device, use +<function>XkbGetSlowKeysDelay</function>. +</para> + +<indexterm significance="preferred" zone="XkbGetSlowKeysDelay"><primary><function>XkbGetSlowKeysDelay</function></primary></indexterm> +<funcsynopsis id="XkbGetSlowKeysDelay"> + <funcprototype> + <funcdef>Bool <function>XkbGetSlowKeysDelay</function></funcdef> +<!-- ( +<parameter>display</parameter>, +<parameter>device_spec</parameter>, +<parameter>delay_rtrn</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int *<parameter>delay_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>delay_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with <emphasis>SlowKeys</emphasis> delay, ms + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetSlowKeysDelay</function> +requests the attributes of the +<emphasis>SlowKeys</emphasis> +control from the server, waits for a reply and backfills +<parameter>delay_rtrn</parameter> +with the +<emphasis>SlowKeys</emphasis> +delay attribute. +<function>XkbGetSlowKeysDelay</function> +returns +<symbol>True</symbol> +if successful; if a compatible version of the Xkb extension is not available +in the server, +<function>XkbGetSlowKeysDelay</function> +returns +<symbol>False</symbol>. +</para> + + +<para> +To set the +<emphasis>SlowKeys</emphasis> +acceptance delay for a keyboard device, use +<function>XkbSetSlowKeysDelay</function>. +</para> + + +<indexterm significance="preferred" zone="XkbSetSlowKeysDelay"><primary><function>XkbSetSlowKeysDelay</function></primary></indexterm> +<funcsynopsis id="XkbSetSlowKeysDelay"> + <funcprototype> + <funcdef>Bool <function>XkbSetSlowKeysDelay</function></funcdef> +<!-- ( +<parameter>display</parameter>, +<parameter>device_spec</parameter>, +<parameter>delay</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int <parameter>delay</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device to configure, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>delay</parameter> + </term> + <listitem> + <para> + <emphasis>SlowKeys</emphasis> delay, ms + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSetSlowKeysDelay</function> +sends a request to configure the +<emphasis>SlowKeys</emphasis> +control to the server. +It does not wait for a reply, and normally returns +<symbol>True</symbol>. +Specifying a value of +<literal>0</literal> +for the +<parameter>delay</parameter> +parameter causes +<function>XkbSetSlowKeysDelay</function> +to generate a +<errorname>BadValue</errorname> +protocol error. If a compatible version of the Xkb extension is not available +in the server +<function>XkbSetSlowKeysDelay</function> +returns +<symbol>False</symbol>. </para> @@ -2419,183 +2443,180 @@ False</emphasis> <title>The BounceKeys Control</title> <para> -Some users may accidentally "bounce" on a key when they release it. They press -it once, then accidentally press it again after they release it. The <emphasis> -BounceKeys</emphasis> - control temporarily disables a key after it has been pressed, effectively -"debouncing" the keyboard. The period of time the key is disabled after it is -released is known as the <emphasis> -BounceKeys delay</emphasis> -. <emphasis> -BounceKeys</emphasis> - is a boolean control. -</para> - - -<para> -When the <emphasis> -BounceKeys</emphasis> - control is active, the server reports acceptance or rejection of any key to -interested clients by sending an appropriate <emphasis> -AccessXNotify</emphasis> - event (see section 10.6.4). <!-- xref --> -</para> - - -<para> -Use <emphasis> -XkbGetBounceKeysDelay</emphasis> - to query the current <emphasis> -BounceKeys</emphasis> - delay for a keyboard device. -</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> -XkbGetBounceKeysDelay</emphasis> -(<emphasis> -display</emphasis> -,<emphasis> - device_spec</emphasis> -,<emphasis> - delay_rtrn</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </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> -delay_rtrn</emphasis> -; /* backfilled with bounce keys delay, ms */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetBounceKeysDelay </emphasis> -requests the attributes of the <emphasis> -BounceKeys</emphasis> - control from the server, waits for a reply, and backfills <emphasis> -delay_rtrn </emphasis> -with the <emphasis> -BounceKeys</emphasis> - delay attribute. <emphasis> -XkbGetBounceKeysDelay </emphasis> -returns<emphasis> - </emphasis> -<emphasis> -True</emphasis> - if successful; if a compatible version of the Xkb extension is not available -in the server <emphasis> -XkbGetSlowKeysDelay</emphasis> - returns <emphasis> -False</emphasis> -. -</para> - - -<para> -To set the <emphasis> -BounceKeys</emphasis> - delay for a keyboard device, use <emphasis> -XkbSetBounceKeysDelay</emphasis> -. -</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> -XkbSetBounceKeysDelay</emphasis> -(<emphasis> -display</emphasis> -,<emphasis> - device_spec</emphasis> -,<emphasis> - delay</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - device_spec</emphasis> -; /* device to configure, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -delay</emphasis> -; /* bounce keys delay, ms */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSetBounceKeysDelay</emphasis> - sends a request to configure the <emphasis> -BounceKeys</emphasis> - control to the server.<emphasis> - </emphasis> -It does not wait for a reply and normally returns <emphasis> -True</emphasis> -. Specifying a value of <emphasis> -zero </emphasis> -for the <emphasis> -delay </emphasis> -parameter causes <emphasis> -XkbSetBounceKeysDelay</emphasis> - to generate a <emphasis> -BadValue</emphasis> - protocol error. If a compatible version of the Xkb extension is not available -in the server, <emphasis> -XkbSetBounceKeysDelay</emphasis> - returns <emphasis> -False</emphasis> -. +Some users may accidentally <quote>bounce</quote> on a key when they release it. +They press it once, then accidentally press it again after they release it. The +<emphasis>BounceKeys</emphasis> +control temporarily disables a key after it has been pressed, effectively +<quote>debouncing</quote> the keyboard. The period of time the key is disabled +after it is released is known as the +<firstterm>BounceKeys delay</firstterm>. +<emphasis>BounceKeys</emphasis> +is a boolean control. +</para> + + +<para> +When the +<emphasis>BounceKeys</emphasis> +control is active, the server reports acceptance or rejection of any key to +interested clients by sending an appropriate +<emphasis>AccessXNotify</emphasis> +event (see <link linkend="AccessXNotify_Events">section 10.6.4</link>). +</para> + + +<para> +Use +<function>XkbGetBounceKeysDelay</function> +to query the current +<emphasis>BounceKeys</emphasis> +delay for a keyboard device. +</para> + +<indexterm significance="preferred" zone="XkbGetBounceKeysDelay"><primary><function>XkbGetBounceKeysDelay</function></primary></indexterm> +<funcsynopsis id="XkbGetBounceKeysDelay"> + <funcprototype> + <funcdef>Bool <function>XkbGetBounceKeysDelay</function></funcdef> +<!-- ( +<parameter>display</parameter>, +<parameter>device_spec</parameter>, +<parameter>delay_rtrn</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int *<parameter>delay_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>delay_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with bounce keys delay, ms + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetBounceKeysDelay</function> +requests the attributes of the +<emphasis>BounceKeys</emphasis> +control from the server, waits for a reply, and backfills +<parameter>delay_rtrn</parameter> +with the +<emphasis>BounceKeys</emphasis> +delay attribute. +<function>XkbGetBounceKeysDelay</function> +returns +<symbol>True</symbol> +if successful; if a compatible version of the Xkb extension is not available +in the server +<function>XkbGetSlowKeysDelay</function> +returns +<symbol>False</symbol>. +</para> + + +<para> +To set the +<emphasis>BounceKeys</emphasis> +delay for a keyboard device, use +<function>XkbSetBounceKeysDelay</function>. +</para> + + +<indexterm significance="preferred" zone="XkbSetBounceKeysDelay"><primary><function>XkbSetBounceKeysDelay</function></primary></indexterm> +<funcsynopsis id="XkbSetBounceKeysDelay"> + <funcprototype> + <funcdef>Bool <function>XkbSetBounceKeysDelay</function></funcdef> +<!-- ( +<parameter>display</parameter>, +<parameter>device_spec</parameter>, +<parameter>delay</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int <parameter>delay</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device to configure, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>delay</parameter> + </term> + <listitem> + <para> + bounce keys delay, ms + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSetBounceKeysDelay</function> +sends a request to configure the +<emphasis>BounceKeys</emphasis> +control to the server. +It does not wait for a reply and normally returns +<symbol>True</symbol>. +Specifying a value of +<emphasis>zero</emphasis> +for the +<parameter>delay</parameter> +parameter causes +<function>XkbSetBounceKeysDelay</function> +to generate a +<errorname>BadValue</errorname> +protocol error. If a compatible version of the Xkb extension is not available +in the server, +<function>XkbSetBounceKeysDelay</function> +returns +<symbol>False</symbol>. </para> </sect2> @@ -2605,32 +2626,30 @@ False</emphasis> <para> Some people find it difficult or even impossible to press two keys at once. For example, a one-fingered typist or someone using a mouth stick cannot press the -<emphasis> -Shift</emphasis> - and <emphasis> -1</emphasis> - keys at the same time. The <emphasis> -StickyKeys</emphasis> - control solves this problem by changing the behavior of the modifier keys. -With <emphasis> -StickyKeys</emphasis> -, the user can first press a modifier, release it, then press another key. For +<keycap>Shift</keycap> +and +<keycap>1</keycap> +keys at the same time. The +<emphasis>StickyKeys</emphasis> +control solves this problem by changing the behavior of the modifier keys. +With +<emphasis>StickyKeys</emphasis>, +the user can first press a modifier, release it, then press another key. For example, to get an exclamation point on a PC-style keyboard, the user can press -the <emphasis> -Shift</emphasis> - key, release it, and then press the <emphasis> -1</emphasis> - key. +the +<keycap>Shift</keycap> +key, release it, and then press the +<keycap>1</keycap> +key. </para> <para> -<emphasis> -StickyKeys</emphasis> - also allows users to lock modifier keys without requiring special locking -keys. When <emphasis> -StickyKeys</emphasis> - is enabled, a modifier is latched when the user presses it just once. The user +<emphasis>StickyKeys</emphasis> +also allows users to lock modifier keys without requiring special locking +keys. When +<emphasis>StickyKeys</emphasis> +is enabled, a modifier is latched when the user presses it just once. The user can press a modifier twice in a row to lock it, and then unlock it by pressing it one more time. </para> @@ -2639,42 +2658,41 @@ it one more time. <para> When a modifier is latched, it becomes unlatched when the user presses a nonmodifier key or a pointer button. For instance, to enter the sequence -<emphasis> -Shift</emphasis> -+<emphasis> -Control</emphasis> -+<emphasis> -Z</emphasis> - the user could press and release the <emphasis> -Shift</emphasis> - key to latch it, then press and release the <emphasis> -Control</emphasis> - key to latch it, and finally press and release the Z key. Because the -<emphasis> -Control</emphasis> - key is a modifier key, pressing it does not unlatch the <emphasis> -Shift</emphasis> - key. Thus, after the user presses the <emphasis> -Control</emphasis> - key, both the <emphasis> -Shift</emphasis> - and <emphasis> -Control</emphasis> - modifiers are latched. When the user presses the <emphasis> -Z</emphasis> - key, the effect is as though the user had pressed <emphasis> -Shift</emphasis> -+<emphasis> -Control</emphasis> -+<emphasis> -Z</emphasis> -. In addition, because the <emphasis> -Z</emphasis> - key is not a modifier key, the <emphasis> -Shift</emphasis> - and <emphasis> -Control</emphasis> - modifiers are unlatched. +<keycombo> +<keycap>Shift</keycap> +<keycap>Control</keycap> +<keycap>Z</keycap> +</keycombo> +the user could press and release the +<keycap>Shift</keycap> +key to latch it, then press and release the +<keycap>Control</keycap> +key to latch it, and finally press and release the +<keycap>Z</keycap> key. Because the +<keycap>Control</keycap> +key is a modifier key, pressing it does not unlatch the +<keycap>Shift</keycap> +key. Thus, after the user presses the +<keycap>Control</keycap> +key, both the +<symbol>Shift</symbol> +and +<symbol>Control</symbol> +modifiers are latched. When the user presses the +<keycap>Z</keycap> +key, the effect is as though the user had pressed +<keycombo> +<keycap>Shift</keycap> +<keycap>Control</keycap> +<keycap>Z</keycap> +</keycombo>. +In addition, because the +<keycap>Z</keycap> +key is not a modifier key, the +<symbol>Shift</symbol> +and +<symbol>Control</symbol> +modifiers are unlatched. </para> @@ -2683,35 +2701,30 @@ Locking a modifier key means that the modifier affects any key or pointer button the user presses until the user unlocks it or it is unlocked programmatically. For example, to enter the sequence ("XKB") on a keyboard where ‘(’ is a shifted ‘9’, ‘)’ is a shifted ‘0’, and ‘"’ -is a shifted single quote, the user could press and release the <emphasis> -Shift</emphasis> - key twice to lock the <emphasis> -Shift</emphasis> - modifier. Then, when the user presses the <emphasis> -9</emphasis> -, <emphasis> -‘</emphasis> -, <emphasis> -x</emphasis> -, <emphasis> -k</emphasis> -, <emphasis> -b</emphasis> -, <emphasis> -‘</emphasis> -, and <emphasis> -0</emphasis> - keys in sequence, it generates ("XKB"). To unlock the <emphasis> -Shift</emphasis> - modifier, the user can press and release the <emphasis> -Shift</emphasis> - key. +is a shifted single quote, the user could press and release the +<keycap>Shift</keycap> +key twice to lock the +<symbol>Shift</symbol> +modifier. Then, when the user presses the +<keycap>9</keycap>, +<keycap>'</keycap>, +<keycap>x</keycap>, +<keycap>k</keycap>, +<keycap>b</keycap>, +<keycap>'</keycap>, +and +<keycap>0</keycap> +keys in sequence, it generates ("XKB"). To unlock the +<symbol>Shift</symbol> +modifier, the user can press and release the +<keycap>Shift</keycap> +key. </para> <para> <emphasis>StickyKeys</emphasis> - is a boolean control with two separate attributes that may be individually +is a boolean control with two separate attributes that may be individually configured: one to automatically disable it, and one to control the latching behavior of modifier keys. </para> @@ -2720,205 +2733,206 @@ behavior of modifier keys. <title>StickyKeys Options</title> <para> -The <emphasis> -StickyKeys</emphasis> - control has two options that can be accessed via the <emphasis> -ax_options</emphasis> - of an <emphasis> -XkbControlsRec</emphasis> - structure (see section 10.8). The first option, <emphasis> -TwoKeys</emphasis> -, specifies whether <emphasis> -StickyKeys</emphasis> - should automatically turn off when two keys are pressed at the same time. This +The +<emphasis>StickyKeys</emphasis> +control has two options that can be accessed via the +<structfield>ax_options</structfield> +of an +<structname>XkbControlsRec</structname> +structure (see <link linkend="The_XkbControlsRec_Structure">section 10.8</link>). The first option, +<emphasis>TwoKeys</emphasis>, +specifies whether +<emphasis>StickyKeys</emphasis> +should automatically turn off when two keys are pressed at the same time. This feature is useful for shared computers so people who do not want them do not -need to turn <emphasis> -StickyKeys</emphasis> - off if a previous user left <emphasis> -StickyKeys</emphasis> - on. The second option, <emphasis> -LatchToLock</emphasis> -, specifies whether or not <emphasis> -StickyKeys</emphasis> - locks a modifier when pressed twice in a row. +need to turn +<emphasis>StickyKeys</emphasis> +off if a previous user left +<emphasis>StickyKeys</emphasis> +on. The second option, +<emphasis>LatchToLock</emphasis>, +specifies whether or not +<emphasis>StickyKeys</emphasis> +locks a modifier when pressed twice in a row. </para> <para> -Use <emphasis> -XkbGetStickyKeysOptions</emphasis> - to query the current <emphasis> -StickyKeys</emphasis> - attributes for a keyboard device. -</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> -XkbGetStickyKeysOptions</emphasis> -(<emphasis> -display</emphasis> -,<emphasis> - device_spec</emphasis> -,<emphasis> - options_rtrn</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </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> -options_rtrn</emphasis> -; /* backfilled with StickyKeys option mask */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetStickyKeysOptions </emphasis> -requests the attributes of the <emphasis> -StickyKeys</emphasis> - control from the server, waits for a reply, and backfills <emphasis> -options_rtrn </emphasis> -with a mask indicating whether the individual <emphasis> -StickyKeys</emphasis> - options are on or off. Valid bits in <emphasis> -options_rtrn</emphasis> - are: -</para> - -<para> -<programlisting> - <emphasis>XkbAX_TwoKeysMask</emphasis> - <emphasis>XkbAX_LatchToLockMask</emphasis> -</programlisting> -</para> +Use +<function>XkbGetStickyKeysOptions</function> +to query the current +<emphasis>StickyKeys</emphasis> +attributes for a keyboard device. +</para> + +<indexterm significance="preferred" zone="XkbGetStickyKeysOptions"><primary><function>XkbGetStickyKeysOptions</function></primary></indexterm> +<funcsynopsis id="XkbGetStickyKeysOptions"> + <funcprototype> + <funcdef>Bool <function>XkbGetStickyKeysOptions</function></funcdef> +<!-- ( +<parameter>display</parameter>, +<parameter>device_spec</parameter>, +<parameter>options_rtrn</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int *<parameter>options_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>options_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with StickyKeys option mask + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetStickyKeysOptions</function> +requests the attributes of the +<emphasis>StickyKeys</emphasis> +control from the server, waits for a reply, and backfills +<parameter>options_rtrn</parameter> +with a mask indicating whether the individual +<emphasis>StickyKeys</emphasis> +options are on or off. Valid bits in +<parameter>options_rtrn</parameter> +are: -<para> -<emphasis> -XkbGetStickyKeysOptions </emphasis> -returns <emphasis> -True</emphasis> - if successful; if a compatible version of the Xkb extension is not available -in the server <emphasis> -XkbGetStickyKeysOptions</emphasis> - returns <emphasis> -False</emphasis> -. + <simplelist type='vert' columns='1'> + <member><symbol>XkbAX_TwoKeysMask</symbol></member> + <member><symbol>XkbAX_LatchToLockMask</symbol></member> + </simplelist> </para> - <para> -To set the <emphasis> -StickyKeys</emphasis> - attributes for a keyboard device, use <emphasis> -XkbSetStickyKeysOptions</emphasis> -. +<function>XkbGetStickyKeysOptions</function> +returns +<symbol>True</symbol> +if successful; if a compatible version of the Xkb extension is not available +in the server +<function>XkbGetStickyKeysOptions</function> +returns +<symbol>False</symbol>. </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> -XkbSetStickyKeysOptions</emphasis> -(<emphasis> -display</emphasis> -,<emphasis> - device_spec, mask, values</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device to configure, or XkbUseCoreKbd */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -mask</emphasis> -; /* selects StickyKeys attributes to modify */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -values;</emphasis> - /* values for selected attributes */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - <para> -<emphasis> -XkbSetStickyKeysOptions</emphasis> - sends a request to configure the <emphasis> -StickyKeys</emphasis> - control to the server.<emphasis> - </emphasis> -It does not wait for a reply and normally returns <emphasis> -True</emphasis> -. The valid bits to use for both the <emphasis> -mask</emphasis> - and <emphasis> -values</emphasis> - parameters are: -</para> +To set the +<emphasis>StickyKeys</emphasis> +attributes for a keyboard device, use +<function>XkbSetStickyKeysOptions</function>. +</para> + + +<indexterm significance="preferred" zone="XkbSetStickyKeysOptions"><primary><function>XkbSetStickyKeysOptions</function></primary></indexterm> +<funcsynopsis id="XkbSetStickyKeysOptions"> + <funcprototype> + <funcdef>Bool <function>XkbSetStickyKeysOptions</function></funcdef> +<!-- ( +<parameter>display</parameter>, +<parameter>device_spec, mask, values</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int <parameter>mask</parameter></paramdef> + <paramdef>unsigned int <parameter>values</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device to configure, or XkbUseCoreKbd + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>mask</parameter> + </term> + <listitem> + <para> + selects StickyKeys attributes to modify + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>values</parameter> + </term> + <listitem> + <para> + values for selected attributes + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSetStickyKeysOptions</function> +sends a request to configure the +<emphasis>StickyKeys</emphasis> +control to the server. +It does not wait for a reply and normally returns +<symbol>True</symbol>. +The valid bits to use for both the +<parameter>mask</parameter> +and +<parameter>values</parameter> +parameters are: -<para> -<programlisting> - <emphasis>XkbAX_TwoKeysMask</emphasis> - <emphasis>XkbAX_LatchToLockMask</emphasis> -</programlisting> + <simplelist type='vert' columns='1'> + <member><symbol>XkbAX_TwoKeysMask</symbol></member> + <member><symbol>XkbAX_LatchToLockMask</symbol></member> + </simplelist> </para> <para> - If a compatible version of the Xkb extension is not available in the server, -<emphasis> -XkbSetStickyKeysOptions</emphasis> - returns <emphasis> -False</emphasis> -. +If a compatible version of the Xkb extension is not available in the server, +<function>XkbSetStickyKeysOptions</function> +returns +<symbol>False</symbol>. </para> </sect3> @@ -2931,36 +2945,33 @@ False</emphasis> There are several controls that apply to the keyboard mapping in general. They control handling of out-of-range group indices and how modifiers are processed and consumed in the server. These are: -</para> -<para> -<programlisting> - <emphasis>GroupsWrap</emphasis> - <emphasis>IgnoreGroupLock</emphasis> - <emphasis>IgnoreLockMods</emphasis> - <emphasis>InternalMods </emphasis> -</programlisting> + <simplelist type='vert' columns='1'> + <member><emphasis>GroupsWrap</emphasis></member> + <member><emphasis>IgnoreGroupLock</emphasis></member> + <member><emphasis>IgnoreLockMods</emphasis></member> + <member><emphasis>InternalMods</emphasis></member> + </simplelist> </para> <para> -<emphasis> -IgnoreGroupLock</emphasis> - is a boolean control; the rest are always active. +<emphasis>IgnoreGroupLock</emphasis> +is a boolean control; the rest are always active. </para> <para> Without the modifier processing options provided by Xkb, passive grabs set via -translations in a client (for example, <emphasis> -Alt<KeyPress>space</emphasis> -) do not trigger if any modifiers other than those specified by the translation -are set. This results in problems in the user interface when either <emphasis> -NumLock</emphasis> - or a secondary keyboard group is active. The <emphasis> -IgnoreLockMods</emphasis> - and <emphasis> -IgnoreGroupLock</emphasis> - controls make it possible to avoid this behavior without exhaustively +translations in a client (for example, +<emphasis>Alt<KeyPress>space</emphasis>) +do not trigger if any modifiers other than those specified by the translation +are set. This results in problems in the user interface when either +<emphasis>NumLock</emphasis> +or a secondary keyboard group is active. The +<emphasis>IgnoreLockMods</emphasis> +and +<emphasis>IgnoreGroupLock</emphasis> +controls make it possible to avoid this behavior without exhaustively specifying a grab for every possible modifier combination. </para> @@ -2968,23 +2979,23 @@ specifying a grab for every possible modifier combination. <title>The GroupsWrap Control</title> <para> -The <emphasis> -GroupsWrap</emphasis> - control determines how illegal groups are handled on a global basis. There are +The +<emphasis>GroupsWrap</emphasis> +control determines how illegal groups are handled on a global basis. There are a number of valid keyboard sequences that can cause the effective group number to go out of range. When this happens, the group must be normalized back to a -valid number. The <emphasis> -GroupsWrap</emphasis> - control specifies how this is done. +valid number. The +<emphasis>GroupsWrap</emphasis> +control specifies how this is done. </para> <para> When dealing with group numbers, all computations are done using the group index, which is the group number minus one. There are three different -algorithms; the <emphasis> -GroupsWrap</emphasis> - control specifies which one is used: +algorithms; the +<emphasis>GroupsWrap</emphasis> +control specifies which one is used: </para> <itemizedlist> @@ -2992,9 +3003,9 @@ GroupsWrap</emphasis> <para>XkbRedirectIntoRange</para> <para> All invalid group numbers are converted to a valid group number by taking the -last four bits of the <emphasis> -GroupsWrap</emphasis> - control and using them as the group index. If the result is still out of +last four bits of the +<emphasis>GroupsWrap</emphasis> +control and using them as the group index. If the result is still out of range, Group one is used. </para> </listitem> @@ -3018,25 +3029,24 @@ modulus applied to the group index. </itemizedlist> <para> -There are no convenience functions for manipulating the <emphasis> -GroupsWrap</emphasis> - control. Manipulate the <emphasis> -GroupsWrap</emphasis> - control via the <emphasis> -groups_wrap</emphasis> - field in the <emphasis> -XkbControlsRec</emphasis> - structure, then use <emphasis> -XkbSetControls</emphasis> - and <emphasis> -XkbGetControls</emphasis> - (see section 10.9 and section 10.10) to query and change this control. <!-- xref --> +There are no convenience functions for manipulating the +<emphasis>GroupsWrap</emphasis> +control. Manipulate the +<emphasis>GroupsWrap</emphasis> +control via the +<structfield>groups_wrap</structfield> +field in the +<structname>XkbControlsRec</structname> +structure, then use +<function>XkbSetControls</function> +and +<function>XkbGetControls</function> +(see <link linkend="Querying_Controls">section 10.9</link> and <link linkend="Changing_Controls">section 10.10</link>) to query and change this control. </para> -<note><para>See also section 15.3.2 or a discussion of the related field, <!-- xref --> -<emphasis> -group_info</emphasis> -, which also normalizes a group under certain circumstances.</para></note> +<note><para>See also <link linkend="Per_Key_Group_Information">section 15.3.2</link> or a discussion of the related field, +<structfield>group_info</structfield>, +which also normalizes a group under certain circumstances.</para></note> </sect2> <sect2 id='The_IgnoreLockMods_Control'> @@ -3050,176 +3060,184 @@ unanticipated side effects. <para> -The <emphasis> -IgnoreLockMods</emphasis> - control specifies modifiers that should be excluded from grab calculations. -These modifiers are also not reported in any core events except <emphasis> -KeyPress</emphasis> - and <emphasis> -KeyRelease</emphasis> - events that do not activate a passive grab and that do not occur while a grab +The +<emphasis>IgnoreLockMods</emphasis> +control specifies modifiers that should be excluded from grab calculations. +These modifiers are also not reported in any core events except +<symbol>KeyPress</symbol> +and +<symbol>KeyRelease</symbol> +events that do not activate a passive grab and that do not occur while a grab is active. </para> <para> -Manipulate the <emphasis> -IgnoreLockMods</emphasis> - control via the <emphasis> -ignore_lock</emphasis> - field in the <emphasis> -XkbControlsRec</emphasis> - structure, then use <emphasis> -XkbSetControls</emphasis> - and <emphasis> -XkbGetControls</emphasis> - (see sections 10.9 and 10.10) to query and change this control. Alternatively, <!-- xref --> -use <emphasis> -XkbSetIgnoreLockMods</emphasis> -. +Manipulate the +<emphasis>IgnoreLockMods</emphasis> +control via the +<structfield>ignore_lock</structfield> +field in the +<structname>XkbControlsRec</structname> +structure, then use +<function>XkbSetControls</function> +and +<function>XkbGetControls</function> +(see <link linkend="Querying_Controls">section 10.9</link> and <link linkend="Changing_Controls">section 10.10</link>) to query and change this control. Alternatively, +use +<function>XkbSetIgnoreLockMods</function>. </para> <para> To set the modifiers that, if locked, are not to be reported in matching events -to passive grabs, use <emphasis> -XkbSetIgnoreLockMods.</emphasis> -</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> -XkbSetIgnoreLockMods</emphasis> -(<emphasis> -display, device_spec, affect_real, real_values, affect_virtual, -virtual_values</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -display</emphasis> -; /* connection to the X server */ - </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> - affect_real</emphasis> -; /* mask of real modifiers affected by this call */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - real_values</emphasis> -; /* values for affected real modifiers (1=>set, 0=>unset) */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - affect_virtual</emphasis> -; /* mask of virtual modifiers affected by this call */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - virtual_values</emphasis> -; /* values for affected virtual modifiers (1=>set, 0=>unset) -*/ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSetIgnoreLockMods</emphasis> - sends a request to the server to change the server’s <emphasis> -IgnoreLockMods</emphasis> - control. <emphasis> -affect_real</emphasis> - and <emphasis> -real_values</emphasis> - are masks of real modifier bits indicating which real modifiers are to be -added and removed from the server’s <emphasis> -IgnoreLockMods</emphasis> - control. Modifiers selected by both <emphasis> -affect_real</emphasis> - and <emphasis> -real_values</emphasis> - are added to the server’s <emphasis> -IgnoreLockMods</emphasis> - control; those selected by <emphasis> -affect_real</emphasis> - but not by <emphasis> -real_values</emphasis> - are removed from the server’s <emphasis> -IgnoreLockMods</emphasis> - control. Valid values for <emphasis> -affect_real</emphasis> - and <emphasis> -real_values</emphasis> - consist of any combination of the eight core modifier bits: <emphasis> -ShiftMask</emphasis> -, <emphasis> -LockMask</emphasis> -, <emphasis> -ControlMask</emphasis> -, <emphasis> -Mod1Mask</emphasis> - - <emphasis> -Mod5Mask</emphasis> -. <emphasis> -affect_virtual</emphasis> - and <emphasis> -virtual_values</emphasis> - are masks of virtual modifier bits indicating which virtual modifiers are to -be added and removed from the server’s <emphasis> -IgnoreLockMods</emphasis> - control. Modifiers selected by both <emphasis> -affect_virtual</emphasis> - and <emphasis> -virtual_values</emphasis> - are added to the server’s <emphasis> -IgnoreLockMods</emphasis> - control; those selected by <emphasis> -affect_virtual</emphasis> - but not by <emphasis> -virtual_values</emphasis> - are removed from the server’s <emphasis> -IgnoreLockMods</emphasis> - control.<emphasis> - </emphasis> -See section 7.1 for a discussion of virtual modifier masks to use in <emphasis> <!-- xref --> -affect_virtual</emphasis> - and <emphasis> -virtual_values</emphasis> -. <emphasis> -XkbSetIgnoreLockMods</emphasis> - does not wait for a reply from the server. It returns <emphasis> -True</emphasis> - if the request was sent, and <emphasis> -False</emphasis> - otherwise. +to passive grabs, use +<function>XkbSetIgnoreLockMods</function>. +</para> + +<indexterm significance="preferred" zone="XkbSetIgnoreLockMods"><primary><function>XkbSetIgnoreLockMods</function></primary></indexterm> +<funcsynopsis id="XkbSetIgnoreLockMods"> + <funcprototype> + <funcdef>Bool <function>XkbSetIgnoreLockMods</function></funcdef> +<!-- ( +<parameter>display, device_spec, affect_real, real_values, affect_virtual, +virtual_values</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int <parameter>affect_real</parameter></paramdef> + <paramdef>unsigned int <parameter>real_values</parameter></paramdef> + <paramdef>unsigned int <parameter>affect_virtual</parameter></paramdef> + <paramdef>unsigned int <parameter>virtual_values</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>affect_real</parameter> + </term> + <listitem> + <para> + mask of real modifiers affected by this call + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>real_values</parameter> + </term> + <listitem> + <para> + values for affected real modifiers (1⇒set, 0⇒unset) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>affect_virtual</parameter> + </term> + <listitem> + <para> + mask of virtual modifiers affected by this call + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>virtual_values</parameter> + </term> + <listitem> + <para> + values for affected virtual modifiers (1⇒set, 0⇒unset) + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSetIgnoreLockMods</function> +sends a request to the server to change the server’s +<emphasis>IgnoreLockMods</emphasis> +control. +<parameter>affect_real</parameter> +and +<parameter>real_values</parameter> +are masks of real modifier bits indicating which real modifiers are to be +added and removed from the server’s +<emphasis>IgnoreLockMods</emphasis> +control. Modifiers selected by both +<parameter>affect_real</parameter> +and +<parameter>real_values</parameter> +are added to the server’s +<emphasis>IgnoreLockMods</emphasis> +control; those selected by +<parameter>affect_real</parameter> +but not by +<parameter>real_values</parameter> +are removed from the server’s +<emphasis>IgnoreLockMods</emphasis> +control. Valid values for +<parameter>affect_real</parameter> +and +<parameter>real_values</parameter> +consist of any combination of the eight core modifier bits: +<symbol>ShiftMask</symbol>, +<symbol>LockMask</symbol>, +<symbol>ControlMask</symbol>, +<symbol>Mod1Mask</symbol> +– +<symbol>Mod5Mask</symbol>. +<parameter>affect_virtual</parameter> +and +<parameter>virtual_values</parameter> +are masks of virtual modifier bits indicating which virtual modifiers are to +be added and removed from the server’s +<emphasis>IgnoreLockMods</emphasis> +control. Modifiers selected by both +<parameter>affect_virtual</parameter> +and +<parameter>virtual_values</parameter> +are added to the server’s +<emphasis>IgnoreLockMods</emphasis> +control; those selected by +<parameter>affect_virtual</parameter> +but not by +<parameter>virtual_values</parameter> +are removed from the server’s +<emphasis>IgnoreLockMods</emphasis> +control. +See <link linkend="Virtual_Modifier_Names_and_Masks">section 7.1</link> for a discussion of virtual modifier masks to use in +<parameter>affect_virtual</parameter> +and +<parameter>virtual_values</parameter>. +<function>XkbSetIgnoreLockMods</function> +does not wait for a reply from the server. It returns +<symbol>True</symbol> +if the request was sent, and +<symbol>False</symbol> +otherwise. </para> </sect2> @@ -3227,18 +3245,18 @@ False</emphasis> <title>The IgnoreGroupLock Control</title> <para> -The <emphasis> -IgnoreGroupLock</emphasis> - control is a boolean control with no attributes. If enabled, it specifies that +The +<emphasis>IgnoreGroupLock</emphasis> +control is a boolean control with no attributes. If enabled, it specifies that the locked state of the keyboard group should not be considered when activating passive grabs. </para> <para> -Because <emphasis> -IgnoreGroupLock</emphasis> - is a boolean control with no attributes, use the general boolean controls -functions (see section 10.1) to change its state. <!-- xref --> +Because +<emphasis>IgnoreGroupLock</emphasis> +is a boolean control with no attributes, use the general boolean controls +functions (see <link linkend="Controls_that_Enable_and_Disable_Other_Controls">section 10.1</link>) to change its state. </para> @@ -3249,171 +3267,176 @@ functions (see section 10.1) to change its state. <!-- xref --> <para> The core protocol does not provide any means to prevent a modifier from being reported in events sent to clients; Xkb, however makes this possible via the -<emphasis> -InternalMods</emphasis> - control. It specifies modifiers that should be consumed by the server and not +<emphasis>InternalMods</emphasis> +control. It specifies modifiers that should be consumed by the server and not reported to clients. When a key is pressed and a modifier that has its bit set -in the <emphasis> -InternalMods</emphasis> - control is reported to the server, the server uses the modifier when +in the +<emphasis>InternalMods</emphasis> +control is reported to the server, the server uses the modifier when determining the actions to apply for the key. The server then clears the bit, so it is not actually reported to the client. In addition, modifiers specified -in the <emphasis> -InternalMods</emphasis> - control are not used to determine grabs and are not used to calculate core +in the +<emphasis>InternalMods</emphasis> +control are not used to determine grabs and are not used to calculate core protocol compatibility state. </para> <para> -Manipulate the <emphasis> -InternalMods</emphasis> - control via the <emphasis> -internal</emphasis> - field in the <emphasis> -XkbControlsRec</emphasis> - structure, using <emphasis> -XkbSetControls</emphasis> - and <emphasis> -XkbGetControls</emphasis> - (see sections10.9 and 10.10). Alternatively, use <emphasis> <!-- xref --> -XkbSetServerInternalMods</emphasis> -. +Manipulate the +<emphasis>InternalMods</emphasis> +control via the +<structfield>internal</structfield> +field in the +<structname>XkbControlsRec</structname> +structure, using +<function>XkbSetControls</function> +and +<function>XkbGetControls</function> +(see <link linkend="Querying_Controls">section 10.9</link> +and <link linkend="Changing_Controls">section 10.10</link>). Alternatively, use +<function>XkbSetServerInternalMods</function>. </para> <para> To set the modifiers that are consumed by the server before events are -delivered to the client, use <emphasis> -XkbSetServerInternalMods.</emphasis> -</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> -XkbSetServerInternalMods</emphasis> -(<emphasis> -display, device_spec, affect_real, real_values, affect_virtual, -virtual_values</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -display</emphasis> -; /* connection to the X server */ - </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> - affect_real</emphasis> -; /* mask of real modifiers affected by this call */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - real_values</emphasis> -; /* values for affected real modifiers (1=>set, 0=>unset) */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - affect_virtual</emphasis> -; /* mask of virtual modifiers affected by this call */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - virtual_values</emphasis> -; /* values for affected virtual modifiers (1=>set, 0=>unset) -*/ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSetServerInternalMods</emphasis> - sends a request to the server to change the internal modifiers consumed by the -server. <emphasis> -affect_real</emphasis> - and <emphasis> -real_values</emphasis> - are masks of real modifier bits indicating which real modifiers are to be +delivered to the client, use +<function>XkbSetServerInternalMods</function>. +</para> + +<indexterm significance="preferred" zone="XkbSetServerInternalMods"><primary><function>XkbSetServerInternalMods</function></primary></indexterm> +<funcsynopsis id="XkbSetServerInternalMods"> + <funcprototype> + <funcdef>Bool <function>XkbSetServerInternalMods</function></funcdef> +<!-- ( +<parameter>display, device_spec, affect_real, real_values, affect_virtual, +virtual_values</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int <parameter>affect_real</parameter></paramdef> + <paramdef>unsigned int <parameter>real_values</parameter></paramdef> + <paramdef>unsigned int <parameter>affect_virtual</parameter></paramdef> + <paramdef>unsigned int <parameter>virtual_values</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + ‘device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>affect_real</parameter> + </term> + <listitem> + <para> + mask of real modifiers affected by this call + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>real_values</parameter> + </term> + <listitem> + <para> + values for affected real modifiers (1⇒set, 0⇒unset) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>affect_virtual</parameter> + </term> + <listitem> + <para> + mask of virtual modifiers affected by this call + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>virtual_values</parameter> + </term> + <listitem> + <para> + values for affected virtual modifiers (1⇒set, 0⇒unset) + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSetServerInternalMods</function> +sends a request to the server to change the internal modifiers consumed by the +server. +<parameter>affect_real</parameter> +and +<parameter>real_values</parameter> +are masks of real modifier bits indicating which real modifiers are to be added and removed from the server’s internal modifiers control. Modifiers -selected by both <emphasis> -affect_real</emphasis> - and <emphasis> -real_values</emphasis> - are added to the server’s internal modifiers control; those selected by -<emphasis> -affect_real</emphasis> - but not by <emphasis> -real_values</emphasis> - are removed from the server’s internal modifiers mask. Valid values for -<emphasis> -affect_real</emphasis> - and <emphasis> -real_values</emphasis> - consist of any combination of the eight core modifier bits: <emphasis> -ShiftMask</emphasis> -, <emphasis> -LockMask</emphasis> -, <emphasis> -ControlMask</emphasis> -, <emphasis> -Mod1Mask</emphasis> - - <emphasis> -Mod5Mask</emphasis> -.<emphasis> - affect_virtual</emphasis> - and <emphasis> -virtual_values</emphasis> - are masks of virtual modifier bits indicating which virtual modifiers are to +selected by both +<parameter>affect_real</parameter> +and +<parameter>real_values</parameter> +are added to the server’s internal modifiers control; those selected by +<parameter>affect_real</parameter> +but not by +<parameter>real_values</parameter> +are removed from the server’s internal modifiers mask. Valid values for +<parameter>affect_real</parameter> +and +<parameter>real_values</parameter> +consist of any combination of the eight core modifier bits: +<symbol>ShiftMask</symbol>, +<symbol>LockMask</symbol>, +<symbol>ControlMask</symbol>, +<symbol>Mod1Mask</symbol> +– +<symbol>Mod5Mask</symbol>. +<parameter>affect_virtual</parameter> +and +<parameter>virtual_values</parameter> +are masks of virtual modifier bits indicating which virtual modifiers are to be added and removed from the server’s internal modifiers control. Modifiers -selected by both <emphasis> -affect_virtual</emphasis> - and <emphasis> -virtual_values</emphasis> - are added to the server’s internal modifiers control; those selected by -<emphasis> -affect_virtual</emphasis> - but not by <emphasis> -virtual_values</emphasis> - are removed from the server’s internal modifiers control.<emphasis> - </emphasis> -See section 7.1 for a discussion of virtual modifier masks to use in <emphasis> <!-- xref --> -affect_virtual</emphasis> - and <emphasis> -virtual_values</emphasis> -.<emphasis> - XkbSetServerInternalMods</emphasis> - does not wait for a reply from the server. It returns <emphasis> -True</emphasis> - if the request was sent and <emphasis> -False</emphasis> - otherwise. +selected by both +<parameter>affect_virtual</parameter> +and +<parameter>virtual_values</parameter> +are added to the server’s internal modifiers control; those selected by +<parameter>affect_virtual</parameter> +but not by +<parameter>virtual_values</parameter> +are removed from the server’s internal modifiers control. +See <link linkend="Virtual_Modifier_Names_and_Masks">section 7.1</link> for a discussion of virtual modifier masks to use in +<parameter>affect_virtual</parameter> +and +<parameter>virtual_values</parameter>. +<function>XkbSetServerInternalMods</function> +does not wait for a reply from the server. It returns +<symbol>True</symbol> +if the request was sent and +<symbol>False</symbol> +otherwise. </para> @@ -3422,77 +3445,87 @@ False</emphasis> <sect1 id='The_XkbControlsRec_Structure'> <title>The XkbControlsRec Structure</title> +<indexterm significance="preferred" zone="The_XkbControlsRec_Structure"> +<primary><structname>XkbControlsRec</structname></primary></indexterm> + <para> Many of the individual controls described in sections 10.1 through 10.7 may be manipulated via convenience functions discussed in those sections. Some of -them, however, have no convenience functions. The <emphasis> -XkbControlsRec</emphasis> - structure allows the manipulation of one or more of the controls in a single -operation and to track changes to any of them in conjunction with the <emphasis> -XkbGetControls</emphasis> - and <emphasis> -XkbSetControls</emphasis> - functions. This is the only way to manipulate those controls that have no +them, however, have no convenience functions. The +<structname>XkbControlsRec</structname> +structure allows the manipulation of one or more of the controls in a single +operation and to track changes to any of them in conjunction with the +<function>XkbGetControls</function> +and +<function>XkbSetControls</function> +functions. This is the only way to manipulate those controls that have no convenience functions. </para> <para> -The <emphasis> -XkbControlsRec</emphasis> - structure is defined as follows: -</para> +The +<structname>XkbControlsRec</structname> +structure is defined as follows: -<para> <programlisting> #define XkbMaxLegalKeyCode 255 #define XkbPerKeyBitArraySize ((XkbMaxLegalKeyCode+1)/8) -</programlisting> -</para> -<para> -<programlisting> + typedef struct { - unsigned char mk_dflt_btn; /* default button for keyboard driven mouse */ - unsigned char num_groups; /* number of keyboard groups */ - unsigned char groups_wrap; /* how to wrap out-of-bounds groups */ - XkbModsRec internal; /* defines server internal modifiers */ - XkbModsRec ignore_lock; /* modifiers to ignore when checking for grab */ - unsigned int enabled_ctrls; /* 1 bit => corresponding boolean control enabled */ - unsigned short repeat_delay; /* ms delay until first repeat */ - unsigned short repeat_interval; /* ms delay between repeats */ - unsigned short slow_keys_delay; /* ms minimum time key must be down to be ok */ - unsigned short debounce_delay; /* ms delay before key reactivated */ - unsigned short mk_delay; /* ms delay to second mouse motion event */ - unsigned short mk_interval; /* ms delay between repeat mouse events */ - unsigned short mk_time_to_max; /* # intervals until constant mouse move */ - unsigned short mk_max_speed; /* multiplier for maximum mouse speed */ - short mk_curve; /* determines mouse move curve type */ - unsigned short ax_options; /* 1 bit => Access X option enabled */ - unsigned short ax_timeout; /* seconds until Access X disabled */ - unsigned short axt_opts_mask; /* 1 bit => options to reset on Access X timeout */ - unsigned short axt_opts_values; /* 1 bit => turn option on, 0=> off */ - unsigned int axt_ctrls_mask; /* which bits in <emphasis> enabled_ctrls</emphasis> to modify */ - unsigned int axt_ctrls_values; /* values for new bits in <emphasis> enabled_ctrls</emphasis> */ - unsigned char per_key_repeat[XkbPerKeyBitArraySize]; /* per key auto repeat */ -} <emphasis>XkbControlsRec</emphasis>, *XkbControlsPtr; + unsigned char mk_dflt_btn; /* default button for + keyboard driven mouse */ + unsigned char num_groups; /* number of keyboard groups */ + unsigned char groups_wrap; /* how to wrap out-of-bounds groups */ + XkbModsRec internal; /* defines server internal modifiers */ + XkbModsRec ignore_lock; /* modifiers to ignore when + checking for grab */ + unsigned int enabled_ctrls; /* 1 bit ⇒ corresponding + boolean control enabled */ + unsigned short repeat_delay; /* ms delay until first repeat */ + unsigned short repeat_interval; /* ms delay between repeats */ + unsigned short slow_keys_delay; /* ms minimum time key must be + down to be ok */ + unsigned short debounce_delay; /* ms delay before key reactivated */ + unsigned short mk_delay; /* ms delay to second mouse + motion event */ + unsigned short mk_interval; /* ms delay between repeat mouse + events */ + unsigned short mk_time_to_max; /* # intervals until constant + mouse move */ + unsigned short mk_max_speed; /* multiplier for maximum mouse speed */ + short mk_curve; /* determines mouse move curve type */ + unsigned short ax_options; /* 1 bit ⇒ Access X option enabled */ + unsigned short ax_timeout; /* seconds until Access X disabled */ + unsigned short axt_opts_mask; /* 1 bit ⇒ options to reset + on Access X timeout */ + unsigned short axt_opts_values; /* 1 bit ⇒ turn option on, 0⇒ off */ + unsigned int axt_ctrls_mask; /* which bits in <structfield>enabled_ctrls</structfield> + to modify */ + unsigned int axt_ctrls_values; /* values for new bits in + <structfield>enabled_ctrls</structfield> */ + unsigned char per_key_repeat[XkbPerKeyBitArraySize]; + /* per key auto repeat */ +} <structname>XkbControlsRec</structname>, *XkbControlsPtr; </programlisting> </para> <para> -The general-purpose functions that work with the <emphasis> -XkbControlsRec</emphasis> - structure use a mask to specify which controls are to be manipulated. Table -10.6 lists these controls, the masks used to select them in the general -function calls (<emphasis> -which</emphasis> - parameter), and the data fields in the <emphasis> -XkbControlsRec</emphasis> - structure that comprise each of the individual controls. Also listed are the +The general-purpose functions that work with the +<structname>XkbControlsRec</structname> +structure use a mask to specify which controls are to be manipulated. +<link linkend="table10.6">Table 10.6</link> +lists these controls, the masks used to select them in the general +function calls +(<structfield>which</structfield> +parameter), and the data fields in the +<structname>XkbControlsRec</structname> +structure that comprise each of the individual controls. Also listed are the bit used to turn boolean controls on and off and the section where each control is described in more detail. </para> -<table frame='topbot'> +<table id='table10.6' frame='topbot'> <title>Xkb Controls</title> <?dbfo keep-together="auto" ?> <tgroup cols='5' align='left' colsep='0' rowsep='0'> @@ -3513,21 +3546,21 @@ is described in more detail. <tbody> <row> <entry>AccessXFeedback</entry> - <entry>XkbAccessXFeedbackMask</entry> + <entry><symbol>XkbAccessXFeedbackMask</symbol></entry> <entry>ax_options: XkbAX_*FBMask</entry> <entry>XkbAccessXFeedback­Mask</entry> - <entry>10.6.3</entry> <!-- xref --> + <entry><link linkend="The_AccessXFeedback_Control">10.6.3</link></entry> </row> <row> <entry>AccessXKeys</entry> <entry></entry> <entry></entry> <entry>XkbAccessXKeys­Mask</entry> - <entry>10.6.1</entry> <!-- xref --> + <entry><link linkend="The_AccessXKeys_Control">10.6.1</link></entry> </row> <row> <entry>AccessXTimeout</entry> - <entry>XkbAccessXTimeoutMask</entry> + <entry><symbol>XkbAccessXTimeoutMask</symbol></entry> <entry> <para>ax_timeout</para> <para>axt_opts_mask</para> @@ -3536,81 +3569,81 @@ is described in more detail. <para>axt_ctrls_values</para> </entry> <entry>XkbAccessXTimeout­Mask</entry> - <entry>10.6.2</entry> + <entry><link linkend="The_AccessXTimeout_Control">10.6.2</link></entry> </row> <row> <entry>AudibleBell</entry> <entry></entry> <entry></entry> - <entry>XkbAudibleBellMask</entry> - <entry>9.2</entry> + <entry><symbol>XkbAudibleBellMask</symbol></entry> + <entry><link linkend="Audible_Bells">9.2</link></entry> </row> <row> <entry>AutoReset</entry> <entry></entry> <entry></entry> <entry></entry> - <entry>10.1.2</entry> + <entry><link linkend="The_AutoReset_Control">10.1.2</link></entry> </row> <row> <entry>BounceKeys</entry> - <entry>XkbBounceKeysMask</entry> + <entry><symbol>XkbBounceKeysMask</symbol></entry> <entry>debounce_delay</entry> - <entry>XkbBounceKeysMask</entry> - <entry>10.6.7</entry> + <entry><symbol>XkbBounceKeysMask</symbol></entry> + <entry><link linkend="The_BounceKeys_Control">10.6.7</link></entry> </row> <row> <entry>Detectable-Autorepeat</entry> <entry></entry> <entry></entry> <entry></entry> - <entry>10.3.3</entry> + <entry><link linkend="The_DetectableAutorepeat_Control">10.3.3</link></entry> </row> <row> <entry>EnabledControls</entry> - <entry>XkbControlsEnabledMask</entry> + <entry><symbol>XkbControlsEnabledMask</symbol></entry> <entry>enabled_ctrls</entry> <entry><emphasis>Non-Boolean Control</emphasis></entry> - <entry>10.1.1</entry> + <entry><link linkend="The_EnabledControls_Control">10.1.1</link></entry> </row> <row> <entry>GroupsWrap</entry> - <entry>XkbGroupsWrapMask</entry> + <entry><symbol>XkbGroupsWrapMask</symbol></entry> <entry>groups_wrap</entry> <entry><emphasis>Non-Boolean Control</emphasis></entry> - <entry>10.7.1</entry> + <entry><link linkend="The_GroupsWrap_Control">10.7.1</link></entry> </row> <row> <entry>IgnoreGroupLock</entry> <entry></entry> <entry></entry> <entry>XkbIgnoreGroupLock­Mask</entry> - <entry>10.7.3</entry> + <entry><link linkend="The_IgnoreGroupLock_Control">10.7.3</link></entry> </row> <row> <entry>IgnoreLockMods</entry> - <entry>XkbIgnoreLockModsMask</entry> + <entry><symbol>XkbIgnoreLockModsMask</symbol></entry> <entry>ignore_lock</entry> <entry><emphasis>Non-Boolean Control</emphasis></entry> - <entry>5.1</entry> + <entry><link linkend="Keyboard_State_Description">5.1</link></entry> </row> <row> <entry>InternalMods</entry> - <entry>XkbInternalModsMask</entry> + <entry><symbol>XkbInternalModsMask</symbol></entry> <entry>internal</entry> <entry><emphasis>Non-Boolean Control</emphasis></entry> - <entry>5.1</entry> + <entry><link linkend="Keyboard_State_Description">5.1</link></entry> </row> <row> <entry>MouseKeys</entry> - <entry>XkbMouseKeysMask</entry> + <entry><symbol>XkbMouseKeysMask</symbol></entry> <entry>mk_dflt_btn</entry> - <entry>XkbMouseKeysMask</entry> - <entry>10.5.1</entry> + <entry><symbol>XkbMouseKeysMask</symbol></entry> + <entry><link linkend="The_MouseKeys_Control">10.5.1</link></entry> </row> <row> <entry>MouseKeysAccel</entry> - <entry>XkbMouseKeysAccelMask</entry> + <entry><symbol>XkbMouseKeysAccelMask</symbol></entry> <entry> <para>mk_delay</para> <para>mk_interval</para> @@ -3619,75 +3652,76 @@ is described in more detail. <para>mk_curve</para> </entry> <entry>XkbMouseKeysAccel­Mask</entry> - <entry>10.5.2</entry> + <entry><link linkend="The_MouseKeysAccel_Control">10.5.2</link></entry> </row> <row> <entry>Overlay1</entry> <entry></entry> <entry></entry> - <entry>XkbOverlay1Mask</entry> - <entry>10.4</entry> + <entry><symbol>XkbOverlay1Mask</symbol></entry> + <entry><link linkend="Controls_for_Keyboard_Overlays_Overlay1_and_Overlay2_Controls">10.4</link></entry> </row> <row> <entry>Overlay2</entry> <entry></entry> <entry></entry> - <entry>XkbOverlay2Mask</entry> - <entry>10.4</entry> + <entry><symbol>XkbOverlay2Mask</symbol></entry> + <entry><link linkend="Controls_for_Keyboard_Overlays_Overlay1_and_Overlay2_Controls">10.4</link></entry> </row> <row> <entry>PerKeyRepeat</entry> - <entry>XkbPerKeyRepeatMask</entry> + <entry><symbol>XkbPerKeyRepeatMask</symbol></entry> <entry>per_key_repeat</entry> <entry><emphasis>Non-Boolean Control</emphasis></entry> - <entry>10.3.1</entry> + <entry><link linkend="The_PerKeyRepeat_Control">10.3.1</link></entry> </row> <row> <entry>RepeatKeys</entry> - <entry>XkbRepeatKeysMask</entry> + <entry><symbol>XkbRepeatKeysMask</symbol></entry> <entry> <para>repeat_delay</para> <para>repeat_interval</para> </entry> - <entry>XkbRepeatKeysMask</entry> - <entry>10.3</entry> + <entry><symbol>XkbRepeatKeysMask</symbol></entry> + <entry><link linkend="Controls_for_Repeat_Key_Behavior">10.3</link></entry> </row> <row> <entry>SlowKeys</entry> - <entry>XkbSlowKeysMask</entry> + <entry><symbol>XkbSlowKeysMask</symbol></entry> <entry>slow_keys_delay</entry> - <entry>XkbSlowKeysMask</entry> - <entry>10.6.6</entry> + <entry><symbol>XkbSlowKeysMask</symbol></entry> + <entry><link linkend="The_SlowKeys_Control">10.6.6</link></entry> </row> <row> <entry>StickyKeys</entry> - <entry>XkbStickyKeysMask</entry> + <entry><symbol>XkbStickyKeysMask</symbol></entry> <entry> <para>ax_options:</para> <para>XkbAX_Two­KeysMask</para> <para>XkbAX_Latch­ToLockMask</para> </entry> - <entry>XkbStickyKeysMask</entry> - <entry>10.6.8</entry> + <entry><symbol>XkbStickyKeysMask</symbol></entry> + <entry><link linkend="The_StickyKeys_Control">10.6.8</link></entry> </row> </tbody> </tgroup> </table> <para> -Table 10.7 shows the actual values for the individual mask bits used to select <!-- xref --> +<link linkend="table10.7">Table 10.7</link> +shows the actual values for the individual mask bits used to select controls for modification and to enable and disable the control. Note that the same mask bit is used to specify general modifications to the parameters used -to configure the control (<emphasis> -which</emphasis> -), and to enable and disable the control (<emphasis> -enabled_ctrls</emphasis> -). The anomalies in the table (no "ok" in column) are for controls that have no +to configure the control +(<structfield>which</structfield>), +and to enable and disable the control +(<structfield>enabled_ctrls</structfield>). +The anomalies in the table (no <quote>ok</quote> in column) are for controls that have no configurable attributes; and for controls that are not boolean controls and therefore cannot be enabled or disabled. </para> -<table frame='topbot'> +<table id='table10.7' frame='topbot'> <title>Controls Mask Bits</title> <?dbfo keep-together="always" ?> <tgroup cols='4' align='left' colsep='0' rowsep='0'> @@ -3705,127 +3739,127 @@ therefore cannot be enabled or disabled. </thead> <tbody> <row> - <entry>XkbRepeatKeysMask</entry> + <entry><symbol>XkbRepeatKeysMask</symbol></entry> <entry>ok</entry> <entry>ok</entry> <entry>(1L<<0)</entry> </row> <row> - <entry>XkbSlowKeysMask</entry> + <entry><symbol>XkbSlowKeysMask</symbol></entry> <entry>ok</entry> <entry>ok</entry> <entry>(1L<<1)</entry> </row> <row> - <entry>XkbBounceKeysMask</entry> + <entry><symbol>XkbBounceKeysMask</symbol></entry> <entry>ok</entry> <entry>ok</entry> <entry>(1L<<2)</entry> </row> <row> - <entry>XkbStickyKeysMask</entry> + <entry><symbol>XkbStickyKeysMask</symbol></entry> <entry>ok</entry> <entry>ok</entry> <entry>(1L<<3)</entry> </row> <row> - <entry>XkbMouseKeysMask</entry> + <entry><symbol>XkbMouseKeysMask</symbol></entry> <entry>ok</entry> <entry>ok</entry> <entry>(1L<<4)</entry> </row> <row> - <entry>XkbMouseKeysAccelMask</entry> + <entry><symbol>XkbMouseKeysAccelMask</symbol></entry> <entry>ok</entry> <entry>ok</entry> <entry>(1L<<5)</entry> </row> <row> - <entry>XkbAccessXKeysMask</entry> + <entry><symbol>XkbAccessXKeysMask</symbol></entry> <entry>ok</entry> <entry>ok</entry> <entry>(1L<<6)</entry> </row> <row> - <entry>XkbAccessXTimeoutMask</entry> + <entry><symbol>XkbAccessXTimeoutMask</symbol></entry> <entry>ok</entry> <entry>ok</entry> <entry>(1L<<7)</entry> </row> <row> - <entry>XkbAccessXFeedbackMask</entry> + <entry><symbol>XkbAccessXFeedbackMask</symbol></entry> <entry>ok</entry> <entry>ok</entry> <entry>(1L<<8)</entry> </row> <row> - <entry>XkbAudibleBellMask</entry> + <entry><symbol>XkbAudibleBellMask</symbol></entry> <entry></entry> <entry>ok</entry> <entry>(1L<<9)</entry> </row> <row> - <entry>XkbOverlay1Mask</entry> + <entry><symbol>XkbOverlay1Mask</symbol></entry> <entry></entry> <entry>ok</entry> <entry>(1L<<10)</entry> </row> <row> - <entry>XkbOverlay2Mask</entry> + <entry><symbol>XkbOverlay2Mask</symbol></entry> <entry></entry> <entry>ok</entry> <entry>(1L<<11)</entry> </row> <row> - <entry>XkbIgnoreGroupLockMask</entry> + <entry><symbol>XkbIgnoreGroupLockMask</symbol></entry> <entry></entry> <entry>ok</entry> <entry>(1L<<12)</entry> </row> <row> - <entry>XkbGroupsWrapMask</entry> + <entry><symbol>XkbGroupsWrapMask</symbol></entry> <entry>ok</entry> <entry></entry> <entry>(1L<<27)</entry> </row> <row> - <entry>XkbInternalModsMask</entry> + <entry><symbol>XkbInternalModsMask</symbol></entry> <entry>ok</entry> <entry></entry> <entry>(1L<<28)</entry> </row> <row> - <entry>XkbIgnoreLockModsMask</entry> + <entry><symbol>XkbIgnoreLockModsMask</symbol></entry> <entry>ok</entry> <entry></entry> <entry>(1L<<29)</entry> </row> <row> - <entry>XkbPerKeyRepeatMask</entry> + <entry><symbol>XkbPerKeyRepeatMask</symbol></entry> <entry>ok</entry> <entry></entry> <entry>(1L<<30)</entry> </row> <row> - <entry>XkbControlsEnabledMask</entry> + <entry><symbol>XkbControlsEnabledMask</symbol></entry> <entry>ok</entry> <entry></entry> <entry>(1L<<31)</entry> </row> <row> - <entry>XkbAccessXOptionsMask</entry> + <entry><symbol>XkbAccessXOptionsMask</symbol></entry> <entry>ok</entry> <entry>ok</entry> <entry>(XkbStickyKeysMask | XkbAccessXFeedbackMask)</entry> </row> <row> - <entry>XkbAllBooleanCtrlsMask</entry> + <entry><symbol>XkbAllBooleanCtrlsMask</symbol></entry> <entry></entry> <entry>ok</entry> <entry>(0x00001FFF) </entry> </row> <row> - <entry>XkbAllControlsMask</entry> + <entry><symbol>XkbAllControlsMask</symbol></entry> <entry>ok</entry> <entry></entry> <entry>(0xF8001FFF)</entry> @@ -3835,9 +3869,9 @@ therefore cannot be enabled or disabled. </table> <para> -The individual fields of the <emphasis> -XkbControlsRec</emphasis> - structure are defined as follows. +The individual fields of the +<structname>XkbControlsRec</structname> +structure are defined as follows. </para> <sect2> @@ -3846,20 +3880,15 @@ XkbControlsRec</emphasis> <title>mk_dflt_btn</title> <para> -<emphasis> -mk_dflt_btn is an attribute of the </emphasis> -<emphasis> -MouseKeys</emphasis> -<emphasis> - control</emphasis> - (see section 10.5<emphasis> <!-- xref --> -). It</emphasis> - specifies the mouse button number to use for keyboard simulated mouse button -operations. Its value should be one of the core symbols <emphasis> -Button1</emphasis> - - <emphasis> -Button5</emphasis> -. +<structfield>mk_dflt_btn</structfield> is an attribute of the +<emphasis>MouseKeys</emphasis> +control +(see <link linkend="Controls_for_Using_the_Mouse_from_the_Keyboard">section 10.5</link>). It +specifies the mouse button number to use for keyboard simulated mouse button +operations. Its value should be one of the core symbols +<symbol>Button1</symbol> +– +<symbol>Button5</symbol>. </para> @@ -3868,11 +3897,10 @@ Button5</emphasis> <title>num_groups</title> <para> -<emphasis> -num_groups</emphasis> - is not a part of any control, but is reported in the <emphasis> -XkbControlsRec</emphasis> - structure whenever any of its components are fetched from the server. It +<structfield>num_groups</structfield> +is not a part of any control, but is reported in the +<structname>XkbControlsRec</structname> +structure whenever any of its components are fetched from the server. It reports the number of groups the particular keyboard configuration uses and is computed automatically by the server whenever the keyboard mapping changes. </para> @@ -3883,17 +3911,16 @@ computed automatically by the server whenever the keyboard mapping changes. <title>groups_wrap</title> <para> -<emphasis> -groups_wrap</emphasis> - is an attribute of the <emphasis> -GroupsWrap</emphasis> - control (see section 10.7.1). It specifies the handling of illegal groups on a <!-- xref --> -global basis. Valid values for <emphasis> -groups_wrap</emphasis> - are shown in Table 10.8. +<structfield>groups_wrap</structfield> +is an attribute of the +<emphasis>GroupsWrap</emphasis> +control (see <link linkend="The_GroupsWrap_Control">section 10.7.1</link>). It specifies the handling of illegal groups on a +global basis. Valid values for +<structfield>groups_wrap</structfield> +are shown in <link linkend="table10.8">Table 10.8</link>. </para> -<table frame='topbot'> +<table id='table10.8' frame='topbot'> <title>GroupsWrap options (groups_wrap field)</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -3907,15 +3934,15 @@ groups_wrap</emphasis> </thead> <tbody> <row> - <entry>XkbWrapIntoRange</entry> + <entry><symbol>XkbWrapIntoRange</symbol></entry> <entry>(0x00)</entry> </row> <row> - <entry>XkbClampIntoRange</entry> + <entry><symbol>XkbClampIntoRange</symbol></entry> <entry>(0x40)</entry> </row> <row> - <entry>XkbRedirectIntoRange</entry> + <entry><symbol>XkbRedirectIntoRange</symbol></entry> <entry>(0x80)</entry> </row> </tbody> @@ -3923,11 +3950,11 @@ groups_wrap</emphasis> </table> <para> -When <emphasis> -groups_wrap</emphasis> - is set to <emphasis> -XkbRedirectIntoRange</emphasis> -, its four low-order bits specify the index of the group to use. +When +<structfield>groups_wrap</structfield> +is set to +<symbol>XkbRedirectIntoRange</symbol>, +its four low-order bits specify the index of the group to use. </para> @@ -3936,23 +3963,18 @@ XkbRedirectIntoRange</emphasis> <title>internal</title> <para> -<emphasis> -internal</emphasis> - is an attribute of the <emphasis> -InternalMods</emphasis> - control (see section 10.7.4). It specifies modifiers to be consumed in the <!-- xref --> +<structfield>internal</structfield> +is an attribute of the +<emphasis>InternalMods</emphasis> +control (see <link linkend="The_InternalMods_Control">section 10.7.4</link>). It specifies modifiers to be consumed in the server and not passed on to clients when events are reported. Valid values -consist of any combination of the eight core modifier bits: <emphasis> -ShiftMask</emphasis> -, <emphasis> -LockMask</emphasis> -, <emphasis> -ControlMask</emphasis> -, <emphasis> -Mod1Mask</emphasis> - - <emphasis> -Mod5Mask</emphasis> -. +consist of any combination of the eight core modifier bits: +<symbol>ShiftMask</symbol>, +<symbol>LockMask</symbol>, +<symbol>ControlMask</symbol>, +<symbol>Mod1Mask</symbol> +– +<symbol>Mod5Mask</symbol>. </para> @@ -3961,23 +3983,18 @@ Mod5Mask</emphasis> <title>ignore_lock</title> <para> -<emphasis> -ignore_lock</emphasis> - is an attribute of the <emphasis> -IgnoreLockMods</emphasis> - control (see section 10.7.2). It specifies modifiers to be ignored in grab <!-- xref --> +<structfield>ignore_lock</structfield> +is an attribute of the +<emphasis>IgnoreLockMods</emphasis> +control (see <link linkend="The_IgnoreLockMods_Control">section 10.7.2</link>). It specifies modifiers to be ignored in grab calculations. Valid values consist of any combination of the eight core -modifier bits: <emphasis> -ShiftMask</emphasis> -, <emphasis> -LockMask</emphasis> -, <emphasis> -ControlMask</emphasis> -, <emphasis> -Mod1Mask</emphasis> - - <emphasis> -Mod5Mask</emphasis> -. +modifier bits: +<symbol>ShiftMask</symbol>, +<symbol>LockMask</symbol>, +<symbol>ControlMask</symbol>, +<symbol>Mod1Mask</symbol> +– +<symbol>Mod5Mask</symbol>. </para> @@ -3986,16 +4003,16 @@ Mod5Mask</emphasis> <title>enabled_ctrls</title> <para> -<emphasis> -enabled_ctrls</emphasis> - is an attribute of the <emphasis> -EnabledControls</emphasis> - control (see section 10.1.1). It contains one bit per boolean control. Each <!-- xref --> +<structfield>enabled_ctrls</structfield> +is an attribute of the +<emphasis>EnabledControls</emphasis> +control (see <link linkend="The_EnabledControls_Control">section 10.1.1</link>). It contains one bit per boolean control. Each bit determines whether the corresponding control is enabled or disabled; a one bit means the control is enabled. The mask bits used to enable these controls -are listed in Table 10.7, using only those masks with "ok" in the <emphasis> -enabled_ctrls</emphasis> - column. +are listed in <link linkend="table10.7">Table 10.7</link>, +using only those masks with <quote>ok</quote> in the +<structfield>enabled_ctrls</structfield> +column. </para> @@ -4004,17 +4021,16 @@ enabled_ctrls</emphasis> <title>repeat_delay and repeat_interval</title> <para> -<emphasis> -repeat_delay</emphasis> - and <emphasis> -repeat_interval</emphasis> - are attributes of the <emphasis> -RepeatKeys</emphasis> - control (see section 10.3.2). <emphasis> <!-- xref --> -repeat_delay</emphasis> - is the initial delay before a key begins repeating, in milliseconds; <emphasis> -repeat_interval</emphasis> - is the delay between subsequent key events, in milliseconds. +<structfield>repeat_delay</structfield> +and +<structfield>repeat_interval</structfield> +are attributes of the +<emphasis>RepeatKeys</emphasis> +control (see <link linkend="The_RepeatKeys_Control">section 10.3.2</link>). +<structfield>repeat_delay</structfield> +is the initial delay before a key begins repeating, in milliseconds; +<structfield>repeat_interval</structfield> +is the delay between subsequent key events, in milliseconds. </para> @@ -4023,13 +4039,12 @@ repeat_interval</emphasis> <title>slow_keys_delay</title> <para> -<emphasis> -slow_keys_delay</emphasis> - is an attribute of the <emphasis> -SlowKeys</emphasis> - control (see section 10.6.6). Its value specifies the <emphasis> <!-- xref --> -SlowKeys</emphasis> - acceptance delay period in milliseconds before a key press is accepted by the +<structfield>slow_keys_delay</structfield> +is an attribute of the +<emphasis>SlowKeys</emphasis> +control (see <link linkend="The_SlowKeys_Control">section 10.6.6</link>). Its value specifies the +<emphasis>SlowKeys</emphasis> +acceptance delay period in milliseconds before a key press is accepted by the server. </para> @@ -4039,13 +4054,12 @@ server. <title>debounce_delay</title> <para> -<emphasis> -debounce_delay</emphasis> - is an attribute of the <emphasis> -BounceKeys</emphasis> - control (see section 10.6.7). Its value specifies the <emphasis> <!-- xref --> -BounceKeys</emphasis> - delay period in milliseconds for which the key is disabled after having been +<structfield>debounce_delay</structfield> +is an attribute of the +<emphasis>BounceKeys</emphasis> +control (see <link linkend="The_BounceKeys_Control">section 10.6.7</link>). Its value specifies the +<emphasis>BounceKeys</emphasis> +delay period in milliseconds for which the key is disabled after having been pressed before another press of the same key is accepted by the server. </para> @@ -4055,19 +4069,15 @@ pressed before another press of the same key is accepted by the server. <title>mk_delay, mk_interval, mk_time_to_max, mk_max_speed, and mk_curve</title> <para> -<emphasis> -mk_delay</emphasis> -, <emphasis> -mk_interval</emphasis> -, <emphasis> -mk_time_to_max</emphasis> -, <emphasis> -mk_max_speed</emphasis> -, and <emphasis> -mk_curve</emphasis> - are attributes of the <emphasis> -MouseKeysAccel</emphasis> - control. Refer to section 10.5.2 for a description of these fields and the <!-- xref --> +<structfield>mk_delay</structfield>, +<structfield>mk_interval</structfield>, +<structfield>mk_time_to_max</structfield>, +<structfield>mk_max_speed</structfield>, +and +<structfield>mk_curve</structfield> +are attributes of the +<emphasis>MouseKeysAccel</emphasis> +control. Refer to <link linkend="The_MouseKeysAccel_Control">section 10.5.2</link> for a description of these fields and the units involved. </para> @@ -4077,20 +4087,19 @@ units involved. <title>ax_options</title> <para> -The <emphasis> -ax_options</emphasis> - field contains attributes used to configure two different controls, the -<emphasis> -StickyKeys</emphasis> - control (see section 10.6.8) and the <emphasis> <!-- xref --> -AccessXFeedback</emphasis> - control (see section 10.6.3). The <emphasis> <!-- xref --> -ax_options</emphasis> - field is a bitmask and may include any combination of the bits defined in -Table 10.9. <!-- xref --> +The +<structfield>ax_options</structfield> +field contains attributes used to configure two different controls, the +<emphasis>StickyKeys</emphasis> +control (see <link linkend="The_StickyKeys_Control">section 10.6.8</link>) and the +<emphasis>AccessXFeedback</emphasis> +control (see <link linkend="The_AccessXFeedback_Control">section 10.6.3</link>). The +<structfield>ax_options</structfield> +field is a bitmask and may include any combination of the bits defined in +<link linkend="table10.9">Table 10.9</link>. </para> -<table frame='topbot'> +<table id='table10.9' frame='topbot'> <title>Access X Enable/Disable Bits (ax_options field)</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -4107,67 +4116,67 @@ Table 10.9. <!-- xref --> <tbody> <row> <entry>AccessXFeedback</entry> - <entry>XkbAX_SKPressFBMask</entry> + <entry><symbol>XkbAX_SKPressFBMask</symbol></entry> <entry>(1L<<0)</entry> </row> <row> <entry></entry> - <entry>XkbAX_SKAcceptFBMask</entry> + <entry><symbol>XkbAX_SKAcceptFBMask</symbol></entry> <entry>(1L << 1)</entry> </row> <row> <entry></entry> - <entry>XkbAX_FeatureFBMask</entry> + <entry><symbol>XkbAX_FeatureFBMask</symbol></entry> <entry>(1L << 2)</entry> </row> <row> <entry></entry> - <entry>XkbAX_SlowWarnFBMask</entry> + <entry><symbol>XkbAX_SlowWarnFBMask</symbol></entry> <entry>(1L << 3)</entry> </row> <row> <entry></entry> - <entry>XkbAX_IndicatorFBMask</entry> + <entry><symbol>XkbAX_IndicatorFBMask</symbol></entry> <entry>(1L << 4)</entry> </row> <row> <entry></entry> - <entry>XkbAX_StickyKeysFBMask</entry> + <entry><symbol>XkbAX_StickyKeysFBMask</symbol></entry> <entry>(1L << 5)</entry> </row> <row> <entry></entry> - <entry>XkbAX_SKReleaseFBMask</entry> + <entry><symbol>XkbAX_SKReleaseFBMask</symbol></entry> <entry>(1L << 8)</entry> </row> <row> <entry></entry> - <entry>XkbAX_SKRejectFBMask</entry> + <entry><symbol>XkbAX_SKRejectFBMask</symbol></entry> <entry>(1L << 9)</entry> </row> <row> <entry></entry> - <entry>XkbAX_BKRejectFBMask</entry> + <entry><symbol>XkbAX_BKRejectFBMask</symbol></entry> <entry>(1L << 10)</entry> </row> <row> <entry></entry> - <entry>XkbAX_DumbBellFBMask</entry> + <entry><symbol>XkbAX_DumbBellFBMask</symbol></entry> <entry>(1L << 11)</entry> </row> <row> <entry>StickyKeys</entry> - <entry>XkbAX_TwoKeysMask</entry> + <entry><symbol>XkbAX_TwoKeysMask</symbol></entry> <entry>(1L << 6)</entry> </row> <row> <entry></entry> - <entry>XkbAX_LatchToLockMask</entry> + <entry><symbol>XkbAX_LatchToLockMask</symbol></entry> <entry>(1L << 7)</entry> </row> <row> <entry></entry> - <entry>XkbAX_AllOptionsMask</entry> + <entry><symbol>XkbAX_AllOptionsMask</symbol></entry> <entry>(0xFFF)</entry> </row> </tbody> @@ -4176,100 +4185,93 @@ Table 10.9. <!-- xref --> <para> The fields pertaining to each control are relevant only when the control is -enabled (<emphasis> -XkbAccessXFeedbackMask</emphasis> - or <emphasis> -XkbStickyKeysMask</emphasis> - bit is turned on in the <emphasis> -enabled_cntrls</emphasis> - field). +enabled +(<symbol>XkbAccessXFeedbackMask</symbol> +or +<symbol>XkbStickyKeysMask</symbol> +bit is turned on in the +<structfield>enabled_ctrls</structfield> +field). </para> <para> -Xkb provides a set of convenience macros for working with the <emphasis> -ax_options</emphasis> - field of an <emphasis> -XkbControlsRec</emphasis> - structure: -</para> +Xkb provides a set of convenience macros for working with the +<structfield>ax_options</structfield> +field of an +<structname>XkbControlsRec</structname> +structure: -<para><programlisting> -#define <emphasis>XkbAX_NeedOption</emphasis> -(c,w) ((c)->ax_options&(w)) +<programlisting> +#define <symbol>XkbAX_NeedOption</symbol>(c,w) ((c)->ax_options & (w)) </programlisting></para> <para> -The <emphasis> -XkbAX_NeedOption</emphasis> - macro is useful for determining whether a particular AccessX option is enabled -or not. It accepts a pointer to an <emphasis> -XkbControlsRec</emphasis> - structure and a valid mask bit from Table 10.9. If the specified mask bit in -the <emphasis> -ax_options</emphasis> - field of the controls structure is set, the macro returns the mask bit. +The +<symbol>XkbAX_NeedOption</symbol> +macro is useful for determining whether a particular AccessX option is enabled +or not. It accepts a pointer to an +<structname>XkbControlsRec</structname> +structure and a valid mask bit from +<link linkend="table10.9">Table 10.9</link>. +If the specified mask bit in the +<structfield>ax_options</structfield> +field of the controls structure is set, the macro returns the mask bit. Otherwise, it returns zero. Thus, -</para> - - -<para> -XkbAX_NeedOption(ctlrec, XkbAX_LatchToLockMask) -</para> +<programlisting> + XkbAX_NeedOption(ctlrec, XkbAX_LatchToLockMask) +</programlisting> -<para> is nonzero if the latch to lock transition for latching keys is enabled, and -zero if it is disabled. Note that <emphasis> -XkbAX_NeedOption</emphasis> - only determines whether or not the particular capability is configured to -operate; the <emphasis> -XkbAccessXFeedbackMask</emphasis> - bit must also be turned on in <emphasis> -enabled_ctrls</emphasis> - for the capability to actually be functioning. +zero if it is disabled. Note that +<symbol>XkbAX_NeedOption</symbol> +only determines whether or not the particular capability is configured to +operate; the +<symbol>XkbAccessXFeedbackMask</symbol> +bit must also be turned on in +<structfield>enabled_ctrls</structfield> +for the capability to actually be functioning. </para> <para><programlisting> -#define <emphasis>XkbAX_AnyFeedback</emphasis> -(c) ((c)->enabled_ctrls&XkbAccessXFeedbackMask) +#define <symbol>XkbAX_AnyFeedback</symbol>(c) \ + ((c)->enabled_ctrls & XkbAccessXFeedbackMask) </programlisting></para> <para> -The <emphasis> -XkbAX_AnyFeeback</emphasis> - macro accepts a pointer to an <emphasis> -XkbControlsRec</emphasis> - structure and tells whether the <emphasis> -AccessXFeedback</emphasis> - control is enabled or not. If the <emphasis> -AccessXFeedback</emphasis> - control is enabled, the macro returns <emphasis> -XkbAccessXFeedbackMask</emphasis> -. Otherwise, it returns zero. +The +<symbol>XkbAX_AnyFeedback</symbol> +macro accepts a pointer to an +<structname>XkbControlsRec</structname> +structure and tells whether the +<emphasis>AccessXFeedback</emphasis> +control is enabled or not. If the +<emphasis>AccessXFeedback</emphasis> +control is enabled, the macro returns +<symbol>XkbAccessXFeedbackMask</symbol>. +Otherwise, it returns zero. </para> <para><programlisting> -#define <emphasis>XkbAX_NeedFeedback</emphasis> -(c,w) (XkbAX_AnyFeedback(c)&&XkbAX_NeedOption(c,w)) +#define <symbol>XkbAX_NeedFeedback</symbol>(c,w) \ + (XkbAX_AnyFeedback(c) && XkbAX_NeedOption(c,w)) </programlisting></para> <para> -The <emphasis> -XkbAX_NeedFeedback</emphasis> - macro is useful for determining if both the <emphasis> -AccessXFeedback</emphasis> - control and a particular AccessX feedback option are enabled. The macro -accepts a pointer to an <emphasis> -XkbControlsRec</emphasis> - structure and a feedback option from the table above. If both the <emphasis> -AccessXFeedback</emphasis> - control and the specified feedback option are enabled, the macro returns -<emphasis> -True</emphasis> -. Otherwise it returns <emphasis> -False</emphasis> -. +The +<symbol>XkbAX_NeedFeedback</symbol> +macro is useful for determining if both the +<emphasis>AccessXFeedback</emphasis> +control and a particular AccessX feedback option are enabled. The macro +accepts a pointer to an +<structname>XkbControlsRec</structname> +structure and a feedback option from the table above. If both the +<emphasis>AccessXFeedback</emphasis> +control and the specified feedback option are enabled, the macro returns +<symbol>True</symbol>. +Otherwise it returns +<symbol>False</symbol>. </para> @@ -4279,19 +4281,15 @@ id='ax_timeout_axt_opts_mask_axt_opts_values_axt_ctrls_mask_and_axt_ctrls_values <title>ax_timeout, axt_opts_mask, axt_opts_values, axt_ctrls_mask, and axt_ctrls_values</title> <para> -<emphasis> -ax_timeout</emphasis> -, <emphasis> -act_opts_mask</emphasis> -, <emphasis> -axt_opts_values</emphasis> -, <emphasis> -axt_ctrls_mask</emphasis> -, and <emphasis> -axt_ctrls_values</emphasis> - are attributes of the <emphasis> -AccessXTimeout</emphasis> - control. Refer to section 10.6.2 for a description of these fields and the <!-- xref --> +<structfield>ax_timeout</structfield>, +<structfield>axt_opts_mask</structfield>, +<structfield>axt_opts_values</structfield>, +<structfield>axt_ctrls_mask</structfield>, +and +<structfield>axt_ctrls_values</structfield> +are attributes of the +<emphasis>AccessXTimeout</emphasis> +control. Refer to <link linkend="The_AccessXTimeout_Control">section 10.6.2</link> for a description of these fields and the units involved. </para> @@ -4301,30 +4299,30 @@ units involved. <title>per_key_repeat</title> <para> -The <emphasis> -per_key_repeat</emphasis> - field mirrors the <emphasis> -auto_repeats</emphasis> - field of the core protocol <emphasis> -XKeyboardState</emphasis> - structure: changing the <emphasis> -auto_repeats</emphasis> - field automatically changes <emphasis> -per_key_repeat</emphasis> - and vice versa. It is provided for convenience and to reduce protocol traffic. +The +<structfield>per_key_repeat</structfield> +field mirrors the +<structfield>auto_repeats</structfield> +field of the core protocol +<structname>XKeyboardState</structname> +structure: changing the +<structfield>auto_repeats</structfield> +field automatically changes +<structfield>per_key_repeat</structfield> +and vice versa. It is provided for convenience and to reduce protocol traffic. For example, to obtain the individual repeat key behavior as well as the repeat -delay and rate, use <emphasis> -XkbGetControls</emphasis> -. If the <emphasis> -per_key_repeat</emphasis> - were not in this structure, you would have to call both <emphasis> -XGetKeyboardControl</emphasis> - and <emphasis> -XkbGetControls</emphasis> - to get this information. The bits correspond to keycodes. The first seven keys -(keycodes 1-7) are indicated in <emphasis> -per_key_repeat</emphasis> -[0], with bit position 0 (low order) corresponding to the fictitious keycode 0. +delay and rate, use +<function>XkbGetControls</function>. +If the +<structfield>per_key_repeat</structfield> +were not in this structure, you would have to call both +<function>XGetKeyboardControl</function> +and +<function>XkbGetControls</function> +to get this information. The bits correspond to keycodes. The first seven keys +(keycodes 1–7) are indicated in +<structfield>per_key_repeat</structfield>[0], +with bit position 0 (low order) corresponding to the fictitious keycode 0. Following array elements correspond to 8 keycodes per element. A 1 bit indicates that the key is a repeating key. </para> @@ -4337,404 +4335,395 @@ indicates that the key is a repeating key. <title>Querying Controls</title> <para> -Use <emphasis> -XkbGetControls</emphasis> - to find the current state of Xkb server controls. -</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> -XkbGetControls</emphasis> -(<emphasis> -display, which, xkb)</emphasis> - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned long<emphasis> - which</emphasis> -; /* mask of controls requested */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr<emphasis> - xkb</emphasis> -; /* keyboard description for controls information*/ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetControls</emphasis> - queries the server for the requested control information, waits for a reply, +Use +<function>XkbGetControls</function> +to find the current state of Xkb server controls. +</para> + +<indexterm significance="preferred" zone="XkbGetControls"><primary><function>XkbGetControls</function></primary></indexterm> +<funcsynopsis id="XkbGetControls"> + <funcprototype> + <funcdef>Status <function>XkbGetControls</function></funcdef> +<!-- ( +<parameter>display, which, xkb)</parameter> --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned long <parameter>which</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask of controls requested + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description for controls information + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetControls</function> +queries the server for the requested control information, waits for a reply, and then copies the server’s values for the requested information into the -<emphasis> -ctrls</emphasis> - structure of the <emphasis> -xkb</emphasis> - argument. Only those components specified by the <emphasis> -which</emphasis> - parameter are copied. Valid values for <emphasis> -which</emphasis> - are any combination of the masks listed in Table 10.7 that have "ok" in the -<emphasis> -which</emphasis> - column. -</para> - - -<para> -If <emphasis> -xkb</emphasis> --><emphasis> -ctrls </emphasis> -is <emphasis> -NULL</emphasis> -, <emphasis> -XkbGetControls</emphasis> - allocates and initializes it before obtaining the values specified by -<emphasis> -which</emphasis> -. If <emphasis> -xkb</emphasis> --><emphasis> -ctrls</emphasis> - is not <emphasis> -NULL</emphasis> -, <emphasis> -XkbGetControls</emphasis> - modifies only those portions of <emphasis> -xkb</emphasis> --><emphasis> -ctrls</emphasis> - corresponding to the values specified by <emphasis> -which</emphasis> -. -</para> - - -<para> -<emphasis> -XkbGetControls</emphasis> - returns <emphasis> -Success</emphasis> - if successful; otherwise, it returns <emphasis> -BadAlloc</emphasis> - if it cannot obtain sufficient storage, <emphasis> -BadMatch</emphasis> - if <emphasis> -xkb</emphasis> - is <emphasis> -NULL</emphasis> - or <emphasis> -which</emphasis> - is empty, or <emphasis> -BadImplementation</emphasis> -. -</para> - - -<para> -To free the <emphasis> -ctrls</emphasis> - member of a keyboard description, use <emphasis> -XkbFreeControls</emphasis> - (see section 10.12) -</para> - - -<para> -The <emphasis> -num_groups</emphasis> - field in the <emphasis> -ctrls</emphasis> - structure is always filled in by <emphasis> -XkbGetControls</emphasis> -, regardless of which bits are selected by <emphasis> -which</emphasis> -. +<structfield>ctrls</structfield> +structure of the +<parameter>xkb</parameter> +argument. Only those components specified by the +<parameter>which</parameter> +parameter are copied. Valid values for +<parameter>which</parameter> +are any combination of the masks listed in +<link linkend="table10.7">Table 10.7</link> that have <quote>ok</quote> in the +<parameter>which</parameter> +column. </para> -</sect1> -<sect1 id='Changing_Controls'> -<title>Changing Controls</title> - <para> -There are two ways to make changes to controls: either change a local copy -keyboard description and call <emphasis> -XkbSetControls</emphasis> -, or, to reduce network traffic, use an<emphasis> - XkbControlsChangesRec</emphasis> - structure and call <emphasis> -XkbChangeControls</emphasis> -. +If +<parameter>xkb</parameter>-><structfield>ctrls</structfield> +is +<symbol>NULL</symbol>, +<function>XkbGetControls</function> +allocates and initializes it before obtaining the values specified by +<parameter>which</parameter>. +If +<parameter>xkb</parameter>-><structfield>ctrls</structfield> +is not +<symbol>NULL</symbol>, +<function>XkbGetControls</function> +modifies only those portions of +<parameter>xkb</parameter>-><structfield>ctrls</structfield> +corresponding to the values specified by +<parameter>which</parameter>. </para> <para> -To change the state of one or more controls, first modify the <emphasis> -ctrls</emphasis> - structure in a local copy of the keyboard description and then use <emphasis> -XkbSetControls</emphasis> - to copy those changes to the X server. +<function>XkbGetControls</function> +returns +<symbol>Success</symbol> +if successful; otherwise, it returns +<errorname>BadAlloc</errorname> +if it cannot obtain sufficient storage, +<errorname>BadMatch</errorname> +if +<parameter>xkb</parameter> +is +<symbol>NULL</symbol> +or +<parameter>which</parameter> +is empty, or +<errorname>BadImplementation</errorname>. </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> -XkbSetControls</emphasis> -(<emphasis> -display, which, xkb)</emphasis> - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display *<emphasis> - display</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned long <emphasis> - which </emphasis> -; /* mask of controls to change */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* <emphasis> -ctrls</emphasis> - field contains new values to be set */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> <para> -For each bit that is set in the <emphasis> -which</emphasis> - parameter, <emphasis> -XkbSetControls</emphasis> - sends the corresponding values from the <emphasis> -xkb</emphasis> --><emphasis> -ctrls</emphasis> - field to the server. Valid values for <emphasis> -which</emphasis> - are any combination of the masks listed in Table 10.7 that have "ok" in the -<emphasis> -which</emphasis> - column. +To free the +<structfield>ctrls</structfield> +member of a keyboard description, use +<function>XkbFreeControls</function> +(see <link linkend="Allocating_and_Freeing_an_XkbControlsRec">section 10.12</link>) </para> <para> -If <emphasis> -xkb</emphasis> --><emphasis> -ctrls</emphasis> - is <emphasis> -NULL</emphasis> -, the server does not support a compatible version of Xkb, or the Xkb extension -has not been properly initialized, <emphasis> -XkbSetControls</emphasis> - returns <emphasis> -False</emphasis> -. Otherwise, it sends the request to the X server and returns <emphasis> -True</emphasis> -. +The +<structfield>num_groups</structfield> +field in the +<structfield>ctrls</structfield> +structure is always filled in by +<function>XkbGetControls</function>, +regardless of which bits are selected by +<parameter>which</parameter>. </para> +</sect1> +<sect1 id='Changing_Controls'> +<title>Changing Controls</title> + <para> -Note that changes to attributes of controls in the <emphasis> -XkbControlsRec</emphasis> - structure are apparent only when the associated control is enabled, although +There are two ways to make changes to controls: either change a local copy +keyboard description and call +<function>XkbSetControls</function>, +or, to reduce network traffic, use an +<structname>XkbControlsChangesRec</structname> +structure and call +<function>XkbChangeControls</function>. +</para> + + +<para> +To change the state of one or more controls, first modify the +<structfield>ctrls</structfield> +structure in a local copy of the keyboard description and then use +<function>XkbSetControls</function> +to copy those changes to the X server. +</para> + +<indexterm significance="preferred" zone="XkbSetControls"><primary><function>XkbSetControls</function></primary></indexterm> +<funcsynopsis id="XkbSetControls"> + <funcprototype> + <funcdef>Bool <function>XkbSetControls</function></funcdef> +<!-- ( +<parameter>display, which, xkb)</parameter> --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned long <parameter>which</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask of controls to change + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + <structfield>ctrls</structfield> field contains new values to be set + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +For each bit that is set in the +<parameter>which</parameter> +parameter, +<function>XkbSetControls</function> +sends the corresponding values from the +<parameter>xkb</parameter>-><structfield>ctrls</structfield> +field to the server. Valid values for +<parameter>which</parameter> +are any combination of the masks listed in +<link linkend="table10.7">Table 10.7</link> that have <quote>ok</quote> in the +<parameter>which</parameter> +column. +</para> + + +<para> +If +<parameter>xkb</parameter>-><structfield>ctrls</structfield> +is +<symbol>NULL</symbol>, +the server does not support a compatible version of Xkb, or the Xkb extension +has not been properly initialized, +<function>XkbSetControls</function> +returns +<symbol>False</symbol>. +Otherwise, it sends the request to the X server and returns +<symbol>True</symbol>. +</para> + + +<para> +Note that changes to attributes of controls in the +<structname>XkbControlsRec</structname> +structure are apparent only when the associated control is enabled, although the corresponding values are still updated in the X server. For example, the -<emphasis> -repeat_delay</emphasis> - and <emphasis> -repeat_interval</emphasis> - fields are ignored unless the <emphasis> -RepeatKeys</emphasis> - control is enabled (that is, the X server’s equivalent of <emphasis> -xkb->ctrls</emphasis> - has <emphasis> -XkbRepeatKeyMask</emphasis> - set in <emphasis> -enabled_ctrls</emphasis> -). It is permissible to modify the attributes of a control in one call to -XkbSetControls and enable the control in a subsequent call. See section 10.1.1 <!-- xref --> +<structfield>repeat_delay</structfield> +and +<structfield>repeat_interval</structfield> +fields are ignored unless the +<emphasis>RepeatKeys</emphasis> +control is enabled (that is, the X server’s equivalent of +<structfield>xkb->ctrls</structfield> +has +<symbol>XkbRepeatKeysMask</symbol> +set in +<structfield>enabled_ctrls</structfield>). +It is permissible to modify the attributes of a control in one call to +XkbSetControls and enable the control in a subsequent call. See <link linkend="The_EnabledControls_Control">section 10.1.1</link> for more information on enabling and disabling controls. </para> <para> -Note that the <emphasis> -enabled_ctrls</emphasis> - field is itself a control — the <emphasis> -EnabledControls</emphasis> - control. As such, to set a specific configuration of enabled and disabled -boolean controls, you must set <emphasis> -enabled_ctrls</emphasis> - to the appropriate bits to enable only the controls you want and disable all -others, then specify the <emphasis> -XkbControlsEnabledMask</emphasis> - in a call to <emphasis> -XkbSetControls</emphasis> -. Because this is somewhat awkward if all you want to do is enable and disable +Note that the +<structfield>enabled_ctrls</structfield> +field is itself a control — the +<emphasis>EnabledControls</emphasis> +control. As such, to set a specific configuration of enabled and disabled +boolean controls, you must set +<structfield>enabled_ctrls</structfield> +to the appropriate bits to enable only the controls you want and disable all +others, then specify the +<symbol>XkbControlsEnabledMask</symbol> +in a call to +<function>XkbSetControls</function>. +Because this is somewhat awkward if all you want to do is enable and disable controls, and not modify any of their attributes, a convenience function is -also provided for this purpose (<emphasis> -XkbChangeEnabledControls</emphasis> -, section 10.1.1). <!-- xref --> +also provided for this purpose +(<function>XkbChangeEnabledControls</function>, +<link linkend="The_EnabledControls_Control">section 10.1.1</link>). </para> <sect2 id='The_XkbControlsChangesRec_Structure'> <title>The XkbControlsChangesRec Structure</title> +<indexterm significance="preferred" zone="The_XkbControlsChangesRec_Structure"> +<primary><structname>XkbControlsChangesRec</structname></primary></indexterm> + <para> -The <emphasis> -XkbControlsChangesRec</emphasis> - structure allows applications to track modifications to an <emphasis> -XkbControlsRec</emphasis> - structure and thereby reduce the amount of traffic sent to the server. The -same <emphasis> -XkbControlsChangesRec</emphasis> - structure may be used in several successive modifications to the same -<emphasis> -XkbControlsRec</emphasis> - structure, then subsequently used to cause all of the changes, and only the -changes, to be propagated to the server. The <emphasis> -XkbControlsChangesRec</emphasis> - structure is defined as follows: -</para> +The +<structname>XkbControlsChangesRec</structname> +structure allows applications to track modifications to an +<structname>XkbControlsRec</structname> +structure and thereby reduce the amount of traffic sent to the server. The +same +<structname>XkbControlsChangesRec</structname> +structure may be used in several successive modifications to the same +<structname>XkbControlsRec</structname> +structure, then subsequently used to cause all of the changes, and only the +changes, to be propagated to the server. The +<structname>XkbControlsChangesRec</structname> +structure is defined as follows: -<para><programlisting> +<programlisting> typedef struct _XkbControlsChanges { - unsigned int changed_ctrls; /* bits indicating changed control data */ - unsigned int enabled_ctrls_changes; /* bits indicating enabled/disabled controls */ - Bool num_groups_changed; /* <emphasis> True</emphasis> if - number of keyboard groups changed */ -} <emphasis>XkbControlsChangesRec</emphasis>,*XkbControlsChangesPtr; + unsigned int changed_ctrls; /* bits indicating changed + control data */ + unsigned int enabled_ctrls_changes; /* bits indicating + enabled/disabled controls */ + Bool num_groups_changed; /* <symbol>True</symbol> if number of keyboard + groups changed */ +} <structname>XkbControlsChangesRec</structname>, *XkbControlsChangesPtr; </programlisting></para> <para> -The <emphasis> -changed_ctrls</emphasis> - field is a mask specifying which logical sets of data in the controls -structure have been modified. In this context, modified means <emphasis> -set</emphasis> -, that is, if a value is set to the same value it previously contained, it has -still been modified, and is noted as changed. Valid values for <emphasis> -changed_ctrls</emphasis> - are any combination of the masks listed in Table 10.7 that have "ok" in the -<emphasis> -changed_ctrls</emphasis> - column. Setting a bit implies the corresponding data fields from the "Relevant -XkbControlsRec Data Fields" column in Table 10.6 have been modified. The -<emphasis> -enabled_ctrls_changes</emphasis> - field specifies which bits in the <emphasis> -enabled_ctrls</emphasis> - field have changed. If the number of keyboard groups has changed, the -<emphasis>num_groups_changed</emphasis> - field is set to <emphasis>True</emphasis>. +The +<structfield>changed_ctrls</structfield> +field is a mask specifying which logical sets of data in the controls +structure have been modified. In this context, modified means +<emphasis>set</emphasis>, +that is, if a value is set to the same value it previously contained, it has +still been modified, and is noted as changed. Valid values for +<structfield>changed_ctrls</structfield> +are any combination of the masks listed in +<link linkend="table10.7">Table 10.7</link> that have <quote>ok</quote> in the +<structfield>changed_ctrls</structfield> +column. Setting a bit implies the corresponding data fields from the +<quote>Relevant XkbControlsRec Data Fields</quote> column in +<link linkend="table10.6">Table 10.6</link> have been modified. The +<structfield>enabled_ctrls_changes</structfield> +field specifies which bits in the +<structfield>enabled_ctrls</structfield> +field have changed. If the number of keyboard groups has changed, the +<structfield>num_groups_changed</structfield> +field is set to <symbol>True</symbol>. </para> <para> If you have an Xkb description with controls that have been modified and an -<emphasis> -XkbControlsChangesRec</emphasis> - that describes the changes that have been made, the <emphasis> -XkbChangeControls</emphasis> - function provides a flexible method for updating the controls in a server to +<structname>XkbControlsChangesRec</structname> +that describes the changes that have been made, the +<function>XkbChangeControls</function> +function provides a flexible method for updating the controls in a server to match those in the changed keyboard description. </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> -XkbChangeControls</emphasis> -(<emphasis> -dpy, xkb, changes</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* keyboard description with changed <emphasis> -xkb->ctrls</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbControlsChangesPtr <emphasis> -changes</emphasis> -; /* which parts of <emphasis> -xkb->ctrls</emphasis> - have changed */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbChangeControls</emphasis> - copies any controls fields specified by <emphasis> -changes</emphasis> - from the keyboard description controls structure, <emphasis> -xkb</emphasis> --><emphasis> -ctrls</emphasis> -, to the server specified by <emphasis> -dpy</emphasis> -. +<indexterm significance="preferred" zone="XkbChangeControls"><primary><function>XkbChangeControls</function></primary></indexterm> +<funcsynopsis id="XkbChangeControls"> + <funcprototype> + <funcdef>Bool <function>XkbChangeControls</function></funcdef> +<!-- ( +<parameter>dpy, xkb, changes</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>XkbControlsChangesPtr <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>xkb</parameter> + </term> + <listitem> + <para> + keyboard description with changed <structfield>xkb->ctrls</structfield> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>changes</parameter> + </term> + <listitem> + <para> + which parts of <structfield>xkb->ctrls</structfield> have changed + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbChangeControls</function> +copies any controls fields specified by +<parameter>changes</parameter> +from the keyboard description controls structure, +<parameter>xkb</parameter>-><structfield>ctrls</structfield>, +to the server specified by +<parameter>dpy</parameter>. </para> @@ -4743,313 +4732,313 @@ dpy</emphasis> <sect1 id='Tracking_Changes_to_Keyboard_Controls'> <title>Tracking Changes to Keyboard Controls</title> +<indexterm significance="preferred" zone="Tracking_Changes_to_Keyboard_Controls"> +<primary>events</primary><secondary><symbol>XkbControlsNotify</symbol></secondary></indexterm> +<indexterm significance="preferred" zone="Tracking_Changes_to_Keyboard_Controls"> +<primary><structname>XkbControlsNotifyEvent</structname></primary></indexterm> + <para> Whenever a field in the controls structure changes in the server’s keyboard -description, the server sends an <emphasis> -XkbControlsNotify</emphasis> - event to all interested clients.To receive <emphasis> -XkbControlsNotify</emphasis> - events under all possible conditions, use <emphasis> -XkbSelectEvents</emphasis> - (see section 4.3) and pass <emphasis> -XkbControlsNotifyMask</emphasis> - in both <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits</emphasis> -. +description, the server sends an +<symbol>XkbControlsNotify</symbol> +event to all interested clients.To receive +<symbol>XkbControlsNotify</symbol> +events under all possible conditions, use +<function>XkbSelectEvents</function> +(see <link linkend="Selecting_Xkb_Events">section 4.3</link>) and pass +<symbol>XkbControlsNotifyMask</symbol> +in both +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter>. </para> <para> -To receive <emphasis> -XkbControlsNotify</emphasis> - events only under certain conditions, use <emphasis> -XkbSelectEventDetails</emphasis> - using <emphasis> -XkbControlsNotify</emphasis> - as the <emphasis> -event_type</emphasis> - and specifying the desired state changes in <emphasis> -bits_to_change</emphasis> - and <emphasis> -values_for_bits</emphasis> - using mask bits from Table 10.7. <!-- xref --> +To receive +<symbol>XkbControlsNotify</symbol> +events only under certain conditions, use +<function>XkbSelectEventDetails</function> +using +<symbol>XkbControlsNotify</symbol> +as the +<structfield>event_type</structfield> +and specifying the desired state changes in +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter> +using mask bits from <link linkend="table10.7">Table 10.7</link>. </para> <para> -The structure for the <emphasis> -XkbControlsNotify</emphasis> - event is defined as follows: -</para> +The structure for the +<symbol>XkbControlsNotify</symbol> +event is defined as follows: -<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> XkbCompatMapNotify</emphasis> */ - int device; /* Xkb device ID, will not be <emphasis> XkbUseCoreKbd</emphasis> */ - unsigned int changed_ctrls; /* bits indicating which controls data have changed*/ - unsigned int enabled_ctrls; /* controls currently enabled in server */ - unsigned int enabled_ctrl_changes; /* bits indicating enabled/disabled controls */ - int num_groups; /* current number of keyboard groups */ - KeyCode keycode; /* != 0 => keycode of key causing change */ - char event_type; /* Type of event causing change */ - char req_major; /* major event code of event causing change */ - char req_minor; /* minor event code of event causing change */ -} <emphasis>XkbControlsNotifyEvent</emphasis>; + 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; /* <symbol>XkbCompatMapNotify</symbol> */ + int device; /* Xkb device ID, + will not be <symbol>XkbUseCoreKbd</symbol> */ + unsigned int changed_ctrls; /* bits indicating which controls + data have changed */ + unsigned int enabled_ctrls; /* controls currently enabled in server */ + unsigned int enabled_ctrl_changes; /* bits indicating + enabled/disabled controls */ + int num_groups; /* current number of keyboard groups */ + KeyCode keycode; /* != 0 ⇒ keycode of key causing change */ + char event_type; /* Type of event causing change */ + char req_major; /* major event code of event causing change */ + char req_minor; /* minor event code of event causing change */ +} <structname>XkbControlsNotifyEvent</structname>; </programlisting></para> <para> -The <emphasis> -changed_ctrls</emphasis> - field specifies the controls components that have changed and consists of bits -taken from the masks defined in Table 10.7 with "ok" in the <emphasis> -changed_ctrls</emphasis> - column. +The +<structfield>changed_ctrls</structfield> +field specifies the controls components that have changed and consists of bits +taken from the masks defined in +<link linkend="table10.7">Table 10.7</link> with <quote>ok</quote> in the +<structfield>changed_ctrls</structfield> +column. </para> <para> -The controls currently enabled in the server are reported in the <emphasis> -enabled_ctrls</emphasis> - field. If any controls were just enabled or disabled (that is, the contents of -the <emphasis> -enabled_ctrls</emphasis> - field changed), they are flagged in the <emphasis> -enabled_ctrl_changes</emphasis> - field. The valid bits for these fields are the masks listed in Table 10.7 with -"ok" in the <emphasis> -enabled_ctrls</emphasis> - column. The <emphasis> -num_groups</emphasis> - field reports the number of groups bound to the key belonging to the most +The controls currently enabled in the server are reported in the +<structfield>enabled_ctrls</structfield> +field. If any controls were just enabled or disabled (that is, the contents of +the +<structfield>enabled_ctrls</structfield> +field changed), they are flagged in the +<structfield>enabled_ctrl_changes</structfield> +field. The valid bits for these fields are the masks listed in +<link linkend="table10.7">Table 10.7</link> with +<quote>ok</quote> in the +<structfield>enabled_ctrls</structfield> +column. The +<structfield>num_groups</structfield> +field reports the number of groups bound to the key belonging to the most number of groups and is automatically updated when the keyboard mapping changes. </para> <para> -If the change was caused by a request from a client, the <emphasis> -keycode</emphasis> - and <emphasis> -event_type</emphasis> - fields are set to <emphasis> -zero </emphasis> -and the <emphasis> -req_major</emphasis> - and <emphasis> -req_minor</emphasis> - fields identify the request. The <emphasis> -req_major</emphasis> - value is the same as the major extension opcode. Otherwise, <emphasis> -event_type</emphasis> - is set to the type of event that caused the change (one of <emphasis> -KeyPress</emphasis> -, <emphasis> -KeyRelease</emphasis> -, <emphasis> -DeviceKeyPress</emphasis> -, <emphasis> -DeviceKeyRelease</emphasis> -, <emphasis> -ButtonPress</emphasis> - or <emphasis> -ButtonRelease</emphasis> -), and <emphasis> -req_major</emphasis> - and <emphasis> -req_minor</emphasis> - are undefined. If <emphasis> -event_type</emphasis> - is <emphasis> -KeyPress</emphasis> -, <emphasis> -KeyRelease</emphasis> -, <emphasis> -DeviceKeyPress</emphasis> -, or <emphasis> -DeviceKeyRelease</emphasis> -, the <emphasis> -keycode</emphasis> - field is set to the key that caused the change. If <emphasis> -event_type</emphasis> - is <emphasis> -ButtonPress</emphasis> - or <emphasis> -ButtonRelease</emphasis> -, <emphasis> -keycode</emphasis> - contains the button number. -</para> - - -<para> -When a client receives an <emphasis> -XkbControlsNotify</emphasis> - event, it can note the changes in a changes structure using <emphasis> -XkbNoteControlsChanges</emphasis> -. -</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> -XkbNoteControlsChanges</emphasis> -(<emphasis> -changes</emphasis> -,<emphasis> - new</emphasis> -,<emphasis> - wanted</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbControlsChangesPtr <emphasis> - changes</emphasis> -; /* records changes indicated by new */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbControlsNotifyEvent * <emphasis> - new</emphasis> -; /* tells which things have changed */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - wanted</emphasis> -; /* tells which parts of new to record in changes */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -The <emphasis> -wanted</emphasis> - parameter is a bitwise inclusive OR of bits taken from the set of masks -specified in Table 10.7 with "ok" in the <emphasis> -changed_ctrls</emphasis> - column. <emphasis> -XkbNoteControlsChanges</emphasis> - copies any changes reported in <emphasis> -new</emphasis> - and specified in <emphasis> -wanted</emphasis> - into the changes record specified by <emphasis> -old</emphasis> -. -</para> - - -<para> -Use <emphasis> -XkbGetControlsChanges</emphasis> - to update a local copy of a keyboard description with the changes previously -noted by one or more calls to <emphasis> -XkbNoteControlsChanges.</emphasis> -</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> -XkbGetControlsChanges</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - xkb</emphasis> -,<emphasis> - changes</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* <emphasis> -xkb->ctrls</emphasis> - will be updated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbNameChangesPtr <emphasis> -changes</emphasis> -; /* indicates which parts of <emphasis> -xkb->ctrls</emphasis> - to update */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetControlsChanges</emphasis> - examines the <emphasis> -changes</emphasis> - parameter, queries the server for the necessary information, and copies the -results into the <emphasis> -xkb</emphasis> --><emphasis> -ctrls</emphasis> - keyboard description. If the <emphasis> -ctrls</emphasis> - field of <emphasis> -xkb</emphasis> - is <emphasis> -NULL</emphasis> -, <emphasis> -XkbGetControlsChanges</emphasis> - allocates and initializes it. To free the <emphasis> -ctrls</emphasis> - field, use <emphasis> -XkbFreeControls</emphasis> - (see section 10.12). <!-- xref --> -</para> - - -<para> -<emphasis> -XkbGetControlsChanges</emphasis> - returns <emphasis> -Success</emphasis> - if successful and can generate <emphasis> -BadAlloc</emphasis> -, <emphasis> -BadImplementation,</emphasis> - and <emphasis> -BadMatch</emphasis> - errors. +If the change was caused by a request from a client, the +<structfield>keycode</structfield> +and +<structfield>event_type</structfield> +fields are set to +<emphasis>zero</emphasis> +and the +<structfield>req_major</structfield> +and +<structfield>req_minor</structfield> +fields identify the request. The +<structfield>req_major</structfield> +value is the same as the major extension opcode. Otherwise, +<structfield>event_type</structfield> +is set to the type of event that caused the change (one of +<symbol>KeyPress</symbol>, +<symbol>KeyRelease</symbol>, +<symbol>DeviceKeyPress</symbol>, +<symbol>DeviceKeyRelease</symbol>, +<symbol>ButtonPress</symbol> +or +<symbol>ButtonRelease</symbol>), +and +<structfield>req_major</structfield> +and +<structfield>req_minor</structfield> +are undefined. If +<structfield>event_type</structfield> +is +<symbol>KeyPress</symbol>, +<symbol>KeyRelease</symbol>, +<symbol>DeviceKeyPress</symbol>, +or +<symbol>DeviceKeyRelease</symbol>, +the +<structfield>keycode</structfield> +field is set to the key that caused the change. If +<structfield>event_type</structfield> +is +<symbol>ButtonPress</symbol> +or +<symbol>ButtonRelease</symbol>, +<structfield>keycode</structfield> +contains the button number. +</para> + + +<para> +When a client receives an +<symbol>XkbControlsNotify</symbol> +event, it can note the changes in a changes structure using +<function>XkbNoteControlsChanges</function>. +</para> + +<indexterm significance="preferred" zone="XkbNoteControlsChanges"><primary><function>XkbNoteControlsChanges</function></primary></indexterm> +<funcsynopsis id="XkbNoteControlsChanges"> + <funcprototype> + <funcdef>void <function>XkbNoteControlsChanges</function></funcdef> +<!-- ( +<parameter>changes</parameter>, +<parameter>new</parameter>, +<parameter>wanted</parameter> +) --> + + <paramdef>XkbControlsChangesPtr <parameter>changes</parameter></paramdef> + <paramdef>XkbControlsNotifyEvent *<parameter>new</parameter></paramdef> + <paramdef>unsigned int <parameter>wanted</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>changes</parameter> + </term> + <listitem> + <para> + records changes indicated by new + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>new</parameter> + </term> + <listitem> + <para> + tells which things have changed + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>wanted</parameter> + </term> + <listitem> + <para> + tells which parts of new to record in changes + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<parameter>wanted</parameter> +parameter is a bitwise inclusive OR of bits taken from the set of masks +specified in <link linkend="table10.7">Table 10.7</link> with <quote>ok</quote> +in the +<structfield>changed_ctrls</structfield> +column. +<function>XkbNoteControlsChanges</function> +copies any changes reported in +<parameter>new</parameter> +and specified in +<parameter>wanted</parameter> +into the changes record specified by +<parameter>changes</parameter>. +</para> + + +<para> +Use +<function>XkbGetControlsChanges</function> +to update a local copy of a keyboard description with the changes previously +noted by one or more calls to +<function>XkbNoteControlsChanges</function>. +</para> + + +<indexterm significance="preferred" zone="XkbGetControlsChanges"><primary><function>XkbGetControlsChanges</function></primary></indexterm> +<funcsynopsis id="XkbGetControlsChanges"> + <funcprototype> + <funcdef>Status <function>XkbGetControlsChanges</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>xkb</parameter>, +<parameter>changes</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>XkbNameChangesPtr <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>xkb</parameter> + </term> + <listitem> + <para> + <structfield>xkb->ctrls</structfield> will be updated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>changes</parameter> + </term> + <listitem> + <para> + indicates which parts of <structfield>xkb->ctrls</structfield> to update + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetControlsChanges</function> +examines the +<parameter>changes</parameter> +parameter, queries the server for the necessary information, and copies the +results into the +<parameter>xkb</parameter>-><structfield>ctrls</structfield> +keyboard description. If the +<structfield>ctrls</structfield> +field of +<parameter>xkb</parameter> +is +<symbol>NULL</symbol>, +<function>XkbGetControlsChanges</function> +allocates and initializes it. To free the +<structfield>ctrls</structfield> +field, use +<function>XkbFreeControls</function> +(see <link linkend="Allocating_and_Freeing_an_XkbControlsRec">section 10.12</link>). +</para> + + +<para> +<function>XkbGetControlsChanges</function> +returns +<symbol>Success</symbol> +if successful and can generate +<errorname>BadAlloc</errorname>, +<errorname>BadImplementation</errorname>, +and +<errorname>BadMatch</errorname> +errors. </para> @@ -5058,190 +5047,188 @@ BadMatch</emphasis> <title>Allocating and Freeing an XkbControlsRec</title> <para> -The need to allocate an <emphasis> -XkbControlsRec</emphasis> - structure seldom arises; Xkb creates one when an application calls <emphasis> -XkbGetControls</emphasis> - or a related function. For those situations where there is not an <emphasis> -XkbControlsRec</emphasis> - structure allocated in the <emphasis> -XkbDescRec</emphasis> -, allocate one by calling <emphasis> -XkbAllocControls</emphasis> -. -</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> -XkbAllocControls</emphasis> -(<emphasis> -xkb, which</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> - xkb</emphasis> -; /* Xkb description in which to allocate ctrls rec */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - which</emphasis> -; /* mask of components of <emphasis> -ctrls</emphasis> - to allocate */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbAllocControls</emphasis> - allocates the <emphasis> -ctrls</emphasis> - field of the <emphasis> -xkb</emphasis> - parameter, initializes all fields to zero, and returns <emphasis> -Success</emphasis> -. If the <emphasis> -ctrls</emphasis> - field is not <emphasis> -NULL</emphasis> -, <emphasis> -XkbAllocControls</emphasis> - simply returns <emphasis> -Success</emphasis> -. If <emphasis> -xkb</emphasis> - is <emphasis> -NULL</emphasis> -, <emphasis> -XkbAllocControls</emphasis> - reports a <emphasis> -BadMatch</emphasis> - error. If the <emphasis> -ctrls</emphasis> - field could not be allocated, it reports a <emphasis> -BadAlloc</emphasis> - error. -</para> - - -<para> -The <emphasis> -which</emphasis> - mask specifies the individual fields of the <emphasis> -ctrls</emphasis> - structure to be allocated and can contain any of the valid masks defined in -Table 10.7. Because none of the currently existing controls have any structures +The need to allocate an +<structname>XkbControlsRec</structname> +structure seldom arises; Xkb creates one when an application calls +<function>XkbGetControls</function> +or a related function. For those situations where there is not an +<structname>XkbControlsRec</structname> +structure allocated in the +<structname>XkbDescRec</structname>, +allocate one by calling +<function>XkbAllocControls</function>. +</para> + +<indexterm significance="preferred" zone="XkbAllocControls"><primary><function>XkbAllocControls</function></primary></indexterm> +<funcsynopsis id="XkbAllocControls"> + <funcprototype> + <funcdef>Status <function>XkbAllocControls</function></funcdef> +<!-- ( +<parameter>xkb, which</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description in which to allocate ctrls rec + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask of components of <structfield>ctrls</structfield> to allocate + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbAllocControls</function> +allocates the +<structfield>ctrls</structfield> +field of the +<parameter>xkb</parameter> +parameter, initializes all fields to zero, and returns +<symbol>Success</symbol>. +If the +<structfield>ctrls</structfield> +field is not +<symbol>NULL</symbol>, +<function>XkbAllocControls</function> +simply returns +<symbol>Success</symbol>. +If +<parameter>xkb</parameter> +is +<symbol>NULL</symbol>, +<function>XkbAllocControls</function> +reports a +<errorname>BadMatch</errorname> +error. If the +<structfield>ctrls</structfield> +field could not be allocated, it reports a +<errorname>BadAlloc</errorname> +error. +</para> + + +<para> +The +<parameter>which</parameter> +mask specifies the individual fields of the +<structfield>ctrls</structfield> +structure to be allocated and can contain any of the valid masks defined in +<link linkend="table10.7">Table 10.7</link>. +Because none of the currently existing controls have any structures associated with them, which is currently of little practical value in this call. </para> <para> -To free memory used by the <emphasis> -ctrls</emphasis> - member of an <emphasis> -XkbDescRec </emphasis> -structure, use <emphasis> -XkbFreeControls:</emphasis> -</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> -XkbFreeControls</emphasis> -(<emphasis> -xkb, which, free_all</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr<emphasis> - xkb</emphasis> -; /* Xkb description in which to free controls components */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -which</emphasis> -; /* mask of components of <emphasis> -ctrls</emphasis> - to free */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> -free_all</emphasis> -; /* <emphasis> -True</emphasis> - => free everything + ctrls itself */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbFreeControls</emphasis> - frees the specified components of the <emphasis> -ctrls</emphasis> - field in the <emphasis> -xkb</emphasis> - keyboard description and sets the corresponding structure component values to -<emphasis> -NULL</emphasis> - or <emphasis> -zero</emphasis> -. The <emphasis> -which</emphasis> - mask specifies the fields of <emphasis> -ctrls</emphasis> - to be freed and can contain any of the controls components specified in Table -10.7. -</para> - - -<para> -If <emphasis> -free_all</emphasis> - is <emphasis> -True</emphasis> -, <emphasis> -XkbFreeControls</emphasis> - frees every non-<emphasis> -NULL</emphasis> - structure component in the controls, frees the <emphasis> -XkbControlsRec</emphasis> - structure referenced by the <emphasis> -ctrls</emphasis> - member of <emphasis> -xkb</emphasis> -, and sets <emphasis> -ctrls</emphasis> - to <emphasis> -NULL.</emphasis> +To free memory used by the +<structfield>ctrls</structfield> +member of an +<structname>XkbDescRec</structname> +structure, use +<function>XkbFreeControls</function>: +</para> + + +<indexterm significance="preferred" zone="XkbFreeControls"><primary><function>XkbFreeControls</function></primary></indexterm> +<funcsynopsis id="XkbFreeControls"> + <funcprototype> + <funcdef>void <function>XkbFreeControls</function></funcdef> +<!-- ( +<parameter>xkb, which, free_all</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>Bool <parameter>free_all</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + Xkb description in which to free controls components + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask of components of <structfield>ctrls</structfield> to free + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>free_all</parameter> + </term> + <listitem> + <para> + <symbol>True</symbol> ⇒ free everything + ctrls itself + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbFreeControls</function> +frees the specified components of the +<structfield>ctrls</structfield> +field in the +<parameter>xkb</parameter> +keyboard description and sets the corresponding structure component values to +<symbol>NULL</symbol> +or +<emphasis>zero</emphasis>. +The +<parameter>which</parameter> +mask specifies the fields of +<structfield>ctrls</structfield> +to be freed and can contain any of the controls components specified in +<link linkend="table10.7">Table 10.7</link>. +</para> + + +<para> +If +<parameter>free_all</parameter> +is +<symbol>True</symbol>, +<function>XkbFreeControls</function> +frees every non- +<symbol>NULL</symbol> +structure component in the controls, frees the +<structname>XkbControlsRec</structname> +structure referenced by the +<structfield>ctrls</structfield> +member of +<parameter>xkb</parameter>, +and sets +<structfield>ctrls</structfield> +to +<symbol>NULL</symbol>. </para> </sect1> @@ -5250,136 +5237,146 @@ NULL.</emphasis> <para> You can configure the boolean per-client controls which affect the state -reported in button and key events. See section 12.1.1, 12.3, 12.5, and 16.3.11 <!-- xref --> -of the XKB Protocol specification for more details. -</para> - - -<para> -To get the current values of the <emphasis> -per-client</emphasis> - controls, use <emphasis> -XkbGetPerClientControls</emphasis> -. -</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> -XkbGetPerClientControls</emphasis> -(<emphasis> -dpy</emphasis> -, <emphasis> -ctrls</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> -ctrls</emphasis> -; /* 1 bit => corresponding control is on */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbGetPerClientControls</emphasis> - backfills <emphasis> -ctrls</emphasis> - with the <emphasis> -per-client </emphasis> -control attributes for this particular client. It returns <emphasis> -True</emphasis> - if successful, and <emphasis> -False</emphasis> - otherwise. -</para> - - -<para> -To change the current values of the <emphasis> -per-client</emphasis> - control attributes, use <emphasis> -XkbSetPerClientControls.</emphasis> -</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> -XkbSetPerClientControls</emphasis> -(<emphasis> -dpy</emphasis> -, <emphasis> -ctrls</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -change</emphasis> -; /* 1 bit => change control */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> -value</emphasis> -; /* 1 bit => control on */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para> -<emphasis> -XkbSetPerClientControls changes the per-client values for the controls selected -by </emphasis> -<emphasis> -change to the corresponding value in value. Legal values for change and value +reported in button and key events. See +<olink targetdoc='xkbproto' targetptr='Setting_a_Passive_Grab_for_an_XKB_State'>section 12.1.1</olink>, +<olink targetdoc='xkbproto' targetptr='Effects_of_XKB_on_Core_Protocol_Events'>12.3</olink>, +<olink targetdoc='xkbproto' targetptr='Sending_Events_to_Clients'>12.5</olink>, +and +<olink targetdoc='xkbproto' targetptr='Querying_and_Changing_Per_Client_Flags'>16.3.11</olink> +of the +<olink targetdoc='xkbproto' targetptr='xkbproto'><citetitle>XKB Protocol specification</citetitle></olink> +for more details. +</para> + + +<para> +To get the current values of the +<emphasis>per-client</emphasis> +controls, use +<function>XkbGetPerClientControls</function>. +</para> + +<indexterm significance="preferred" zone="XkbGetPerClientControls"><primary><function>XkbGetPerClientControls</function></primary></indexterm> +<funcsynopsis id="XkbGetPerClientControls"> + <funcprototype> + <funcdef>Bool <function>XkbGetPerClientControls</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>ctrls</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int *<parameter>ctrls</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>ctrls</parameter> + </term> + <listitem> + <para> + 1 bit ⇒ corresponding control is on + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetPerClientControls</function> +backfills +<parameter>ctrls</parameter> +with the +<emphasis>per-client</emphasis> +control attributes for this particular client. It returns +<symbol>True</symbol> +if successful, and +<symbol>False</symbol> +otherwise. +</para> + + +<para> +To change the current values of the +<emphasis>per-client</emphasis> +control attributes, use +<function>XkbSetPerClientControls</function>. +</para> + + +<indexterm significance="preferred" zone="XkbSetPerClientControls"><primary><function>XkbSetPerClientControls</function></primary></indexterm> +<funcsynopsis id="XkbSetPerClientControls"> + <funcprototype> + <funcdef>Bool <function>XkbSetPerClientControls</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>ctrls</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>change</parameter></paramdef> + <paramdef>unsigned int *<parameter>value</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>change</parameter> + </term> + <listitem> + <para> + 1 bit ⇒ change control + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>value</parameter> + </term> + <listitem> + <para> + 1 bit ⇒ control on + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbSetPerClientControls</function> +changes the per-client values for the controls selected by +<parameter>change</parameter> to the corresponding value in +<parameter>value</parameter>. Legal values for +<parameter>change</parameter> and <parameter>value</parameter> are: XkbPCF_GrabsUseXKBStateMask, XkbPCF_LookupStateWhenGrabbed, and XkbPCF_SendEventUsesXKBState. More than one control may be changed at one time by OR-ing the values together. XkbSetPerClientControls backfills value with the -</emphasis> -<emphasis> -per-client </emphasis> -<emphasis> -control attributes for this particular client. </emphasis> -It returns <emphasis> -True</emphasis> - if successful, and <emphasis> -False</emphasis> - otherwise. +<emphasis>per-client</emphasis> +control attributes for this particular client. +It returns +<symbol>True</symbol> +if successful, and +<symbol>False</symbol> +otherwise. </para> </sect1> |