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.

Added 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.
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.

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.

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

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

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).

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.

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.

Added 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.