diff options
Diffstat (limited to 'libX11/specs/XKB/ch09.xml')
| -rw-r--r-- | libX11/specs/XKB/ch09.xml | 1060 |
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> => 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> -> 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> |