libX11 git update 14 sep 2011

1 files changed, 1060 insertions, 0 deletions

diff --git a/libX11/specs/XKB/ch09.xml b/libX11/specs/XKB/ch09.xml
new file mode 100644
index 000000000..d04669a12
--- /dev/null
+++ b/libX11/specs/XKB/ch09.xml
@@ -0,0 +1,1060 @@
+<chapter id='bells'>
+<title>Bells</title>
+
+<para>
+The core X protocol allows only applications to explicitly sound the system
+bell with a given duration, pitch, and volume. Xkb extends this capability by
+allowing clients to attach symbolic names to bells, disable audible bells, and
+receive an event whenever the keyboard bell is rung. For the purposes of this
+document, the <emphasis>
+audible</emphasis>
+ bell is defined to be the system bell, or the default keyboard bell, as
+opposed to any other audible sound generated elsewhere in the system.
+</para>
+
+
+<para>
+You can ask to receive <emphasis>
+XkbBellNotify</emphasis>
+ events (see section 9.4) when any client rings any one of the following: <!-- xref -->
+</para>
+
+<itemizedlist>
+<listitem>
+  <para>
+The default bell
+  </para>
+</listitem>
+<listitem>
+  <para>
+Any bell on an input device that can be specified by a <emphasis>
+bell_class</emphasis>
+ and <emphasis>
+bell_id</emphasis>
+ pair
+  </para>
+</listitem>
+<listitem>
+  <para>
+Any bell specified only by an arbitrary name. (This is, from the server’s
+point of view, merely a name, and not connected with any physical
+sound-generating device. Some client application must generate the sound, or
+visual feedback, if any, that is associated with the name.)
+  </para>
+</listitem>
+</itemizedlist>
+
+<para>
+You can also ask to receive <emphasis>
+XkbBellNotify</emphasis>
+ events when the server rings the default bell or if any client has requested
+events only (without the bell sounding) for any of the bell types previously
+listed.
+</para>
+
+<para>
+You can disable audible bells on a global basis (to set the <emphasis>
+AudibleBell</emphasis>
+ control, see Chapter 10). 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 you disable audible bells and request to receive <emphasis>
+XkbBellNotify</emphasis>
+ events, you can generate feedback different from the default bell.
+</para>
+
+
+<para>
+You can, however, override the <emphasis>
+AudibleBell</emphasis>
+ control by calling one of the functions that force the ringing of a bell in
+spite of the setting of the <emphasis>
+AudibleBell</emphasis>
+ control — <emphasis>
+XkbForceDeviceBell</emphasis>
+ or <emphasis>
+XkbForceBell</emphasis>
+ (see section 9.3.3). In this case the server does not generate a bell event. <!-- xref -->
+</para>
+
+
+<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. The <emphasis>
+AccessXFeedback</emphasis>
+ control is used to configure the specific types of operations that generate
+feedback. See section 10.6.3 for a discussion on <emphasis> <!-- xref -->
+AccessXFeedback</emphasis>
+ control.
+</para>
+
+<para>
+This chapter describes bell names, the functions used to generate named bells,
+and the events the server generates for bells.
+</para>
+
+<sect1 id='bell_names'>
+<title>Bell Names</title>
+
+<para>
+You can associate a name to an act of ringing a bell by converting the name to
+an Atom and then using this name when you call the functions listed in this
+chapter. If an event is generated as a result, the name is then passed to all
+other clients interested in receiving <emphasis>
+XkbBellNotify</emphasis>
+ events. Note that these are arbitrary names and that there is no binding to
+any sounds. Any sounds or other effects (such as visual bells on the screen)
+must be generated by a client application upon receipt of the bell event
+containing the name. There is no default name for the default keyboard bell.
+The server does generate some predefined bells for the AccessX controls (see
+section 10.6.3). These named bells are shown in Table 9.1; the name is included
+in any bell event sent to clients that have requested to receive <emphasis>
+XkbBellNotify</emphasis>
+ events.
+</para>
+
+<table frame='none'>
+<title>Predefined Bells</title>
+<tgroup cols='2'>
+<colspec colsep='0'/>
+<colspec colsep='0'/>
+<thead>
+<row rowsep='0'>
+  <entry>Action</entry>
+  <entry>Named Bell</entry>
+</row>
+</thead>
+<tbody>
+<row rowsep='0'>
+    <entry>Indicator turned on</entry>
+    <entry>AX_IndicatorOn</entry>
+</row>
+<row rowsep='0'>
+    <entry>Indicator turned off</entry>
+    <entry>AX_IndicatorOff</entry>
+</row>
+<row rowsep='0'>
+    <entry>More than one indicator changed state</entry>
+    <entry>AX_IndicatorChange</entry>
+</row>
+<row rowsep='0'>
+    <entry>Control turned on</entry>
+    <entry>AX_FeatureOn</entry>
+</row>
+<row rowsep='0'>
+    <entry>Control turned off</entry>
+    <entry>AX_FeatureOff</entry>
+</row>
+<row rowsep='0'>
+    <entry>More than one control changed state</entry>
+    <entry>AX_FeatureChange</entry>
+</row>
+<row rowsep='0'>
+    <entry>SlowKeys and BounceKeys about to be turned on or off</entry>
+    <entry>AX_SlowKeysWarning</entry>
+</row>
+<row rowsep='0'>
+    <entry>SlowKeys key pressed</entry>
+    <entry>AX_SlowKeyPress</entry>
+</row>
+<row rowsep='0'>
+    <entry>SlowKeys key accepted</entry>
+    <entry>AX_SlowKeyAccept</entry>
+</row>
+<row rowsep='0'>
+    <entry>SlowKeys key rejected</entry>
+    <entry>AX_SlowKeyReject</entry>
+</row>
+<row rowsep='0'>
+    <entry>Accepted SlowKeys key released</entry>
+    <entry>AX_SlowKeyRelease</entry>
+</row>
+<row rowsep='0'>
+    <entry>BounceKeys key rejected</entry>
+    <entry>AX_BounceKeyReject</entry>
+</row>
+<row rowsep='0'>
+    <entry>StickyKeys key latched</entry>
+    <entry>AX_StickyLatch</entry>
+</row>
+<row rowsep='0'>
+    <entry>StickyKeys key locked</entry>
+    <entry>AX_StickyLock</entry>
+</row>
+<row rowsep='0'>
+    <entry>StickyKeys key unlocked</entry>
+    <entry>AX_StickyUnlock</entry>
+  </row>
+</tbody>
+</tgroup>
+</table>
+
+</sect1>
+<sect1 id='audible_bells'>
+<title>Audible Bells</title>
+
+<para>
+Using Xkb you can generate bell events that do not necessarily ring the system
+bell. This is useful if you need to use an audio server instead of the system
+beep. For example, when an audio client starts, it could disable the audible
+bell (the system bell) and then listen for <emphasis>
+XkbBellNotify</emphasis>
+ events (see section 9.4). When it receives a <emphasis> <!-- xref -->
+XkbBellNotify</emphasis>
+ event, the audio client could then send a request to an audio server to play a
+sound.
+</para>
+
+
+<para>
+You can control the audible bells feature by passing the <emphasis>
+XkbAudibleBellMask</emphasis>
+ to <emphasis>
+XkbChangeEnabledControls</emphasis>
+ (see section 10.1.1). If you set <emphasis> <!-- xref -->
+XkbAudibleBellMask</emphasis>
+ on, the server rings the system bell when a bell event occurs. This is the
+default. If you set <emphasis>
+XkbAudibleBellMask</emphasis>
+ off and a bell event occurs, the server does not ring the system bell unless
+you call <emphasis>
+XkbForceDeviceBell</emphasis>
+ or <emphasis>
+XkbForceBell</emphasis>
+ (see section 9.3.3). <!-- xref -->
+</para>
+
+<para>
+Audible bells are also part of the per-client auto-reset controls. For more
+information on auto-reset controls, see section 10.1.2. <!-- xref -->
+</para>
+
+</sect1>
+<sect1 id='bell_functions'>
+<title>Bell Functions</title>
+
+<para>
+Use the functions described in this section to ring bells and to generate bell
+events.
+</para>
+
+<para>
+The input extension has two types of feedbacks that can generate bells — bell
+feedback and keyboard feedback. Some of the functions in this section have
+<emphasis>
+bell_class</emphasis>
+ and <emphasis>
+bell_id</emphasis>
+ parameters; set them as follows: Set <emphasis>
+bell_class</emphasis>
+ to <emphasis>
+BellFeedbackClass</emphasis>
+ or <emphasis>
+KbdFeedbackClass</emphasis>
+. A device can have more than one feedback of each type; set <emphasis>
+bell_id</emphasis>
+ to the particular bell feedback of <emphasis>
+bell_class</emphasis>
+ type.
+</para>
+
+<para>
+Table 9.2 shows the conditions that cause a bell to sound or an <emphasis> <!-- xref -->
+XkbBellNotifyEvent</emphasis>
+ to be generated when a bell function is called.
+</para>
+
+<table frame='none'>
+<title>Bell Sounding and Bell Event Generating</title>
+<tgroup cols='4'>
+<colspec colsep='0'/>
+<colspec colsep='0'/>
+<colspec colsep='0'/>
+<colspec colsep='0'/>
+<thead>
+  <row rowsep='0'>
+    <entry>Function called</entry>
+    <entry>AudibleBell</entry>
+    <entry>Server sounds a bell</entry>
+    <entry>Server sends an XkbBellNotifyEvent</entry>
+  </row>
+</thead>
+<tbody>
+<row rowsep='0'>
+    <entry>XkbDeviceBell</entry>
+    <entry>On</entry>
+    <entry>Yes</entry>
+    <entry>Yes</entry>
+</row>
+<row rowsep='0'>
+    <entry>XkbDeviceBell</entry>
+    <entry>Off</entry>
+    <entry>No</entry>
+    <entry>Yes</entry>
+</row>
+<row rowsep='0'>
+    <entry>XkbBell</entry>
+    <entry>On</entry>
+    <entry>Yes</entry>
+    <entry>Yes</entry>
+</row>
+<row rowsep='0'>
+    <entry>XkbBell</entry>
+    <entry>Off</entry>
+    <entry>No</entry>
+    <entry>Yes</entry>
+</row>
+<row rowsep='0'>
+    <entry>XkbDeviceBellEvent</entry>
+    <entry>On or Off</entry>
+    <entry>No</entry>
+    <entry>Yes</entry>
+</row>
+<row rowsep='0'>
+    <entry>XkbBellEvent</entry>
+    <entry>On or Off</entry>
+    <entry>No</entry>
+    <entry>Yes</entry>
+</row>
+<row rowsep='0'>
+    <entry>XkbDeviceForceBell</entry>
+    <entry>On or Off</entry>
+    <entry>Yes</entry>
+    <entry>No</entry>
+</row>
+<row rowsep='0'>
+    <entry>XkbForceBell</entry>
+    <entry>On or Off</entry>
+    <entry>Yes</entry>
+    <entry>No</entry>
+  </row>
+</tbody>
+</tgroup>
+</table>
+
+<sect2 id='generating_named_bells'>
+<title>Generating Named Bells</title>
+
+<para>
+To ring the bell on an X input extension device or the default keyboard, use
+<emphasis>
+XkbDeviceBell.</emphasis>
+</para>
+
+<informaltable frame='none'>
+<tgroup cols='1'>
+<colspec colsep='0'/>
+<tbody>
+  <row rowsep='0'>
+    <entry role='functiondecl'>
+Bool <emphasis>
+XkbDeviceBell</emphasis>
+(<emphasis>
+display, window, device_id, bell_class, bell_id, percent, name</emphasis>
+)
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+Display *<emphasis>
+      display</emphasis>
+;            /* connection to the X server */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+Window<emphasis>
+      window</emphasis>
+;            /* window for which the bell is generated, or None */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+unsigned int      <emphasis>
+device_spec</emphasis>
+;            /* device ID, or <emphasis>
+XkbUseCoreKbd</emphasis>
+ */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+unsigned int      <emphasis>
+bell_class</emphasis>
+;            /* X input extension bell class of the bell to be rung */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+unsigned int      <emphasis>
+bell_id</emphasis>
+;            /* X input extension bell ID of the bell to be rung */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+int      <emphasis>
+percent</emphasis>
+;            /* bell volume, from -100 to 100 inclusive */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+Atom      <emphasis>
+name</emphasis>
+;            /* a name for the bell, or <emphasis>
+NULL</emphasis>
+ */
+    </entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>
+Set <emphasis>
+percent</emphasis>
+ to be the volume relative to the base volume for the keyboard as described for
+<emphasis>
+XBell</emphasis>.
+</para>
+
+<para>
+Note that <emphasis>
+bell_class</emphasis>
+ and <emphasis>
+bell_id</emphasis>
+ indicate the bell to physically ring. <emphasis>
+name</emphasis>
+ is simply an arbitrary moniker for the client application’s use.
+</para>
+
+<para>
+To determine the current feedback settings of an extension input device, use
+<emphasis>
+XGetFeedbackControl</emphasis>
+. See the X input extension documentation for more information on <emphasis>
+XGetFeedbackControl</emphasis>
+ and related data structures.
+</para>
+
+<para>
+If a compatible keyboard extension is not present in the X server, <emphasis>
+XkbDeviceBell</emphasis>
+ immediately returns <emphasis>
+False</emphasis>
+. Otherwise, <emphasis>
+XkbDeviceBell </emphasis>
+rings the bell as specified for the display and keyboard device and returns
+<emphasis>
+True</emphasis>
+. If you have disabled the audible bell, the server does not ring the system
+bell, although it does generate a <emphasis>
+XkbBellNotify</emphasis>
+ event.
+</para>
+
+<para>
+You can call <emphasis>
+XkbDeviceBell</emphasis>
+ without first initializing the keyboard extension.
+</para>
+
+<para>
+As a convenience function, Xkb provides a function to ring the bell on the
+default keyboard: <emphasis>
+XkbBell.</emphasis>
+</para>
+
+<informaltable frame='none'>
+<tgroup cols='1'>
+<colspec colsep='0'/>
+<tbody>
+  <row rowsep='0'>
+    <entry role='functiondecl'>
+Bool <emphasis>
+XkbBell</emphasis>
+(<emphasis>
+display, window, percent, name</emphasis>
+)
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+Display *      <emphasis>
+display</emphasis>
+;            /* connection to the X server */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+Window<emphasis>
+      window</emphasis>
+;            /* event window, or None*/
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+int<emphasis>
+      percent</emphasis>
+;            /* relative volume, which can range from -100 to 100 inclusive */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+Atom<emphasis>
+      name</emphasis>
+;            /* a bell name, or <emphasis>
+NULL</emphasis>
+ */
+    </entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>
+If a compatible keyboard extension isn’t present in the X server, <emphasis>
+XkbBell</emphasis>
+ calls <emphasis>
+XBell </emphasis>
+with the specified <emphasis>
+display</emphasis>
+ and <emphasis>
+percent</emphasis>
+, and returns <emphasis>
+False</emphasis>
+. Otherwise, <emphasis>
+XkbBell </emphasis>
+calls <emphasis>
+XkbDeviceBell</emphasis>
+ with the specified <emphasis>
+display, window, percent, </emphasis>
+and <emphasis>
+name</emphasis>
+, a <emphasis>
+device_spec</emphasis>
+ of <emphasis>
+XkbUseCoreKbd</emphasis>
+, a <emphasis>
+bell_class </emphasis>
+of <emphasis>
+XkbDfltXIClass</emphasis>
+, and a <emphasis>
+bell_id </emphasis>
+of <emphasis>
+XkbDfltXIId,</emphasis>
+ and returns <emphasis>
+True</emphasis>.
+</para>
+
+<para>
+If you have disabled the audible bell, the server does not ring the system
+bell, although it does generate a <emphasis>
+XkbBellNotify</emphasis>
+ event.
+</para>
+
+<para>
+You can call <emphasis>
+XkbBell</emphasis>
+ without first initializing the keyboard extension.
+</para>
+
+</sect2>
+<sect2 id='generating_named_bell_events'>
+<title>Generating Named Bell Events</title>
+
+<para>
+Using Xkb, you can also generate a named bell event that does not ring any
+bell. This allows you to do things such as generate events when your
+application starts.
+</para>
+
+<para>
+For example, if an audio client listens for these types of bells, it can
+produce a "whoosh" sound when it receives a named bell event to indicate a
+client just started. In this manner, applications can generate start-up
+feedback and not worry about producing annoying beeps if an audio server is not
+running.
+</para>
+
+
+<para>
+To cause a bell event for an X input extension device or for the keyboard,
+without ringing the corresponding bell, use <emphasis>
+XkbDeviceBellEvent.</emphasis>
+</para>
+
+<informaltable frame='none'>
+<tgroup cols='1'>
+<colspec colsep='0'/>
+<tbody>
+  <row rowsep='0'>
+    <entry role='functiondecl'>
+Bool <emphasis>
+XkbDeviceBellEvent</emphasis>
+(<emphasis>
+display, window, device_spec, bell_class, bell_id, percent, name</emphasis>
+)
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+Display *      <emphasis>
+display</emphasis>
+;      /* connection to the X server */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+Window      <emphasis>
+window</emphasis>
+;      /* event window, or None*/
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+unsigned int      <emphasis>
+device_spec</emphasis>
+;      /* device ID, or <emphasis>
+XkbUseCoreKbd</emphasis>
+ */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+unsigned int      <emphasis>
+bell_class;</emphasis>
+      /* input extension bell class for the event */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+unsigned int      <emphasis>
+bell_id</emphasis>
+;      /* input extension bell ID for the event */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+int      <emphasis>
+percent</emphasis>
+;      /* volume for the bell, which can range from -100 to 100 inclusive */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+Atom      <emphasis>
+name</emphasis>
+;      /* a bell name, or <emphasis>
+NULL</emphasis>
+ */
+    </entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>
+If a compatible keyboard extension isn’t present in the X server, <emphasis>
+XkbDeviceBellEvent</emphasis>
+ immediately returns <emphasis>
+False</emphasis>
+. Otherwise, <emphasis>
+XkbDeviceBellEvent</emphasis>
+ causes an <emphasis>
+XkbBellNotify</emphasis>
+ event to be sent to all interested clients and returns <emphasis>
+True</emphasis>
+. Set <emphasis>
+percent</emphasis>
+ to be the volume relative to the base volume for the keyboard as described for
+<emphasis>XBell</emphasis>.
+</para>
+
+
+<para>
+In addition, <emphasis>
+XkbDeviceBellEvent</emphasis>
+ may generate <emphasis>
+Atom</emphasis>
+ protocol errors as well as <emphasis>
+XkbBellNotify</emphasis>
+ events. You can call <emphasis>
+XkbBell</emphasis>
+ without first initializing the keyboard extension.
+</para>
+
+
+<para>
+As a convenience function, Xkb provides a function to cause a bell event for
+the keyboard without ringing the bell: <emphasis>
+XkbBellEvent.</emphasis>
+</para>
+
+
+<informaltable frame='none'>
+<tgroup cols='1'>
+<colspec colsep='0'/>
+<tbody>
+  <row rowsep='0'>
+    <entry role='functiondecl'>
+Bool <emphasis>
+XkbBellEvent</emphasis>
+(<emphasis>
+display, window, percent, name</emphasis>
+)
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+Display *      <emphasis>
+display</emphasis>
+;            /* connection to the X server */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+Window      <emphasis>
+window</emphasis>
+;            /* the event window, or None */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+int      <emphasis>
+percent</emphasis>
+;            /* relative volume, which can range from -100 to 100 inclusive */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+Atom      <emphasis>
+name</emphasis>
+;            /* a bell name, or <emphasis>
+NULL</emphasis>
+ */
+    </entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>
+If a compatible keyboard extension isn’t present in the X server, <emphasis>
+XkbBellEvent</emphasis>
+ immediately returns <emphasis>
+False</emphasis>
+. Otherwise, <emphasis>
+XkbBellEvent </emphasis>
+calls<emphasis>
+ XkbDeviceBellEvent</emphasis>
+ with the specified <emphasis>
+display, window, percent, </emphasis>
+and <emphasis>
+name</emphasis>
+, a <emphasis>
+device_spec</emphasis>
+ of <emphasis>
+XkbUseCoreKbd</emphasis>
+, a <emphasis>
+bell_class </emphasis>
+of <emphasis>
+XkbDfltXIClass</emphasis>
+, and a <emphasis>
+bell_id </emphasis>
+of <emphasis>
+XkbDfltXIId,</emphasis>
+ and returns what <emphasis>
+XkbDeviceBellEvent</emphasis>
+ returns.
+</para>
+
+<para>
+<emphasis>XkbBellEvent</emphasis>
+generates a <emphasis>XkbBellNotify</emphasis>
+event.
+</para>
+
+
+<para>
+You can call <emphasis>
+XkbBellEvent</emphasis>
+without first initializing the keyboard extension.
+</para>
+
+</sect2>
+<sect2 id='forcing_a_server_generated_bell'>
+<title>Forcing a Server-Generated Bell</title>
+
+<para>
+To ring the bell on any keyboard, overriding user preference settings for
+audible bells, use <emphasis>XkbForceDeviceBell</emphasis>.
+</para>
+
+<informaltable frame='none'>
+<tgroup cols='1'>
+<colspec colsep='0'/>
+<tbody>
+  <row rowsep='0'>
+    <entry role='functiondecl'>
+Bool <emphasis>
+XkbForceDeviceBell</emphasis>
+(<emphasis>
+display, window, device_spec, bell_class, bell_id, percent</emphasis>
+)
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+Display *      <emphasis>
+display</emphasis>
+;            /* connection to the X server */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+Window      <emphasis>
+window</emphasis>
+;            /* event window, or None */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+unsigned int      <emphasis>
+device_spec</emphasis>
+;            /* device ID, or <emphasis>
+XkbUseCoreKbd</emphasis>
+ */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+unsigned int      <emphasis>
+bell_class</emphasis>
+;            /* input extension class of the bell to be rung */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+unsigned int      <emphasis>
+bell_id</emphasis>
+;            /* input extension ID of the bell to be rung */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+int      <emphasis>
+percent</emphasis>
+;            /* relative volume, which can range from -100 to 100 inclusive */
+    </entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>
+If a compatible keyboard extension isn’t present in the X server, <emphasis>
+XkbForceDeviceBell</emphasis>
+ immediately returns <emphasis>
+False</emphasis>
+. Otherwise, <emphasis>
+XkbForceDeviceBell </emphasis>
+rings the bell as specified for the display and keyboard device and returns
+<emphasis>
+True</emphasis>
+. Set <emphasis>
+percent</emphasis>
+ to be the volume relative to the base volume for the keyboard as described for
+<emphasis>
+XBell</emphasis>
+. There is no <emphasis>
+name</emphasis>
+ parameter because <emphasis>
+XkbForceDeviceBell </emphasis>
+does not cause an <emphasis>
+XkbBellNotify</emphasis>
+ event.
+</para>
+
+<para>
+You can call <emphasis>
+XkbBell</emphasis>
+ without first initializing the keyboard extension.
+</para>
+
+<para>
+To ring the bell on the default keyboard, overriding user preference settings
+for audible bells, use <emphasis>
+XkbForceBell</emphasis>.
+</para>
+
+<informaltable frame='none'>
+<tgroup cols='1'>
+<colspec colsep='0'/>
+<tbody>
+  <row rowsep='0'>
+    <entry role='functiondecl'>
+Bool <emphasis>
+XkbForceBell</emphasis>
+(<emphasis>
+display, percent)</emphasis>
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+Display *      <emphasis>
+display</emphasis>
+;      /* connection to the X server */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+int      <emphasis>
+percent</emphasis>
+;      /* volume for the bell, which can range from -100 to 100 inclusive */
+    </entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>
+If a compatible keyboard extension isn’t present in the X server, <emphasis>
+XkbForceBell</emphasis>
+ calls <emphasis>
+XBell </emphasis>
+with the specified <emphasis>
+display</emphasis>
+ and <emphasis>
+percent</emphasis>
+ and returns <emphasis>
+False</emphasis>
+. Otherwise, <emphasis>
+XkbForceBell </emphasis>
+calls <emphasis>
+XkbForceDeviceBell</emphasis>
+ with the specified <emphasis>
+display </emphasis>
+and<emphasis>
+ percent</emphasis>
+, <emphasis>
+device_spec</emphasis>
+ =<emphasis>
+XkbUseCoreKbd</emphasis>
+, <emphasis>
+bell_class </emphasis>
+= <emphasis>
+XkbDfltXIClass</emphasis>
+, <emphasis>
+bell_id </emphasis>
+= <emphasis>
+XkbDfltXIId,</emphasis>
+ <emphasis>
+window</emphasis>
+ = None, and <emphasis>
+name</emphasis>
+ = <emphasis>
+NULL</emphasis>
+, and returns what<emphasis>
+ XkbForceDeviceBell</emphasis>
+ returns.
+</para>
+
+<para>
+<emphasis>
+XkbForceBell </emphasis>
+does not cause an <emphasis>
+XkbBellNotify</emphasis>
+ event.
+</para>
+
+<para>
+You can call <emphasis>
+XkbBell</emphasis>
+ without first initializing the keyboard extension.
+</para>
+
+</sect2>
+</sect1>
+<sect1 id='detecting_bells'>
+<title>Detecting Bells</title>
+
+<para>
+Xkb generates <emphasis>
+XkbBellNotify</emphasis>
+ events for all bells except for those resulting from calls to <emphasis>
+XkbForceDeviceBell</emphasis>
+ and <emphasis>
+XkbForceBell</emphasis>
+. To receive <emphasis>
+XkbBellNotify</emphasis>
+ events under all possible conditions, pass <emphasis>
+XkbBellNotifyMask</emphasis>
+ in both the <emphasis>
+bits_to_change </emphasis>
+and<emphasis>
+ values_for_bits</emphasis>
+ parameters to <emphasis>
+XkbSelectEvents</emphasis>
+ (see section 4.3). <!-- xref -->
+</para>
+
+<para>
+The <emphasis>
+XkbBellNotify</emphasis>
+ event has no event details. It is either selected or it is not. However, you
+can call <emphasis>
+XkbSelectEventDetails</emphasis>
+ using <emphasis>
+XkbBellNotify</emphasis>
+ as the <emphasis>
+event_type</emphasis>
+ and specifying <emphasis>
+XkbAllBellNotifyMask</emphasis>
+ in <emphasis>
+bits_to_change</emphasis>
+ and <emphasis>
+values_for_bits.</emphasis>
+ This has the same effect as a call to <emphasis>
+XkbSelectEvents</emphasis>.
+</para>
+
+<para>
+The structure for the <emphasis>
+XkbBellNotify</emphasis>
+ event type contains:
+</para>
+
+<para><programlisting>
+typedef struct _XkbBellNotify {
+      int             type;        /* Xkb extension base event code */
+      unsigned long   serial;      /* X server serial number for event */
+      Bool            send_event;  /* <emphasis> True</emphasis> =&gt; synthetically generated */
+      Display *       display;     /* server connection where event generated */
+      Time            time;        /* server time when event generated */
+      int             xkb_type;    /* <emphasis> XkbBellNotify</emphasis> */
+      unsigned int    device;      /* Xkb device ID, will not be <emphasis> XkbUseCoreKbd</emphasis> */
+      int             percent;     /* requested volume as % of max */
+      int             pitch;       /* requested pitch in Hz */
+      int             duration;    /* requested duration in microseconds */
+      unsigned int    bell_class;  /* X input extension feedback class */
+      unsigned int    bell_id;     /* X input extension feedback ID */
+      Atom            name;        /* "name" of requested bell */
+      Window          window;      /* window associated with event */
+      Bool            event_only;  /* <emphasis> False</emphasis> -&gt; the server did not produce a beep */
+} <emphasis>XkbBellNotifyEvent</emphasis>;
+</programlisting></para>
+
+<para>
+If your application needs to generate visual bell feedback on the screen when
+it receives a bell event, use the window ID in the <emphasis>
+XkbBellNotifyEvent</emphasis>
+, if present.
+</para>
+
+</sect1>
+</chapter>