XkbGetKeyExplicitComponents(3)

💖 NAME 💖

ok so XkbGetKeyExplicitComponents — bestie, it grabs the explicit components (that's the explicit array, iykyk) for a subset of the keys in a keyboard description. It's the section 3 (library function) girlie from the XKB function crew. 💅

---

✨ SYNOPSIS ✨

Status XkbGetKeyExplicitComponents (Display *dpy, unsigned int first,
       unsigned int num, XkbDescPtr xkb);

---

🌸 ARGUMENTS 🌸

• dpy — the connection to the server, your lil phone line to the X server basically 📞
• first — keycode of the first key to fetch
• num — how many keys you want explicit info for
• xkb — the Xkb description where the results get dropped off

---

🦋 DESCRIPTION 🦋

ok so picture this: whenever a client remaps the keyboard using core protocol requests, Xkb looks at the map and figures out likely default values for the components that the core protocol literally cannot specify. (More on how Xkb picks those defaults lives in "Core Keyboard Mapping to Xkb Keyboard Mapping Transformation" — go read that if you're nosy.)

⚠️ real talk: the original manpage itself has a big ol' note right here that reads: DO THE FOUR PAGES OF "CORE KEYBOARD MAPPING TO XKB KEYBOARD MAPPING TRANSFORMATION" NEED TO BE ADDED HERE? — yes bestie, that question is in the manpage. we leave it exactly as it is. no cap. 💀

So this automatic remapping? It might just replace definitions that an application explicitly asked for. Rude. Which is why the Xkb keyboard description defines an explicit components mask for each key. Anything listed in a key's explicit components mask does not get changed by the automatic keyboard mapping. Protection. Boundaries. Self-care. 🫶

These explicit component masks live in the explicit field of the server map, which is an array indexed by keycode. Each entry is a mask that's a bitwise inclusive OR of the values in Table 1:

⭐ Table 1 — Explicit Component Masks ⭐

• ExplicitKeyType1 — (1<<0) — protects against automatic determination of the key type associated with Group1.
• ExplicitKeyType2 — (1<<1) — protects against automatic determination of the key type associated with Group2.
• ExplicitKeyType3 — (1<<2) — protects against automatic determination of the key type associated with Group3.
• ExplicitKeyType4 — (1<<3) — protects against automatic determination of the key type associated with Group4.
• ExplicitInterpret — (1<<4) — protects against application of any of the fields of a symbol interpretation to the key in question.
• ExplicitAutoRepeat — (1<<5) — protects against automatic determination of auto-repeat status for the key, as specified in a symbol interpretation.
• ExplicitBehavior — (1<<6) — protects against automatic assignment of the XkbKB_Lock behavior to the key, if the XkbSI_LockingKey flag is set in a symbol interpretation.
• ExplicitVModMap — (1<<7) — protects against automatic determination of the virtual modifier map for the key based on the actions assigned to the key and the symbol interpretations that match the key.

---

Now the actual function, periodt: XkbGetKeyExplicitComponents sends a request to the server to get the explicit components for num keys on the keyboard, starting at key first. Then it waits for a reply (she's patient, she's committed ✨) and returns the explicit components in the server->explicit array of xkb. If it works out, XkbGetKeyExplicitComponents returns Success. And xkb must be a pointer to a valid Xkb keyboard description — no fake ones, bestie.

If the server map inside xkb hasn't been allocated yet? No worries — XkbGetKeyExplicitComponents allocates and initializes it before obtaining the actions. Iconic behavior honestly. 👑

But watch out, the drama is real:

• If the server doesn't have a compatible version of Xkb, or the Xkb extension hasn't been properly initialized, XkbGetKeyExplicitComponents returns BadMatch.
• If num is less than 1 or greater than XkbMaxKeyCount, XkbGetKeyExplicitComponents returns BadValue.
• If any allocation errors happen, XkbGetKeyExplicitComponents returns BadAlloc.

---

💀 DIAGNOSTICS 💀

• BadAlloc — unable to allocate storage. she's out of room, no space left in the group chat 😭
• BadMatch — a compatible version of Xkb was not available in the server, or an argument has correct type and range, but is otherwise invalid.
• BadValue — an argument is out of range. out of pocket, out of range, same energy fr fr.

---

🌈 SIGN-OFF 🌈

that's the whole page bestie, go protect those explicit components 💖 from the X v11 Rel. 6.4 era, dated 20 Jul 1999, and yes this lil love letter is filed under XkbGetKeyExplicitComponents(3) — mwah, slay, bye! 🎀🦋✨