SDL Mouse Functions tcod.sdl.mouse#

SDL mouse and cursor functions.

You can use this module to move or capture the cursor.

You can also set the cursor icon to an OS-defined or custom icon.

New in version 13.5.

class tcod.sdl.mouse.Cursor(sdl_cursor_p: Any)[source]#

A cursor icon for use with set_cursor.

class tcod.sdl.mouse.SystemCursor(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

An enumerator of system cursor icons.

ARROW = 0#
CROSSHAIR = 3#
HAND = 11#
IBEAM = 1#
NO = 10#
SIZEALL = 9#
SIZENESW = 6#
SIZENS = 8#
SIZENWSE = 5#
SIZEWE = 7#
WAIT = 2#
WAITARROW = 4#
tcod.sdl.mouse.capture(enable: bool) → None[source]#

Enable or disable mouse capture to track the mouse outside of a window.

It is highly recommended to read the related remarks section in the SDL docs before using this.

Example:

# Make mouse button presses capture the mouse until all buttons are released.
# This means that dragging the mouse outside of the window will not cause an interruption in motion events.
for event in tcod.event.get():
    match event:
        case tcod.event.MouseButtonDown(button=button, pixel=pixel):  # Clicking the window captures the mouse.
            tcod.sdl.mouse.capture(True)
        case tcod.event.MouseButtonUp():  # When all buttons are released then the mouse is released.
            if tcod.event.mouse.get_global_state().state == 0:
                tcod.sdl.mouse.capture(False)
        case tcod.event.MouseMotion(pixel=pixel, pixel_motion=pixel_motion, state=state):
            pass  # While a button is held this event is still captured outside of the window.

See also

tcod.sdl.mouse.set_relative_mode https://wiki.libsdl.org/SDL_CaptureMouse

tcod.sdl.mouse.get_cursor() → Cursor | None[source]#

Return the active cursor, or None if these is no mouse.

tcod.sdl.mouse.get_default_cursor() → Cursor[source]#

Return the default cursor.

tcod.sdl.mouse.get_focus() → Window | None[source]#

Return the window which currently has mouse focus.

tcod.sdl.mouse.get_global_state() → MouseState[source]#

Return the mouse state relative to the desktop.

See also

https://wiki.libsdl.org/SDL_GetGlobalMouseState

tcod.sdl.mouse.get_relative_mode() → bool[source]#

Return True if relative mouse mode is enabled.

tcod.sdl.mouse.get_relative_state() → MouseState[source]#

Return the mouse state, the coordinates are relative to the last time this function was called.

See also

https://wiki.libsdl.org/SDL_GetRelativeMouseState

tcod.sdl.mouse.get_state() → MouseState[source]#

Return the mouse state relative to the window with mouse focus.

See also

https://wiki.libsdl.org/SDL_GetMouseState

tcod.sdl.mouse.new_color_cursor(pixels: numpy.typing.ArrayLike, hot_xy: tuple[int, int]) → Cursor[source]#

Create a new color cursor.

Parameters:

  • pixels – A row-major array of RGB or RGBA pixels.

  • hot_xy – The position of the pointer relative to the mouse sprite, starting from the upper-left at (0, 0).

See also

set_cursor

tcod.sdl.mouse.new_cursor(data: NDArray[np.bool_], mask: NDArray[np.bool_], hot_xy: tuple[int, int] = (0, 0)) → Cursor[source]#

Return a new non-color Cursor from the provided parameters.

Parameters:

  • data – A row-major boolean array for the data parameters. See the SDL docs for more info.

  • mask – A row-major boolean array for the mask parameters. See the SDL docs for more info.

  • hot_xy – The position of the pointer relative to the mouse sprite, starting from the upper-left at (0, 0).

See also

set_cursor https://wiki.libsdl.org/SDL_CreateCursor

tcod.sdl.mouse.new_system_cursor(cursor: SystemCursor) → Cursor[source]#

Return a new Cursor from one of the system cursors labeled by SystemCursor.

See also

set_cursor

tcod.sdl.mouse.set_cursor(cursor: Cursor | SystemCursor | None) → None[source]#

Change the active cursor to the one provided.

Parameters:

cursor – A cursor created from new_cursor, new_color_cursor, or new_system_cursor. Can also take values of SystemCursor directly. None will force the current cursor to be redrawn.

tcod.sdl.mouse.set_relative_mode(enable: bool) → None[source]#

Enable or disable relative mouse mode which will lock and hide the mouse and only report mouse motion.

See also

tcod.sdl.mouse.capture https://wiki.libsdl.org/SDL_SetRelativeMouseMode

tcod.sdl.mouse.show(visible: bool | None = None) → bool[source]#

Optionally show or hide the mouse cursor then return the state of the cursor.

Parameters:

visible – If None then only return the current state. Otherwise set the mouse visibility.

Returns:

True if the cursor is visible.

New in version 16.0.

tcod.sdl.mouse.warp_global(x: int, y: int) → None[source]#

Move the mouse cursor to a position on the desktop.

tcod.sdl.mouse.warp_in_window(window: Window, x: int, y: int) → None[source]#

Move the mouse cursor to a position within a window.