1XkbForceDeviceBell(3)            XKB FUNCTIONS           XkbForceDeviceBell(3)
2
3
4

NAME

6       XkbForceDeviceBell  -  Rings  the bell on any keyboard, overriding user
7       preference settings for audible bells
8

SYNOPSIS

10       Bool XkbForceDeviceBell (Display *display, Window window, unsigned  int
11              device_spec,  unsigned int bell_class, unsigned int bell_id, int
12              percent);
13

ARGUMENTS

15       - display
16              connection to the X server
17
18       - window
19              event window, or None
20
21       - device_spec
22              device ID, or XkbUseCoreKbd
23
24       - bell_class
25              input extension class of the bell to be rung
26
27       - bell_id
28              input extension ID of the bell to be rung
29
30       - percent
31              relative volume, which can range from -100 to 100 inclusive
32

DESCRIPTION

34       The core X protocol allows only applications to  explicitly  sound  the
35       system  bell with a given duration, pitch, and volume. Xkb extends this
36       capability by allowing clients to attach symbolic names to bells,  dis‐
37       able  audible bells, and receive an event whenever the keyboard bell is
38       rung. For the purposes of this document, the audible bell is defined to
39       be  the  system  bell,  or the default keyboard bell, as opposed to any
40       other audible sound generated elsewhere in the system.  You can ask  to
41       receive  XkbBellNotify events when any client rings any one of the fol‐
42       lowing:
43
44
45       •    The default bell
46
47       •    Any bell on an input device that can be specified by a  bell_class
48            and bell_id pair
49
50       •    Any  bell  specified only by an arbitrary name. (This is, from the
51            server's point of view, merely a name, and not connected with  any
52            physical  sound-generating  device.  Some  client application must
53            generate the sound, or visual feedback, if any, that is associated
54            with the name.)
55
56
57       You  can also ask to receive XkbBellNotify events when the server rings
58       the default bell or if any client has requested  events  only  (without
59       the bell sounding) for any of the bell types previously listed.
60
61       You  can disable audible bells on a global basis. For example, a client
62       that replaces the keyboard bell with some other audible cue might  want
63       to  turn  off  the  AudibleBell control to prevent the server from also
64       generating a sound and avoid cacophony. If you  disable  audible  bells
65       and  request to receive XkbBellNotify events, you can generate feedback
66       different from the default bell.
67
68       You can, however, override the AudibleBell control by  calling  one  of
69       the  functions that force the ringing of a bell in spite of the setting
70       of the AudibleBell control - XkbForceDeviceBell  or  XkbForceBell.   In
71       this case the server does not generate a bell event.
72
73       Just  as some keyboards can produce keyclicks to indicate when a key is
74       pressed or repeating, Xkb can provide feedback for the controls by  us‐
75       ing  special beep codes. The AccessXFeedback control is used to config‐
76       ure the specific types of operations that generate feedback.
77
78       Bell Names
79
80       You can associate a name to an act of ringing a bell by converting  the
81       name  to  an  Atom and then using this name when you call the functions
82       listed in this chapter. If an event is generated as a result, the  name
83       is  then passed to all other clients interested in receiving XkbBellNo‐
84       tify events. Note that these are arbitrary names and that there  is  no
85       binding  to  any  sounds.  Any  sounds or other effects (such as visual
86       bells on the screen) must be generated by a client application upon re‐
87       ceipt  of  the bell event containing the name. There is no default name
88       for the default keyboard bell. The server does generate some predefined
89       bells for the AccessX controls. These named bells are shown in Table 1;
90       the name is included in any bell event sent to clients  that  have  re‐
91       quested to receive XkbBellNotify events.
92
93
94                         Table 1 Predefined Bells
95       ──────────────────────────────────────────────────────────────
96       Action                                     Named Bell
97       ──────────────────────────────────────────────────────────────
98       Indicator turned on                        AX_IndicatorOn
99       Indicator turned off                       AX_IndicatorOff
100       More than one indicator changed state      AX_IndicatorChange
101       Control turned on                          AX_FeatureOn
102       Control turned off                         AX_FeatureOff
103       More than one control changed state        AX_FeatureChange
104       SlowKeys  and  BounceKeys  about  to  be   AX_SlowKeysWarning
105       turned on or off
106       SlowKeys key pressed                       AX_SlowKeyPress
107       SlowKeys key accepted                      AX_SlowKeyAccept
108       SlowKeys key rejected                      AX_SlowKeyReject
109       Accepted SlowKeys key released             AX_SlowKeyRelease
110       BounceKeys key rejected                    AX_BounceKeyReject
111       StickyKeys key latched                     AX_StickyLatch
112       StickyKeys key locked                      AX_StickyLock
113       StickyKeys key unlocked                    AX_StickyUnlock
114
115       Audible Bells
116
117       Using Xkb you can generate bell events that do not necessarily ring the
118       system  bell. This is useful if you need to use an audio server instead
119       of the system beep. For example, when an audio client starts, it  could
120       disable the audible bell (the system bell) and then listen for XkbBell‐
121       Notify events. When it receives a XkbBellNotify event, the audio client
122       could then send a request to an audio server to play a sound.
123
124       You  can  control  the audible bells feature by passing the XkbAudible‐
125       BellMask to XkbChangeEnabledControls.  If  you  set  XkbAudibleBellMask
126       on, the server rings the system bell when a bell event occurs.  This is
127       the default. If you set XkbAudibleBellMask off and a bell event occurs,
128       the  server  does  not ring the system bell unless you call XkbForceDe‐
129       viceBell or XkbForceBell.
130
131       Audible bells are also part of the per-client auto-reset controls.
132
133       Bell Functions
134
135       Use the functions described in this section to ring bells and to gener‐
136       ate bell events.
137
138       The  input extension has two types of feedbacks that can generate bells
139       - bell feedback and keyboard feedback. Some of the  functions  in  this
140       section  have  bell_class  and bell_id parameters; set them as follows:
141       Set bell_class to BellFeedbackClass or KbdFeedbackClass. A  device  can
142       have more than one feedback of each type; set bell_id to the particular
143       bell feedback of bell_class type.
144
145       Table 2 shows the conditions that cause a bell to sound or an  XkbBell‐
146       NotifyEvent to be generated when a bell function is called.
147
148
149                    Table 2 Bell Sounding and Bell Event Generating
150       ───────────────────────────────────────────────────────────────────────────
151       Function called      AudibleBell   Server sounds a bell   Server sends an
152       XkbBellNotifyEvent
153       ───────────────────────────────────────────────────────────────────────────
154       XkbDeviceBell        On            Yes                    Yes
155       XkbDeviceBell        Off           No                     Yes
156       XkbBell              On            Yes                    Yes
157       XkbBell              Off           No                     Yes
158       XkbDeviceBellEvent   On or Off     No                     Yes
159       XkbBellEvent         On or Off     No                     Yes
160       XkbDeviceForceBell   On or Off     Yes                    No
161       XkbForceBell         On or Off     Yes                    No
162
163
164       If  a compatible keyboard extension isn't present in the X server, Xkb‐
165       ForceDeviceBell immediately returns False.  Otherwise,  XkbForceDevice‐
166       Bell  rings  the  bell as specified for the display and keyboard device
167       and returns True. Set percent to be the volume  relative  to  the  base
168       volume for the keyboard as described for XBell.
169
170       There is no name parameter because XkbForceDeviceBell does not cause an
171       XkbBellNotify event.
172
173       You can call XkbBell without first initializing the keyboard extension.
174

STRUCTURES

176       Xkb generates XkbBellNotify events for all bells except for  those  re‐
177       sulting  from calls to XkbForceDeviceBell and XkbForceBell.  To receive
178       XkbBellNotify events under all possible conditions, pass XkbBellNotify‐
179       Mask in both the bits_to_change and values_for_bits parameters to XkbS‐
180       electEvents.
181
182       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  XkbAllBellEventsMask   in
185       bits_to_change and values_for_bits.  This has the same effect as a call
186       to XkbSelectEvents.
187
188       The structure for the XkbBellNotify event type contains:
189
190          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              int            percent;     /* requested volume as % of max */
199              int            pitch;       /* requested pitch in Hz */
200              int            duration;    /* requested duration in microseconds */
201              unsigned int   bell_class;  /* X input extension feedback class */
202              unsigned int   bell_id;     /* X input extension feedback ID */
203              Atom           name;        /* "name" of requested bell */
204              Window         window;      /* window associated with event */
205              Bool           event_only;  /* False -> the server did not produce a beep */
206          } XkbBellNotifyEvent;
207
208       If your application needs to  generate  visual  bell  feedback  on  the
209       screen when it receives a bell event, use the window ID in the XkbBell‐
210       NotifyEvent, if present.
211

SEE ALSO

213       XBell(3),  XkbBell(3),  XkbBellNotify(3),  XkbChangeEnabledControls(3),
214       XkbDeviceBell(3),    XkbForceBell(3),   XkbForceDeviceBell(3),   XkbSe‐
215       lectEventDetails(3), XkbSelectEvents(3)
216
217
218
219
220
221
222
223X Version 11                    libX11 1.7.3.1           XkbForceDeviceBell(3)
Impressum