XkbDeviceBellEvent(3)

🎀 XkbDeviceBellEvent(3) — XKB FUNCTIONS 🎀

okay bestie, welcome to the XKB FUNCTIONS page for XkbDeviceBellEvent 💅 this whole function is literally “make a bell event happen, but do not actually ring the bell.” the audacity. the control. we love a main character who refuses to make noise 😭✨

🌸 NAME 🌸

XkbDeviceBellEvent — creates a bell event for an X input extension device or for the keyboard, without ringing the corresponding bell 🎀

Not me sending the notification and then muting the actual sound. iconic behavior, honestly 💅

🦋 SYNOPSIS 🦋

Bool XkbDeviceBellEvent (Display *display, Window window, unsigned int
       device_spec, unsigned int bell_class, unsigned int bell_id, int
       percent, Atom name);

✨ ARGUMENTS ✨

• display — connection to the X server. your whole link to the server, bestie 🫶
• window — event window, or None. yes, None is a valid vibe here 💀
• device_spec — device ID, or XkbUseCoreKbd. use the core keyboard if that’s the assignment 👑
• bell_class — input extension bell class for the event. which flavor of bell feedback are we talking about 🔔
• bell_id — input extension bell ID for the event. the specific bell’s little ID card 🪪
• percent — volume for the bell, which can range from -100 to 100 inclusive. yes, inclusive, and yes, negative volume is a thing 😭
• name — a bell name, or NULL. name it or leave it unnamed, your call 🎀

💖 DESCRIPTION 💖

okay so the core X protocol only lets applications explicitly sound the system bell with a given duration, pitch, and volume. that’s the baseline. Xkb extends this capability by letting clients attach symbolic names to bells, disable audible bells, and receive an event whenever the keyboard bell is rung 🔔✨

For the purposes of this document, the audible bell is defined to be the system bell, or the default keyboard bell, as opposed to any other audible sound generated elsewhere in the system. like, we are specifically talking about that bell, not random other sounds doing their own thing 💅

You can ask to receive XkbBellNotify events when any client rings any one of the following:

• The default bell.
• Any bell on an input device that can be specified by a bell_class and bell_id pair.
• Any bell specified only by an arbitrary name. (This is, from the server’s point of view, merely a name, and not connected with any physical sound-generating device. Some client application must generate the sound, or visual feedback, if any, that is associated with the name.) 🫶

You can also ask to receive XkbBellNotify events when the server rings the default bell or if any client has requested events only (without the bell sounding) for any of the bell types previously listed. yes, events only, no sound, the quiet-luxury bell experience 😌

You can disable audible bells on a global basis. For example, a client that replaces the keyboard bell with some other audible cue might want to turn off the AudibleBell control to prevent the server from also generating a sound and avoid cacophony. if you disable audible bells and request to receive XkbBellNotify events, you can generate feedback different from the default bell. customize the vibe, bestie 🎨

You can, however, override the AudibleBell control by calling one of the functions that force the ringing of a bell in spite of the setting of the AudibleBell control — XkbForceDeviceBell or XkbForceBell. In this case the server does not generate a bell event. so like, forced bell = actual sound, no event. the rules are rules 💀

Just as some keyboards can produce keyclicks to indicate when a key is pressed or repeating, Xkb can provide feedback for the controls by using special beep codes. The AccessXFeedback control is used to configure the specific types of operations that generate feedback. beep codes are lowkey iconic 🎛️

🎀 Bell Names 🎀

You can associate a name to an act of ringing a bell by converting the name to an Atom and then using this name when you call the functions listed in this chapter. If an event is generated as a result, the name is then passed to all other clients interested in receiving XkbBellNotify events. 📨

Note that these are arbitrary names and that there is no binding to any sounds. Any sounds or other effects (such as visual bells on the screen) must be generated by a client application upon receipt of the bell event containing the name. so the name is giving “metaphorical bell,” and the actual sound is somebody else’s job 😭🔔

There is no default name for the default keyboard bell. The server does generate some predefined bells for the AccessX controls. These named bells are shown in the Table 1 below; the name is included in any bell event sent to clients that have requested to receive XkbBellNotify events.

Table 1 — Predefined Bells ✨

• Indicator turned on → AX_IndicatorOn
• Indicator turned off → AX_IndicatorOff
• More than one indicator changed state → AX_IndicatorChange
• Control turned on → AX_FeatureOn
• Control turned off → AX_FeatureOff
• More than one control changed state → AX_FeatureChange
• SlowKeys and BounceKeys about to be turned on or off → AX_SlowKeysWarning
• SlowKeys key pressed → AX_SlowKeyPress
• SlowKeys key accepted → AX_SlowKeyAccept
• SlowKeys key rejected → AX_SlowKeyReject
• Accepted SlowKeys key released → AX_SlowKeyRelease
• BounceKeys key rejected → AX_BounceKeyReject
• StickyKeys key latched → AX_StickyLatch
• StickyKeys key locked → AX_StickyLock
• StickyKeys key unlocked → AX_StickyUnlock

🔔 Audible Bells 🔔

Using Xkb you can generate bell events that do not necessarily ring the system bell. This is useful if you need to use an audio server instead of the system beep. For example, when an audio client starts, it could disable the audible bell (the system bell) and then listen for XkbBellNotify events. When it receives a XkbBellNotify event, the audio client could then send a request to an audio server to play a sound. that’s the pipeline, bestie — event in, cute little audio server request out 🎧✨

You can control the audible bells feature by passing the XkbAudibleBellMask to XkbChangeEnabledControls. If you set XkbAudibleBellMask on, the server rings the system bell when a bell event occurs. This is the default. If you set XkbAudibleBellMask off and a bell event occurs, the server does not ring the system bell unless you call XkbForceDeviceBell or XkbForceBell. default behavior said “yes sound,” but you can absolutely turn it off and do your own thing 💅

Audible bells are also part of the per-client auto-reset controls. noted, filed away, very demure 🎀

🧚 Bell Functions 🧚

Use the functions described in this section to ring bells and to generate bell events. that’s the whole assignment: bells and/or events 🔔📣

The input extension has two types of feedbacks that can generate bells — bell feedback and keyboard feedback. Some of the functions in this section have bell_class and bell_id parameters; set them as follows: Set bell_class to BellFeedbackClass or KbdFeedbackClass. A device can have more than one feedback of each type; set bell_id to the particular bell feedback of bell_class type. pick your class, pick your specific feedback ID, slay 🫶

Table 2 shows the conditions that cause a bell to sound or an XkbBellNotifyEvent to be generated when a bell function is called.

Table 2 — Bell Sounding and Bell Event Generating 🔥

• XkbDeviceBell — AudibleBell: On; server sounds a bell: Yes; server sends an XkbBellNotifyEvent: Yes
• XkbDeviceBell — AudibleBell: Off; server sounds a bell: No; server sends an XkbBellNotifyEvent: Yes
• XkbBell — AudibleBell: On; server sounds a bell: Yes; server sends an XkbBellNotifyEvent: Yes
• XkbBell — AudibleBell: Off; server sounds a bell: No; server sends an XkbBellNotifyEvent: Yes
• XkbDeviceBellEvent — AudibleBell: On or Off; server sounds a bell: No; server sends an XkbBellNotifyEvent: Yes
• XkbBellEvent — AudibleBell: On or Off; server sounds a bell: No; server sends an XkbBellNotifyEvent: Yes
• XkbDeviceForceBell — AudibleBell: On or Off; server sounds a bell: Yes; server sends an XkbBellNotifyEvent: No
• XkbForceBell — AudibleBell: On or Off; server sounds a bell: Yes; server sends an XkbBellNotifyEvent: No

If a compatible keyboard extension isn’t present in the X server, XkbDeviceBellEvent immediately returns False. Otherwise, XkbDeviceBellEvent causes an XkbBellNotify event to be sent to all interested clients and returns True. Set percent to be the volume relative to the base volume for the keyboard as described for XBell. 📊

In addition, XkbDeviceBellEvent may generate Atom protocol errors as well as XkbBellNotify events. You can call XkbBell without first initializing the keyboard extension. okay but the Atom protocol errors are giving “plot twist” 😭💀

👑 RETURN VALUES 👑

• True — The XkbDeviceBellEvent sends an XkbBellNotify event to to all interested clients and returns True. (yes, “to to” — the manpage said it, not me 😭💅)
• False — If a compatible keyboard extension isn’t present in the X server, XkbDeviceBellEvent immediately returns False.

✨ STRUCTURES ✨

Okay bestie, so here's the tea on how Xkb handles its bell events 🎀 — because not all bells are treated the same, and that's lowkey important:

Xkb generates XkbBellNotify events for all bells — except the ones that come from calls to XkbForceDeviceBell and XkbForceBell. 🙈 So like, the forced ones are the rebels that don't send the notification, iykyk.

So if you want to receive XkbBellNotify events under all possible conditions, you gotta pass XkbBellNotifyMask in both the bits_to_change and values_for_bits parameters to XkbSelectEvents. Both, bestie. Not one. Both. 💅

---

Also important: the XkbBellNotify event has no event details. It's either selected or it's not — no in-between, no nuance, it's giving all-or-nothing main character energy. 👑

But — and this is the fun part — you can call XkbSelectEventDetails using XkbBellNotify as the event_type, and specify XkbAllBellEventsMask in bits_to_change and values_for_bits. That does exactly the same thing as calling XkbSelectEvents. Same vibe, different route. ✨

---

🦋 The XkbBellNotify event structure

The structure for the XkbBellNotify event type contains:

typedef struct _XkbBellNotify {
    int            type;        /* Xkb extension base event code */
    unsigned long  serial;      /* X server serial number for event */
    Bool           send_event;  /* True => synthetically generated */
    Display *      display;     /* server connection where event generated */
    Time           time;        /* server time when event generated */
    int            xkb_type;    /* XkbBellNotify */
    unsigned int   device;      /* Xkb device ID, will not be XkbUseCoreKbd */
    int            percent;     /* requested volume as % of max */
    int            pitch;       /* requested pitch in Hz */
    int            duration;    /* requested duration in microseconds */
    unsigned int   bell_class;  /* X input extension feedback class */
    unsigned int   bell_id;     /* X input extension feedback ID */
    Atom           name;        /* "name" of requested bell */
    Window         window;      /* window associated with event */
    Bool           event_only;  /* False -> the server did not produce a beep */
} XkbBellNotifyEvent;

Let's break down these fields real quick so nothing's mysterious 🧚:

• type — the Xkb extension base event code. Standard boilerplate, she's just doing her job.
• serial — the X server serial number for the event. The receipt number of the whole thing 🧾
• send_event — True means it was synthetically generated. So True = "someone made this up", False = the real deal.
• display — the server connection where the event was generated. That's your connection, bestie.
• time — the server time when the event was generated. When it all went down, timestamp style ⏰
• xkb_type — this one's just XkbBellNotify. That's literally it.
• device — the Xkb device ID, and heads up: it will not be XkbUseCoreKbd. So don't go looking for it there, k?
• percent — the requested volume, as a percentage of max. So 100 = full send 🔊
• pitch — the requested pitch, in Hz. High pitch = extra, low pitch = moody.
• duration — the requested duration, in microseconds. Tiny, tiny units. Micro. Microscopic. 🫶
• bell_class — the X input extension feedback class. Very official-sounding, honestly iconic.
• bell_id — the X input extension feedback ID. The bell's own little ID card 🎀
• name — the "name" of the requested bell, as an Atom. (Yes, "name" in quotes — that's how the original writes it, and it's giving mysterious.)
• window — the window associated with the event. If there's a window attached, this is where she lives. 🪟
• event_only — False means the server did not produce a beep. So like… False here is actually the "no beep happened" flag. Kinda backwards, but okay, we respect her choices. 💀

---

🌸 One little tip for the visual girlies

If your application needs to generate visual bell feedback on the screen when it receives a bell event — like, you know, flash the window or something cute — use the window ID in the XkbBellNotifyEvent, if present. If it's there, use it. If not, well… that's the vibe check result, and she didn't pass. 🦋

No cap: if the window isn't present in the event, don't go making one up. The page says "if present" and we mean it, bestie. 💖

---

💜 SEE ALSO 💜

Go read these next, they're all part of the same friend group:

• XBell(3)
• XkbBellNotify(3)
• XkbChangeEnabledControls(3)
• XkbDeviceBell(3)
• XkbForceBell(3)
• XkbForceDeviceBell(3)
• XkbSelectEvents(3)
• XkbSelectEventDetails(3)
• XkbUseCoreKbd(3)

---

Okay that's the whole page, bestie, you made it! 🎉 This one's from X Version 11, shipped with libX11 1.8.14, and the page is dated XkbDeviceBellEvent(3) — go forth and ring those bells responsibly, mwah 💋🔔✨