poll_mouse(3alleg4)

👑 poll_mouse — the mouse-vibes-check function 💖

okay bestie, so we're deep in the Allegro manual (the 3alleg4 edition, obvs) and today's main character is poll_mouse. she's a little function with big responsibilities. let's get into it 🫶

✨ SYNOPSIS ✨

like, the formal entrance:

#include <allegro.h>

int poll_mouse();

that's it. that's the whole signature. she's lowkey simple but she carries the whole mouse state on some platforms. no cap. 💅

🌸 DESCRIPTION 🌸

so here's the tea, bestie 🍓

Allegro will read your mouse input asynchronously whenever it possibly can — like, literally from inside an interrupt handler, she's doing the most in the background so you don't have to think about it. iconic behaviour honestly.

but — and this is the plot twist 😭 — on some platforms that asynchronous thing just isn't possible. and in those cases you, yes you, must call this routine at regular intervals to update the mouse state variables. it's giving "the mouse isn't gonna update herself, bestie."

and here's the part that's actually kind of devious of Allegro, ngl: to help you test your mouse polling code even if you're programming on a platform that doesn't require it — after the first time that you call this function, Allegro will switch into polling mode. so from that point onwards you will have to call this routine in order to get any mouse input at all, regardless of whether the current driver actually needs to be polled or not.

⚠️ read that again bestie. one (1) call and you're committed. it's a situationship you can't get out of. from then on, no poll_mouse(), no mouse. periodt. 💀

🎀 RETURN VALUE 🎀

• returns zero on success 🥳
• returns a negative number on failure — ie. no mouse driver installed 😭

so yeah, vibe check the return value, fr fr. don't just ignore it and then wonder why your cursor is ghosting you.

🦋 SEE ALSO 🦋

the whole friend group, go say hi:

• mouse_needs_poll(3alleg4)
• install_mouse(3alleg4)
• mouse_x(3alleg4)
• exlights(3alleg4)
• exmouse(3alleg4)
• exshade(3alleg4)
• exspline(3alleg4)
• extrans(3alleg4)

and that's the page!! this was brought to you by the Allegro girlies, version 4.4.3, and this little poll_mouse(3alleg4) moment happened back in the day — go call your mouse, bestie, she's waiting 💜✨🎀