1<chapter id='Keyboard_Bells'>
2<title>Keyboard Bells</title>
3
4<para>
5The core protocol provides requests to control the pitch, volume and duration
6of the keyboard bell and a request to explicitly sound the bell.
7</para>
8
9
10<para>
11The X Keyboard Extension allows clients to disable the audible bell, attach a
12symbolic name to a bell request or receive an event when the keyboard bell is
13rung.
14</para>
15
16<sect1 id='Client_Notification_of_Bells'>
17<title>Client Notification of Bells</title>
18
19<para>
20Clients can ask to receive <emphasis>
21XkbBellNotify</emphasis>
22 event when a bell is requested by a client or generated by the server. Bells
23can be sounded due to core protocol <emphasis>
24Bell</emphasis>
25 requests, X Input Extension <emphasis>
26DeviceBell</emphasis>
27 requests, X Keyboard Extension <emphasis>
28XkbBell</emphasis>
29 requests or for reasons internal to the server such as the XKB <emphasis>
30AccessXFeedback</emphasis>
31 control.
32</para>
33
34
35<para>
36Bell events caused by the <emphasis>
37XkbBell</emphasis>
38 request or by the <emphasis>
39AccessXFeedback</emphasis>
40 control include an optional window and symbolic name for the bell. If present,
41the window makes it possible to provide some kind of visual indication of which
42window caused the sound. The symbolic name can report some information about
43the reason the bell was generated and makes it possible to generate a distinct
44sound for each type of bell.
45</para>
46
47
48</sect1>
49<sect1 id='Disabling_Server_Generated_Bells'>
50<title>Disabling Server Generated Bells</title>
51
52<para>
53The global <emphasis>
54AudibleBell</emphasis>
55 boolean control for a keyboard indicates whether bells sent to that device
56should normally cause the server to generate a sound. Applications which
57provide "sound effects" for the various named bells will typically disable the
58server generation of bells to avoid burying the user in sounds.
59</para>
60
61
62<para>
63When the <emphasis>
64AudibleBell</emphasis>
65 control is active, all bells caused by core protocol <emphasis>
66Bell</emphasis>
67 and X Input Extension <emphasis>
68DeviceBell</emphasis>
69 requests cause the server to generate a sound, as do all bells generated by
70the XKB <emphasis>
71AccessXFeedback</emphasis>
72 control. Bells requested via the X<emphasis>
73kbBell</emphasis>
74 request normally cause a server-generated sound, but clients can ask the
75server not to sound the default keyboard bell.
76</para>
77
78
79<para>
80When the <emphasis>
81AudibleBell</emphasis>
82 control is disabled, the server generates a sound only for bells that are
83generated using the <emphasis>
84XkbBell</emphasis>
85 request and which specify forced delivery of the bell.
86</para>
87
88
89</sect1>
90<sect1 id='Generating_Named_Bells'>
91<title>Generating Named Bells</title>
92
93<para>
94The <emphasis>
95XkbBell</emphasis>
96 request allows clients to specify a symbolic name which is reported in the
97bell events they cause. Bells generated by the <emphasis>
98AccessXFeedback</emphasis>
99 control of this extension also include a symbolic name, but all kinds of
100feedback cause a single event even if they sound multiple tones.
101</para>
102
103
104<para>
105The X server is permitted to use symbolic bell names (when present) to generate
106sounds other than simple tones, but it is not required to do so.
107</para>
108
109
110<para>
111Aside from those used by the XKB <emphasis>
112AccessXFeedback</emphasis>
113 control (see <link linkend='The_AccessXFeedback_Control'>The AccessXFeedback
114Control</link>), this extension does not specify bell names or their
115interpretation.
116</para>
117
118
119</sect1>
120<sect1 id='Generating_Optional_Named_Bells'>
121<title>Generating Optional Named Bells</title>
122
123<para>
124Under some circumstances, some kind of quiet audio feedback is useful, but a
125normal keyboard bell is not. For example, a quiet "launch effect" can be
126helpful to let the user know that an application has been started, but a loud
127bell would simply be annoying.
128</para>
129
130
131<para>
132To simplify generation of these kinds of effects, the <emphasis>
133XkbBell</emphasis>
134 request allows clients to specify "event only" bells. The X server never
135generates a normal keyboard bell for "event only" bells, regardless of the
136setting of the global <emphasis>
137AudibleBell</emphasis>
138 control.
139</para>
140
141
142<para>
143If the X server generates different sounds depending bell name, it is permitted
144to generate a sound even for "event only" bells. This field is intended simply
145to weed out "normal" keyboard bells.
146</para>
147
148
149</sect1>
150<sect1 id='Forcing_a_Server_Generated_Bell'>
151<title>Forcing a Server Generated Bell</title>
152
153<para>
154Occasionally, it is useful to force the server to generate a sound. For
155example, a client could "filter" server bells, generating sound effects for
156some but sounding the normal server bell for others. Such a client needs a way
157to tell the server that the requested bell should be generated regardless of
158the setting of the <emphasis>
159AudibleBell</emphasis>
160 control.
161</para>
162
163
164<para>
165To simplify this process, clients which call the <emphasis>
166XkbBell</emphasis>
167 request can specify that a bell is forced. A forced bell always causes a
168server generated sound and never causes a <emphasis>
169XkbBellNotify</emphasis>
170 event. Because forced bells do not cause bell notify events, they have no
171associated symbolic name or event window.
172</para>
173</sect1>
174</chapter>
175