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 the event window, or None
18 percent
20 relative volume, which can range from -100 to 100 inclusive
21 name a bell name, or NULL
23
25 The core X protocol allows only applications to explicitly sound the
26 system bell with a given duration, pitch, and volume. Xkb extends this
27 capability by allowing clients to attach symbolic names to bells, dis‐
28 able audible bells, and receive an event whenever the keyboard bell is
29 rung. For the purposes of this document, the audible bell is defined to
30 be the system bell, or the default keyboard bell, as opposed to any
31 other audible sound generated elsewhere in the system. You can ask to
32 receive XkbBellNotify events when any client rings any one of the fol‐
33 lowing:
34 • The default bell
37 • Any bell on an input device that can be specified by a bell_class
39 and bell_id pair
40 • Any bell specified only by an arbitrary name. (This is, from the
42 server's point of view, merely a name, and not connected with any
43 physical sound-generating device. Some client application must
44 generate the sound, or visual feedback, if any, that is associated
45 with the name.)
46 You can also ask to receive XkbBellNotify events when the server
48 rings the default bell or if any client has requested events only
49 (without the bell sounding) for any of the bell types previously
50 listed.
51 You can disable audible bells on a global basis. For example, a
53 client that replaces the keyboard bell with some other audible cue
54 might want to turn off the AudibleBell control to prevent the
55 server from also generating a sound and avoid cacophony. If you
56 disable audible bells and request to receive XkbBellNotify events,
57 you can generate feedback different from the default bell.
58 You can, however, override the AudibleBell control by calling one
60 of the functions that force the ringing of a bell in spite of the
61 setting of the AudibleBell control - XkbForceDeviceBell or Xkb‐
62 ForceBell. In this case the server does not generate a bell
63 event.
64 Just as some keyboards can produce keyclicks to indicate when a
66 key is pressed or repeating, Xkb can provide feedback for the con‐
67 trols by using special beep codes. The AccessXFeedback control is
68 used to configure the specific types of operations that generate
69 feedback.
70 Bell Names
72 You can associate a name to an act of ringing a bell by converting
74 the name to an Atom and then using this name when you call the
75 functions listed in this chapter. If an event is generated as a
76 result, the name is then passed to all other clients interested in
77 receiving XkbBellNotify events. Note that these are arbitrary
78 names and that there is no binding to any sounds. Any sounds or
79 other effects (such as visual bells on the screen) must be gener‐
80 ated by a client application upon receipt of the bell event con‐
81 taining the name. There is no default name for the default key‐
82 board bell. The server does generate some predefined bells for the
83 AccessX controls. These named bells are shown in Table 1; the name
84 is included in any bell event sent to clients that have requested
85 to receive XkbBellNotify events.
86 Table 1 Predefined Bells
89 ──────────────────────────────────────────────────────────────
90 Action Named Bell
91 ──────────────────────────────────────────────────────────────
92 Indicator turned on AX_IndicatorOn
93 Indicator turned off AX_IndicatorOff
94 More than one indicator changed state AX_IndicatorChange
95 Control turned on AX_FeatureOn
96 Control turned off AX_FeatureOff
97 More than one control changed state AX_FeatureChange
98 SlowKeys and BounceKeys about to be AX_SlowKeysWarning
99 turned on or off
100 SlowKeys key pressed AX_SlowKeyPress
101 SlowKeys key accepted AX_SlowKeyAccept
102 SlowKeys key rejected AX_SlowKeyReject
103 Accepted SlowKeys key released AX_SlowKeyRelease
104 BounceKeys key rejected AX_BounceKeyReject
105 StickyKeys key latched AX_StickyLatch
106 StickyKeys key locked AX_StickyLock
107 StickyKeys key unlocked AX_StickyUnlock
108 Audible Bells
110 Using Xkb you can generate bell events that do not necessarily
112 ring the system bell. This is useful if you need to use an audio
113 server instead of the system beep. For example, when an audio
114 client starts, it could disable the audible bell (the system bell)
115 and then listen for XkbBellNotify events. When it receives a
116 XkbBellNotify event, the audio client could then send a request to
117 an audio server to play a sound.
118 You can control the audible bells feature by passing the XkbAudi‐
120 bleBellMask to XkbChangeEnabledControls. If you set XkbAudible‐
121 BellMask on, the server rings the system bell when a bell event
122 occurs. This is the default. If you set XkbAudibleBellMask off and
123 a bell event occurs, the server does not ring the system bell un‐
124 less you call XkbForceDeviceBell or XkbForceBell.
125 Audible bells are also part of the per-client auto-reset controls.
127 Bell Functions
129 Use the functions described in this section to ring bells and to
131 generate bell events.
132 The input extension has two types of feedbacks that can generate
134 bells - bell feedback and keyboard feedback. Some of the functions
135 in this section have bell_class and bell_id parameters; set them
136 as follows: Set bell_class to BellFeedbackClass or KbdFeedback‐
137 Class. A device can have more than one feedback of each type; set
138 bell_id to the particular bell feedback of bell_class type.
139 Table 2 shows the conditions that cause a bell to sound or an
141 XkbBellNotifyEvent to be generated when a bell function is called.
142 Table 2 Bell Sounding and Bell Event Generating
145 ───────────────────────────────────────────────────────────────────────────
146 Function called AudibleBell Server sounds a bell Server sends an
147 XkbBellNotifyEvent
148 ───────────────────────────────────────────────────────────────────────────
149 XkbDeviceBell On Yes Yes
150 XkbDeviceBell Off No Yes
151 XkbBell On Yes Yes
152 XkbBell Off No Yes
153 XkbDeviceBellEvent On or Off No Yes
154 XkbBellEvent On or Off No Yes
155 XkbDeviceForceBell On or Off Yes No
156 XkbForceBell On or Off Yes No
157 If a compatible keyboard extension isn't present in the X server,
159 XkbBellEvent immediately returns False. Otherwise, XkbBellEvent
160 calls XkbDeviceBellEvent with the specified display, window, per‐
161 cent, and name, a device_spec of XkbUseCoreKbd, a bell_class of
162 XkbDfltXIClass, and a bell_id of XkbDfltXIId, and returns what
163 XkbDeviceBellEvent returns.
164 XkbBellEvent generates a XkbBellNotify event.
166 You can call XkbBellEvent without first initializing the keyboard
168 extension.
169
171 False The XkbBellEvent immediately returns False, if a compat‐
172 ible keyboard extension isn't present in the X server.
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
213 XkbChangeEnabledControls(3), XkbDeviceBellEvent(3), XkbForceBell(3),
214 XkbForceDeviceBell(3), XkbSelectEventDetails(3), XkbSelectEvents(3)
215X Version 11 libX11 1.8.7 XkbBellEvent(3)