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.

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

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

Added in version 13.8.

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.

Added in version 13.8.

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.

Added in version 13.8.

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.

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

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

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

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

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

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

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

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

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

Added in version 13.8.

ev_joyballmotion(event: JoystickBall, /) T | None[source]

Called when a joystick ball is moved.

Added in version 13.8.

ev_joyhatmotion(event: JoystickHat, /) T | None[source]

Called when a joystick hat is moved.

Added in version 13.8.

ev_joybuttondown(event: JoystickButton, /) T | None[source]

Called when a joystick button is pressed.

Added in version 13.8.

ev_joybuttonup(event: JoystickButton, /) T | None[source]

Called when a joystick button is released.

Added in version 13.8.

ev_joydeviceadded(event: JoystickDevice, /) T | None[source]

Called when a joystick is added.

Added in version 13.8.

ev_joydeviceremoved(event: JoystickDevice, /) T | None[source]

Called when a joystick is removed.

Added in version 13.8.

ev_controlleraxismotion(event: ControllerAxis, /) T | None[source]

Called when a controller analog is moved.

Added in version 13.8.

ev_controllerbuttondown(event: ControllerButton, /) T | None[source]

Called when a controller button is pressed.

Added in version 13.8.

ev_controllerbuttonup(event: ControllerButton, /) T | None[source]

Called when a controller button is released.

Added in version 13.8.

ev_controllerdeviceadded(event: ControllerDevice, /) T | None[source]

Called when a standard controller is added.

Added in version 13.8.

ev_controllerdeviceremoved(event: ControllerDevice, /) T | None[source]

Called when a standard controller is removed.

Added in version 13.8.

ev_controllerdeviceremapped(event: ControllerDevice, /) T | None[source]

Called when a standard controller is remapped.

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

Added in version 12.3.

tcod.event.get_modifier_state() Modifier[source]

Return a bitmask of the active keyboard modifiers.

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

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

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

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