Re: [AD] hardware cursors clarifications

[Evert Glebbeek <eglebbk@xxxxxxxxxx>]

On Sunday 13 March 2005 00:25, Peter Wang wrote:
> I'm trying to understand the hardware cursors API. 

Heh... sorry it's such a confusing mess...
This piece of code floating somewhere between the display driver and the 
mouse driver doesn't really help either.

> What's the intended relationship between set_mouse_sprite(bmp) and 
> set_mouse_sprite_bitmap(MOUSE_CURSOR_ALLEGRO, bmp)?

The MOUSE_CURSOR_ALLEGRO changes the BITMAP Allegro will display if it is 
drawing its own (`Allegro') cursor rather than a native system cursor.
set_mouse_sprite() changes the current mouse cursor to the bitmap passed to 
it. In that sense, it should be like setting the Allegro cursor using 
set_mouse_sprite_bitmap() and then switching to this with 
select_mouse_cursor().

> Is it even a good idea to use the latter?

Probably not. That said, I *think* it did work fine when I tested it, but 
it may have become broken since then.
But this API was mainly intended to provide a way to change Allegro's 
substitute cursors if no native cursor is available. That there is a way 
to the Allegro cursor as well this way is partly a side-effect of the 
implementation and partly born from the idea that set_mouse_sprite() could 
be made strictly identical to set_mouse_sprite_bitmap(CURSOR_ALLEGRO,bmp); 
select_mouse_cursor(CURSOR_ALLEGRO).

> How does set_mouse_sprite_bitmap() affect  
> mouse_sprite, mouse_x_focus, mouse_y_focus (if at all)?

It doesn't and shouldn't. It changes the bitmap Allegro will use when the 
current cursor is changed to a different type. It shouldn't affect the 
currently displayed cursor. For true system native cursors, changing the 
mouse_x_focus and mouse_y_focus is probably not a very good idea anyway 
(we shouldn't care either, since the OS should know how to handle its own 
cursors).

+   This function allows you to use the operating system's native mouse
+   cursors rather than some custom cursor. You will need to enable this
+   functionality by calling enable_hardware_cursor() beforehand. If the
+   operating system does not support this functionality, or if it has
+   not been enabled, then Allegro will substitute its own cursor images.
+   You can change these substitute images using set_mouse_cursor_bitmap().

Exactly.

+   Note that the effects of this function are not apparent until 
show_mouse()
+   is called.

Yes.

+   To know whether the operating system's native cursor is being used,
+   or if Allegro has made a substitution, you can check the 
GFX_SYSTEM_CURSOR
+   flag in gfx_capabilities after calling show_mouse().

Yes.

+   This function changes the cursor image Allegro uses if
+   select_mouse_cursor() is called but no native operating system cursor
+   can be used, e.g. because you did not call enable_hardware_cursor().
+
+   The cursor argument can be one of:<br>
+   <b>MOUSE_CURSOR_ALLEGRO</b><br>
+   <b>MOUSE_CURSOR_ARROW</b><br>
+   <b>MOUSE_CURSOR_BUSY</b><br>
+   <b>MOUSE_CURSOR_QUESTION</b><br>
+   <b>MOUSE_CURSOR_EDIT</b><br>
+
+   but <i>not</i> MOUSE_CURSOR_NONE.

Indeed!

+   The bmp argument can either point to a valid bitmap or it can be NULL.
+   Passing a bitmap makes Allegro use that image in place of its own
+   default substition (should the operating system's native cursor
+   be unavailable). The bitmap must remain available for the duration
+   in which it could be used. Passing NULL lets Allegro revert to its
+   default substitutions.
+
+   The effect of this function will not be apparent until show_mouse() is
+   called.

Yes.

Evert