XkbVirtualModsToReal(3)

✨ XkbVirtualModsToReal ✨

Okay bestie, buckle up, because we're diving into XkbVirtualModsToReal(3) from the XKB FUNCTIONS crew 💅 this is the little function that figures out how virtual modifiers map onto real, core-X-protocol modifiers. Sounds fake but it's real, fr fr.

---

🌸 NAME 🌸

XkbVirtualModsToReal — determines the mapping of virtual modifiers to core X protocol modifiers ✨

---

🎀 SYNOPSIS 🎀

Bool XkbVirtualModsToReal (XkbDescPtr xkb, unsigned int virtual_mask,
       unsigned int *mask_rtrn);

---

🦋 ARGUMENTS 🦋

• xkb — the keyboard description for the input device 🎹
• virtual_mask — the virtual modifier mask you want translated, mwah 💋
• mask_rtrn — gets backfilled with the real modifiers, slay 💫

---

💖 DESCRIPTION 💖

So Xkb keeps a virtual modifier mapping, and what that does is list the virtual modifiers that are associated with — or bound to — each key. The way this works: the real modifiers bound to a virtual modifier always include all of the modifiers bound to any of the keys that specify that virtual modifier in their virtual modifier mapping. Periodt. 💅

The server.vmodmap array tells you which virtual modifiers are bound to each key; every entry in it is a bitmask for the virtual modifier bits. And server.vmodmap is indexed by keycode, iykyk. 🔑

Now, the vmodmap and vmods members of the server map? Those are the "master" virtual modifier definitions, the main character energy of the whole thing 👑 Xkb automatically propagates any changes to these fields out to all the other fields that use virtual modifier mappings. No manual syncing needed, we love that for us. ✨

Example time, because I know you want one 🍓 Say Mod3 is bound to the Num_Lock key by the core protocol modifier mapping, and the NumLock virtual modifier is bound to the Num_Lock key by the virtual modifier mapping — then Mod3 gets added to the set of modifiers associated with NumLock. Cute, right? 🎀

The virtual modifier mapping normally gets updated whenever actions are automatically applied to symbols, so honestly very few applications should ever need to change the virtual modifier mapping explicitly. Leave it to the server, bestie 🙈

Wanna pull the virtual modifiers off the server? Use XkbGetMap ✨ Or use XkbGetVirtualMods to update a local copy of the virtual modifiers bindings from the server. And to set the binding of a virtual modifier to a real modifier, use XkbGetVirtualMods. (Yes, same function, that's what the page says, no cap 💀)

So here's the actual vibe check on the function itself 🫶 If the keyboard description defined by xkb includes bindings for virtual modifiers, XkbVirtualModsToReal uses those bindings to determine the set of real modifiers that correspond to the set of virtual modifiers specified in virtual_mask. And virtual_mask is a mask specifying the virtual modifiers to translate — the i-th bit (0 relative) of the mask represents the i-th virtual modifier. The way that bit math ate, honestly 🔥

If mask_rtrn is non-NULL, XkbVirtualModsToReal backfills it with the resulting real modifier mask 💫 If the keyboard description in xkb does not include virtual modifier bindings, XkbVirtualModsToReal returns False; otherwise, it returns True. That's it, that's the whole function 🧚

---

⭐ RETURN VALUES ⭐

• True — XkbVirtualModsToReal returns True if the keyboard description in xkb does include virtual modifier bindings ✅
• False — XkbVirtualModsToReal returns False if the keyboard description in xkb does not include virtual modifier bindings ❌

---

👑 SEE ALSO 👑

XkbGetMap(3), XkbGetVirtualMods(3) — go read those next, bestie 📚

---

🌈 NOTES 🌈

Heads up: it is totally possible for a local (client-side) keyboard description — that's the xkb parameter — to not contain any virtual modifier information, simply because the client hasn't requested it 🫠 Meanwhile the server's corresponding definition may absolutely contain virtual modifier information. So like, don't panic if your local copy is looking empty, it's giving "not my fault" energy 😭

---

That's the whole page, bestie, you ate that 🍓💜 This iconic little writeup came from X Version 11, libX11 1.8.14, and it's the XkbVirtualModsToReal(3) page — go forth and translate those virtual modifiers, mwah 💋✨