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