The Allegro mouse handler runs on top of the DOS int33 mouse driver, so it will only work when the DOS driver (usually mouse.com or mouse.exe) is active. It is useful as a simple wrapper for the int33 functions, and also because it can display mouse pointers in SVGA modes, which most implementations of the standard driver cannot.
int install_mouse();
Installs the Allegro mouse handler. You must do this before using any
other mouse functions. Returns -1 on failure (ie. if the int33 driver is
not loaded), otherwise the number of buttons on the mouse.
void remove_mouse();
Removes the mouse handler. You don't normally need to bother calling
this, because allegro_exit() will do it for you.
extern volatile int mouse_x;
extern volatile int mouse_y;
extern volatile int mouse_b;
extern volatile int mouse_pos;
Global variables containing the current mouse position and button state.
The mouse_x and mouse_y positions are integers ranging from zero to the
bottom right corner of the screen. 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. For 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 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
variables, since you can copy this value into a local variable with a
single instruction and then split it up at your leisure.
void show_mouse(BITMAP *bmp);
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 SVGA
bank switching 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.
void scare_mouse();
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
cursor). The previous mouse state is stored for subsequent calls to
unscare_mouse().
void unscare_mouse();
Undoes the effect of a previous call to scare_mouse(), restoring the
original pointer state.
extern int freeze_mouse_flag;
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.
void position_mouse(int x, int y);
Moves the mouse to the specified screen position. It is safe to call even
when a mouse pointer is being displayed.
void set_mouse_range(int x1, int y1, int x2, int y2);
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).
void set_mouse_speed(int xspeed, int yspeed);
Sets the mouse speed. Larger values of xspeed and yspeed represent slower
mouse movement: the default for both is 2.
void set_mouse_sprite(BITMAP *sprite);
You don't like my mouse pointer? No problem. Use this function to supply
an alternative of your own. If you change the pointer and then want to
get my lovely arrow back again, call set_mouse_sprite(NULL).
void set_mouse_sprite_focus(int x, int y);
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.
void get_mouse_mickeys(int *mickeyx, int *mickeyy);
Measures how far the mouse has moved since the last call to this
function. 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.
extern void (*mouse_callback)(int flags);
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, and MOUSE_FLAG_MIDDLE_UP.