# Mouse ## ALLEGRO_MOUSE_STATE
    typedef struct ALLEGRO_MOUSE_STATE
Public fields (read only): x - mouse x y - mouse y w, z - Mouse wheel position (2D 'ball') buttons - mouse buttons ## al_create_mouse_cursor
    ALLEGRO_MOUSE_CURSOR *al_create_mouse_cursor(ALLEGRO_BITMAP *bmp,
       int x_focus, int y_focus)
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. ## al_destroy_mouse_cursor
    void al_destroy_mouse_cursor(ALLEGRO_MOUSE_CURSOR *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. ## al_get_cursor_position
    bool al_get_cursor_position(int *ret_x, int *ret_y)
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. ## al_get_mouse
    ALLEGRO_MOUSE *al_get_mouse(void)
Return a pointer to an object representing the mouse, that can be used as an event source. ## al_get_mouse_num_axes
    unsigned int al_get_mouse_num_axes(void)
Return the number of buttons on the mouse. ## al_get_mouse_num_buttons
    unsigned int al_get_mouse_num_buttons(void)
Return the number of buttons on the mouse. ## al_get_mouse_state
    void al_get_mouse_state(ALLEGRO_MOUSE_STATE *ret_state)
Save the state of the mouse specified at the time the function is called into the given structure. ## al_get_mouse_state_axis
    int al_get_mouse_state_axis(ALLEGRO_MOUSE_STATE *ret_state, int axis)
Extract the mouse axis value from the saved state. ## al_hide_mouse_cursor
    bool al_hide_mouse_cursor(void)
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. ## al_install_mouse
    bool al_install_mouse(void)
Install a mouse driver. Return value: Returns true if successful. If a driver was already installed, nothing happens and true is returned. ## al_is_mouse_installed
    bool al_is_mouse_installed(void)
Returns true if al_install_mouse was called successfully. ## al_mouse_button_down
    bool al_mouse_button_down(ALLEGRO_MOUSE_STATE *state, int button)
Return true if the mouse button specified was held down in the state specified. ## al_set_mouse_axis
    bool al_set_mouse_axis(int which, int value)
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. ## al_set_mouse_cursor
    bool al_set_mouse_cursor(ALLEGRO_MOUSE_CURSOR *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. ## al_set_mouse_range
    bool al_set_mouse_range(int x1, int y1, int x2, int y2)
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. ## al_set_mouse_w
    bool al_set_mouse_w(int w)
Set the mouse wheel position to the given value. Return value: Returns true on success, false on failure. ## al_set_mouse_xy
    bool al_set_mouse_xy(int x, int y)
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. ## al_set_mouse_z
    bool al_set_mouse_z(int z)
Set the mouse wheel position to the given value. Return value: Returns true on success, false on failure. ## al_set_system_mouse_cursor
    bool al_set_system_mouse_cursor(ALLEGRO_SYSTEM_MOUSE_CURSOR cursor_id)
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. ## al_show_mouse_cursor
    bool al_show_mouse_cursor(void)
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. ## al_uninstall_mouse
    void al_uninstall_mouse(void)
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.

Last updated: 2009-05-04 10:18:45 UTC