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_Windowtype, 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_SHOWNWill be shown when created
SDL_WINDOW_HIDDENWill be hidden when created
SDL_WINDOW_BORDERLESSWill not be decorated by the OS
SDL_WINDOW_RESIZABLEWill be resizable
SDL_WINDOW_MINIMIZEDWill be created in a minimized state
SDL_WINDOW_MAXIMIZEDWill be created in a maximized state
SDL_WINDOW_FULLSCREENWill be fullscreen
SDL_WINDOW_FULLSCREEN_DESKTOPWill be fullscreen at the current desktop resolution
SDL_WINDOW_OPENGLWill be usable with an OpenGL context
SDL_WINDOW_VULKANWill be usable with a Vulkan instance
SDL_WINDOW_METALWill be usable with a Metal context
SDL_WINDOW_ALLOW_HIGHDPIWill be created in high-DPI mode (if supported)
SDL_WINDOW_INPUT_FOCUSWill have input focus when created
SDL_WINDOW_MOUSE_FOCUSWill have mouse focus when created
SDL_WINDOW_INPUT_GRABBEDWill prevent the mouse from leaving the bounds of the window
SDL_WINDOW_MOUSE_CAPTUREWill 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_TOPShould stay on top of other windows
SDL_WINDOW_SKIP_TASKBARShould not be added to the taskbar
SDL_WINDOW_UTILITYShould be treated as a utility window
SDL_WINDOW_TOOLTIPShould be treated as a tooltip
SDL_WINDOW_POPUP_MENUShould 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
- 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.
- 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_Surfaceused 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()orsdl2.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