keyboard_ucallback(3alleg4)

💖 keyboard_ucallback — the Allegro manual, but make it make sense 💖

okay so bestie, we're in the Allegro manual today and the page is literally called keyboard_ucallback(3alleg4). yes, the whole (3alleg4) thing is part of the name, it's giving "library function, section 3, Allegro 4" energy. periodt. 💅

✨ NAME ✨

keyboard_ucallback — your very own user-specified unicode keyboard callback handler. it lives in the Allegro game programming library, which is iconic of it. 👑

🌸 SYNOPSIS 🌸

#include <allegro.h>

extern int (*keyboard_ucallback)(int key, int *scancode);

🦋 DESCRIPTION 🦋

so this is the unicode-aware version of keyboard_callback(). glow up achieved. ✨

if you set this function, the keyboard handler calls it in response to every single keypress. not some. every. 🫶

here's the tea on what it gets handed and what it hands back:

• it's passed the character value and the scancode that are about to be added into the input buffer
• it can modify the scancode value (yes, you get to reach in and change it, main character behavior fr fr)
• it returns a new or modified key code

and here's the sneaky little trick: if it both sets the scancode to zero AND returns zero, then that keypress gets ignored entirely. poof. gone. not in the buffer. 🚫

⚠️ okay huge important thing, no cap: this routine executes in an interrupt context, so it must be in locked memory. do not skip this. it is not a vibe. it is a requirement. 😭

example, bestie:

int silence_g_key(int key, int *scancode)
{
   if (key == 'g') {
      *scancode = 0;
      return 0;
   }
   return key;
} END_OF_FUNCTION(silence_g_key)

...

   install_timer();
   LOCK_FUNCTION(silence_g_key);
   install_keyboard();
   keyboard_ucallback = silence_g_key;

see how that one just straight-up silences the letter g? living its truth. 🍓

💀 one more thing, and this one bites people: this keyboard callback has priority over the non-unicode callback. if you set both of them, only the unicode one will work. the other one is just sitting there, uninvited, at a party it wasn't invited to. 🙈

👑 SEE ALSO 👑

• install_keyboard(3alleg4)
• readkey(3alleg4)
• ureadkey(3alleg4)
• keyboard_callback(3alleg4)
• keyboard_lowlevel_callback(3alleg4)

and that's the whole page, bestie! this one's from Allegro, version 4.4.3, and it's the keyboard_ucallback(3alleg4) page of the Allegro manual. go forth and lock your functions. iykyk. 💜🦋✨