show_os_cursor(3)

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

okay bestie so this is a page from the Allegro manual (yes, the game programming library, the icon itself ✨), and today we're talking about show_os_cursor, a low level function that just… displays the operating system cursor. that's it. that's the whole job. 💅

---

✨ NAME ✨

show_os_cursor — a low level function to display the operating system cursor, from the Allegro game programming library 🎀

---

🦋 SYNOPSIS 🦋

#include <allegro.h>

int show_os_cursor(int cursor);

---

💅 DESCRIPTION 💅

so here's the tea: Allegro has its own mouse cursor API, and that API is so extra — it will automatically emulate a cursor in software if no other cursor is available. cute, right? but maybe you don't need all that. maybe you're built different. in that case, you can use this low level function to try to display or hide the system cursor directly. no middleman, no vibes, just you and the OS. 🫶

the cursor parameter takes the same values as select_mouse_cursor. and honestly? this function is very similar to calling enable_hardware_cursor, select_mouse_cursor and show_mouse — except for one major thing: it will not try to do anything if no system cursor is available. it's giving "no cursor? okay, not my problem." 💀

the most common use for this function is to just call it once at the beginning of the program, to tell it to display the system cursor inside the Allegro window. main character energy, honestly. ✨

the return value can be used to see if this succeeded or not. and here's where it gets a lil humbling:

• on some systems (e.g. DirectX fullscreen) this is not supported and the function will always fail 😭
• in other cases, only some of the cursors will work
• or, in the case of MOUSE_CURSOR_ALLEGRO, only certain bitmap sizes may be supported 🙈

⚠️ NEVER use show_os_cursor together with the function show_mouse and other functions affecting it (select_mouse_cursor, enable_hardware_cursor, disable_hardware_cursor, scare_mouse, unscare_mouse). those implement the standard high level mouse API, and they do not work together with this low level function. it's giving two girlies fighting over one aux cord. it will not end well. 🚫

---

👑 RETURN VALUE 👑

• returns 0 if a system cursor is being displayed after the function returns ✅
• or -1 otherwise ❌

that's it. two outcomes. very binary of it. 💅

---

🌈 SEE ALSO 🌈

• show_mouse(3)
• set_mouse_cursor_bitmap(3)
• select_mouse_cursor(3)

---

and that's the whole page, bestie! this one comes to you courtesy of Allegro, version 4.4.3 🎀 go forth and cursor responsibly, ily, mwah 💖🌸