Re: [AD] Mouse cusor documentation

[Elias Pschernig <elias@xxxxxxxxxx>]

On Sun, 2004-10-03 at 15:27 +0200, Evert Glebbeek wrote:
> On Sunday 03 October 2004 15:08, Elias Pschernig wrote:
> > Why do you have to call show_mouse() for the gfx_capabilities flag to
> > get updated?
> 
> Because gfx_capabilities is only updated after show_mouse() has been 
> called. You don't know if you have a hardware cursor or not until after 
> show_mouse() has been called. It's always been this way.
> Also, note that you can't check for the precense of relevant entries in teh 
> vtable to set gfx_capabilities once and for all: in Windows, you will only 
> be able to get a hardware cursor for cursors upto 32x32 pixels, not above. 
> So setting it always is unreliable.
> 
> > After all, you could already have called show_mouse()
> > before.
> 
> After having called show_mouse, gfx_capbilities reflects wether or not a 
> hardware mouse cursor is in use right now.
> 

Well, the docs aren't clear. Will this work?

show_mouse (screen);
enable_hardware_cursor ();
if (gfx_capabilities & GFX_HW_CURSOR) ...

Currently, I read the docs so it should work. If you specifically need
to call "show_mouse (screen)" *after* having called
enable_hardware_cursor, then it should be stated in the docs (I didn't
check, so I don't know..). I'd actually like the above to work though -
it fits better into how my idea of the complete mouse API looks like.

> 
> > And I still think "show_mouse(my_bitmap)" should always disable the
> > hardware cursor, else we break old programs.
> 
> No, we don't. Allegro uses a software cursor automatically if it can't let 
> the OS draw the cursor. No need to disable the hardware cursor for that.
> 

Ah, ok. So only if you pass screen to show_mouse it will use a hardware
cursor, is this true? If yes, I think it is a good idea to mention it in
the docs. (And again, I don't like the idea of special casing screen,
and would like this to be changed.)

> > Only show_mouse(screen)
> > might allow it - but I'd prefer the API pointed out in that other
> > thread, where only enable_hardware_cursor() can show the hardware
> > cursor, and show_mouse() always draws a software cursor.
> 
> I'm not sure... I think this could be considered an API breakage. Anyway, 
> with the new system and custom cursors, the code needs to be somewhat 
> rethought anyway.
> 

Yeah, we'll eventually sort everything out in that other thread :)

> > (This isn't relevant for 4.1.16 - maybe just add a note that the
> > hardware cursor functions aren't finalized yet and likely to change in
> > 4.1.17).
> 
> I don't think this will (should) affect how things work now: for custom 
> cursors, I don't think there is a real difference in behavior between 
> 4.1.16 and 4.1.17.
> 

Well, the points above show that there is some variation possibility -
so better warn users that if they use enable_hardware_cursor now in some
special circumstanes this might break once the complete hardware/system
cursor API is finalized.

-- 
Elias Pschernig