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:
-
Standard Allegro cursor
Allegro is responsible for drawing the mouse cursor from a timer. 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.
-
Custom operating system cursor (hardware cursor)
Allegro will let the operating system draw the mouse cursor. Use
set_mouse_sprite() and show_mouse() (or show_os_cursor) 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 up to 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.
-
Default operating system cursor
Allegro will not draw its own cursor, but use the operating system default
cursor. You can use the select_mouse_cursor() function to select the cursor
shape to display. As with custom operating system cursors, you need to call
enable_hardware_cursor() before you can use this. Or you can use the
low level show_os_cursor() function.
Not all drivers will support all functionality. See the platform specific
information for more details.
Installs the Allegro mouse handler. You must do this before using any
other mouse functions.
Return value:
Returns -1 on failure, zero if the mouse handler is already installed (in
which case this function does nothing) and the number of buttons on the
mouse if the mouse handler has successfully been installed (ie. this is
the first time a handler is installed or you have removed the previous
one).
Note that the number of mouse buttons returned by this function is more
an indication than a physical reality. With most devices there is no way
of telling how many buttons there are, and any user can override the
number of mouse buttons returned by this function with a custom
configuration file and the variable num_buttons. Even if this value is
overridden by the user, the global mouse variables will still report
whatever the hardware is sending.
See also:
remove_mouse,
poll_mouse,
mouse_x,
show_mouse,
get_mouse_mickeys,
position_mouse,
set_mouse_range,
set_mouse_speed,
Standard config variables.
Examples using this:
Available Allegro examples.
Removes the mouse handler. You don't normally need to bother calling
this, because allegro_exit() will do it for you.
See also:
install_mouse,
allegro_exit.
Wherever possible, Allegro will read the mouse input asynchronously (ie.
from inside an interrupt handler), but on some platforms that may not be
possible, in which case you must call this routine at regular intervals
to update the mouse state variables. To help you test your mouse polling
code even if you are programming on a platform that doesn't require it,
after the first time that you call this function Allegro will switch into
polling mode, so from that point onwards you will have to call this
routine in order to get any mouse input at all, regardless of whether the
current driver actually needs to be polled or not.
Return value:
Returns zero on success, or a negative number on failure (ie. no mouse
driver installed).
See also:
mouse_needs_poll,
install_mouse,
mouse_x.
Examples using this:
exlights,
exmouse,
exshade,
exspline,
extrans.
Returns TRUE if the current mouse driver is operating in polling mode.
See also:
poll_mouse,
install_mouse,
mouse_x.
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.
See also:
install_mouse,
show_mouse,
set_mouse_sprite,
get_mouse_mickeys,
gfx_capabilities,
disable_hardware_cursor,
show_os_cursor.
Examples using this:
exsyscur.
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.
See also:
install_mouse,
show_mouse,
set_mouse_sprite,
get_mouse_mickeys,
gfx_capabilities,
enable_hardware_cursor.
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().
Note that the effects of this function are not apparent until show_mouse()
is called.
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().
The cursor argument selects the type of cursor to be displayed:
MOUSE_CURSOR_NONE
Selects an invisible mouse cursor. In that sense, it is similar to calling
show_mouse(NULL);
MOUSE_CURSOR_ALLEGRO
Selects the custom Allegro cursor, i.e. the one that you set with
set_mouse_sprite().
MOUSE_CURSOR_ARROW
The operating system default arrow cursor.
MOUSE_CURSOR_BUSY
The operating system default `busy' cursor (hourglass).
MOUSE_CURSOR_QUESTION
The operating system default `question' cursor (arrow with question mark).
MOUSE_CURSOR_EDIT
The operating system default `edit' cursor (vertical bar).
Example:
/* initialize mouse sub-system */
install_mouse();
enable_hardware_cursor();
/* Set busy pointer */
select_mouse_cursor(MOUSE_CURSOR_BUSY);
show_mouse(screen);
/* Initialize stuff */
...
/* Set normal arrow pointer */
select_mouse_cursor(MOUSE_CURSOR_ARROW);
See also:
install_mouse,
show_mouse,
set_mouse_sprite,
gfx_capabilities,
enable_hardware_cursor,
set_mouse_cursor_bitmap,
show_os_cursor.
Examples using this:
exsyscur.
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:
MOUSE_CURSOR_ALLEGRO
MOUSE_CURSOR_ARROW
MOUSE_CURSOR_BUSY
MOUSE_CURSOR_QUESTION
MOUSE_CURSOR_EDIT
but not MOUSE_CURSOR_NONE.
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 substitution (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.
See also:
install_mouse,
show_mouse,
set_mouse_sprite,
gfx_capabilities,
enable_hardware_cursor,
show_os_cursor.
Global variables containing the current mouse position and button state.
Wherever possible these values will be updated asynchronously, but if
mouse_needs_poll() returns TRUE, you must manually call poll_mouse() to
update them with the current input state. The `mouse_x' and `mouse_y'
positions are integers ranging from zero to the bottom right corner of
the screen. The `mouse_z' and `mouse_w' variables hold the current vertical
and horizontal wheel position, when using an input driver that supports
wheel mice. The `mouse_b' variable is a bitfield indicating the state of
each button: bit 0 is the left button, bit 1 the right, and bit 2 the
middle button. Additional non standard mouse buttons might be available
as higher bits in this variable. Usage example:
if (mouse_b & 1)
printf("Left button is pressed\n");
if (!(mouse_b & 2))
printf("Right button is not pressed\n");
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. Example:
int pos, x, y;
pos = mouse_pos;
x = pos >> 16;
y = pos & 0x0000ffff;
See also:
install_mouse,
poll_mouse,
mouse_needs_poll.
Examples using this:
exalpha,
exlights,
exmouse,
exshade,
exspline,
extrans.
Global variables containing the current mouse sprite and the focus
point. These are read-only, and only to be modified using the
set_mouse_sprite() and set_mouse_sprite_focus() functions.
See also:
set_mouse_sprite,
set_mouse_sprite_focus.
Tells Allegro to display a mouse pointer on the screen. This will only
work if the timer module has been installed. The mouse pointer will be
drawn onto the specified bitmap, which should normally be `screen' (see
later for information about bitmaps). To hide the mouse pointer, call
show_mouse(NULL).
Warning: if you draw anything onto the screen while the pointer is
visible, a mouse movement interrupt could occur in the middle of your
drawing operation. If this happens the mouse buffering and graphics drawing
code will get confused and will leave 'mouse droppings' all over the
screen. To prevent this, you must make sure you turn off the mouse
pointer whenever you draw onto the screen. This is not needed if you are
using a hardware cursor.
Note: you must not be showing a mouse pointer on a bitmap at the time that
the bitmap is destroyed with destroy_bitmap(), e.g. call show_mouse(NULL);
before destroying the bitmap. This does not apply to `screen' since you
never destroy `screen' with destroy_bitmap().
See also:
install_mouse,
install_timer,
set_mouse_sprite,
scare_mouse,
freeze_mouse_flag,
show_os_cursor.
Examples using this:
exmouse,
expal,
exshade,
exspline,
exsyscur.
Helper for hiding the mouse pointer prior to a drawing operation. This
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
or OS cursor). The previous mouse state is stored for subsequent calls to
unscare_mouse().
See also:
unscare_mouse,
scare_mouse_area,
show_mouse.
Like scare_mouse(), but will only hide the cursor if it is inside the
specified rectangle. Otherwise the cursor will simply be frozen in place
until you call unscare_mouse(), so it cannot interfere with your drawing.
See also:
unscare_mouse,
scare_mouse,
show_mouse.
Undoes the effect of a previous call to scare_mouse() or
scare_mouse_area(), restoring the original pointer state.
See also:
scare_mouse,
scare_mouse_area.
In case you do not need Allegro's mouse cursor API, which automatically
emulates a cursor in software if no other cursor is available, you can
use this low level function to try to display or hide the system cursor
directly. The cursor parameter takes the same values as
select_mouse_cursor. This function is very similar to calling
enable_hardware_cursor, select_mouse_cursor and show_mouse, but will
not try to do anything if no system cursor is available.
The most common use for this function is to just call it once at the
beginning of the program to tell it to display the system cursor inside
the Allegro window. The return value can be used to see if this
succeeded or not. On some systems (e.g. DirectX fullscreen) this is not
supported and the function will always fail, and in other cases only
some of the cursors will work, or in the case of MOUSE_CURSOR_ALLEGRO,
only certain bitmap sizes may be supported.
You never should use show_os_cursor together with the function
show_mouse and other functions affecting it (select_mouse_cursor,
enable_hardware_cursor, disable_hardware_cursor, scare_mouse,
unscare_mouse). They implement the standard high level mouse API, and
don't work together with this low level function.
Return value:
Returns 0 if a system cursor is being displayed after the function
returns, or -1 otherwise.
See also:
show_mouse,
set_mouse_cursor_bitmap,
select_mouse_cursor.
If this flag is set, the mouse pointer won't be redrawn when the mouse
moves. This can avoid the need to hide the pointer every time you draw to
the screen, as long as you make sure your drawing doesn't overlap with
the current pointer position.
See also:
show_mouse.
Moves the mouse to the specified screen position. It is safe to call even
when a mouse pointer is being displayed.
See also:
install_mouse,
position_mouse_z,
set_mouse_range,
set_mouse_speed,
position_mouse_w.
Sets the mouse wheel position variable to the specified value.
See also:
install_mouse,
position_mouse,
position_mouse_w.
Sets the horizontal mouse wheel position to the specified value.
See also:
install_mouse,
position_mouse.
Sets the area of the screen within which the mouse can move. Pass the top
left corner and the bottom right corner (inclusive). If you don't call
this function the range defaults to (0, 0, SCREEN_W-1, SCREEN_H-1).
See also:
install_mouse,
set_mouse_speed,
position_mouse.
Sets the mouse speed. Larger values of xspeed and yspeed represent slower
mouse movement: the default for both is 2.
See also:
install_mouse,
set_mouse_range,
position_mouse.
You don't like Allegro's mouse pointer? No problem. Use this function to
supply an alternative of your own. If you change the pointer and then want
to get Allegro's lovely arrow back again, call set_mouse_sprite(NULL).
As a bonus, set_mouse_sprite(NULL) uses the current palette in choosing
colors for the arrow. So if your arrow mouse sprite looks ugly after
changing the palette, call set_mouse_sprite(NULL).
See also:
install_mouse,
show_mouse,
set_mouse_sprite_focus.
Examples using this:
exmouse.
The mouse focus is the bit of the pointer that represents the actual
mouse position, ie. the (mouse_x, mouse_y) position. By default this is
the top left corner of the arrow, but if you are using a different mouse
pointer you might need to alter it.
See also:
set_mouse_sprite.
Examples using this:
exmouse.
Measures how far the mouse has moved since the last call to this
function. The values of mickeyx and mickeyy will become negative if the
mouse is moved left or up, respectively. The mouse will continue to
generate movement mickeys even when it reaches the edge of the screen, so
this form of input can be useful for games that require an infinite range
of mouse movement.
Note that the infinite movement may not work in windowed mode, since under
some platforms the mouse would leave the window, and may not work at all
if the hardware cursor is in use.
See also:
install_mouse.
Examples using this:
exmouse.
Called by the interrupt handler whenever the mouse moves or one of the
buttons changes state. This function must be in locked memory, and must
execute _very_ quickly! It is passed the event flags that triggered the
call, which is a bitmask containing any of the values MOUSE_FLAG_MOVE,
MOUSE_FLAG_LEFT_DOWN, MOUSE_FLAG_LEFT_UP, MOUSE_FLAG_RIGHT_DOWN,
MOUSE_FLAG_RIGHT_UP, MOUSE_FLAG_MIDDLE_DOWN, MOUSE_FLAG_MIDDLE_UP, and
MOUSE_FLAG_MOVE_Z. Note that even if the mouse has more than three buttons,
only the first three can be trapped using a callback.
See also:
install_mouse.
This function can be useful to prevent having two mouse pointers on the
screen at the same time when running your program in windowed mode and
drawing the mouse pointer yourself. Other possible uses include the
ability to pause your game when the mouse goes off of the window, or
only scrolling the view when the pointer is near the edge of the window,
but not while off of the window.
Example :
if (mouse_on_screen()) {draw_sprite(buffer , mouse_sprite , mouse_x , mouse_y);}
Return value:
Returns 0 if the mouse pointer is off of the screen, or non-zero otherwise.