1XkbDeviceBell(3) XKB FUNCTIONS XkbDeviceBell(3)
2
6 XkbDeviceBell - Rings the bell on an X input extension device or the
7 default keyboard
8
10 Bool XkbDeviceBell (Display *display, Window window, unsigned int de‐
11 vice_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 window for which the bell is generated, or None
19 device_spec
21 device ID, or XkbUseCoreKbd
22 bell_class
24 X input extension bell class of the bell to be rung
25 bell_id
27 X input extension bell ID of the bell to be rung
28 percent
30 bell volume, from -100 to 100 inclusive
31 name a name for the bell, 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 ; the
94 name is included in any bell event sent to clients that have re‐
95 quested 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 The 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 Set percent to be the volume relative to the base volume for the
169 keyboard as described for .I XBell.
170 Note that bell_class and bell_id indicate the bell to physically
172 ring. name is simply an arbitrary moniker for the client applica‐
173 tion's use.
174 To determine the current feedback settings of an extension input
176 device, use XGetFeedbackControl. See the X input extension docu‐
177 mentation for more information on XGetFeedbackControl and related
178 data structures.
179 If a compatible keyboard extension is not present in the X server,
181 XkbDeviceBell immediately returns False. Otherwise, XkbDeviceBell
182 rings the bell as specified for the display and keyboard device
183 and returns True. If you have disabled the audible bell, the
184 server does not ring the system bell, although it does generate a
185 XkbBellNotify event.
186 You can call XkbDeviceBell without first initializing the keyboard
188 extension.
189
191 Xkb generates XkbBellNotify events for all bells except for those re‐
192 sulting from calls to XkbForceDeviceBell and XkbForceBell. To receive
193 XkbBellNotify events under all possible conditions, pass XkbBellNotify‐
194 Mask in both the bits_to_change and values_for_bits parameters to XkbS‐
195 electEvents.
196 The XkbBellNotify event has no event details. It is either selected or
198 it is not. However, you can call XkbSelectEventDetails using XkbBell‐
199 Notify as the event_type and specifying XkbAllBellEventsMask in
200 bits_to_change and values_for_bits. This has the same effect as a call
201 to XkbSelectEvents.
202 The structure for the XkbBellNotify event type contains:
204 typedef struct _XkbBellNotify {
206 int type; /* Xkb extension base event code */
207 unsigned long serial; /* X server serial number for event */
208 Bool send_event; /* True => synthetically generated */
209 Display * display; /* server connection where event generated */
210 Time time; /* server time when event generated */
211 int xkb_type; /* XkbBellNotify */
212 unsigned int device; /* Xkb device ID, will not be XkbUseCoreKbd */
213 int percent; /* requested volume as % of max */
214 int pitch; /* requested pitch in Hz */
215 int duration; /* requested duration in microseconds */
216 unsigned int bell_class; /* X input extension feedback class */
217 unsigned int bell_id; /* X input extension feedback ID */
218 Atom name; /* "name" of requested bell */
219 Window window; /* window associated with event */
220 Bool event_only; /* False -> the server did not produce a beep */
221 } XkbBellNotifyEvent;
222 If your application needs to generate visual bell feedback on the
224 screen when it receives a bell event, use the window ID in the XkbBell‐
225 NotifyEvent, if present.
226
229 XBell(3), XkbBellNotify(3), XkbChangeEnabledControls(3), XkbDevice‐
230 Bell(3), XkbForceBell(3), XkbForceDeviceBell(3), XGetFeedbackCon‐
231 trol(3), XkbSelectEvents(3)
232X Version 11 libX11 1.8.7 XkbDeviceBell(3)