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

NAME

6       XkbDeviceBellEvent  -  Creates  a  bell  event for an X input extension
7       device or for the keyboard, without ringing the corresponding bell
8

SYNOPSIS

10       Bool XkbDeviceBellEvent (Display *display, Window window, unsigned  int
11              device_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              event window, or None
20
21       - device_spec
22              device ID, or XkbUseCoreKbd
23
24       - bell_class
25              input extension bell class for the event
26
27       - bell_id
28              input extension bell ID for the event
29
30       - percent
31              volume for the bell, which can range from -100 to 100 inclusive
32
33       - name a bell name, 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
95            below; the name is included in any bell event sent to clients that
96            have requested 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
135            unless 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            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            If a compatible keyboard extension isn't present in the X  server,
170            XkbDeviceBellEvent  immediately  returns  False. Otherwise, XkbDe‐
171            viceBellEvent causes an XkbBellNotify event  to  be  sent  to  all
172            interested  clients and returns True. Set percent to be the volume
173            relative to the base volume for  the  keyboard  as  described  for
174            XBell.
175
176            In  addition, XkbDeviceBellEvent may generate Atom protocol errors
177            as well as XkbBellNotify events.  You  can  call  XkbBell  without
178            first initializing the keyboard extension.
179

RETURN VALUES

181       True           The  XkbDeviceBellEvent  sends an XkbBellNotify event to
182                      to all interested clients and returns True.
183
184       False          If a compatible keyboard extension isn't present in  the
185                      X server, XkbDeviceBellEvent immediately returns False
186

STRUCTURES

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

SEE ALSO

227       XBell(3),   XkbBellNotify(3),  XkbChangeEnabledControls(3),  XkbDevice‐
228       Bell(3),  XkbForceBell(3),  XkbForceDeviceBell(3),  XkbSelectEvents(3),
229       XkbSelectEventDetails(3), XkbUseCoreKbd(3)
230
231
232
233
234
235
236X Version 11                     libX11 1.6.5            XkbDeviceBellEvent(3)
Impressum