Re: [AD] Using system mouse cursor

[Evert Glebbeek <eglebbk@xxxxxxxxxx>]

On Saturday 25 September 2004 15:22, Evert Glebbeek wrote:
> Docs to follow.

Attached. This includes the documentation for all new mouse functions I 
have created by now, as well as a bit of general information at the start 
of the Mouse routines section. This will probably need a few iterations 
before it satisfies everyone though...

Evert

--- allegro/docs/src/allegro._tx	2004-09-25 13:51:25.000000000 +0200
+++ alleg_work/docs/src/allegro._tx	2004-09-25 16:56:56.000000000 +0200
@@ -2139,6 +2139,38 @@
 @heading
 Mouse routines
 
+Allegro provides functions for reading the mouse state and displaying a mouse
+cursor on-screen. Typically, you can read the x and y positions of the mouse
+cursor and which buttons are pressed down. In addition, you can also read the
+mouse mickeys (number of pixels moved since last call).
+
+Allegro offers three ways to display the mouse cursor:
+<ul>
+<li>
+Standard Allegro cursor<br>
+   Allegro is responsible for drawing the mouse cursor. Use set_mouse_sprite()
+   and show_mouse() to define your own cursor and display it on the screen.
+   You need to call scare_mouse()/unscare_mouse() to hide the mouse cursor 
+   whenever you draw to the screen.
+<li>
+Custom operating system cursor (hardware cursor)<br>
+   Allegro will let the operating system draw the mouse cursor. Use
+   set_mouse_sprite() and show_mouse() to define your own cursor and display
+   it on the screen. Not all graphics drivers are capable of this and some
+   may only be able to display cursors upto a certain size. Allegro will fall
+   back on its own cursor drawing if it cannot let the OS handle this.
+   On some platforms, the hardware cursor is incompatible with 
+   get_mouse_mickeys() and it is therefor disabled by default. You need to call
+   enable_hardware_cursor() to enable it explicitly.
+<li>
+Default operating system cursor<br>
+   Allegro will not draw its own cursor, but use the operating system default
+   cursor. Once you have enabled this mode, calls to show_mouse() are ignored
+   until you disable it again.
+</ul>
+Not all drivers will support all functionality. See the platform specific
+information for more details.
+
 @@int @install_mouse();
 @xref remove_mouse, poll_mouse, mouse_x, show_mouse, get_mouse_mickeys
 @xref position_mouse, set_mouse_range, set_mouse_speed
@@ -2186,6 +2218,63 @@
 @xref poll_mouse, install_mouse, mouse_x
    Returns TRUE if the current mouse driver is operating in polling mode.
 
+@@void @enable_hardware_cursor(void);
+@xref install_mouse, show_mouse, set_mouse_sprite, get_mouse_mickeys, gfx_capabilities, disable_hardware_cursor
+   After calling this function, Allegro will let the operating system draw the
+   mouse cursor instead of doing it itself. This is not possible with all
+   graphics drivers though: you'll need to check the gfx_capabilities flags
+   after calling show_mouse() to see if this works. On some platforms, enabling
+   the hardware cursor causes get_mouse_mickeys() to return only a limited
+   range of values, so you should not call this function if you need mouse 
+   mickeys.
+
+@@void @disable_hardware_cursor(void);
+@xref install_mouse, show_mouse, set_mouse_sprite, get_mouse_mickeys, gfx_capabilities, enable_hardware_cursor
+   After calling this function, Allegro will be responsible for drawing the
+   mouse cursor rather than the operating system. On some platforms calling
+   enable_hardware_cursor() makes teh return values of get_mouse_mickeys()
+   unreliable. After calling this function, get_mouse_mickeys() returns 
+   reliable results again.
+
+@@int @select_os_cursor(int cursor));
+@xref install_mouse, show_mouse
+   On platforms where this makes sense this will use the operating system
+   native mouse cursor rather than a cursor drawn by Allegro. You cannot
+   draw both at the same time: show_mouse() will do nothing after a succesful 
+   call to this function. Conversely, using show_mouse() to draw the mouse
+   will make select_os_cursor() do nothing.
+   
+   The cursor argument selects the type of pointer you want to display:
+   
+   <b>MOUSE_OS_NONE</b><br>
+   Disables (hides) the operating system cursor. You can use show_mouse() again
+   to draw your own cursor after passing this argument.
+   
+   <b>MOUSE_OS_ARROW</b><br>
+   Selects the standard arrow cursor.
+   
+   <b>MOUSE_OS_BUSY</b><br>
+   Selects the standard busy cursor (hourglass).
+   
+   <b>MOUSE_OS_QUESTION</b><br>
+   Selects the standard question cursor (arrow with question mark).
+   
+   You can use this function very easily to display the operating system
+   cursor if it is available, or fall back to Allegro's cursor if it is not:
+<codeblock>
+   if (!select_os_cursor(MOUSE_OS_ARROW))
+      set_mouse_sprite(my_cursor);
+   show_mouse(screen);
+<endblock>
+   If select_os_cursor() succeeded, set_mouse_sprite() is not called and 
+   show_mouse() does nothing. If it failed, set_mouse_sprite() is called and
+   show_mouse() will draw the Allegro cursor.
+
+@retval
+   Returns non-zero if the OS cursor is displayed after a call to this
+   function, or zero if not. This is usually a sign that something went wrong,
+   but note that select_os_cursor(MOUSE_OS_NONE) always returns zero.
+
 @@extern volatile int @mouse_x;
 @@extern volatile int @mouse_y;
 @@extern volatile int @mouse_z;
@@ -2224,7 +2313,7 @@
    set_mouse_sprite() and set_mouse_sprite_focus() functions.
 
 @@void @show_mouse(BITMAP *bmp);
-@domain.hid install_mouse, install_timer, set_mouse_sprite, scare_mouse
+@xref install_mouse, install_timer, set_mouse_sprite, select_os_cursor, scare_mouse
 @xref freeze_mouse_flag
 @eref exmouse, exshade, exspline
    Tells Allegro to display a mouse pointer on the screen. This will only 
@@ -9227,6 +9316,9 @@
 <endblock>
       Note that, mainly for performance reasons, this driver requires the
       width of the screen to be a multiple of 4.
+      This driver is capable of displaying a hardware cursor, but there are
+      size restrictions. Typically, the cursor image cannot be more than
+      32x32 pixels.
 <li>
    GFX_DIRECTX_OVL<br>
       The DirectX overlay driver. It uses special hardware features to run 
@@ -9549,6 +9641,10 @@
    GFX_XWINDOWS<br>
       The standard X graphics driver. This should work on any Unix system, 
       and can operate remotely. It does not require root permissions.
+      If the ARGB cursor extension is available, this driver is capable
+      of displaying a hardware cursor. This needs to be enabled by calling
+      enable_hardware_cursor() becaue it cannot be used reliably alongside
+      get_mouse_mickeys().
 <li>
    GFX_XWINDOWS_FULLSCREEN<br>
       The same as above, but while GFX_XWINDOWS runs windowed, this one uses
@@ -9556,6 +9652,10 @@
       without root permissions. You're still using the standard X protocol
       though, so expect the same low performances as with the windowed
       driver version.
+      If the ARGB cursor extension is available, this driver is capable
+      of displaying a hardware cursor. This needs to be enabled by calling
+      enable_hardware_cursor() becaue it cannot be used reliably alongside
+      get_mouse_mickeys().
 <li>
    GFX_XDGA2<br>
       Use new DGA 2.0 extension provided by XFree86 4.0.x. This will work