sdl2.ext.window - Creating and Working with SDL2 Windows

This module contains the Window class, which provides a friendly Pythonic API for creating, moving, resizing, closing, or otherwise working with SDL2 windows.

Window routines to manage on-screen windows.

class sdl2.ext.window.Window(title, size, position=None, flags=None)[source]

Creates a visible window with an optional border and title text.

In SDL2, a window is the object through which visuals are displayed and all input events are captured. This class is a Pythonic alternative to working directly with SDL2’s SDL_Window type, wrapping a number of useful functions for working with windows.

The created Window is hidden by default, but can be shown using the show() method. Additionally, the type and properties of the created window can be configured using various flags:

Flag

Description

SDL_WINDOW_SHOWN

Will be shown when created

SDL_WINDOW_HIDDEN

Will be hidden when created

SDL_WINDOW_BORDERLESS

Will not be decorated by the OS

SDL_WINDOW_RESIZABLE

Will be resizable

SDL_WINDOW_MINIMIZED

Will be created in a minimized state

SDL_WINDOW_MAXIMIZED

Will be created in a maximized state

SDL_WINDOW_FULLSCREEN

Will be fullscreen

SDL_WINDOW_FULLSCREEN_DESKTOP

Will be fullscreen at the current desktop resolution

SDL_WINDOW_OPENGL

Will be usable with an OpenGL context

SDL_WINDOW_VULKAN

Will be usable with a Vulkan instance

SDL_WINDOW_METAL

Will be usable with a Metal context

SDL_WINDOW_ALLOW_HIGHDPI

Will be created in high-DPI mode (if supported)

SDL_WINDOW_INPUT_FOCUS

Will have input focus when created

SDL_WINDOW_MOUSE_FOCUS

Will have mouse focus when created

SDL_WINDOW_INPUT_GRABBED

Will prevent the mouse from leaving the bounds of the window

SDL_WINDOW_MOUSE_CAPTURE

Will capture mouse to track input outside of the window when created

There are also a few additional window creation flags that only affect the X11 window manager (i.e. most distributions of Linux and BSD):

Flag

Description

SDL_WINDOW_ALWAYS_ON_TOP

Should stay on top of other windows

SDL_WINDOW_SKIP_TASKBAR

Should not be added to the taskbar

SDL_WINDOW_UTILITY

Should be treated as a utility window

SDL_WINDOW_TOOLTIP

Should be treated as a tooltip

SDL_WINDOW_POPUP_MENU

Should be treated as a popup menu

To combine multiple flags, you can use a bitwise OR to combine two or more together before passing them to the flags argument. For example, to create a fullscreen window that supports an OpenGL context and is shown on creation, you would use:

win_flags = (
    sdl2.SDL_WINDOW_FULLSCREEN | sdl2.SDL_WINDOW_OPENGL |
    sdl2.SDL_WINDOW_SHOWN
)
sdl2.ext.Window("PySDL2", (800, 600), flags=win_flags)
Parameters:
  • title (str) – The title to use for the window.

  • size (tuple) – The initial size (in pixels) of the window, in the format (width, height).

  • position (tuple, optional) – The initial (x, y) coordinates of the top-left corner of the window. If not specified, defaults to letting the system’s window manager choose a location for the window.

  • flags (int, optional) – The window attribute flags with which the window will be created. Defaults to SDL_WINDOW_HIDDEN.

window

The underlying SDL2 Window object. If the window has been closed, this value will be None.

Type:

SDL_Window, None

property position

The (x, y) pixel coordinates of the top-left corner of the window.

Type:

tuple

property title

The title of the window.

Type:

str

property size

The current dimensions of the window (in pixels) in the form (width, height).

Type:

tuple

create()[source]

Creates the window if it does not already exist.

open()[source]

Creates and shows the window.

close()[source]

Closes and destroys the window.

Once this method has been called, the window cannot be re-opened. However, you can create a new window with the same settings using the create() method.

show()[source]

Shows the window on the display.

If the window is already visible, this method does nothing.

hide()[source]

Hides the window.

If the window is already hidden, this method does nothing.

maximize()[source]

Maximizes the window.

minimize()[source]

Minimizes the window into the system’s dock or task bar.

restore()[source]

Restores a minimized or maximized window to its original state.

If the window has not been minimized or maximized, this method does nothing.

refresh()[source]

Updates the window to reflect any changes made to its surface.

Note

This only needs to be called if the window surface was acquired and modified using get_surface().

get_surface()[source]

Gets the SDL_Surface used by the window.

This method obtains the SDL surface used by the window, which can be then be modified to change the contents of the window (e.g draw shapes or images) using functions such as sdl2.SDL_BlitSurface() or sdl2.ext.fill().

The obtained surface will be invalidated if the window is resized. As such, you will need to call this method again whenever this happens in order to continue to access the window’s contents.

Note

If using OpenGL/Vulkan/Metal rendering or the SDL rendering API (e.g. sdl2.SDL_CreateRenderer()) for drawing to the window, this method should not be used.

Returns:

The surface associated with the window.

Return type:

SDL_Surface