| Re: [AD] Using system mouse cursor |
[ Thread Index |
Date Index
| More lists.liballeg.org/allegro-developers Archives
]
On 2004-09-25, Evert Glebbeek <eglebbk@xxxxxxxxxx> wrote:
> 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...
First one attached. However, I'm not happy with the ending sentence
of the first paragraph, because in interrupt driven platforms the
user doesn't make calls unless he wishes too. So no good saying
"...since the last call". Call, to what?
Index: docs/src/allegro._tx
===================================================================
RCS file: /cvsroot/alleg/allegro/docs/src/allegro._tx,v
retrieving revision 1.260
diff -u -r1.260 allegro._tx
--- docs/src/allegro._tx 26 Sep 2004 21:05:55 -0000 1.260
+++ docs/src/allegro._tx 26 Sep 2004 21:07:41 -0000
@@ -2142,6 +2142,38 @@
@heading
Mouse routines
+Allegro provides functions for reading the mouse state and displaying a mouse
+cursor on-screen. You can read from global variables the absolute position of
+the mouse and the state of the mouse buttons. Additionally, you can read the
+mouse position difference as mouse mickeys, which is the number of pixels the
+cursor moved since the 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. In such cases 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 this mode.
+</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
@@ -2189,6 +2221,62 @@
@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;
@@ -2227,7 +2315,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
@@ -9384,6 +9472,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
@@ -9707,6 +9798,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
@@ -9714,6 +9809,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