# Mouse routines

These functions are declared in the main Allegro header file:

~~~~c
 #include <allegro5/allegro.h>
~~~~

## API: ALLEGRO_MOUSE_STATE

Public fields (read only):

* x - mouse x position
* y - mouse y position
* w, z - mouse wheel position (2D 'ball')
* display - the display the mouse is on (coordinates are relative to this)
* buttons - mouse buttons bitfield

    The zeroth bit is set if the primary mouse button is held down,
    the first bit is set if the secondary mouse button is held down,
    and so on.

* pressure - pressure, ranging from `0.0` to `1.0`

See also: [al_get_mouse_state], [al_get_mouse_state_axis], [al_mouse_button_down]

## Mouse button constants

Unlike other indexes, the first mouse button is numbered 1 when returned in
the event.mouse.button field of ALLEGRO_EVENT_MOUSE_BUTTON_UP and
ALLEGRO_EVENT_MOUSE_BUTTON_DOWN events.

As a convenience, the following ALLEGRO_MOUSE_BUTTON constants are provided below.
However, depending on the hardware there may be more or fewer mouse buttons. You
can check [al_get_mouse_num_buttons] if you want to be sure.

~~~~c
typedef enum ALLEGRO_MOUSE_BUTTON
{
   ALLEGRO_MOUSE_BUTTON_LEFT = 1,
   ALLEGRO_MOUSE_BUTTON_RIGHT = 2,
   ALLEGRO_MOUSE_BUTTON_MIDDLE = 3
} ALLEGRO_MOUSE_BUTTON;
~~~~

Since: 5.2.10

See also: [al_get_mouse_num_buttons], [al_mouse_button_down]

## API: al_install_mouse

Install a mouse driver.

Returns true if successful. If a driver was already installed, nothing
happens and true is returned.

## API: al_is_mouse_installed

Returns true if [al_install_mouse] was called successfully.

## API: al_uninstall_mouse

Uninstalls the active mouse driver, if any.  This will
automatically unregister the mouse event source with any event
queues.

This function is automatically called when Allegro is shut down.

## API: al_get_mouse_num_axes

Return the number of axes on the mouse.
The first axis is 0.

See also: [al_get_mouse_num_buttons]

## API: al_get_mouse_num_buttons

Return the number of buttons on the mouse.
The first button is 1.

See also: [al_get_mouse_num_axes]

## API: al_get_mouse_state

Save the state of the mouse specified at the time the function
is called into the given structure.

Example:

~~~~c
ALLEGRO_MOUSE_STATE state;

al_get_mouse_state(&state);
if (state.buttons & 1) {
    /* Primary (e.g. left) mouse button is held. */
    printf("Mouse position: (%d, %d)\n", state.x, state.y);
}
if (state.buttons & 2) {
    /* Secondary (e.g. right) mouse button is held. */
}
if (state.buttons & 4) {
    /* Tertiary (e.g. middle) mouse button is held. */
}
~~~~

See also: [ALLEGRO_MOUSE_STATE], [al_get_mouse_state_axis],
[al_mouse_button_down]

## API: al_get_mouse_state_axis

Extract the mouse axis value from the saved state.
The axes are numbered from 0, in this order:
x-axis, y-axis, z-axis, w-axis.

See also: [ALLEGRO_MOUSE_STATE], [al_get_mouse_state], [al_mouse_button_down]

## API: al_mouse_button_down

Return true if the mouse button specified was held down in the state
specified.

Unlike most things, the first mouse button is numbered 1.  As a convenience, the constants
ALLEGRO_MOUSE_BUTTON_LEFT, ALLEGRO_MOUSE_BUTTON_RIGHT, ALLEGRO_MOUSE_BUTTON_MIDDLE are provided.
However, depending on the hardware there may be more or fewer mouse buttons. You can check
[al_get_mouse_num_buttons] if you want to be sure.

See also: [ALLEGRO_MOUSE_STATE], [al_get_mouse_state], [al_get_mouse_state_axis]

## API: al_set_mouse_xy

Try to position the mouse at the given coordinates on the given display.
The mouse movement resulting from a successful move will generate an
[ALLEGRO_EVENT_MOUSE_WARPED] event.

Returns true on success, false on failure.

See also: [al_set_mouse_z], [al_set_mouse_w]

## API: al_set_mouse_z

Set the mouse wheel position to the given value.

Returns true on success, false on failure.

See also: [al_set_mouse_w]

## API: al_set_mouse_w

Set the second mouse wheel position to the given value.

Returns true on success, false on failure.

See also: [al_set_mouse_z]

## API: al_set_mouse_axis

Set the given mouse axis to the given value.

The axis number must not be 0 or 1, which are the X and Y axes.
Use [al_set_mouse_xy] for that.

Returns true on success, false on failure.

See also: [al_set_mouse_xy], [al_set_mouse_z], [al_set_mouse_w]

## API: al_get_mouse_event_source

Retrieve the mouse event source. All [mouse events][ALLEGRO_EVENT_MOUSE_AXES]
are generated by this event source.

Returns NULL if the mouse subsystem was not installed.


## API: al_set_mouse_wheel_precision

Sets the precision of the mouse wheel (the z and w coordinates). This precision
manifests itself as a multiplier on the `dz` and `dw` fields in mouse events.
It also affects the `z` and `w` fields of events and [ALLEGRO_MOUSE_STATE], but
not in a simple way if you alter the precision often, so it is suggested to
reset those axes to 0 when you change precision. Setting this to a high value
allows you to detect small changes in those two axes for some high precision
mice. A flexible way of using this precision is to set it to a high value (120
is likely sufficient for most, if not all, mice) and use a floating point `dz`
and `dw` like so:

~~~~c
al_set_mouse_wheel_precision(120);

ALLEGRO_EVENT event;
al_wait_for_event(event_queue, &event);
if (event.type == ALLEGRO_EVENT_MOUSE_AXES) {
  double dz = (double)event.mouse.dz / al_get_mouse_wheel_precision();
  /* Use dz in some way... */
}
~~~~

Precision is set to 1 by default. It is impossible to set it to a lower
precision than that.

Since: 5.1.10

See also: [al_get_mouse_wheel_precision]

## API: al_get_mouse_wheel_precision

Gets the precision of the mouse wheel (the z and w coordinates).

Since: 5.1.10

See also: [al_set_mouse_wheel_precision]


## Mouse cursors

### API: al_create_mouse_cursor

Create a mouse cursor from the bitmap provided. `x_focus` and `y_focus`
describe the bit of the cursor that will represent the actual mouse position.

Returns a pointer to the cursor on success, or NULL on failure.

See also: [al_set_mouse_cursor], [al_destroy_mouse_cursor]

### API: al_destroy_mouse_cursor

Free the memory used by the given cursor.

Has no effect if `cursor` is NULL.

See also: [al_create_mouse_cursor]

### API: al_set_mouse_cursor

Set the given mouse cursor to be the current mouse cursor for the given
display.

If the cursor is currently 'shown' (as opposed to 'hidden') the change is
immediately visible.

Returns true on success, false on failure.

See also: [al_set_system_mouse_cursor], [al_show_mouse_cursor],
[al_hide_mouse_cursor]

### API: al_set_system_mouse_cursor

Set the given system mouse cursor to be the current mouse cursor
for the given display.  If the cursor is currently 'shown' (as opposed
to 'hidden') the change is immediately visible.

If the cursor doesn't exist on the current platform another cursor will be
silently be substituted.

The cursors are:

* ALLEGRO_SYSTEM_MOUSE_CURSOR_DEFAULT
* ALLEGRO_SYSTEM_MOUSE_CURSOR_ARROW
* ALLEGRO_SYSTEM_MOUSE_CURSOR_BUSY
* ALLEGRO_SYSTEM_MOUSE_CURSOR_QUESTION
* ALLEGRO_SYSTEM_MOUSE_CURSOR_EDIT
* ALLEGRO_SYSTEM_MOUSE_CURSOR_MOVE
* ALLEGRO_SYSTEM_MOUSE_CURSOR_RESIZE_N
* ALLEGRO_SYSTEM_MOUSE_CURSOR_RESIZE_W
* ALLEGRO_SYSTEM_MOUSE_CURSOR_RESIZE_S
* ALLEGRO_SYSTEM_MOUSE_CURSOR_RESIZE_E
* ALLEGRO_SYSTEM_MOUSE_CURSOR_RESIZE_NW
* ALLEGRO_SYSTEM_MOUSE_CURSOR_RESIZE_SW
* ALLEGRO_SYSTEM_MOUSE_CURSOR_RESIZE_SE
* ALLEGRO_SYSTEM_MOUSE_CURSOR_RESIZE_NE
* ALLEGRO_SYSTEM_MOUSE_CURSOR_PROGRESS
* ALLEGRO_SYSTEM_MOUSE_CURSOR_PRECISION
* ALLEGRO_SYSTEM_MOUSE_CURSOR_LINK
* ALLEGRO_SYSTEM_MOUSE_CURSOR_ALT_SELECT
* ALLEGRO_SYSTEM_MOUSE_CURSOR_UNAVAILABLE

Returns true on success, false on failure.

See also: [al_set_mouse_cursor], [al_show_mouse_cursor], [al_hide_mouse_cursor]

### API: al_can_get_mouse_cursor_position

Returns true if getting the global mouse cursor position is available.

Since: 5.2.9

See also: [al_get_mouse_cursor_position]

### API: al_get_mouse_cursor_position

On platforms where this information is available, this function returns the
global location of the mouse cursor, relative to the desktop. You should
not normally use this function, as the information is not useful except
for special scenarios as moving a window.

Returns true on success, false on failure.

See also: [al_can_get_mouse_cursor_position]

### API: al_hide_mouse_cursor

Hide the mouse cursor in the given display. This has no effect on what the
current mouse cursor looks like; it just makes it disappear.

Returns true on success (or if the cursor already was hidden), false
otherwise.

See also: [al_show_mouse_cursor]

### API: al_show_mouse_cursor

Make a mouse cursor visible in the given display.

Returns true if a mouse cursor is shown as a result of the call (or one
already was visible), false otherwise.

See also: [al_hide_mouse_cursor]

### API: al_grab_mouse

Confine the mouse cursor to the given display.  The mouse cursor can only be
confined to one display at a time.

Returns true if successful, otherwise returns false.
Do not assume that the cursor will remain confined until you call
[al_ungrab_mouse].  It may lose the confined status at any time for other
reasons.

> *Note:* not yet implemented on Mac OS X.

See also: [al_ungrab_mouse]

### API: al_ungrab_mouse

Stop confining the mouse cursor to any display belonging to the program.

> *Note:* not yet implemented on Mac OS X.

See also: [al_grab_mouse]
