tcod.event

An alternative, more direct implementation of event handling based on using cffi calls to SDL functions. The current code is partially incomplete.

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. Do not use isinstance to tell events apart as that method won’t be forward compatible.

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)[source]

The base event class.

type

str – This events type.

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[source]

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

class tcod.event.Quit(type: Optional[str] = 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

str – Always “QUIT”.

classmethod from_sdl_event(sdl_event: Any) → tcod.event.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]
type

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

scancode

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

sym

int – The keyboard symbol.

mod

int – A bitmask of modifier keys.

repeat

bool – True if this event exists because of key repeat.

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(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)[source]
type

str – Always “MOUSEMOTION”.

pixel

Point – The pixel coordinates of the mouse.

pixel_motion

Point – The pixel delta.

tile

Point – The integer tile coordinates of the mouse on the screen.

tile_motion

Point – The integer tile delta.

state

int – 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
classmethod from_sdl_event(sdl_event: Any) → tcod.event.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] = (0, 0), button: int = 0)[source]
type

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

pixel

Point – The pixel coordinates of the mouse.

tile

Point – The integer tile coordinates of the mouse on the screen.

button

int – 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
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] = (0, 0), button: int = 0)[source]
class tcod.event.MouseButtonUp(pixel: Tuple[int, int] = (0, 0), tile: Tuple[int, int] = (0, 0), button: int = 0)[source]
class tcod.event.MouseWheel(x: int, y: int, flipped: bool = False)[source]
type

str – Always “MOUSEWHEEL”.

x

int – Horizontal scrolling. A positive value means scrolling right.

y

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

flipped

bool – If True then the values of x and y are the opposite of their usual values.

classmethod from_sdl_event(sdl_event: Any) → tcod.event.MouseWheel[source]

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

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

str – Always “TEXTINPUT”.

text

str – A Unicode string with the input.

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

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

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

str – A window event could mean various event types.

classmethod from_sdl_event(sdl_event: Any) → Any[source]

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

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

str – Always “WINDOWMOVED”.

x

int – Movement on the x-axis.

x

int – Movement on the y-axis.

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

str – “WINDOWRESIZED” or “WINDOWSIZECHANGED”

width

int – The current width of the window.

height

int – The current height of the window.

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) → tcod.event.Undefined[source]

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

class tcod.event.EventDispatch[source]

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.

Example:

import tcod
import tcod.event

class State(tcod.event.EventDispatch):
    def ev_quit(self, event):
        raise SystemExit()

    def ev_keydown(self, event):
        print(event)

    def ev_mousebuttondown(self, event):
        print(event)

    def ev_mousemotion(self, event):
        print(event)

root_console = tcod.console_init_root(80, 60)
state = State()
while True:
    for event in tcod.event.wait()
        state.dispatch(event)
dispatch(event: Any) → None[source]

Send an event to an ev_* method.

* will be the events type converted to lower-case.

If event.type is an empty string or None then it will be ignored.

ev_keydown(event: tcod.event.KeyDown) → None[source]

Called when a keyboard key is pressed or repeated.

ev_keyup(event: tcod.event.KeyUp) → None[source]

Called when a keyboard key is released.

ev_mousebuttondown(event: tcod.event.MouseButtonDown) → None[source]

Called when a mouse button is pressed.

ev_mousebuttonup(event: tcod.event.MouseButtonUp) → None[source]

Called when a mouse button is released.

ev_mousemotion(event: tcod.event.MouseMotion) → None[source]

Called when the mouse is moved.

ev_mousewheel(event: tcod.event.MouseWheel) → None[source]

Called when the mouse wheel is scrolled.

ev_quit(event: tcod.event.Quit) → None[source]

Called when the termination of the program is requested.

ev_textinput(event: tcod.event.TextInput) → None[source]

Called to handle Unicode input.

ev_windowclose(event: tcod.event.WindowEvent) → None[source]

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

ev_windowenter(event: tcod.event.WindowEvent) → None[source]

Called when the window gains mouse focus.

ev_windowexposed(event: tcod.event.WindowEvent) → None[source]

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) → None[source]

Called when the window gains keyboard focus.

ev_windowfocuslost(event: tcod.event.WindowEvent) → None[source]

Called when the window loses keyboard focus.

ev_windowhidden(event: tcod.event.WindowEvent) → None[source]

Called when the window is hidden.

ev_windowleave(event: tcod.event.WindowEvent) → None[source]

Called when the window loses mouse focus.

ev_windowmaximized(event: tcod.event.WindowEvent) → None[source]

Called when the window is maximized.

ev_windowminimized(event: tcod.event.WindowEvent) → None[source]

Called when the window is minimized.

ev_windowmoved(event: tcod.event.WindowMoved) → None[source]

Called when the window is moved.

ev_windowresized(event: tcod.event.WindowResized) → None[source]

Called when the window is resized.

ev_windowrestored(event: tcod.event.WindowEvent) → None[source]

Called when the window is restored.

ev_windowshown(event: tcod.event.WindowEvent) → None[source]

Called when the window is shown.

ev_windowsizechanged(event: tcod.event.WindowResized) → None[source]

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

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.

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)
tcod.event.wait(timeout: Optional[float] = 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.

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)