SDL2 Event Handling `tcod.event`#

A light-weight implementation of event handling built on calls to SDL.

Many event constants are derived directly from SDL. For example: tcod.event.KeySym.UP and tcod.event.Scancode.A refer to SDL’s SDLK_UP and SDL_SCANCODE_A respectfully. See this table for all of SDL’s keyboard constants.

Printing any event will tell you its attributes in a human readable format. An events type attribute if omitted is just the classes name with all letters upper-case.

As a general guideline, you should use KeyboardEvent.sym for command inputs, and TextInput.text for name entry fields.

Example:

import tcod

KEY_COMMANDS = {
    tcod.event.KeySym.UP: "move N",
    tcod.event.KeySym.DOWN: "move S",
    tcod.event.KeySym.LEFT: "move W",
    tcod.event.KeySym.RIGHT: "move E",
}

context = tcod.context.new()
while True:
    console = context.new_console()
    context.present(console, integer_scaling=True)
    for event in tcod.event.wait():
        context.convert_event(event)  # Adds tile coordinates to mouse events.
        if isinstance(event, tcod.event.Quit):
            print(event)
            raise SystemExit()
        elif isinstance(event, tcod.event.KeyDown):
            print(event)  # Prints the Scancode and KeySym enums for this event.
            if event.sym in KEY_COMMANDS:
                print(f"Command: {KEY_COMMANDS[event.sym]}")
        elif isinstance(event, tcod.event.MouseButtonDown):
            print(event)  # Prints the mouse button constant names for this event.
        elif isinstance(event, tcod.event.MouseMotion):
            print(event)  # Prints the mouse button mask bits in a readable format.
        else:
            print(event)  # Print any unhandled events.

Python 3.10 introduced match statements which can be used to dispatch events more gracefully:

Example:

import tcod

KEY_COMMANDS = {
    tcod.event.KeySym.UP: "move N",
    tcod.event.KeySym.DOWN: "move S",
    tcod.event.KeySym.LEFT: "move W",
    tcod.event.KeySym.RIGHT: "move E",
}

context = tcod.context.new()
while True:
    console = context.new_console()
    context.present(console, integer_scaling=True)
    for event in tcod.event.wait():
        context.convert_event(event)  # Adds tile coordinates to mouse events.
        match event:
            case tcod.event.Quit():
                raise SystemExit()
            case tcod.event.KeyDown(sym) if sym in KEY_COMMANDS:
                print(f"Command: {KEY_COMMANDS[sym]}")
            case tcod.event.KeyDown(sym=sym, scancode=scancode, mod=mod, repeat=repeat):
                print(f"KeyDown: {sym=}, {scancode=}, {mod=}, {repeat=}")
            case tcod.event.MouseButtonDown(button=button, pixel=pixel, tile=tile):
                print(f"MouseButtonDown: {button=}, {pixel=}, {tile=}")
            case tcod.event.MouseMotion(pixel=pixel, pixel_motion=pixel_motion, tile=tile, tile_motion=tile_motion):
                print(f"MouseMotion: {pixel=}, {pixel_motion=}, {tile=}, {tile_motion=}")
            case tcod.event.Event() as event:
                print(event)  # Show any unhandled events.

New in version 8.4.

class tcod.event.Point(x: int, y: int)[source]#

A 2D position used for events with mouse coordinates.

x: int#: A pixel or tile coordinate starting with zero as the left-most position.

y: int#: A pixel or tile coordinate starting with zero as the top-most position.

class tcod.event.Event(type: str | None = None)[source]#

The base event class.

type#

This events type.

Type:: str

sdl_event#: When available, this holds a python-cffi ‘SDL_Event*’ pointer. All sub-classes have this attribute.

classmethod from_sdl_event(sdl_event: Any) → Event[source]#: Return a class instance from a python-cffi ‘SDL_Event*’ pointer.

class tcod.event.Quit(type: str | None = None)[source]#

An application quit request event.

For more info on when this event is triggered see: https://wiki.libsdl.org/SDL_EventType#SDL_QUIT

type#

Always “QUIT”.

Type:: str

classmethod from_sdl_event(sdl_event: Any) → Quit[source]#: Return a class instance from a python-cffi ‘SDL_Event*’ pointer.

class tcod.event.KeyboardEvent(scancode: int, sym: int, mod: int, repeat: bool = False)[source]#

Base keyboard event.

type#

Will be “KEYDOWN” or “KEYUP”, depending on the event.

Type:: str

scancode#

The keyboard scan-code, this is the physical location of the key on the keyboard rather than the keys symbol.

Type:: Scancode

sym#

The keyboard symbol.

Type:: KeySym

mod#

A bitmask of the currently held modifier keys.

For example, if shift is held then event.mod & tcod.event.Modifier.SHIFT will evaluate to a true value.

Type:: Modifier

repeat#

True if this event exists because of key repeat.

Type:: bool

Changed in version 12.5: scancode, sym, and mod now use their respective enums.

classmethod from_sdl_event(sdl_event: Any) → Any[source]#: Return a class instance from a python-cffi ‘SDL_Event*’ pointer.

class tcod.event.KeyDown(scancode: int, sym: int, mod: int, repeat: bool = False)[source]#

class tcod.event.KeyUp(scancode: int, sym: int, mod: int, repeat: bool = False)[source]#

class tcod.event.MouseMotion(position: tuple[int, int] = (0, 0), motion: tuple[int, int] = (0, 0), tile: tuple[int, int] | None = (0, 0), tile_motion: tuple[int, int] | None = (0, 0), state: int = 0)[source]#

Mouse motion event.

type#

Always “MOUSEMOTION”.

Type:: str

position#

The pixel coordinates of the mouse.

Type:: Point

motion#

The pixel delta.

Type:: Point

tile#

The integer tile coordinates of the mouse on the screen.

Type:: Point

tile_motion#

The integer tile delta.

Type:: Point

state#

A bitmask of which mouse buttons are currently held.

Will be a combination of the following names:

tcod.event.BUTTON_LMASK
tcod.event.BUTTON_MMASK
tcod.event.BUTTON_RMASK
tcod.event.BUTTON_X1MASK
tcod.event.BUTTON_X2MASK

Type:: int

Changed in version 15.0: Renamed pixel attribute to position. Renamed pixel_motion attribute to motion.

classmethod from_sdl_event(sdl_event: Any) → MouseMotion[source]#: Return a class instance from a python-cffi ‘SDL_Event*’ pointer.

class tcod.event.MouseButtonEvent(pixel: tuple[int, int] = (0, 0), tile: tuple[int, int] | None = (0, 0), button: int = 0)[source]#

Mouse button event.

type#

Will be “MOUSEBUTTONDOWN” or “MOUSEBUTTONUP”, depending on the event.

Type:: str

position#

The pixel coordinates of the mouse.

Type:: Point

tile#

The integer tile coordinates of the mouse on the screen.

Type:: Point

button#

Which mouse button.

This will be one of the following names:

tcod.event.BUTTON_LEFT
tcod.event.BUTTON_MIDDLE
tcod.event.BUTTON_RIGHT
tcod.event.BUTTON_X1
tcod.event.BUTTON_X2

Type:: int

classmethod from_sdl_event(sdl_event: Any) → Any[source]#: Return a class instance from a python-cffi ‘SDL_Event*’ pointer.

class tcod.event.MouseButtonDown(pixel: tuple[int, int] = (0, 0), tile: tuple[int, int] | None = (0, 0), button: int = 0)[source]#: Same as MouseButtonEvent but with type="MouseButtonDown".

class tcod.event.MouseButtonUp(pixel: tuple[int, int] = (0, 0), tile: tuple[int, int] | None = (0, 0), button: int = 0)[source]#: Same as MouseButtonEvent but with type="MouseButtonUp".

class tcod.event.MouseWheel(x: int, y: int, flipped: bool = False)[source]#

Mouse wheel event.

type#

Always “MOUSEWHEEL”.

Type:: str

x#

Horizontal scrolling. A positive value means scrolling right.

Type:: int

y#

Vertical scrolling. A positive value means scrolling away from the user.

Type:: int

flipped#

If True then the values of x and y are the opposite of their usual values. This depends on the settings of the Operating System.

Type:: bool

classmethod from_sdl_event(sdl_event: Any) → MouseWheel[source]#: Return a class instance from a python-cffi ‘SDL_Event*’ pointer.

class tcod.event.TextInput(text: str)[source]#

SDL text input event.

type#

Always “TEXTINPUT”.

Type:: str

text#

A Unicode string with the input.

Type:: str

classmethod from_sdl_event(sdl_event: Any) → TextInput[source]#: Return a class instance from a python-cffi ‘SDL_Event*’ pointer.

class tcod.event.WindowEvent(type: str | None = None)[source]#

A window event.

type: Final[Literal['WindowShown', 'WindowHidden', 'WindowExposed', 'WindowMoved', 'WindowResized', 'WindowSizeChanged', 'WindowMinimized', 'WindowMaximized', 'WindowRestored', 'WindowEnter', 'WindowLeave', 'WindowFocusGained', 'WindowFocusLost', 'WindowClose', 'WindowTakeFocus', 'WindowHitTest']]#: The current window event. This can be one of various options.

classmethod from_sdl_event(sdl_event: Any) → WindowEvent | Undefined[source]#: Return a class instance from a python-cffi ‘SDL_Event*’ pointer.

class tcod.event.WindowMoved(x: int, y: int)[source]#

Window moved event.

x#

Movement on the x-axis.

Type:: int

y#

Movement on the y-axis.

Type:: int

type: Final[Literal['WINDOWMOVED']]#: Always “WINDOWMOVED”.

class tcod.event.WindowResized(type: str, width: int, height: int)[source]#

Window resized event.

width#

The current width of the window.

Type:: int

height#

The current height of the window.

Type:: int

type: Final[Literal['WindowResized', 'WindowSizeChanged']]#: WindowResized” or “WindowSizeChanged

class tcod.event.JoystickEvent(type: str, which: int)[source]#

A base class for joystick events.

New in version 13.8.

which#: The ID of the joystick this event is for.

class tcod.event.JoystickAxis(type: str, which: int, axis: int, value: int)[source]#

When a joystick axis changes in value.

New in version 13.8.

See also

tcod.sdl.joystick

which: int#: The ID of the joystick this event is for.

axis#: The index of the changed axis.

value#: The raw value of the axis in the range -32768 to 32767.

classmethod from_sdl_event(sdl_event: Any) → JoystickAxis[source]#: Return a class instance from a python-cffi ‘SDL_Event*’ pointer.

class tcod.event.JoystickBall(type: str, which: int, ball: int, dx: int, dy: int)[source]#

When a joystick ball is moved.

New in version 13.8.

See also

tcod.sdl.joystick

which: int#: The ID of the joystick this event is for.

ball#: The index of the moved ball.

dx#: The X motion of the ball.

dy#: The Y motion of the ball.

classmethod from_sdl_event(sdl_event: Any) → JoystickBall[source]#: Return a class instance from a python-cffi ‘SDL_Event*’ pointer.

class tcod.event.JoystickHat(type: str, which: int, x: Literal[-1, 0, 1], y: Literal[-1, 0, 1])[source]#

When a joystick hat changes direction.

New in version 13.8.

See also

tcod.sdl.joystick

which: int#: The ID of the joystick this event is for.

x#: The new X direction of the hat.

y#: The new Y direction of the hat.

classmethod from_sdl_event(sdl_event: Any) → JoystickHat[source]#: Return a class instance from a python-cffi ‘SDL_Event*’ pointer.

class tcod.event.JoystickButton(type: str, which: int, button: int)[source]#

When a joystick button is pressed or released.

New in version 13.8.

Example:

for event in tcod.event.get():
    match event:
        case JoystickButton(which=which, button=button, pressed=True):
            print(f"Pressed {button=} on controller {which}.")
        case JoystickButton(which=which, button=button, pressed=False):
            print(f"Released {button=} on controller {which}.")

which: int#: The ID of the joystick this event is for.

button#: The index of the button this event is for.

property pressed: bool#: True if the joystick button has been pressed, False when the button was released.

classmethod from_sdl_event(sdl_event: Any) → JoystickButton[source]#: Return a class instance from a python-cffi ‘SDL_Event*’ pointer.

class tcod.event.JoystickDevice(type: str, which: int)[source]#

An event for when a joystick is added or removed.

New in version 13.8.

Example:

joysticks: set[tcod.sdl.joystick.Joystick] = {}
for event in tcod.event.get():
    match event:
        case tcod.event.JoystickDevice(type="JOYDEVICEADDED", joystick=new_joystick):
            joysticks.add(new_joystick)
        case tcod.event.JoystickDevice(type="JOYDEVICEREMOVED", joystick=joystick):
            joysticks.remove(joystick)

which: int#: When type=”JOYDEVICEADDED” this is the device ID. When type=”JOYDEVICEREMOVED” this is the instance ID.

classmethod from_sdl_event(sdl_event: Any) → JoystickDevice[source]#: Return a class instance from a python-cffi ‘SDL_Event*’ pointer.

class tcod.event.ControllerEvent(type: str, which: int)[source]#

Base class for controller events.

New in version 13.8.

which#: The ID of the joystick this event is for.

property controller: GameController#: The GameController for this event.

class tcod.event.ControllerAxis(type: str, which: int, axis: ControllerAxis, value: int)[source]#

When a controller axis is moved.

New in version 13.8.

axis#: Which axis is being moved. One of ControllerAxis.

value#

The new value of this events axis.

This will be -32768 to 32767 for all axes except for triggers which are 0 to 32767 instead.

classmethod from_sdl_event(sdl_event: Any) → ControllerAxis[source]#: Return a class instance from a python-cffi ‘SDL_Event*’ pointer.

class tcod.event.ControllerButton(type: str, which: int, button: ControllerButton, pressed: bool)[source]#

When a controller button is pressed or released.

New in version 13.8.

button#: The button for this event. One of ControllerButton.

pressed#: True if the button was pressed, False if it was released.

classmethod from_sdl_event(sdl_event: Any) → ControllerButton[source]#: Return a class instance from a python-cffi ‘SDL_Event*’ pointer.

class tcod.event.ControllerDevice(type: str, which: int)[source]#

When a controller is added, removed, or remapped.

New in version 13.8.

classmethod from_sdl_event(sdl_event: Any) → ControllerDevice[source]#: Return a class instance from a python-cffi ‘SDL_Event*’ pointer.

class tcod.event.Undefined[source]#

This class is a place holder for SDL events without their own tcod.event class.

classmethod from_sdl_event(sdl_event: Any) → Undefined[source]#: Return a class instance from a python-cffi ‘SDL_Event*’ pointer.

tcod.event.get_mouse_state() → MouseState[source]#: Return the current state of the mouse.

New in version 9.3.

tcod.event.add_watch(callback: _EventCallback) → _EventCallback[source]#

Add a callback for watching events.

This function can be called with the callback to register, or be used as a decorator.

Callbacks added as event watchers can later be removed with tcod.event.remove_watch.

Warning

How uncaught exceptions in a callback are handled is not currently defined by tcod. They will likely be handled by sys.unraisablehook. This may be later changed to pass the exception to a tcod.event.get or tcod.event.wait call.

Parameters:: callback (Callable[[Event], None]) – A function which accepts Event parameters.

Example:

import tcod.event

@tcod.event.add_watch
def handle_events(event: tcod.event.Event) -> None:
    if isinstance(event, tcod.event.KeyDown):
        print(event)

New in version 13.4.

tcod.event.remove_watch(callback: Callable[[Event], None]) → None[source]#

Remove a callback as an event watcher.

Parameters:: callback (Callable[[Event], None]) – A function which has been previously registered with tcod.event.add_watch.

New in version 13.4.

class tcod.event.EventDispatch[source]#

Dispatches events to methods depending on the events type attribute.

To use this class, make a sub-class and override the relevant ev_* methods. Then send events to the dispatch method.

Changed in version 11.12: This is now a generic class. The type hints at the return value of dispatch and the ev_* methods.

Example:

import tcod

MOVE_KEYS = {  # key_symbol: (x, y)
    # Arrow keys.
    tcod.event.KeySym.LEFT: (-1, 0),
    tcod.event.KeySym.RIGHT: (1, 0),
    tcod.event.KeySym.UP: (0, -1),
    tcod.event.KeySym.DOWN: (0, 1),
    tcod.event.KeySym.HOME: (-1, -1),
    tcod.event.KeySym.END: (-1, 1),
    tcod.event.KeySym.PAGEUP: (1, -1),
    tcod.event.KeySym.PAGEDOWN: (1, 1),
    tcod.event.KeySym.PERIOD: (0, 0),
    # Numpad keys.
    tcod.event.KeySym.KP_1: (-1, 1),
    tcod.event.KeySym.KP_2: (0, 1),
    tcod.event.KeySym.KP_3: (1, 1),
    tcod.event.KeySym.KP_4: (-1, 0),
    tcod.event.KeySym.KP_5: (0, 0),
    tcod.event.KeySym.KP_6: (1, 0),
    tcod.event.KeySym.KP_7: (-1, -1),
    tcod.event.KeySym.KP_8: (0, -1),
    tcod.event.KeySym.KP_9: (1, -1),
    tcod.event.KeySym.CLEAR: (0, 0),  # Numpad `clear` key.
    # Vi Keys.
    tcod.event.KeySym.h: (-1, 0),
    tcod.event.KeySym.j: (0, 1),
    tcod.event.KeySym.k: (0, -1),
    tcod.event.KeySym.l: (1, 0),
    tcod.event.KeySym.y: (-1, -1),
    tcod.event.KeySym.u: (1, -1),
    tcod.event.KeySym.b: (-1, 1),
    tcod.event.KeySym.n: (1, 1),
}


class State(tcod.event.EventDispatch[None]):
    """A state-based superclass that converts `events` into `commands`.

    The configuration used to convert events to commands are hard-coded
    in this example, but could be modified to be user controlled.

    Subclasses will override the `cmd_*` methods with their own
    functionality.  There could be a subclass for every individual state
    of your game.
    """

    def ev_quit(self, event: tcod.event.Quit) -> None:
        """The window close button was clicked or Alt+F$ was pressed."""
        print(event)
        self.cmd_quit()

    def ev_keydown(self, event: tcod.event.KeyDown) -> None:
        """A key was pressed."""
        print(event)
        if event.sym in MOVE_KEYS:
            # Send movement keys to the cmd_move method with parameters.
            self.cmd_move(*MOVE_KEYS[event.sym])
        elif event.sym == tcod.event.KeySym.ESCAPE:
            self.cmd_escape()

    def ev_mousebuttondown(self, event: tcod.event.MouseButtonDown) -> None:
        """The window was clicked."""
        print(event)

    def ev_mousemotion(self, event: tcod.event.MouseMotion) -> None:
        """The mouse has moved within the window."""
        print(event)

    def cmd_move(self, x: int, y: int) -> None:
        """Intent to move: `x` and `y` is the direction, both may be 0."""
        print("Command move: " + str((x, y)))

    def cmd_escape(self) -> None:
        """Intent to exit this state."""
        print("Command escape.")
        self.cmd_quit()

    def cmd_quit(self) -> None:
        """Intent to exit the game."""
        print("Command quit.")
        raise SystemExit()


root_console = libtcodpy.console_init_root(80, 60)
state = State()
while True:
    libtcodpy.console_flush()
    for event in tcod.event.wait():
        state.dispatch(event)

dispatch(event: Any) → T | None[source]#

Send an event to an ev_* method.

* will be the event.type attribute converted to lower-case.

Values returned by ev_* calls will be returned by this function. This value always defaults to None for any non-overridden method.

Changed in version 11.12: Now returns the return value of ev_* methods. event.type values of None are deprecated.

ev_quit(event: Quit) → T | None[source]#: Called when the termination of the program is requested.

ev_keydown(event: KeyDown) → T | None[source]#: Called when a keyboard key is pressed or repeated.

ev_keyup(event: KeyUp) → T | None[source]#: Called when a keyboard key is released.

ev_mousemotion(event: MouseMotion) → T | None[source]#: Called when the mouse is moved.

ev_mousebuttondown(event: MouseButtonDown) → T | None[source]#: Called when a mouse button is pressed.

ev_mousebuttonup(event: MouseButtonUp) → T | None[source]#: Called when a mouse button is released.

ev_mousewheel(event: MouseWheel) → T | None[source]#: Called when the mouse wheel is scrolled.

ev_textinput(event: TextInput) → T | None[source]#: Called to handle Unicode input.

ev_windowshown(event: WindowEvent) → T | None[source]#: Called when the window is shown.

ev_windowhidden(event: WindowEvent) → T | None[source]#: Called when the window is hidden.

ev_windowexposed(event: WindowEvent) → T | None[source]#

Called when a window is exposed, and needs to be refreshed.

This usually means a call to libtcodpy.console_flush is necessary.

ev_windowmoved(event: WindowMoved) → T | None[source]#: Called when the window is moved.

ev_windowresized(event: WindowResized) → T | None[source]#: Called when the window is resized.

ev_windowsizechanged(event: WindowResized) → T | None[source]#: Called when the system or user changes the size of the window.

ev_windowminimized(event: WindowEvent) → T | None[source]#: Called when the window is minimized.

ev_windowmaximized(event: WindowEvent) → T | None[source]#: Called when the window is maximized.

ev_windowrestored(event: WindowEvent) → T | None[source]#: Called when the window is restored.

ev_windowenter(event: WindowEvent) → T | None[source]#: Called when the window gains mouse focus.

ev_windowleave(event: WindowEvent) → T | None[source]#: Called when the window loses mouse focus.

ev_windowfocusgained(event: WindowEvent) → T | None[source]#: Called when the window gains keyboard focus.

ev_windowfocuslost(event: WindowEvent) → T | None[source]#: Called when the window loses keyboard focus.

ev_windowclose(event: WindowEvent) → T | None[source]#: Called when the window manager requests the window to be closed.

ev_joyaxismotion(event: JoystickAxis) → T | None[source]#: Called when a joystick analog is moved.

New in version 13.8.

ev_joyballmotion(event: JoystickBall) → T | None[source]#: Called when a joystick ball is moved.

New in version 13.8.

ev_joyhatmotion(event: JoystickHat) → T | None[source]#: Called when a joystick hat is moved.

New in version 13.8.

ev_joybuttondown(event: JoystickButton) → T | None[source]#: Called when a joystick button is pressed.

New in version 13.8.

ev_joybuttonup(event: JoystickButton) → T | None[source]#: Called when a joystick button is released.

New in version 13.8.

ev_joydeviceadded(event: JoystickDevice) → T | None[source]#: Called when a joystick is added.

New in version 13.8.

ev_joydeviceremoved(event: JoystickDevice) → T | None[source]#: Called when a joystick is removed.

New in version 13.8.

ev_controlleraxismotion(event: ControllerAxis) → T | None[source]#: Called when a controller analog is moved.

New in version 13.8.

ev_controllerbuttondown(event: ControllerButton) → T | None[source]#: Called when a controller button is pressed.

New in version 13.8.

ev_controllerbuttonup(event: ControllerButton) → T | None[source]#: Called when a controller button is released.

New in version 13.8.

ev_controllerdeviceadded(event: ControllerDevice) → T | None[source]#: Called when a standard controller is added.

New in version 13.8.

ev_controllerdeviceremoved(event: ControllerDevice) → T | None[source]#: Called when a standard controller is removed.

New in version 13.8.

ev_controllerdeviceremapped(event: ControllerDevice) → T | None[source]#: Called when a standard controller is remapped.

New in version 13.8.

tcod.event.get_keyboard_state() → NDArray[np.bool_][source]#

Return a boolean array with the current keyboard state.

Index this array with a scancode. The value will be True if the key is currently held.

Example:

state = tcod.event.get_keyboard_state()

# Get a WASD movement vector:
x = int(state[tcod.event.Scancode.D]) - int(state[tcod.event.Scancode.A])
y = int(state[tcod.event.Scancode.S]) - int(state[tcod.event.Scancode.W])

# Key with 'z' glyph is held:
is_z_held = state[tcod.event.KeySym.z.scancode]

New in version 12.3.

tcod.event.get_modifier_state() → Modifier[source]#: Return a bitmask of the active keyboard modifiers.

New in version 12.3.

tcod.event.__getattr__(name: str) → int[source]#: Migrate deprecated access of event constants.

Getting events#

The primary way to capture events is with the tcod.event.get and tcod.event.wait functions. These functions return events in a loop until the internal event queue is empty. Use isinstance(), tcod.event.EventDispatch, or match statements (introduced in Python 3.10) to determine which event was returned.

tcod.event.get() → Iterator[Any][source]#

Return an iterator for all pending events.

Events are processed as the iterator is consumed. Breaking out of, or discarding the iterator will leave the remaining events on the event queue. It is also safe to call this function inside of a loop that is already handling events (the event iterator is reentrant.)

tcod.event.wait(timeout: float | None = None) → Iterator[Any][source]#

Block until events exist, then return an event iterator.

timeout is the maximum number of seconds to wait as a floating point number with millisecond precision, or it can be None to wait forever.

Returns the same iterator as a call to tcod.event.get.

This function is useful for simple games with little to no animations. The following example sleeps whenever no events are queued:

Example:

context: tcod.context.Context  # Context object initialized earlier.
while True:  # Main game-loop.
    console: tcod.console.Console  # Console used for rendering.
    ...  # Render the frame to `console` and then:
    context.present(console)  # Show the console to the display.
    # The ordering to draw first before waiting for events is important.
    for event in tcod.event.wait():  # Sleeps until the next events exist.
        ...  # All events are handled at once before the next frame.

See tcod.event.get examples for how different events are handled.

Keyboard Enums#

KeySym: Keys based on their glyph.
Scancode: Keys based on their physical location.
Modifier: Keyboard modifier keys.

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

Keyboard constants based on their symbol.

These names are derived from SDL except for the numbers which are prefixed with N (since raw numbers can not be a Python name.)

New in version 12.3.

UNKNOWN	0
BACKSPACE	8
TAB	9
RETURN	13
ESCAPE	27
SPACE	32
EXCLAIM	33
QUOTEDBL	34
HASH	35
DOLLAR	36
PERCENT	37
AMPERSAND	38
QUOTE	39
LEFTPAREN	40
RIGHTPAREN	41
ASTERISK	42
PLUS	43
COMMA	44
MINUS	45
PERIOD	46
SLASH	47
N0	48
N1	49
N2	50
N3	51
N4	52
N5	53
N6	54
N7	55
N8	56
N9	57
COLON	58
SEMICOLON	59
LESS	60
EQUALS	61
GREATER	62
QUESTION	63
AT	64
LEFTBRACKET	91
BACKSLASH	92
RIGHTBRACKET	93
CARET	94
UNDERSCORE	95
BACKQUOTE	96
a	97
b	98
c	99
d	100
e	101
f	102
g	103
h	104
i	105
j	106
k	107
l	108
m	109
n	110
o	111
p	112
q	113
r	114
s	115
t	116
u	117
v	118
w	119
x	120
y	121
z	122
DELETE	127
SCANCODE_MASK	1073741824
CAPSLOCK	1073741881
F1	1073741882
F2	1073741883
F3	1073741884
F4	1073741885
F5	1073741886
F6	1073741887
F7	1073741888
F8	1073741889
F9	1073741890
F10	1073741891
F11	1073741892
F12	1073741893
PRINTSCREEN	1073741894
SCROLLLOCK	1073741895
PAUSE	1073741896
INSERT	1073741897
HOME	1073741898
PAGEUP	1073741899
END	1073741901
PAGEDOWN	1073741902
RIGHT	1073741903
LEFT	1073741904
DOWN	1073741905
UP	1073741906
NUMLOCKCLEAR	1073741907
KP_DIVIDE	1073741908
KP_MULTIPLY	1073741909
KP_MINUS	1073741910
KP_PLUS	1073741911
KP_ENTER	1073741912
KP_1	1073741913
KP_2	1073741914
KP_3	1073741915
KP_4	1073741916
KP_5	1073741917
KP_6	1073741918
KP_7	1073741919
KP_8	1073741920
KP_9	1073741921
KP_0	1073741922
KP_PERIOD	1073741923
APPLICATION	1073741925
POWER	1073741926
KP_EQUALS	1073741927
F13	1073741928
F14	1073741929
F15	1073741930
F16	1073741931
F17	1073741932
F18	1073741933
F19	1073741934
F20	1073741935
F21	1073741936
F22	1073741937
F23	1073741938
F24	1073741939
EXECUTE	1073741940
HELP	1073741941
MENU	1073741942
SELECT	1073741943
STOP	1073741944
AGAIN	1073741945
UNDO	1073741946
CUT	1073741947
COPY	1073741948
PASTE	1073741949
FIND	1073741950
MUTE	1073741951
VOLUMEUP	1073741952
VOLUMEDOWN	1073741953
KP_COMMA	1073741957
KP_EQUALSAS400	1073741958
ALTERASE	1073741977
SYSREQ	1073741978
CANCEL	1073741979
CLEAR	1073741980
PRIOR	1073741981
RETURN2	1073741982
SEPARATOR	1073741983
OUT	1073741984
OPER	1073741985
CLEARAGAIN	1073741986
CRSEL	1073741987
EXSEL	1073741988
KP_00	1073742000
KP_000	1073742001
THOUSANDSSEPARATOR	1073742002
DECIMALSEPARATOR	1073742003
CURRENCYUNIT	1073742004
CURRENCYSUBUNIT	1073742005
KP_LEFTPAREN	1073742006
KP_RIGHTPAREN	1073742007
KP_LEFTBRACE	1073742008
KP_RIGHTBRACE	1073742009
KP_TAB	1073742010
KP_BACKSPACE	1073742011
KP_A	1073742012
KP_B	1073742013
KP_C	1073742014
KP_D	1073742015
KP_E	1073742016
KP_F	1073742017
KP_XOR	1073742018
KP_POWER	1073742019
KP_PERCENT	1073742020
KP_LESS	1073742021
KP_GREATER	1073742022
KP_AMPERSAND	1073742023
KP_DBLAMPERSAND	1073742024
KP_VERTICALBAR	1073742025
KP_DBLVERTICALBAR	1073742026
KP_COLON	1073742027
KP_HASH	1073742028
KP_SPACE	1073742029
KP_AT	1073742030
KP_EXCLAM	1073742031
KP_MEMSTORE	1073742032
KP_MEMRECALL	1073742033
KP_MEMCLEAR	1073742034
KP_MEMADD	1073742035
KP_MEMSUBTRACT	1073742036
KP_MEMMULTIPLY	1073742037
KP_MEMDIVIDE	1073742038
KP_PLUSMINUS	1073742039
KP_CLEAR	1073742040
KP_CLEARENTRY	1073742041
KP_BINARY	1073742042
KP_OCTAL	1073742043
KP_DECIMAL	1073742044
KP_HEXADECIMAL	1073742045
LCTRL	1073742048
LSHIFT	1073742049
LALT	1073742050
LGUI	1073742051
RCTRL	1073742052
RSHIFT	1073742053
RALT	1073742054
RGUI	1073742055
MODE	1073742081
AUDIONEXT	1073742082
AUDIOPREV	1073742083
AUDIOSTOP	1073742084
AUDIOPLAY	1073742085
AUDIOMUTE	1073742086
MEDIASELECT	1073742087
WWW	1073742088
MAIL	1073742089
CALCULATOR	1073742090
COMPUTER	1073742091
AC_SEARCH	1073742092
AC_HOME	1073742093
AC_BACK	1073742094
AC_FORWARD	1073742095
AC_STOP	1073742096
AC_REFRESH	1073742097
AC_BOOKMARKS	1073742098
BRIGHTNESSDOWN	1073742099
BRIGHTNESSUP	1073742100
DISPLAYSWITCH	1073742101
KBDILLUMTOGGLE	1073742102
KBDILLUMDOWN	1073742103
KBDILLUMUP	1073742104
EJECT	1073742105
SLEEP	1073742106

__repr__() → str[source]#: Return the fully qualified name of this enum.

property keysym: KeySym#

Return a keycode from a scancode.

Returns itself since it is already a KeySym.

See also

Scancode.keysym

property label: str#

A human-readable name of a keycode.

Returns “” if the keycode doesn’t have a name.

Be sure not to confuse this with .name, which will return the enum name rather than the human-readable name.

Example:

>>> tcod.event.KeySym.F1.label
'F1'
>>> tcod.event.KeySym.BACKSPACE.label
'Backspace'

property scancode: Scancode#

Return a scancode from a keycode.

Based on the current keyboard layout.

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

A Scancode represents the physical location of a key.

For example the scan codes for WASD remain in the same physical location regardless of the actual keyboard layout.

These names are derived from SDL except for the numbers which are prefixed with N (since raw numbers can not be a Python name.)

New in version 12.3.

UNKNOWN	0
A	4
B	5
C	6
D	7
E	8
F	9
G	10
H	11
I	12
J	13
K	14
L	15
M	16
N	17
O	18
P	19
Q	20
R	21
S	22
T	23
U	24
V	25
W	26
X	27
Y	28
Z	29
N1	30
N2	31
N3	32
N4	33
N5	34
N6	35
N7	36
N8	37
N9	38
N0	39
RETURN	40
ESCAPE	41
BACKSPACE	42
TAB	43
SPACE	44
MINUS	45
EQUALS	46
LEFTBRACKET	47
RIGHTBRACKET	48
BACKSLASH	49
NONUSHASH	50
SEMICOLON	51
APOSTROPHE	52
GRAVE	53
COMMA	54
PERIOD	55
SLASH	56
CAPSLOCK	57
F1	58
F2	59
F3	60
F4	61
F5	62
F6	63
F7	64
F8	65
F9	66
F10	67
F11	68
F12	69
PRINTSCREEN	70
SCROLLLOCK	71
PAUSE	72
INSERT	73
HOME	74
PAGEUP	75
DELETE	76
END	77
PAGEDOWN	78
RIGHT	79
LEFT	80
DOWN	81
UP	82
NUMLOCKCLEAR	83
KP_DIVIDE	84
KP_MULTIPLY	85
KP_MINUS	86
KP_PLUS	87
KP_ENTER	88
KP_1	89
KP_2	90
KP_3	91
KP_4	92
KP_5	93
KP_6	94
KP_7	95
KP_8	96
KP_9	97
KP_0	98
KP_PERIOD	99
NONUSBACKSLASH	100
APPLICATION	101
POWER	102
KP_EQUALS	103
F13	104
F14	105
F15	106
F16	107
F17	108
F18	109
F19	110
F20	111
F21	112
F22	113
F23	114
F24	115
EXECUTE	116
HELP	117
MENU	118
SELECT	119
STOP	120
AGAIN	121
UNDO	122
CUT	123
COPY	124
PASTE	125
FIND	126
MUTE	127
VOLUMEUP	128
VOLUMEDOWN	129
KP_COMMA	133
KP_EQUALSAS400	134
INTERNATIONAL1	135
INTERNATIONAL2	136
INTERNATIONAL3	137
INTERNATIONAL4	138
INTERNATIONAL5	139
INTERNATIONAL6	140
INTERNATIONAL7	141
INTERNATIONAL8	142
INTERNATIONAL9	143
LANG1	144
LANG2	145
LANG3	146
LANG4	147
LANG5	148
LANG6	149
LANG7	150
LANG8	151
LANG9	152
ALTERASE	153
SYSREQ	154
CANCEL	155
CLEAR	156
PRIOR	157
RETURN2	158
SEPARATOR	159
OUT	160
OPER	161
CLEARAGAIN	162
CRSEL	163
EXSEL	164
KP_00	176
KP_000	177
THOUSANDSSEPARATOR	178
DECIMALSEPARATOR	179
CURRENCYUNIT	180
CURRENCYSUBUNIT	181
KP_LEFTPAREN	182
KP_RIGHTPAREN	183
KP_LEFTBRACE	184
KP_RIGHTBRACE	185
KP_TAB	186
KP_BACKSPACE	187
KP_A	188
KP_B	189
KP_C	190
KP_D	191
KP_E	192
KP_F	193
KP_XOR	194
KP_POWER	195
KP_PERCENT	196
KP_LESS	197
KP_GREATER	198
KP_AMPERSAND	199
KP_DBLAMPERSAND	200
KP_VERTICALBAR	201
KP_DBLVERTICALBAR	202
KP_COLON	203
KP_HASH	204
KP_SPACE	205
KP_AT	206
KP_EXCLAM	207
KP_MEMSTORE	208
KP_MEMRECALL	209
KP_MEMCLEAR	210
KP_MEMADD	211
KP_MEMSUBTRACT	212
KP_MEMMULTIPLY	213
KP_MEMDIVIDE	214
KP_PLUSMINUS	215
KP_CLEAR	216
KP_CLEARENTRY	217
KP_BINARY	218
KP_OCTAL	219
KP_DECIMAL	220
KP_HEXADECIMAL	221
LCTRL	224
LSHIFT	225
LALT	226
LGUI	227
RCTRL	228
RSHIFT	229
RALT	230
RGUI	231
MODE	257
AUDIONEXT	258
AUDIOPREV	259
AUDIOSTOP	260
AUDIOPLAY	261
AUDIOMUTE	262
MEDIASELECT	263
WWW	264
MAIL	265
CALCULATOR	266
COMPUTER	267
AC_SEARCH	268
AC_HOME	269
AC_BACK	270
AC_FORWARD	271
AC_STOP	272
AC_REFRESH	273
AC_BOOKMARKS	274
BRIGHTNESSDOWN	275
BRIGHTNESSUP	276
DISPLAYSWITCH	277
KBDILLUMTOGGLE	278
KBDILLUMDOWN	279
KBDILLUMUP	280
EJECT	281
SLEEP	282
APP1	283
APP2	284

__repr__() → str[source]#: Return the fully qualified name of this enum.

property keysym: KeySym#

Return a KeySym from a scancode.

Based on the current keyboard layout.

property label: str#

Return a human-readable name of a key based on its scancode.

Be sure not to confuse this with .name, which will return the enum name rather than the human-readable name.

See also

KeySym.label

property scancode: Scancode#

Return a scancode from a keycode.

Returns itself since it is already a Scancode.

See also

KeySym.scancode

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

Keyboard modifier flags, a bit-field of held modifier keys.

Use bitwise and to check if a modifier key is held.

The following example shows some common ways of checking modifiers. All non-zero return values are considered true.

Example:

>>> mod = tcod.event.Modifier(4098)
>>> mod & tcod.event.Modifier.SHIFT  # Check if any shift key is held.
<Modifier.RSHIFT: 2>
>>> mod & tcod.event.Modifier.LSHIFT  # Check if left shift key is held.
<Modifier.NONE: 0>
>>> not mod & tcod.event.Modifier.LSHIFT  # Check if left shift key is NOT held.
True
>>> mod & tcod.event.Modifier.SHIFT and mod & tcod.event.Modifier.CTRL  # Check if Shift+Control is held.
<Modifier.NONE: 0>

New in version 12.3.

NONE = 0#

LSHIFT = 1#: Left shift.

RSHIFT = 2#: Right shift.

SHIFT = 3#: LSHIFT | RSHIFT

LCTRL = 64#: Left control.

RCTRL = 128#: Right control.

CTRL = 192#: LCTRL | RCTRL

LALT = 256#: Left alt.

RALT = 512#: Right alt.

ALT = 768#: LALT | RALT

LGUI = 1024#: Left meta key.

RGUI = 2048#: Right meta key.

GUI = 3072#: LGUI | RGUI

NUM = 4096#: Numpad lock.

CAPS = 8192#: Caps lock.

MODE = 16384#: Alt graph.

SDL2 Event Handling tcod.event#

Getting events#

Keyboard Enums#

SDL2 Event Handling `tcod.event`#