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

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

Always “QUIT”.

Type:str
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

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

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

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

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

Same as MouseButtonEvent but with type="MouseButtonUp".

class tcod.event.MouseWheel(x: int, y: int, flipped: bool = False)[source]
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[source]

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

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

Always “TEXTINPUT”.

Type:str
text

A Unicode string with the input.

Type:str
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

A window event could mean various event types.

Type:str
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

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