# 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()`.

sdl2.ext.mouse.show_cursor()

  Unhides the mouse cursor if it is currently hidden.

sdl2.ext.mouse.hide_cursor()

  Hides the mouse cursor if it is currently visible.

sdl2.ext.mouse.cursor_hidden()

  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)

  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_delta()

  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)

  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.

sdl2.ext.mouse.mouse_button_state()

  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`

class sdl2.ext.mouse.ButtonState(buttonmask)

  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

  property any_pressed

    True if any buttons are currently pressed, otherwise False.

    Type:

      bool

  property left

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

    Type:

      int

  property right

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

    Type:

      int

  property middle

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

    Type:

      int

  property x1

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

    Type:

      int

  property x2

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

    Type:

      int