show_mouse(3)

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

okay bestie, we're in the show_mouse(3) page of the Allegro manual, and honestly? this one's a little diva. she's simple, she's iconic, but she has rules. let's get into it 🎀

---

✨ NAME ✨

show_mouse — tells Allegro to display a mouse pointer on the screen. that's it. that's her whole job. 💅

---

✨ SYNOPSIS ✨

#include <allegro.h>

void show_mouse(BITMAP *bmp);

look at her. one function. one parameter. no drama. (the drama is later, iykyk 😭)

---

✨ DESCRIPTION ✨

so show_mouse does exactly what it says on the tin, no cap: it tells Allegro to put a mouse pointer on the screen. 🖱️✨

but here's the catch, bestie — this will only work if the timer module has been installed. no timer, no pointer. that's the vibe check and you gotta pass it. ⏰

the pointer gets drawn onto the bitmap you hand it, which should normally be screen (there's more info about bitmaps later in the docs, don't worry babe, we'll get there). and when you want the pointer to ✨go away✨? you call show_mouse(NULL). poof. gone. lowkey elegant. 🫶

⚠️ WARNING, and i need you to actually read this one ⚠️ if you draw anything onto the screen while the pointer is visible, a mouse movement interrupt could happen in the middle of your drawing operation. and if that happens? the mouse buffering and graphics drawing code get confused and leave 'mouse droppings' all over the screen. 💀💀💀 MOUSE DROPPINGS. it's giving horror movie. to prevent this, you must make sure you turn off the mouse pointer whenever you draw onto the screen. that's not a suggestion, that's the law. small mercy tho: this is not needed if you're using a hardware cursor. 👑

📝 NOTE, also important 📝 you must not be showing a mouse pointer on a bitmap at the time that the bitmap is destroyed with destroy_bitmap(). like, ever. for real. so do this: c show_mouse(NULL); before you destroy the bitmap. turn her off first, then clean up. order matters, bestie. and guess what — this rule does not apply to screen, because you never destroy screen with destroy_bitmap(). screen is forever. main character energy only. 🌈⭐

---

✨ SEE ALSO ✨

go read these next, they're all in the group chat:

• install_mouse(3)
• install_timer(3)
• set_mouse_sprite(3)
• scare_mouse(3)
• freeze_mouse_flag(3)
• show_os_cursor(3)
• exmouse(3)
• expal(3)
• exshade(3)
• exspline(3)
• exsyscur(3)

---

okay that's the whole page, you're basically a mouse-pointer expert now, no cap 🎓💖

and for the cute sign-off: this gorgeous little document is from Allegro, version 4.4.3, and it's the show_mouse(3) page. mwah. 💋 periodt. 🌸🦋