sdl2.ext.mouse - Configuring and Handling Mouse Input¶

This module provides a number of functions to make it easier to configure and retrieve mouse input in PySDL2.

The show_cursor(), hide_cursor(), and cursor_hidden() functions allow you to easily show, hide, and check the visibility of the mouse cursor. Additionally, you can check the cursor’s absolute or relative location with the mouse_coords() and mouse_delta() functions (respectively), or obtain the current state of the mouse buttons with mouse_button_state(). The location of the mouse cursor can be changed programatically using warp_mouse().

class sdl2.ext.mouse.ButtonState(buttonmask)[source]¶

A class representing the state of the mouse buttons.

Parameters:	buttonmask (int) – The raw SDL button mask to parse.

raw¶

The raw SDL button mask representing the button state.

Type:	int

any_pressed¶

True if any buttons are currently pressed, otherwise False.

Type:	bool

left¶

The state of the left mouse button (0 = up, 1 = down).

Type:	int

right¶

The state of the right mouse button (0 = up, 1 = down).

Type:	int

middle¶

The state of the middle mouse button (0 = up, 1 = down).

Type:	int

x1¶

The state of the first extra mouse button (0 = up, 1 = down).

Type:	int

x2¶

The state of the second extra mouse button (0 = up, 1 = down).

Type:	int

sdl2.ext.mouse.show_cursor()[source]¶: Unhides the mouse cursor if it is currently hidden.

sdl2.ext.mouse.hide_cursor()[source]¶: Hides the mouse cursor if it is currently visible.

sdl2.ext.mouse.cursor_hidden()[source]¶

Checks whether the mouse cursor is currently visible.

Returns:	True if the cursor is hidden, otherwise False.
Return type:	bool

sdl2.ext.mouse.mouse_coords(desktop=False)[source]¶

Get the current x/y coordinates of the mouse cursor.

By default, this function reports the coordinates relative to the top-left corner of the SDL window that currently has focus. To obtain the mouse coordinates relative to the top-right corner of the full desktop, this function can optionally be called with desktop argument set to True.

Parameters:	desktop (bool, optional) – If True, reports the mouse coordinates relative to the full desktop instead of the currently-focused SDL window. Defaults to False.
Returns:	The current (x, y) coordinates of the mouse cursor.
Return type:	tuple

sdl2.ext.mouse.mouse_button_state()[source]¶

Gets the current state of each button of the mouse.

Mice in SDL are currently able to have up to 5 buttons: left, right, middle, and two extras (x1 and x2). You can check each of these individually, or alternatively check whether any buttons have been pressed:

bstate = mouse_button_state()
if bstate.any_pressed:
    if bstate.left == 1:
        print("left button down!")
    if bstate.right == 1:
        print("right button down!")

Returns:	A representation of the current button state of the mouse.
Return type:	`ButtonState`

sdl2.ext.mouse.mouse_delta()[source]¶

Get the relative change in cursor position since last checked.

The first time this function is called, it will report the (x, y) change in cursor position since the SDL video or event system was initialized. Subsequent calls to this function report the change in position since the previous time the function was called.

Returns:	The (x, y) change in cursor coordinates since the function was last called.
Return type:	tuple

sdl2.ext.mouse.warp_mouse(x, y, window=None, desktop=False)[source]¶

Warps the mouse cursor to a given location on the screen.

By default, this warps the mouse cursor relative to the top-left corner of whatever SDL window currently has mouse focus. For example,:

warp_mouse(400, 300)

would warp the mouse to the middle of a 800x600 SDL window. Alternatively, the cursor can be warped within a specific SDL window or relative to the full desktop.

Parameters:

x (int) – The new X position for the mouse cursor.
y (int) – The new Y position for the mouse cursor.
window (SDL_Window or Window, optional) – The SDL window within which to warp the mouse cursor. If not specified (the default), the cursor will be warped within the SDL window that currently has mouse focus.
desktop (bool, optional) – If True, the mouse cursor will be warped relative to the full desktop instead of the current SDL window. Defaults to False.