1061 lines
26 KiB
XML
1061 lines
26 KiB
XML
<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>
|