| Re: [AD] Using system mouse cursor |
[ Thread Index |
Date Index
| More lists.liballeg.org/allegro-developers Archives
]
On Sunday 26 September 2004 23:10, Grzegorz Adam Hankiewicz wrote:
> 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?
Ok, slightly reworked patch attached. It doesn't change much from your
version, although I have taken the liberty of adding a little bit of
information and an example to some other sections of the mouse docs.
Evert
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 27 Sep 2004 17:14:11 -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 the absolute position of the mouse and the
+state of the mouse buttons from global variables. Additionally, you can read
+the mouse position difference as mouse mickeys, which is the number of pixels
+the cursor moved since the last time this information was read.
+
+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 the 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;
@@ -2212,11 +2300,19 @@
if (!(mouse_b & 2))
printf("Right button is not pressed\n");
<endblock>
- The `mouse_pos' variable has the current X coordinate in the high word and
- the Y in the low word. This may be useful in tight polling loops where a
- mouse interrupt could occur between your reading of the two separate
+ The `mouse_pos' variable has the current X coordinate in the upper 16 bits
+ and the Y in the lower 16 bits. This may be useful in tight polling loops
+ where a mouse interrupt could occur between your reading of the two separate
variables, since you can copy this value into a local variable with a
- single instruction and then split it up at your leisure.
+ single instruction and then split it up at your leisure. Example:
+<codeblock>
+ int pos, x, y;
+
+ pos = mouse_pos;
+ x = pos >> 16;
+ y = pos & 0x0000ffff;
+<endblock>
+
@@extern BITMAP *@mouse_sprite;
@@extern int @mouse_x_focus;
@@ -2227,7 +2323,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
@@ -2249,7 +2345,7 @@
will temporarily get rid of the pointer, but only if that is really
required (ie. the mouse is visible, and is displayed on the physical
screen rather than some other memory surface, and it is not a hardware
- cursor). The previous mouse state is stored for subsequent calls to
+ or OS cursor). The previous mouse state is stored for subsequent calls to
unscare_mouse().
@@void @scare_mouse_area(int x, int y, int w, int h);
@@ -9384,6 +9480,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 +9806,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 +9817,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