install_keyboard(3alleg4)

✨ install_keyboard ✨

okay so bestie, we're diving into the Allegro manual today and this one is literally the glow-up your keyboard needs 💖 it's install_keyboard, and no cap, it's kind of a big deal.

🌸 NAME 🌸

install_keyboard — installs the Allegro keyboard interrupt handler. that's it. that's the whole job. iconic behaviour honestly 👑

🎀 SYNOPSIS 🎀

#include <allegro.h>

int install_keyboard();

💅 DESCRIPTION 💅

So. install_keyboard installs the Allegro keyboard interrupt handler. You must call this before using any of the keyboard input routines. like, before. don't skip it, don't "do it later", it's giving prerequisites and we respect the prerequisites 🫶

And once you've set up the Allegro handler? yeah, that's it — you can no longer use operating system calls or C library functions to access the keyboard. it's Allegro's keyboard now. you handed over the aux cord, no takebacks 💀

⚠️ also, heads up: on some platforms the keyboard won't work unless you've set a graphics mode, even if this function returns a success value before you call set_gfx_mode. lowkey sneaky of it. this can happen in environments with graphic windowed modes, because Allegro usually reads the keyboard through the graphical window — which only shows up after the set_gfx_mode call. so the success return is not the whole story, bestie 😭

Example, so you can see the vibe:

allegro_init();
install_timer();
install_keyboard();
/* We are not 100% sure we can read the keyboard yet! */
if (set_gfx_mode(GFX_AUTODETECT, 640, 480, 0, 0) != 0)
   abort_on_error("Couldn't set graphic mode!");

/* Now we are guaranteed to be able to read the keyboard. */
readkey();

see how install_keyboard() comes before set_gfx_mode? and see how the comment says you're not 100% sure yet? then after set_gfx_mode succeeds, now you're guaranteed. slay. that's the whole arc 🌈

⭐ RETURN VALUE ⭐

Returns zero on success, or a negative number on failure. but ngl, you may decide not to check the return value, because this function is very unlikely to fail. it's the low-maintenance friend of the Allegro API 💖

🦋 SEE ALSO 🦋

• remove_keyboard(3alleg4)
• poll_keyboard(3alleg4)
• key(3alleg4)
• keypressed(3alleg4)
• readkey(3alleg4)
• ureadkey(3alleg4)
• keyboard_callback(3alleg4)
• keyboard_ucallback(3alleg4)
• keyboard_lowlevel_callback(3alleg4)
• three_finger_flag(3alleg4)
• key_led_flag(3alleg4)
• set_leds(3alleg4)
• set_keyboard_rate(3alleg4)
• set_gfx_mode(3alleg4)

go read those too, they're all part of the same keyboard cinematic universe 🎬✨

and that's the tea, bestie 💜 this page came to you straight from the Allegro manual, version 4.4.3 — install_keyboard(3alleg4), periodt. now go call it before you touch a single key 🎀💖