1XkbForceDeviceBell(3) XKB FUNCTIONS XkbForceDeviceBell(3)
2
6 XkbForceDeviceBell - Rings the bell on any keyboard, overriding user
7 preference settings for audible bells
8
10 Bool XkbForceDeviceBell (Display *display, Window window, unsigned int
11 device_spec, unsigned int bell_class, unsigned int bell_id, int
12 percent);
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 class of the bell to be rung
25 bell_id
27 input extension ID of the bell to be rung
28 percent
30 relative volume, which can range from -100 to 100 inclusive
31
33 The core X protocol allows only applications to explicitly sound the
34 system bell with a given duration, pitch, and volume. Xkb extends this
35 capability by allowing clients to attach symbolic names to bells, dis‐
36 able audible bells, and receive an event whenever the keyboard bell is
37 rung. For the purposes of this document, the audible bell is defined to
38 be the system bell, or the default keyboard bell, as opposed to any
39 other audible sound generated elsewhere in the system. You can ask to
40 receive XkbBellNotify events when any client rings any one of the fol‐
41 lowing:
42 • The default bell
45 • Any bell on an input device that can be specified by a bell_class
47 and bell_id pair
48 • Any bell specified only by an arbitrary name. (This is, from the
50 server's point of view, merely a name, and not connected with any
51 physical sound-generating device. Some client application must
52 generate the sound, or visual feedback, if any, that is associated
53 with the name.)
54 You can also ask to receive XkbBellNotify events when the server rings
57 the default bell or if any client has requested events only (without
58 the bell sounding) for any of the bell types previously listed.
59 You can disable audible bells on a global basis. For example, a client
61 that replaces the keyboard bell with some other audible cue might want
62 to turn off the AudibleBell control to prevent the server from also
63 generating a sound and avoid cacophony. If you disable audible bells
64 and request to receive XkbBellNotify events, you can generate feedback
65 different from the default bell.
66 You can, however, override the AudibleBell control by calling one of
68 the functions that force the ringing of a bell in spite of the setting
69 of the AudibleBell control - XkbForceDeviceBell or XkbForceBell. In
70 this case the server does not generate a bell event.
71 Just as some keyboards can produce keyclicks to indicate when a key is
73 pressed or repeating, Xkb can provide feedback for the controls by us‐
74 ing special beep codes. The AccessXFeedback control is used to config‐
75 ure the specific types of operations that generate feedback.
76 Bell Names
78 You can associate a name to an act of ringing a bell by converting the
80 name to an Atom and then using this name when you call the functions
81 listed in this chapter. If an event is generated as a result, the name
82 is then passed to all other clients interested in receiving XkbBellNo‐
83 tify events. Note that these are arbitrary names and that there is no
84 binding to any sounds. Any sounds or other effects (such as visual
85 bells on the screen) must be generated by a client application upon re‐
86 ceipt of the bell event containing the name. There is no default name
87 for the default keyboard bell. The server does generate some predefined
88 bells for the AccessX controls. These named bells are shown in Table 1;
89 the name is included in any bell event sent to clients that have re‐
90 quested to receive XkbBellNotify events.
91 Table 1 Predefined Bells
94 ──────────────────────────────────────────────────────────────
95 Action Named Bell
96 ──────────────────────────────────────────────────────────────
97 Indicator turned on AX_IndicatorOn
98 Indicator turned off AX_IndicatorOff
99 More than one indicator changed state AX_IndicatorChange
100 Control turned on AX_FeatureOn
101 Control turned off AX_FeatureOff
102 More than one control changed state AX_FeatureChange
103 SlowKeys and BounceKeys about to be AX_SlowKeysWarning
104 turned on or off
105 SlowKeys key pressed AX_SlowKeyPress
106 SlowKeys key accepted AX_SlowKeyAccept
107 SlowKeys key rejected AX_SlowKeyReject
108 Accepted SlowKeys key released AX_SlowKeyRelease
109 BounceKeys key rejected AX_BounceKeyReject
110 StickyKeys key latched AX_StickyLatch
111 StickyKeys key locked AX_StickyLock
112 StickyKeys key unlocked AX_StickyUnlock
113 Audible Bells
115 Using Xkb you can generate bell events that do not necessarily ring the
117 system bell. This is useful if you need to use an audio server instead
118 of the system beep. For example, when an audio client starts, it could
119 disable the audible bell (the system bell) and then listen for XkbBell‐
120 Notify events. When it receives a XkbBellNotify event, the audio client
121 could then send a request to an audio server to play a sound.
122 You can control the audible bells feature by passing the XkbAudible‐
124 BellMask to XkbChangeEnabledControls. If you set XkbAudibleBellMask
125 on, the server rings the system bell when a bell event occurs. This is
126 the default. If you set XkbAudibleBellMask off and a bell event occurs,
127 the server does not ring the system bell unless you call XkbForceDe‐
128 viceBell or XkbForceBell.
129 Audible bells are also part of the per-client auto-reset controls.
131 Bell Functions
133 Use the functions described in this section to ring bells and to gener‐
135 ate bell events.
136 The input extension has two types of feedbacks that can generate bells
138 - bell feedback and keyboard feedback. Some of the functions in this
139 section have bell_class and bell_id parameters; set them as follows:
140 Set bell_class to BellFeedbackClass or KbdFeedbackClass. A device can
141 have more than one feedback of each type; set bell_id to the particular
142 bell feedback of bell_class type.
143 Table 2 shows the conditions that cause a bell to sound or an XkbBell‐
145 NotifyEvent to be generated when a bell function is called.
146 Table 2 Bell Sounding and Bell Event Generating
149 ───────────────────────────────────────────────────────────────────────────
150 Function called AudibleBell Server sounds a bell Server sends an
151 XkbBellNotifyEvent
152 ───────────────────────────────────────────────────────────────────────────
153 XkbDeviceBell On Yes Yes
154 XkbDeviceBell Off No Yes
155 XkbBell On Yes Yes
156 XkbBell Off No Yes
157 XkbDeviceBellEvent On or Off No Yes
158 XkbBellEvent On or Off No Yes
159 XkbDeviceForceBell On or Off Yes No
160 XkbForceBell On or Off Yes No
161 If a compatible keyboard extension isn't present in the X server, Xkb‐
164 ForceDeviceBell immediately returns False. Otherwise, XkbForceDevice‐
165 Bell rings the bell as specified for the display and keyboard device
166 and returns True. Set percent to be the volume relative to the base
167 volume for the keyboard as described for XBell.
168 There is no name parameter because XkbForceDeviceBell does not cause an
170 XkbBellNotify event.
171 You can call XkbBell without first initializing the keyboard extension.
173
175 Xkb generates XkbBellNotify events for all bells except for those re‐
176 sulting from calls to XkbForceDeviceBell and XkbForceBell. To receive
177 XkbBellNotify events under all possible conditions, pass XkbBellNotify‐
178 Mask in both the bits_to_change and values_for_bits parameters to XkbS‐
179 electEvents.
180 The XkbBellNotify event has no event details. It is either selected or
182 it is not. However, you can call XkbSelectEventDetails using XkbBell‐
183 Notify as the event_type and specifying XkbAllBellEventsMask in
184 bits_to_change and values_for_bits. This has the same effect as a call
185 to XkbSelectEvents.
186 The structure for the XkbBellNotify event type contains:
188 typedef struct _XkbBellNotify {
190 int type; /* Xkb extension base event code */
191 unsigned long serial; /* X server serial number for event */
192 Bool send_event; /* True => synthetically generated */
193 Display * display; /* server connection where event generated */
194 Time time; /* server time when event generated */
195 int xkb_type; /* XkbBellNotify */
196 unsigned int device; /* Xkb device ID, will not be XkbUseCoreKbd */
197 int percent; /* requested volume as % of max */
198 int pitch; /* requested pitch in Hz */
199 int duration; /* requested duration in microseconds */
200 unsigned int bell_class; /* X input extension feedback class */
201 unsigned int bell_id; /* X input extension feedback ID */
202 Atom name; /* "name" of requested bell */
203 Window window; /* window associated with event */
204 Bool event_only; /* False -> the server did not produce a beep */
205 } XkbBellNotifyEvent;
206 If your application needs to generate visual bell feedback on the
208 screen when it receives a bell event, use the window ID in the XkbBell‐
209 NotifyEvent, if present.
210
212 XBell(3), XkbBell(3), XkbBellNotify(3), XkbChangeEnabledControls(3),
213 XkbDeviceBell(3), XkbForceBell(3), XkbForceDeviceBell(3), XkbSe‐
214 lectEventDetails(3), XkbSelectEvents(3)
215X Version 11 libX11 1.8.7 XkbForceDeviceBell(3)