Mouse routines

These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

ALLEGRO_MOUSE_STATE

typedef struct ALLEGRO_MOUSE_STATE ALLEGRO_MOUSE_STATE;

Source Code

Public fields (read only):

See also: al_get_mouse_state, al_get_mouse_state_axis, al_mouse_button_down

al_install_mouse

bool al_install_mouse(void)

Source Code

Install a mouse driver.

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

Examples:

al_is_mouse_installed

bool al_is_mouse_installed(void)

Source Code

Returns true if al_install_mouse was called successfully.

al_uninstall_mouse

void al_uninstall_mouse(void)

Source Code

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.

al_get_mouse_num_axes

unsigned int al_get_mouse_num_axes(void)

Source Code

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

See also: al_get_mouse_num_buttons

al_get_mouse_num_buttons

unsigned int al_get_mouse_num_buttons(void)

Source Code

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

See also: al_get_mouse_num_axes

Examples:

al_get_mouse_state

void al_get_mouse_state(ALLEGRO_MOUSE_STATE *ret_state)

Source Code

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

Example:

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

Examples:

al_get_mouse_state_axis

int al_get_mouse_state_axis(const ALLEGRO_MOUSE_STATE *state, int axis)

Source Code

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

al_mouse_button_down

bool al_mouse_button_down(const ALLEGRO_MOUSE_STATE *state, int button)

Source Code

Return true if the mouse button specified was held down in the state specified. Unlike most things, the first mouse button is numbered 1.

See also: ALLEGRO_MOUSE_STATE, al_get_mouse_state, al_get_mouse_state_axis

Examples:

al_set_mouse_xy

bool al_set_mouse_xy(ALLEGRO_DISPLAY *display, int x, int y)

Source Code

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

Examples:

al_set_mouse_z

bool al_set_mouse_z(int z)

Source Code

Set the mouse wheel position to the given value.

Returns true on success, false on failure.

See also: al_set_mouse_w

al_set_mouse_w

bool al_set_mouse_w(int w)

Source Code

Set the second mouse wheel position to the given value.

Returns true on success, false on failure.

See also: al_set_mouse_z

Examples:

al_set_mouse_axis

bool al_set_mouse_axis(int which, int value)

Source Code

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

al_get_mouse_event_source

ALLEGRO_EVENT_SOURCE *al_get_mouse_event_source(void)

Source Code

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

Returns NULL if the mouse subsystem was not installed.

Examples:

al_set_mouse_wheel_precision

void al_set_mouse_wheel_precision(int precision)

Source Code

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:

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

Examples:

al_get_mouse_wheel_precision

int al_get_mouse_wheel_precision(void)

Source Code

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

al_create_mouse_cursor

ALLEGRO_MOUSE_CURSOR *al_create_mouse_cursor(ALLEGRO_BITMAP *bmp,
   int x_focus, int y_focus)

Source Code

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

Examples:

al_destroy_mouse_cursor

void al_destroy_mouse_cursor(ALLEGRO_MOUSE_CURSOR *cursor)

Source Code

Free the memory used by the given cursor.

Has no effect if cursor is NULL.

See also: al_create_mouse_cursor

Examples:

al_set_mouse_cursor

bool al_set_mouse_cursor(ALLEGRO_DISPLAY *display, ALLEGRO_MOUSE_CURSOR *cursor)

Source Code

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

Examples:

al_set_system_mouse_cursor

bool al_set_system_mouse_cursor(ALLEGRO_DISPLAY *display,
   ALLEGRO_SYSTEM_MOUSE_CURSOR cursor_id)

Source Code

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:

Returns true on success, false on failure.

See also: al_set_mouse_cursor, al_show_mouse_cursor, al_hide_mouse_cursor

Examples:

al_get_mouse_cursor_position

bool al_get_mouse_cursor_position(int *ret_x, int *ret_y)

Source Code

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.

Examples:

al_hide_mouse_cursor

bool al_hide_mouse_cursor(ALLEGRO_DISPLAY *display)

Source Code

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

Examples:

al_show_mouse_cursor

bool al_show_mouse_cursor(ALLEGRO_DISPLAY *display)

Source Code

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

Examples:

al_grab_mouse

bool al_grab_mouse(ALLEGRO_DISPLAY *display)

Source Code

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

al_ungrab_mouse

bool al_ungrab_mouse(void)

Source Code

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

Allegro version 5.2.8 - Last updated: 2022-06-06 01:17:45 UTC