Mouse routines


int install_mouse();

Installs the Allegro mouse handler. You must do this before using any other mouse functions. Returns -1 on failure, otherwise the number of buttons on the mouse.
See also: remove_mouse, poll_mouse, mouse_x, show_mouse, get_mouse_mickeys, position_mouse, set_mouse_range, set_mouse_speed, Standard config variables.
void remove_mouse();

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.
int poll_mouse();

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. Returns zero on success, or a negative number on failure (ie. no mouse driver installed).
See also: mouse_needs_poll, install_mouse, mouse_x.
int mouse_needs_poll();

Returns TRUE if the current mouse driver is operating in polling mode.
See also: poll_mouse, install_mouse, mouse_x.
extern volatile int mouse_x;

extern volatile int mouse_y;

extern volatile int mouse_z;

extern volatile int mouse_b;

extern volatile int mouse_pos;

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 variable holds the current 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. 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.
See also: install_mouse, poll_mouse, mouse_needs_poll.
extern BITMAP *mouse_sprite;

extern int mouse_x_focus;

extern int mouse_y_focus;

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.
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.
See also: install_mouse, install_timer, set_mouse_sprite, scare_mouse, freeze_mouse_flag.
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().
See also: unscare_mouse, scare_mouse_area, show_mouse.
void scare_mouse_area(int x, int y, int w, int h);

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.
void unscare_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.
extern volatile 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.
See also: show_mouse.
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.
See also: install_mouse, position_mouse_z, set_mouse_range, set_mouse_speed.
void position_mouse_z(int z);

Sets the mouse wheel position variable to the specified value.
See also: install_mouse, position_mouse.
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).
See also: install_mouse, set_mouse_speed, position_mouse.
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.
See also: install_mouse, set_mouse_range, position_mouse.
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).

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.
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.
See also: set_mouse_sprite.
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.
See also: install_mouse.
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, MOUSE_FLAG_MIDDLE_UP, and MOUSE_FLAG_MOVE_Z.
See also: install_mouse.
Back to contents