XkbGetControlsChanges(3)

🌸 XkbGetControlsChanges(3) — the XKB FUNCTIONS glow-up ✨

okay so bestie, welcome to the XkbGetControlsChanges(3) page, brought to you by the XKB FUNCTIONS girlies 💅 this one is all about updating your local copy of a keyboard description with the changes that got noted earlier by one or more XkbNoteControlsChanges calls. it's giving "sync your vibes" energy, fr fr 🦋

---

📖 NAME

XkbGetControlsChanges — updates a local copy of a keyboard description with the changes previously noted by one or more calls to XkbNoteControlsChanges ✨

🎀 SYNOPSIS

XkbGetControlsChanges (Display *dpy, XkbDescPtr xkb, XkbNameChangesPtr
       changes);

🫶 ARGUMENTS

• dpy — your connection to the X server, aka the group chat you're connected to 💖
• xkb — xkb->ctrls is the thing that's gonna get updated, no cap
• changes — tells you which parts of xkb->ctrls to update 👑

💜 DESCRIPTION

so here's the lore: whenever a field in the controls structure changes in the server's keyboard description, the server sends an XkbControlsNotify event to all the interested clients 📣

wanna catch XkbControlsNotify events under all possible conditions? iconic. use XkbSelectEvents and pass XkbControlsNotifyMask in both bits_to_change and values_for_bits 👑

wanna catch them only under certain conditions? use XkbSelectEventDetails with XkbControlsNotify as the event_type, and specify the desired state changes in bits_to_change and values_for_bits using the mask bits from Table 1 🌈

Table 1 shows the actual values for the individual mask bits used to select controls for modification and to enable and disable the control. heads up: the same mask bit is used to specify general modifications to the parameters used to configure the control (which), and to enable and disable the control (enabled_ctrls). the anomalies in the table (the ones with no "ok" in a column) are for controls that have no configurable attributes, and for controls that are not boolean controls and therefore cannot be enabled or disabled 🙈

                            Table 1 Controls Mask Bits
───────────────────────────────────────────────────────────────────────────
Mask Bit                 which or        enabled   Value
                         changed_ctrls   _ctrls
───────────────────────────────────────────────────────────────────────────
XkbRepeatKeysMask        ok              ok        (1L<<0)
XkbSlowKeysMask          ok              ok        (1L<<1)
XkbBounceKeysMask        ok              ok        (1L<<2)
XkbStickyKeysMask        ok              ok        (1L<<3)
XkbMouseKeysMask         ok              ok        (1L<<4)
XkbMouseKeysAccelMask    ok              ok        (1L<<5)
XkbAccessXKeysMask       ok              ok        (1L<<6)
XkbAccessXTimeoutMask    ok              ok        (1L<<7)
XkbAccessXFeedbackMask   ok              ok        (1L<<8)
XkbAudibleBellMask                       ok        (1L<<9)
XkbOverlay1Mask                          ok        (1L<<10)
XkbOverlay2Mask                          ok        (1L<<11)
XkbIgnoreGroupLockMask                   ok        (1L<<12)
XkbGroupsWrapMask        ok                        (1L<<27)
XkbInternalModsMask      ok                        (1L<<28)
XkbIgnoreLockModsMask    ok                        (1L<<29)
XkbPerKeyRepeatMask      ok                        (1L<<30)
XkbControlsEnabledMask   ok                        (1L<<31)
XkbAccessXOptionsMask    ok              ok        (XkbStickyKeysMask |
                                                   XkbAccessXFeedbackMask)
XkbAllBooleanCtrlsMask                   ok        (0x00001FFF)
XkbAllControlsMask       ok                        (0xF8001FFF)

the changed_ctrls field specifies the controls components that have changed, and it consists of bits taken from the masks defined in Table 10.7 with "ok" in the changed_ctrls column 💫

the controls currently enabled in the server are reported in the enabled_ctrls field. if any controls were just enabled or disabled (like, the contents of the enabled_ctrls field changed), they get flagged in the enabled_ctrl_changes field 🚩 the valid bits for these fields are the masks listed in Table 10.7 with "ok" in the enabled_ctrls column. the num_groups field reports the number of groups bound to the key belonging to the most number of groups, and it's automatically updated when the keyboard mapping changes 👑

if the change was caused by a request from a client, the keycode and event_type fields are set to zero, and the req_major and req_minor fields identify the request. the req_major value is the same as the major extension opcode 🧚 otherwise, event_type is set to the type of event that caused the change (one of KeyPress, KeyRelease, DeviceKeyPress, DeviceKeyRelease, ButtonPress or ButtonRelease), and req_major and req_minor are undefined 💀 if event_type is KeyPress, KeyRelease, DeviceKeyPress, or DeviceKeyRelease, the keycode field is set to the key that caused the change. if event_type is ButtonPress or ButtonRelease, keycode contains the button number 🔥

when a client receives an XkbControlsNotify event, it can note the changes in a changes structure using XkbNoteControlsChanges 📝

XkbGetControlsChanges examines the changes parameter, queries the server for the necessary information, and copies the results into the xkb->ctrls keyboard description. if the ctrls field of xkb is NULL, XkbGetControlsChanges allocates and initializes it. to free the ctrls field, use XkbFreeControls 🫶

XkbGetControlsChanges returns Success if successful, and can generate BadAlloc, BadImplementation, and BadMatch errors 🌸

⭐ RETURN VALUES

• Success — the XkbGetControlsChanges function returns Success if the query of the server was successful 👑

🧚 STRUCTURES

the structure for the XkbControlsNotify event is defined as follows:

typedef struct {
    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;      /* XkbCompatMapNotify */
    int           device;        /* Xkb device ID, will not be XkbUseCoreKbd */
    unsigned int  changed_ctrls; /* bits indicating which controls data have changed*/
    unsigned int  enabled_ctrls; /* controls currently enabled in server */
    unsigned int  enabled_ctrl_changes; /* bits indicating enabled/disabled controls */
    int           num_groups;    /* current number of keyboard groups */
    KeyCode       keycode;       /* != 0 => keycode of key causing change */
    char          event_type;    /* Type of event causing change */
    char          req_major;     /* major event code of event causing change */
    char          req_minor;     /* minor event code of event causing change */
} XkbControlsNotifyEvent;

💀 DIAGNOSTICS

• BadAlloc — unable to allocate storage 😭
• BadImplementation — invalid reply from server 💀
• BadMatch — a compatible version of Xkb was not available in the server, or an argument has correct type and range but is otherwise invalid 🙈

🔥 SEE ALSO

XkbFreeControls(3), XkbNoteControlsChanges(3), XkbSelectEventDetails(3), XkbSelectEvents(3) 🦋

---

and that's the whole page bestie, mwah 💖 this little love letter to libX11 1.8.14 came from X Version 11, and the page itself is XkbGetControlsChanges(3) — slay, go forth and sync those controls ✨👑🎀