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

NAME

6       XkbBellEvent  - Provides a function that initiates a bell event for the
7       keyboard without ringing the bell
8

SYNOPSIS

10       Bool XkbBellEvent (Display *display, Window window, int  percent,  Atom
11              name);
12

ARGUMENTS

14       - display
15              connection to the X server
16
17       - window
18              the event window, or None
19
20       - percent,
21              relative volume, which can range from -100 to 100 inclusive
22
23       - name a bell name, or NULL
24

DESCRIPTION

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

RETURN VALUES

172       False          The XkbBellEvent immediately returns False, if a compat‐
173                      ible keyboard extension isn't present in the X server.
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       */
199              int            percent;     /* requested volume as % of max */
200              int            pitch;       /* requested pitch in Hz */
201              int            duration;    /* requested duration in microseconds */
202              unsigned int   bell_class;  /* X input extension feedback class */
203              unsigned int   bell_id;     /* X input extension feedback ID */
204              Atom           name;        /* "name" of requested bell */
205              Window         window;      /* window associated with event */
206              Bool           event_only;  /* False -> the server did not produce a beep
207       */
208          } XkbBellNotifyEvent;
209
210       If your application needs to  generate  visual  bell  feedback  on  the
211       screen when it receives a bell event, use the window ID in the XkbBell‐
212       NotifyEvent, if present.
213
214

SEE ALSO

216       XkbChangeEnabledControls(3),  XkbDeviceBellEvent(3),   XkbForceBell(3),
217       XkbForceDeviceBell(3), XkbSelectEventDetails(3), XkbSelectEvents(3)
218
219
220
221
222
223
224X Version 11                     libX11 1.7.2                  XkbBellEvent(3)
Impressum