SDL Window and Display API tcod.sdl.video#

SDL2 Window and Display handling.

There are two main ways to access the SDL window. Either you can use this module to open a window yourself bypassing libtcod’s context, or you can use Context.sdl_window to get the window being controlled by that context (if the context has one.)

New in version 13.4.

class tcod.sdl.video.FlashOperation(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Values for Window.flash.

BRIEFLY = 1#

Flash briefly.

CANCEL = 0#

Stop flashing.

UNTIL_FOCUSED = 2#

Flash until focus is gained.

class tcod.sdl.video.Window(sdl_window_p: Any)[source]#

An SDL2 Window object.

flash(operation: FlashOperation = FlashOperation.UNTIL_FOCUSED) → None[source]#

Get the users attention.

hide() → None[source]#

Hide this window.

maximize() → None[source]#

Make the window as big as possible.

minimize() → None[source]#

Minimize the window to an iconic state.

raise_window() → None[source]#

Raise the window and set input focus.

restore() → None[source]#

Restore a minimized or maximized window to its original size and position.

set_icon(pixels: numpy.typing.ArrayLike) → None[source]#

Set the window icon from an image.

Parameters:

pixels – A row-major array of RGB or RGBA pixel values.

show() → None[source]#

Show this window.

property border_size: tuple[int, int, int, int]#

Get the (top, left, bottom, right) size of the window decorations around the client area.

If this fails or the window doesn’t have decorations yet then the value will be (0, 0, 0, 0).

See also

https://wiki.libsdl.org/SDL_GetWindowBordersSize

property flags: WindowFlags#

The current flags of this window, read-only.

property fullscreen: int#

Get or set the fullscreen status of this window.

Can be set to the WindowFlags.FULLSCREEN or WindowFlags.FULLSCREEN_DESKTOP flags.

Example:

# Toggle fullscreen.
window: tcod.sdl.video.Window
if window.fullscreen:
    window.fullscreen = False  # Set windowed mode.
else:
    window.fullscreen = tcod.sdl.video.WindowFlags.FULLSCREEN_DESKTOP
property grab: bool#

Get or set this windows input grab mode.

See also

https://wiki.libsdl.org/SDL_SetWindowGrab

property max_size: tuple[int, int]#

Get or set this windows maximum client area.

property min_size: tuple[int, int]#

Get or set this windows minimum client area.

property mouse_rect: tuple[int, int, int, int] | None#

Get or set the mouse confinement area when the window has mouse focus.

Setting this will not automatically grab the cursor.

New in version 13.5.

property opacity: float#

Get or set this windows opacity. 0.0 is fully transparent and 1.0 is fully opaque.

Will error if you try to set this and opacity isn’t supported.

property position: tuple[int, int]#

Get or set the (x, y) position of the window.

This attribute can be set the move the window. The constants tcod.lib.SDL_WINDOWPOS_CENTERED or tcod.lib.SDL_WINDOWPOS_UNDEFINED may be used.

property resizable: bool#

Get or set if this window can be resized.

property size: tuple[int, int]#

Get or set the pixel (width, height) of the window client area.

This attribute can be set to change the size of the window but the given size must be greater than (1, 1) or else ValueError will be raised.

property title: str#

Get or set the title of the window.

class tcod.sdl.video.WindowFlags(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bit flags which make up a windows state.

See also

https://wiki.libsdl.org/SDL_WindowFlags

ALLOW_HIGHDPI = 8192#
ALWAYS_ON_TOP = 32768#
BORDERLESS = 16#
FOREIGN = 2048#
FULLSCREEN = 1#
FULLSCREEN_DESKTOP = 4097#
HIDDEN = 8#
INPUT_FOCUS = 512#
MAXIMIZED = 128#
METAL = 536870912#
MINIMIZED = 64#
MOUSE_CAPTURE = 16384#
MOUSE_FOCUS = 1024#
MOUSE_GRABBED = 256#
OPENGL = 2#
POPUP_MENU = 524288#
RESIZABLE = 32#
SHOWN = 4#
SKIP_TASKBAR = 65536#
TOOLTIP = 262144#
UTILITY = 131072#
VULKAN = 268435456#
tcod.sdl.video.get_grabbed_window() → Window | None[source]#

Return the window which has input grab enabled, if any.

tcod.sdl.video.new_window(width: int, height: int, *, x: int | None = None, y: int | None = None, title: str | None = None, flags: int = 0) → Window[source]#

Initialize and return a new SDL Window.

Parameters:

  • width – The requested pixel width of the window.

  • height – The requested pixel height of the window.

  • x – The left-most position of the window.

  • y – The top-most position of the window.

  • title – The title text of the new window. If no option is given then sys.arg[0] will be used as the title.

  • flags – The SDL flags to use for this window, such as tcod.sdl.video.WindowFlags.RESIZABLE. See WindowFlags for more options.

Example:

import tcod.sdl.video
# Create a new resizable window with a custom title.
window = tcod.sdl.video.new_window(640, 480, title="Title bar text", flags=tcod.sdl.video.WindowFlags.RESIZABLE)

See also

tcod.sdl.render.new_renderer()

tcod.sdl.video.screen_saver_allowed(allow: bool | None = None) → bool[source]#

Allow or prevent a screen saver from being displayed and return the current allowed status.

If allow is None then only the current state is returned. Otherwise it will change the state before checking it.

SDL typically disables the screensaver by default. If you’re unsure, then don’t touch this.

Example:

import tcod.sdl.video

print(f"Screen saver was allowed: {tcod.sdl.video.screen_saver_allowed()}")
# Allow the screen saver.
# Might be okay for some turn-based games which don't use a gamepad.
tcod.sdl.video.screen_saver_allowed(True)