tcod.context - Window Management

This module is used to create and handle libtcod contexts.

See Getting Started for beginner examples on how to use this module.

Context’s are intended to replace several libtcod functions such as tcod.console_init_root, tcod.console_flush, tcod.console.recommended_size, and many other functions which rely on hidden global objects within libtcod. If you begin using contexts then most of these functions will no longer work properly.

Instead of calling tcod.console_init_root you can call tcod.context.new with different keywords depending on how you plan to setup the size of the console. You should use tcod.tileset to load the font for a context.

Note

If you use contexts then you should expect the following functions to no longer be available, because these functions rely on a global console, tileset, or some other kind of global state:

tcod.console_init_root, tcod.console_set_custom_font, tcod.console_flush, tcod.console_is_fullscreen, tcod.console_is_window_closed, tcod.console_set_fade, tcod.console_set_fullscreen, tcod.console_set_window_title, tcod.sys_set_fps, tcod.sys_get_last_frame_length, tcod.sys_set_renderer, tcod.sys_save_screenshot, tcod.sys_force_fullscreen_resolution, tcod.sys_get_current_resolution, tcod.sys_register_SDL_renderer, tcod.console_map_ascii_code_to_font, tcod.sys_get_char_size, tcod.sys_update_char, tcod.console.recommended_size, tcod.tileset.get_default, tcod.tileset.set_default.

Some event functions can no longer return tile coordinates for the mouse: tcod.sys_check_for_event, tcod.sys_wait_for_event, tcod.mouse_get_status.

New in version 11.12.

class tcod.context.Context(context_p: Any)

Context manager for libtcod context objects.

You should use tcod.context.new_terminal or tcod.context.new_window to create a new context.

__enter__() → tcod.context.Context

This context can be used as a context manager.

__exit__(*args) → None

The libtcod context is closed as this context manager exits.

change_tileset(tileset: Optional[tcod.tileset.Tileset]) → None

Change the active tileset used by this context.

close() → None

Delete the context, closing any windows opened by this context.

This instance is invalid after this call.

convert_event(event: tcod.event.Event) → None

Fill in the tile coordinates of a mouse event using this context.

new_console(min_columns: int = 1, min_rows: int = 1, magnification: float = 1.0, order: Union[typing_extensions.Literal['C'][C], typing_extensions.Literal['F'][F]] = 'C') → tcod.console.Console

Return a new console sized for this context.

min_columns and min_rows are the minimum size to use for the new console.

magnification determines the apparent size of the tiles on the output display. A magnification larger then 1.0 will output smaller consoles, which will show as larger tiles when presented. magnification must be greater than zero.

order is passed to tcod.console.Console to determine the memory order of its NumPy attributes.

The times where it is the most useful to call this method are:

• After the context is created, even if the console was given a specific size.
• After the change_tileset method is called.
• After any window resized event, or any manual resizing of the window.

New in version 11.18.

Changed in version 11.19: Added order parameter.

See also

tcod.console.Console

pixel_to_subtile(x: int, y: int) → Tuple[float, float]

Convert window pixel coordinates to sub-tile coordinates.

pixel_to_tile(x: int, y: int) → Tuple[int, int]

Convert window pixel coordinates to tile coordinates.

present(console: tcod.console.Console, *, keep_aspect: bool = False, integer_scaling: bool = False, clear_color: Tuple[int, int, int] = (0, 0, 0), align: Tuple[float, float] = (0.5, 0.5)) → None

Present a console to this context’s display.

console is the console you want to present.

If keep_aspect is True then the console aspect will be preserved with a letterbox. Otherwise the console will be stretched to fill the screen.

If integer_scaling is True then the console will be scaled in integer increments. This will have no effect if the console must be shrunk. You can use tcod.console.recommended_size to create a console which will fit the window without needing to be scaled.

clear_color is an RGB tuple used to clear the screen before the console is presented, this will affect the border/letterbox color.

align is an (x, y) tuple determining where the console will be placed when letter-boxing exists. Values of 0 will put the console at the upper-left corner. Values of 0.5 will center the console.

recommended_console_size(min_columns: int = 1, min_rows: int = 1) → Tuple[int, int]

Return the recommended (columns, rows) of a console for this context.

min_columns, min_rows are the lowest values which will be returned.

If result is only used to create a new console then you may want to call Context.new_console instead.

save_screenshot(path: Optional[str] = None) → None

Save a screen-shot to the given file path.

renderer_type

Return the libtcod renderer type used by this context.

sdl_window_p

A cffi SDL_Window* pointer. This pointer might be NULL.

This pointer will become invalid if the context is closed or goes out of scope.

Python-tcod’s FFI provides most SDL functions. So it’s possible for anyone with the SDL2 documentation to work directly with SDL’s pointers.

Example:

import tcod

def toggle_fullscreen(context: tcod.context.Context) -> None:
    """Toggle a context window between fullscreen and windowed modes."""
    if not context.sdl_window_p:
        return
    fullscreen = tcod.lib.SDL_GetWindowFlags(context.sdl_window_p) & (
        tcod.lib.SDL_WINDOW_FULLSCREEN | tcod.lib.SDL_WINDOW_FULLSCREEN_DESKTOP
    )
    tcod.lib.SDL_SetWindowFullscreen(
        context.sdl_window_p,
        0 if fullscreen else tcod.lib.SDL_WINDOW_FULLSCREEN_DESKTOP,
    )

tcod.context.new(*, x: Optional[int] = None, y: Optional[int] = None, width: Optional[int] = None, height: Optional[int] = None, columns: Optional[int] = None, rows: Optional[int] = None, renderer: Optional[int] = None, tileset: Optional[tcod.tileset.Tileset] = None, vsync: bool = True, sdl_window_flags: Optional[int] = None, title: Optional[str] = None, argv: Optional[Iterable[str]] = None) → tcod.context.Context

Create a new context with the desired pixel size.

x, y, width, and height are the desired position and size of the window. If these are None then they will be derived from columns and rows. So if you plan on having a console of a fixed size then you should set columns and rows instead of the window keywords.

columns and rows is the desired size of the console. Can be left as None when you’re setting a context by a window size instead of a console.

Providing no size information at all is also acceptable.

renderer is the desired libtcod renderer to use. Typical options are tcod.context.RENDERER_OPENGL2 for a faster renderer or tcod.context.RENDERER_SDL2 for a reliable renderer.

tileset is the font/tileset for the new context to render with. The fall-back tileset available from passing None is useful for prototyping, but will be unreliable across platforms.

vsync is the Vertical Sync option for the window. The default of True is recommended but you may want to use False for benchmarking purposes.

sdl_window_flags is a bit-field of SDL window flags, if None is given then a default of tcod.context.SDL_WINDOW_RESIZABLE is used. There’s more info on the SDL documentation: https://wiki.libsdl.org/SDL_CreateWindow#Remarks

title is the desired title of the window.

argv these arguments are passed to libtcod and allow an end-user to make last second changes such as forcing fullscreen or windowed mode, or changing the libtcod renderer. By default this will pass in sys.argv but you can disable this feature by providing an empty list instead. Certain commands such as -help will raise a SystemExit exception from this function with the output message.

When a window size is given instead of a console size then you can use Context.recommended_console_size to automatically find the size of the console which should be used.

New in version 11.16.

tcod.context.new_window(width: int, height: int, *, renderer: Optional[int] = None, tileset: Optional[tcod.tileset.Tileset] = None, vsync: bool = True, sdl_window_flags: Optional[int] = None, title: Optional[str] = None) → tcod.context.Context

Create a new context with the desired pixel size.

Deprecated since version 11.16: tcod.context.new provides more options, such as window position.

tcod.context.new_terminal(columns: int, rows: int, *, renderer: Optional[int] = None, tileset: Optional[tcod.tileset.Tileset] = None, vsync: bool = True, sdl_window_flags: Optional[int] = None, title: Optional[str] = None) → tcod.context.Context

Create a new context with the desired console size.

Deprecated since version 11.16: tcod.context.new provides more options.

tcod.context.SDL_WINDOW_FULLSCREEN

Exclusive fullscreen mode.

It’s generally not recommended to use this flag unless you know what you’re doing. SDL_WINDOW_FULLSCREEN_DESKTOP should be used instead whenever possible.

tcod.context.SDL_WINDOW_FULLSCREEN_DESKTOP

A borderless fullscreen window at the desktop resolution.

tcod.context.SDL_WINDOW_HIDDEN

Window is hidden.

tcod.context.SDL_WINDOW_BORDERLESS

Window has no decorative border.

tcod.context.SDL_WINDOW_RESIZABLE

Window can be resized.

tcod.context.SDL_WINDOW_MINIMIZED

Window is minimized.

tcod.context.SDL_WINDOW_MAXIMIZED

Window is maximized.

tcod.context.SDL_WINDOW_INPUT_GRABBED

Window has grabbed the input.

tcod.context.SDL_WINDOW_ALLOW_HIGHDPI

High DPI mode, see the SDL documentation.

tcod.context.RENDERER_OPENGL

A renderer for older versions of OpenGL.

Should support OpenGL 1 and GLES 1

tcod.context.RENDERER_OPENGL2

An SDL2/OPENGL2 renderer. Usually faster than regular SDL2.

Recommended if you need a high performance renderer.

Should support OpenGL 2.0 and GLES 2.0.

tcod.context.RENDERER_SDL

Same as RENDERER_SDL2, but forces SDL2 into software mode.

tcod.context.RENDERER_SDL2

The main SDL2 renderer.

Rendering is decided by SDL2 and can be changed by using an SDL2 hint: https://wiki.libsdl.org/SDL_HINT_RENDER_DRIVER