tcod.event - SDL2 Event Handling

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

Many event constants are derived directly from SDL. For example: tcod.event.K_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.

Remember to add the line import tcod.event, as importing this module is not implied by import tcod.

New in version 8.4.

class tcod.event.Point(x, y)

x

Alias for field number 0

y

Alias for field number 1

class tcod.event.Event(type: Optional[str] = None)

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) → Any

Return a class instance from a python-cffi ‘SDL_Event*’ pointer.

class tcod.event.Quit(type: Optional[str] = None)

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) → tcod.event.Quit

Return a class instance from a python-cffi ‘SDL_Event*’ pointer.

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

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:int

sym

The keyboard symbol.

Type:int

mod

A bitmask of the currently held modifier keys.

You can use the following to check if a modifier key is held:

• tcod.event.KMOD_LSHIFT

  Left shift bit.

• tcod.event.KMOD_RSHIFT

  Right shift bit.

• tcod.event.KMOD_LCTRL

  Left control bit.

• tcod.event.KMOD_RCTRL

  Right control bit.

• tcod.event.KMOD_LALT

  Left alt bit.

• tcod.event.KMOD_RALT

  Right alt bit.

• tcod.event.KMOD_LGUI

  Left meta key bit.

• tcod.event.KMOD_RGUI

  Right meta key bit.

• tcod.event.KMOD_SHIFT

  tcod.event.KMOD_LSHIFT | tcod.event.KMOD_RSHIFT

• tcod.event.KMOD_CTRL

  tcod.event.KMOD_LCTRL | tcod.event.KMOD_RCTRL

• tcod.event.KMOD_ALT

  tcod.event.KMOD_LALT | tcod.event.KMOD_RALT

• tcod.event.KMOD_GUI

  tcod.event.KMOD_LGUI | tcod.event.KMOD_RGUI

• tcod.event.KMOD_NUM

  Num lock bit.

• tcod.event.KMOD_CAPS

  Caps lock bit.

• tcod.event.KMOD_MODE

  AltGr key bit.

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

Type:int

repeat

True if this event exists because of key repeat.

Type:bool

classmethod from_sdl_event(sdl_event: Any) → Any

Return a class instance from a python-cffi ‘SDL_Event*’ pointer.

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

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

class tcod.event.MouseMotion(pixel: Tuple[int, int] = (0, 0), pixel_motion: Tuple[int, int] = (0, 0), tile: Tuple[int, int] = (0, 0), tile_motion: Tuple[int, int] = (0, 0), state: int = 0)

type

Always “MOUSEMOTION”.

Type:str

pixel

The pixel coordinates of the mouse.

Type:Point

pixel_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

classmethod from_sdl_event(sdl_event: Any) → tcod.event.MouseMotion

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] = (0, 0), button: int = 0)

type

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

Type:str

pixel

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

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] = (0, 0), button: int = 0)

Same as MouseButtonEvent but with type="MouseButtonDown".

class tcod.event.MouseButtonUp(pixel: Tuple[int, int] = (0, 0), tile: Tuple[int, int] = (0, 0), button: int = 0)

Same as MouseButtonEvent but with type="MouseButtonUp".

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

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) → tcod.event.MouseWheel

Return a class instance from a python-cffi ‘SDL_Event*’ pointer.

class tcod.event.TextInput(text: str)

type

Always “TEXTINPUT”.

Type:str

text

A Unicode string with the input.

Type:str

classmethod from_sdl_event(sdl_event: Any) → tcod.event.TextInput

Return a class instance from a python-cffi ‘SDL_Event*’ pointer.

class tcod.event.WindowEvent(type: Optional[str] = None)

type

A window event could mean various event types.

Type:str

classmethod from_sdl_event(sdl_event: Any) → Any

Return a class instance from a python-cffi ‘SDL_Event*’ pointer.

class tcod.event.WindowMoved(x: int, y: int)

type

Always “WINDOWMOVED”.

Type:str

x

Movement on the x-axis.

Type:int

x

Movement on the y-axis.

Type:int

class tcod.event.WindowResized(type: str, width: int, height: int)

type

“WINDOWRESIZED” or “WINDOWSIZECHANGED”

Type:str

width

The current width of the window.

Type:int

height

The current height of the window.

Type:int

class tcod.event.Undefined

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

classmethod from_sdl_event(sdl_event: Any) → tcod.event.Undefined

Return a class instance from a python-cffi ‘SDL_Event*’ pointer.

class tcod.event.EventDispatch

This class 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 hists at the return value of dispatch and the ev_* methods.

Example:

import tcod

MOVE_KEYS = {  # key_symbol: (x, y)
    # Arrow keys.
    tcod.event.K_LEFT: (-1, 0),
    tcod.event.K_RIGHT: (1, 0),
    tcod.event.K_UP: (0, -1),
    tcod.event.K_DOWN: (0, 1),
    tcod.event.K_HOME: (-1, -1),
    tcod.event.K_END: (-1, 1),
    tcod.event.K_PAGEUP: (1, -1),
    tcod.event.K_PAGEDOWN: (1, 1),
    tcod.event.K_PERIOD: (0, 0),
    # Numpad keys.
    tcod.event.K_KP_1: (-1, 1),
    tcod.event.K_KP_2: (0, 1),
    tcod.event.K_KP_3: (1, 1),
    tcod.event.K_KP_4: (-1, 0),
    tcod.event.K_KP_5: (0, 0),
    tcod.event.K_KP_6: (1, 0),
    tcod.event.K_KP_7: (-1, -1),
    tcod.event.K_KP_8: (0, -1),
    tcod.event.K_KP_9: (1, -1),
    tcod.event.K_CLEAR: (0, 0),  # Numpad `clear` key.
    # Vi Keys.
    tcod.event.K_h: (-1, 0),
    tcod.event.K_j: (0, 1),
    tcod.event.K_k: (0, -1),
    tcod.event.K_l: (1, 0),
    tcod.event.K_y: (-1, -1),
    tcod.event.K_u: (1, -1),
    tcod.event.K_b: (-1, 1),
    tcod.event.K_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.K_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 = tcod.console_init_root(80, 60)
state = State()
while True:
    tcod.console_flush()
    for event in tcod.event.wait():
        state.dispatch(event)

dispatch(event: Any) → Optional[T]

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_keydown(event: tcod.event.KeyDown) → Optional[T]

Called when a keyboard key is pressed or repeated.

ev_keyup(event: tcod.event.KeyUp) → Optional[T]

Called when a keyboard key is released.

ev_mousebuttondown(event: tcod.event.MouseButtonDown) → Optional[T]

Called when a mouse button is pressed.

ev_mousebuttonup(event: tcod.event.MouseButtonUp) → Optional[T]

Called when a mouse button is released.

ev_mousemotion(event: tcod.event.MouseMotion) → Optional[T]

Called when the mouse is moved.

ev_mousewheel(event: tcod.event.MouseWheel) → Optional[T]

Called when the mouse wheel is scrolled.

ev_quit(event: tcod.event.Quit) → Optional[T]

Called when the termination of the program is requested.

ev_textinput(event: tcod.event.TextInput) → Optional[T]

Called to handle Unicode input.

ev_windowclose(event: tcod.event.WindowEvent) → Optional[T]

Called when the window manager requests the window to be closed.

ev_windowenter(event: tcod.event.WindowEvent) → Optional[T]

Called when the window gains mouse focus.

ev_windowexposed(event: tcod.event.WindowEvent) → Optional[T]

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

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

ev_windowfocusgained(event: tcod.event.WindowEvent) → Optional[T]

Called when the window gains keyboard focus.

ev_windowfocuslost(event: tcod.event.WindowEvent) → Optional[T]

Called when the window loses keyboard focus.

ev_windowhidden(event: tcod.event.WindowEvent) → Optional[T]

Called when the window is hidden.

ev_windowleave(event: tcod.event.WindowEvent) → Optional[T]

Called when the window loses mouse focus.

ev_windowmaximized(event: tcod.event.WindowEvent) → Optional[T]

Called when the window is maximized.

ev_windowminimized(event: tcod.event.WindowEvent) → Optional[T]

Called when the window is minimized.

ev_windowmoved(event: tcod.event.WindowMoved) → Optional[T]

Called when the window is moved.

ev_windowresized(event: tcod.event.WindowResized) → Optional[T]

Called when the window is resized.

ev_windowrestored(event: tcod.event.WindowEvent) → Optional[T]

Called when the window is restored.

ev_windowshown(event: tcod.event.WindowEvent) → Optional[T]

Called when the window is shown.

ev_windowsizechanged(event: tcod.event.WindowResized) → Optional[T]

Called when the system or user changes the size of the window.

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

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

Example:

for event in tcod.event.get():
    if event.type == "QUIT":
        print(event)
        raise SystemExit()
    elif event.type == "KEYDOWN":
        print(event)
    elif event.type == "MOUSEBUTTONDOWN":
        print(event)
    elif event.type == "MOUSEMOTION":
        print(event)
    else:
        print(event)
# For loop exits after all current events are processed.

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

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.

Example:

for event in tcod.event.wait():
    if event.type == "QUIT":
        print(event)
        raise SystemExit()
    elif event.type == "KEYDOWN":
        print(event)
    elif event.type == "MOUSEBUTTONDOWN":
        print(event)
    elif event.type == "MOUSEMOTION":
        print(event)
    else:
        print(event)
# For loop exits on timeout or after at least one event is processed.

tcod.event.get_mouse_state() → tcod.event.MouseState

Return the current state of the mouse.

New in version 9.3.