XkbSetControls(3)

🦋 NAME 🦋

okay so welcome to XkbSetControls from the XKB FUNCTIONS section (section 3, bestie 💅) — it copies changes to the X server based on a modified ctrls structure in a local copy of the keyboard description. that's the whole vibe. no cap.

---

✨ SYNOPSIS ✨

Bool XkbSetControls (Display *display, unsigned long which, XkbDescPtr
       xkb);

---

🎀 ARGUMENTS 🎀

• display — connection to X server. the whole reason we're here 🫶
• which — mask of controls requested. it's giving "pick your fighters" energy ⭐
• xkb — keyboard description for controls information. this is where the ctrls tea lives 💜

---

💖 DESCRIPTION 💖

so for each bit that's set in the which parameter, XkbSetControls sends the corresponding values from the xkb->ctrls field to the server. literally bit by bit, she's delivering 📦✨

valid values for which are any combination of the masks listed in Table 1 that have "ok" in the which column. iykyk 👑

Table 1 shows the actual values for the individual mask bits used to select controls for modification and to enable and disable the control. note (and this is the important part, don't skip it 🙈) that 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 rows with no "ok" in the column) are for controls that have no configurable attributes; and for controls that are not boolean controls and therefore cannot be enabled or disabled. lowkey rude of them but ok 💀

🌈 Table 1 — Controls Mask Bits 🌈

each bullet is one mask bit, showing whether it's "ok" in which or changed_ctrls, whether it's "ok" in enabled_ctrls, and its value ✨

• XkbRepeatKeysMask — which or changed_ctrls: ok · enabled_ctrls: ok · value (1L<<0)
• XkbSlowKeysMask — which or changed_ctrls: ok · enabled_ctrls: ok · value (1L<<1)
• XkbBounceKeysMask — which or changed_ctrls: ok · enabled_ctrls: ok · value (1L<<2)
• XkbStickyKeysMask — which or changed_ctrls: ok · enabled_ctrls: ok · value (1L<<3)
• XkbMouseKeysMask — which or changed_ctrls: ok · enabled_ctrls: ok · value (1L<<4)
• XkbMouseKeysAccelMask — which or changed_ctrls: ok · enabled_ctrls: ok · value (1L<<5)
• XkbAccessXKeysMask — which or changed_ctrls: ok · enabled_ctrls: ok · value (1L<<6)
• XkbAccessXTimeoutMask — which or changed_ctrls: ok · enabled_ctrls: ok · value (1L<<7)
• XkbAccessXFeedbackMask — which or changed_ctrls: ok · enabled_ctrls: ok · value (1L<<8)
• XkbAudibleBellMask — which or changed_ctrls: (blank — not ok) · enabled_ctrls: ok · value (1L<<9)
• XkbOverlay1Mask — which or changed_ctrls: (blank — not ok) · enabled_ctrls: ok · value (1L<<10)
• XkbOverlay2Mask — which or changed_ctrls: (blank — not ok) · enabled_ctrls: ok · value (1L<<11)
• XkbIgnoreGroupLockMask — which or changed_ctrls: (blank — not ok) · enabled_ctrls: ok · value (1L<<12)
• XkbGroupsWrapMask — which or changed_ctrls: ok · enabled_ctrls: (blank — not ok) · value (1L<<27)
• XkbInternalModsMask — which or changed_ctrls: ok · enabled_ctrls: (blank — not ok) · value (1L<<28)
• XkbIgnoreLockModsMask — which or changed_ctrls: ok · enabled_ctrls: (blank — not ok) · value (1L<<29)
• XkbPerKeyRepeatMask — which or changed_ctrls: ok · enabled_ctrls: (blank — not ok) · value (1L<<30)
• XkbControlsEnabledMask — which or changed_ctrls: ok · enabled_ctrls: (blank — not ok) · value (1L<<31)
• XkbAccessXOptionsMask — which or changed_ctrls: ok · enabled_ctrls: ok · value (XkbStickyKeysMask | XkbAccessXFeedbackMask)
• XkbAllBooleanCtrlsMask — which or changed_ctrls: (blank — not ok) · enabled_ctrls: ok · value (0x00001FFF)
• XkbAllControlsMask — which or changed_ctrls: ok · enabled_ctrls: (blank — not ok) · value (0xF8001FFF)

---

🧚 the fail conditions, gather round 🧚

if xkb->ctrls is NULL, or the server does not support a compatible version of Xkb, or the Xkb extension has not been properly initialized, XkbSetControls returns False. otherwise, it sends the request to the X server and returns True. and that's it, that's the whole storyline 😭💖

👑 control attributes — the lore 👑

note that changes to attributes of controls in the XkbControlsRec structure are apparent only when the associated control is enabled, although the corresponding values are still updated in the X server. for example, the repeat_delay and repeat_interval fields are ignored unless the RepeatKeys control is enabled (that is, the X server's equivalent of xkb->ctrls has XkbRepeatKeyMask set in enabled_ctrls). ngl that's the fine print, read it twice 🙈

it is permissible to modify the attributes of a control in one call to XkbSetControls and enable the control in a subsequent call. see XkbChangeEnabledControls for more information on enabling and disabling controls. spread it out, she doesn't mind ✨

⭐ enabled_ctrls is itself a control — plot twist ⭐

note that the enabled_ctrls field is itself a control — the EnabledControls control. as such, to set a specific configuration of enabled and disabled boolean controls, you must set enabled_ctrls to the appropriate bits to enable only the controls you want and disable all others, then specify the XkbControlsEnabledMask in a call to XkbSetControls. main character energy, honestly 🔥

because this is somewhat awkward if all you want to do is enable and disable controls, and not modify any of their attributes, a convenience function is also provided for this purpose, XkbChangeEnabledControls. she's the shortcut bestie 🫶

---

💜 RETURN VALUES 💜

• True — the XkbSetControls function returns True when it sends the request to the X server. slay ✅
• False — the XkbSetControls function returns False when xkb->ctrls is NULL, the server does not support a compatible version of Xkb, or the Xkb extension has not been properly initialized. sad girl hours 😭

---

🌸 DIAGNOSTICS 🌸

• BadAlloc — unable to allocate storage. out of room, no vibe 💀
• BadMatch — a compatible version of Xkb was not available in the server or an argument has correct type and range, but is otherwise invalid. right shape, wrong energy 🙈

---

🍓 SEE ALSO 🍓

• XkbChangeEnabledControls(3)
• XkbFreeControls(3)

go read them, they're the supporting cast 💅

---

ok that's the whole page, you ate that 💖 no notes.

---

mwah 💋 this has been X Version 11, libX11 1.8.14, XkbSetControls(3) — catch you in the next manpage bestie 🌈✨🎀