XkbKeyActionsPtr(3)

✨ XkbKeyActionsPtr(3) — XKB FUNCTIONS ✨

okay so this page is from XKB FUNCTIONS, and today’s main character is XkbKeyActionsPtr. Buckle up, bestie 💖

💅 NAME 💅

XkbKeyActionsPtr — returns a pointer to the two-dimensional array of key actions associated with the key corresponding to keycode. That’s the whole name-section vibe 🎀

🦋 SYNOPSIS 🦋

       XkbKeyActionPtr XkbKeyActionsPtr (XkbDescPtr xkb, KeyCode keycode);

(yes, the return type in the synopsis is XkbKeyActionPtr while the function is XkbKeyActionsPtr — copy it exactly, iykyk 🙈)

🌸 ARGUMENTS 🌸

• xkb — the Xkb description of interest, aka the struct you’re poking at.
• keycode — the keycode of interest. The specific key’s little ID number.

🧚 DESCRIPTION 🧚

A key action defines what effect key presses and releases have on the internal state of the server. For example, the expected key action for pressing the Shift key is to set the Shift modifier. Every keysym bound to every key has zero or one key action tied to it. That’s the rule 💫

Think of the keyboard mapping’s whole key-symbol list living in the syms field of the client map — same energy for key actions: the whole list lives in the acts array of the server map. size_acts tells you the total size of acts, and num_acts tells you how many entries it has 🦋

The key_acts array is indexed by keycode and describes the actions associated with a key. It has min_key_code unused entries at the start so you can index it directly with a keycode. A key_acts entry of zero means that key has no actions associated with it. A nonzero entry is an index into the acts field of the server map — kinda like how the offset field of a KeySymMapRec structure is an index into the syms field of the client map ✨

So why is acts a linear list of XkbActions? Memory consumption, periodt. Xkb lets individual keys have multiple shift levels and a different number of groups per key, so one single two-dimensional array of KeySyms could potentially be very large and sparse. Instead, Xkb provides a small two-dimensional array of XkbActions for each key. To store all those individual arrays, Xkb concatenates each array together in the acts field of the server map. It’s giving efficient storage 💅

The key action structures are made only of fields of type char or unsigned char. Why? To optimize data transfer when the server sends bytes over the wire. If the fields were anything but bytes, the server would have to sift through all the actions and swap any nonbyte fields. Because they consist of nothing but bytes, it can just copy them out. No cap, that’s the whole trick 👑

XkbKeyActionsPtr returns a pointer to the two-dimensional array of key actions associated with the key corresponding to keycode. Use XkbKeyActionsPtr only if the key actually has some actions associated with it — that is, if XkbKeyNumActions (xkb, keycode) returns something greater than zero. Otherwise the page says don’t use it, bestie, and we listen 😭

🎀 STRUCTURES 🎀

The KeySymMapRec structure is defined as follows:

           #define XkbNumKbdGroups             4
           #define XkbMaxKbdGroup              (XkbNumKbdGroups-1)

           typedef struct {                    /* map to keysyms for a single keycode */
               unsigned char       kt_index[XkbNumKbdGroups];  /* key type index for each group */
               unsigned char       group_info; /* # of groups and out of range group handling */
               unsigned char       width;      /* max # of shift levels for key */
               unsigned short      offset;     /* index to keysym table in syms array */
       } XkbSymMapRec, *XkbSymMapPtr;

🌈 SEE ALSO 🌈

• XkbKeyNumActions(3) — go check it out, it’s the vibe check for whether you even have actions to point at 🫶

---

okay that’s the page! Signed off with X Version 11, libX11 1.8.14 — and the footer’s date slot is literally empty in the original, so no date shown, no cap 😭💅🫶