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

NAME

6       XkbDeviceBell  -  Rings  the bell on an X input extension device or the
7       default keyboard
8

SYNOPSIS

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

ARGUMENTS

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

DESCRIPTION

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

STRUCTURES

192       Xkb generates XkbBellNotify events for all bells except for  those  re‐
193       sulting  from calls to XkbForceDeviceBell and XkbForceBell.  To receive
194       XkbBellNotify events under all possible conditions, pass XkbBellNotify‐
195       Mask in both the bits_to_change and values_for_bits parameters to XkbS‐
196       electEvents.
197
198       The XkbBellNotify event has no event details. It is either selected  or
199       it  is not.  However, you can call XkbSelectEventDetails using XkbBell‐
200       Notify  as  the  event_type  and  specifying  XkbAllBellEventsMask   in
201       bits_to_change and values_for_bits.  This has the same effect as a call
202       to XkbSelectEvents.
203
204       The structure for the XkbBellNotify event type contains:
205
206          typedef struct _XkbBellNotify {
207              int            type;        /* Xkb extension base event code */
208              unsigned long  serial;      /* X server serial number for event */
209              Bool           send_event;  /* True => synthetically generated */
210              Display *      display;     /* server connection where event generated */
211              Time           time;        /* server time when event generated */
212              int            xkb_type;    /* XkbBellNotify */
213              unsigned int   device;      /* Xkb device ID, will not be XkbUseCoreKbd */
214              int            percent;     /* requested volume as % of max */
215              int            pitch;       /* requested pitch in Hz */
216              int            duration;    /* requested duration in microseconds */
217              unsigned int   bell_class;  /* X input extension feedback class */
218              unsigned int   bell_id;     /* X input extension feedback ID */
219              Atom           name;        /* "name" of requested bell */
220              Window         window;      /* window associated with event */
221              Bool           event_only;  /* False -> the server did not produce a beep */
222          } XkbBellNotifyEvent;
223
224       If your application needs to  generate  visual  bell  feedback  on  the
225       screen when it receives a bell event, use the window ID in the XkbBell‐
226       NotifyEvent, if present.
227
228

SEE ALSO

230       XBell(3),  XkbBellNotify(3),  XkbChangeEnabledControls(3),   XkbDevice‐
231       Bell(3),   XkbForceBell(3),   XkbForceDeviceBell(3),   XGetFeedbackCon‐
232       trol(3), XkbSelectEvents(3)
233
234
235
236
237X Version 11                    libX11 1.7.3.1                XkbDeviceBell(3)
Impressum