show_os_cursor(3alleg4)

💅 show_os_cursor — the Allegro manual's little low-level cursor bestie ✨

okay so you're reading the page for show_os_cursor(3alleg4) from the Allegro manual (that's the Allegro game programming library, in case you were wondering 🎀). She's a low level function whose whole job is displaying the operating system cursor. no frills, no drama, just vibes.

✨ SYNOPSIS ✨

#include <allegro.h>

int show_os_cursor(int cursor);

like. that's it. that's the whole signature. she's simple. 💖

🦋 DESCRIPTION 🦋

So here's the tea, bestie: Allegro has its own whole mouse cursor API, and that API will automatically emulate a cursor in software if there's no other cursor available. Cute of her honestly. But if you don't need all that, you can reach for this low level function instead and just try to display or hide the system cursor directly.

The cursor parameter takes the same values as select_mouse_cursor. so same menu, same options, no new vocabulary to learn, we love a consistent API. 🫶

It's very similar to calling enable_hardware_cursor, select_mouse_cursor and show_mouse — except here's the difference, and it's a big one: this function will not try to do anything if no system cursor is available. no fallback, no pretending, no software emulation standing in. it just... doesn't. 💀

The most common use for this function is genuinely just calling it once at the beginning of your program to tell it to display the system cursor inside the Allegro window. that's the whole moment. and you can check the return value to see if it actually succeeded or not. 🌸

now the part where she gets real with you: on some systems (e.g. DirectX fullscreen) this is not supported and the function will always fail. and 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. so like. manage your expectations accordingly. 😭

And listen, this is important, so I'm saying it loud:

You never should 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 don't work together with this low level function. pick a lane, bestie. you cannot serve two mouse APIs. 🙈

👑 RETURN VALUE 👑

• Returns 0 if a system cursor is being displayed after the function returns ✨
• Returns -1 otherwise 💀

that's it. zero or negative one. binary queen. 💅

🌈 SEE ALSO 🌈

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

and that's the whole page, no cap 💜 this was written by Allegro, version 4.4.3, and yes she's still out here in show_os_cursor(3alleg4) form, iconic, never changed, never will. go display a cursor. or don't. but don't mix it with show_mouse. mwah 🎀