1XkbDeviceBellEvent(3) XKB FUNCTIONS XkbDeviceBellEvent(3)
2
6 XkbDeviceBellEvent - Creates a bell event for an X input extension de‐
7 vice or for the keyboard, without ringing the corresponding bell
8
10 Bool XkbDeviceBellEvent (Display *display, Window window, unsigned int
11 device_spec, unsigned int bell_class, unsigned int bell_id, int
12 percent, Atom name);
13
15 display
16 connection to the X server
17 window event window, or None
19 device_spec
21 device ID, or XkbUseCoreKbd
22 bell_class
24 input extension bell class for the event
25 bell_id
27 input extension bell ID for the event
28 percent
30 volume for the bell, which can range from -100 to 100 inclusive
31 name a bell name, or NULL
33
35 The core X protocol allows only applications to explicitly sound the
36 system bell with a given duration, pitch, and volume. Xkb extends this
37 capability by allowing clients to attach symbolic names to bells, dis‐
38 able audible bells, and receive an event whenever the keyboard bell is
39 rung. For the purposes of this document, the audible bell is defined to
40 be the system bell, or the default keyboard bell, as opposed to any
41 other audible sound generated elsewhere in the system. You can ask to
42 receive XkbBellNotify events when any client rings any one of the fol‐
43 lowing:
44 • The default bell
47 • Any bell on an input device that can be specified by a bell_class
49 and bell_id pair
50 • Any bell specified only by an arbitrary name. (This is, from the
52 server's point of view, merely a name, and not connected with any
53 physical sound-generating device. Some client application must
54 generate the sound, or visual feedback, if any, that is associated
55 with the name.)
56 You can also ask to receive XkbBellNotify events when the server
58 rings the default bell or if any client has requested events only
59 (without the bell sounding) for any of the bell types previously
60 listed.
61 You can disable audible bells on a global basis. For example, a
63 client that replaces the keyboard bell with some other audible cue
64 might want to turn off the AudibleBell control to prevent the
65 server from also generating a sound and avoid cacophony. If you
66 disable audible bells and request to receive XkbBellNotify events,
67 you can generate feedback different from the default bell.
68 You can, however, override the AudibleBell control by calling one
70 of the functions that force the ringing of a bell in spite of the
71 setting of the AudibleBell control - XkbForceDeviceBell or Xkb‐
72 ForceBell. In this case the server does not generate a bell
73 event.
74 Just as some keyboards can produce keyclicks to indicate when a
76 key is pressed or repeating, Xkb can provide feedback for the con‐
77 trols by using special beep codes. The AccessXFeedback control is
78 used to configure the specific types of operations that generate
79 feedback.
80 Bell Names
82 You can associate a name to an act of ringing a bell by converting
84 the name to an Atom and then using this name when you call the
85 functions listed in this chapter. If an event is generated as a
86 result, the name is then passed to all other clients interested in
87 receiving XkbBellNotify events. Note that these are arbitrary
88 names and that there is no binding to any sounds. Any sounds or
89 other effects (such as visual bells on the screen) must be gener‐
90 ated by a client application upon receipt of the bell event con‐
91 taining the name. There is no default name for the default key‐
92 board bell. The server does generate some predefined bells for the
93 AccessX controls. These named bells are shown in the Table 1 be‐
94 low; the name is included in any bell event sent to clients that
95 have requested to receive XkbBellNotify events.
96 Table 1 Predefined Bells
99 ──────────────────────────────────────────────────────────────
100 Action Named Bell
101 ──────────────────────────────────────────────────────────────
102 Indicator turned on AX_IndicatorOn
103 Indicator turned off AX_IndicatorOff
104 More than one indicator changed state AX_IndicatorChange
105 Control turned on AX_FeatureOn
106 Control turned off AX_FeatureOff
107 More than one control changed state AX_FeatureChange
108 SlowKeys and BounceKeys about to be AX_SlowKeysWarning
109 turned on or off
110 SlowKeys key pressed AX_SlowKeyPress
111 SlowKeys key accepted AX_SlowKeyAccept
112 SlowKeys key rejected AX_SlowKeyReject
113 Accepted SlowKeys key released AX_SlowKeyRelease
114 BounceKeys key rejected AX_BounceKeyReject
115 StickyKeys key latched AX_StickyLatch
116 StickyKeys key locked AX_StickyLock
117 StickyKeys key unlocked AX_StickyUnlock
118 Audible Bells
120 Using Xkb you can generate bell events that do not necessarily
122 ring the system bell. This is useful if you need to use an audio
123 server instead of the system beep. For example, when an audio
124 client starts, it could disable the audible bell (the system bell)
125 and then listen for XkbBellNotify events. When it receives a
126 XkbBellNotify event, the audio client could then send a request to
127 an audio server to play a sound.
128 You can control the audible bells feature by passing the XkbAudi‐
130 bleBellMask to XkbChangeEnabledControls. If you set XkbAudible‐
131 BellMask on, the server rings the system bell when a bell event
132 occurs. This is the default. If you set XkbAudibleBellMask off and
133 a bell event occurs, the server does not ring the system bell un‐
134 less you call XkbForceDeviceBell or XkbForceBell.
135 Audible bells are also part of the per-client auto-reset controls.
137 Bell Functions
139 Use the functions described in this section to ring bells and to
141 generate bell events.
142 The input extension has two types of feedbacks that can generate
144 bells - bell feedback and keyboard feedback. Some of the functions
145 in this section have bell_class and bell_id parameters; set them
146 as follows: Set bell_class to BellFeedbackClass or KbdFeedback‐
147 Class. A device can have more than one feedback of each type; set
148 bell_id to the particular bell feedback of bell_class type.
149 Table 2 shows the conditions that cause a bell to sound or an
151 XkbBellNotifyEvent to be generated when a bell function is called.
152 Table 2 Bell Sounding and Bell Event Generating
155 ───────────────────────────────────────────────────────────────────────────
156 Function called AudibleBell Server sounds a bell Server sends an
157 XkbBellNotifyEvent
158 ───────────────────────────────────────────────────────────────────────────
159 XkbDeviceBell On Yes Yes
160 XkbDeviceBell Off No Yes
161 XkbBell On Yes Yes
162 XkbBell Off No Yes
163 XkbDeviceBellEvent On or Off No Yes
164 XkbBellEvent On or Off No Yes
165 XkbDeviceForceBell On or Off Yes No
166 XkbForceBell On or Off Yes No
167 If a compatible keyboard extension isn't present in the X server,
169 XkbDeviceBellEvent immediately returns False. Otherwise, XkbDe‐
170 viceBellEvent causes an XkbBellNotify event to be sent to all in‐
171 terested clients and returns True. Set percent to be the volume
172 relative to the base volume for the keyboard as described for
173 XBell.
174 In addition, XkbDeviceBellEvent may generate Atom protocol errors
176 as well as XkbBellNotify events. You can call XkbBell without
177 first initializing the keyboard extension.
178
180 True The XkbDeviceBellEvent sends an XkbBellNotify event to
181 to all interested clients and returns True.
182 False If a compatible keyboard extension isn't present in the
184 X server, XkbDeviceBellEvent immediately returns False
185
187 Xkb generates XkbBellNotify events for all bells except for those re‐
188 sulting from
189 calls to XkbForceDeviceBell and XkbForceBell. To receive
190 XkbBellNotify events under all possible conditions, pass
191 XkbBellNotifyMask in both the bits_to_change and values_for_bits
192 parameters to XkbSelectEvents.
193 The XkbBellNotify event has no event details. It is either se‐
195 lected or it is not. However, you can call XkbSelectEventDe‐
196 tails using XkbBellNotify as the event_type and specifying Xk‐
197 bAllBellEventsMask in bits_to_change and values_for_bits. This
198 has the same effect as a call to XkbSelectEvents.
199 The structure for the XkbBellNotify event type contains:
201 typedef struct _XkbBellNotify {
203 int type; /* Xkb extension base event code */
204 unsigned long serial; /* X server serial number for event */
205 Bool send_event; /* True => synthetically generated */
206 Display * display; /* server connection where event generated */
207 Time time; /* server time when event generated */
208 int xkb_type; /* XkbBellNotify */
209 unsigned int device; /* Xkb device ID, will not be XkbUseCoreKbd */
210 int percent; /* requested volume as % of max */
211 int pitch; /* requested pitch in Hz */
212 int duration; /* requested duration in microseconds */
213 unsigned int bell_class; /* X input extension feedback class */
214 unsigned int bell_id; /* X input extension feedback ID */
215 Atom name; /* "name" of requested bell */
216 Window window; /* window associated with event */
217 Bool event_only; /* False -> the server did not produce a beep */
218 } XkbBellNotifyEvent;
219 If your application needs to generate visual bell feedback on
221 the screen when it receives a bell event, use the window ID in
222 the XkbBellNotifyEvent, if present.
223
226 XBell(3), XkbBellNotify(3), XkbChangeEnabledControls(3), XkbDevice‐
227 Bell(3), XkbForceBell(3), XkbForceDeviceBell(3), XkbSelectEvents(3),
228 XkbSelectEventDetails(3), XkbUseCoreKbd(3)
229X Version 11 libX11 1.8.7 XkbDeviceBellEvent(3)