SDL Window and Display API `tcod.sdl.video`¶

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

Added in version 13.4.

class tcod.sdl.video.Capitalization(value)[source]¶

Text capitalization for text input.

Added in version 19.1.

LETTERS = 3¶: All letters will be capitalized.

NONE = 0¶: No auto-capitalization will be done.

SENTENCES = 1¶: The first letter of sentences will be capitalized.

WORDS = 2¶: The first letter of words will be capitalized.

class tcod.sdl.video.FlashOperation(value)[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.TextInputType(value)[source]¶

SDL input types for text input.

Added in version 19.1.

NUMBER = 6¶: The input is a number.

NUMBER_PASSWORD_HIDDEN = 7¶: The input is a secure PIN that is hidden.

NUMBER_PASSWORD_VISIBLE = 8¶: The input is a secure PIN that is visible.

TEXT = 0¶: The input is text.

TEXT_EMAIL = 2¶: The input is an e-mail address.

TEXT_NAME = 1¶: The input is a person’s name.

TEXT_PASSWORD_HIDDEN = 4¶: The input is a secure password that is hidden.

TEXT_PASSWORD_VISIBLE = 5¶: The input is a secure password that is visible.

TEXT_USERNAME = 3¶: The input is a username.

class tcod.sdl.video.Window(sdl_window_p: Any | int)[source]¶

An SDL Window object.

Created from tcod.sdl.video.new_window when working with SDL directly.

When using the libtcod Context you can access its Window via Context.sdl_window.

__eq__(other: object) → bool[source]¶: Return True if self and other wrap the same window.

__hash__() → int[source]¶: Return the hash of this instances SDL window pointer.

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.

set_text_input_area(rect: tuple[int, int, int, int], cursor: int) → None[source]¶

Assign the area used for entering Unicode text input.

Parameters:

rect – (x, y, width, height) rectangle used for text input
cursor – Cursor X position, relative to rect[0]

Added in version 19.1.

show() → None[source]¶: Show this window.

start_text_input(*, type: TextInputType = TextInputType.TEXT, capitalization: Capitalization | None = None, autocorrect: bool = True, multiline: bool | None = None, android_type: int | None = None) → None[source]¶

Start receiving text input events supporting Unicode. This may open an on-screen keyboard.

This method is meant to be paired with set_text_input_area.

Parameters:

type – Type of text being inputted, see TextInputType
capitalization – Capitalization hint, default is based on type given, see Capitalization.
autocorrect – Enable auto completion and auto correction.
multiline – Allow multiple lines of text.
android_type – Input type for Android, see SDL docs.

Example:

context: tcod.context.Context  # Assuming tcod context is used

if context.sdl_window:
    context.sdl_window.start_text_input()

    ... # Handle Unicode input using TextInput events

    context.sdl_window.stop_text_input()  # Close on-screen keyboard when done

Added in version 19.1.

stop_text_input() → None[source]¶: Stop receiving text events for this window and close relevant on-screen keyboards.

See also

start_text_input

Added in version 19.1.

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

property flags: WindowFlags¶: The current flags of this window, read-only.

property fullscreen: bool¶

Get or set the fullscreen status of this window.

Example:

# Toggle fullscreen.
window: tcod.sdl.video.Window
window.fullscreen = not window.fullscreen

property grab: bool¶: Get or set this windows input grab mode.

Deprecated since version 19.0: This attribute as been split into mouse_grab and keyboard_grab.

property keyboard_grab: bool¶

Get or set this windows keyboard input grab mode.

https://wiki.libsdl.org/SDL3/SDL_SetWindowKeyboardGrab

Added in version 19.0.

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_grab: bool¶: Get or set this windows mouse input grab mode.

Added in version 19.0.

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.

Added 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 relative_mouse_mode: bool¶: Enable or disable relative mouse mode which will lock and hide the mouse and only report mouse motion.

See also

tcod.sdl.mouse.capture https://wiki.libsdl.org/SDL_SetWindowRelativeMouseMode

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

Bit flags which make up a windows state.

See also

https://wiki.libsdl.org/SDL_WindowFlags

ALLOW_HIGHDPI = 8192¶

ALWAYS_ON_TOP = 65536¶

BORDERLESS = 16¶

FULLSCREEN = 1¶

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¶

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)

SDL Window and Display API tcod.sdl.video¶

SDL Window and Display API `tcod.sdl.video`¶