# Mouse

## API: ALLEGRO_MOUSE_STATE

Public fields (read only):

* x - mouse x
* y - mouse y
* w, z - Mouse wheel position (2D 'ball')

buttons - mouse buttons

## API: al_create_mouse_cursor

Create a mouse cursor from the bitmap provided.  There must be a current
display in effect.

*Return value:*

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

## API: al_destroy_mouse_cursor

Free the memory used by the given cursor.

The display that was in effect when the cursor was created must
still be in effect.
XXX that's terrible and should be changed

Has no effect if `cursor` is NULL.

## API: al_get_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.

*Return value:*

Returns true on success, false on failure.

## API: al_get_mouse

Return a pointer to an object representing the mouse, that can
be used as an event source.

## API: al_get_mouse_num_axes

Return the number of buttons on the mouse.

## API: al_get_mouse_num_buttons

Return the number of buttons on the mouse.

## API: al_get_mouse_state

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

## API: al_get_mouse_state_axis

Extract the mouse axis value from the saved state.

## API: al_hide_mouse_cursor

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

*Return value:*

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

## API: al_install_mouse

Install a mouse driver.

*Return value:*

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_mouse_button_down

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

## API: al_set_mouse_axis

Set the given mouse axis to the given value.

For now: the axis number must not be 0 or 1, which are the X and Y axes.

*Return value:*

Returns true on success, false on failure.

## API: al_set_mouse_cursor

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

The display that was in effect when the cursor was created must still be
in effect.
XXX that's terrible and should be changed

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

*Return value:*

Returns true on success, false on failure.

## API: al_set_mouse_range

Sets the area of the screen within which the mouse can move.
The coordinates are inclusive. (XXX: change this?)
XXX: This should be relative to an ALLEGRO_DISPLAY.

*Return value:*

Returns true on success, false on failure.

## API: al_set_mouse_w

Set the mouse wheel position to the given value.

*Return value:*

Returns true on success, false on failure.

## API: al_set_mouse_xy

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

*Return value:*

Returns true on success, false on failure.
XXX: This should be relative to an ALLEGRO_DISPLAY.

## API: al_set_mouse_z

Set the mouse wheel position to the given value.

*Return value:*

Returns true on success, false on failure.

## API: al_set_system_mouse_cursor

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

*Return value:*

Returns true on success, false on failure.

## API: al_show_mouse_cursor

Make a mouse cursor visible in the current display of the calling thread.

*Return value:*

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

## 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.

