pygame.Window — pygame-ce v2.5.6 documentation

pygame.Window¶

Pygame object that represents a window.

Window(title='pygame window', size=(640, 480), position=WINDOWPOS_UNDEFINED, *, fullscreen=..., fullscreen_desktop=..., opengl=..., vulkan=..., hidden=..., borderless=..., resizable=..., minimized=..., maximized=..., mouse_grabbed=..., keyboard_grabbed=..., input_focus=..., mouse_focus=..., allow_high_dpi=..., mouse_capture=..., always_on_top=..., utility=...) -> Window

pygame.Window.grab_mouse	—	Get or set the window's mouse grab mode.
pygame.Window.grab_keyboard	—	Get or set the window's keyboard grab mode.
pygame.Window.mouse_grabbed	—	Get if the mouse cursor is confined to the window (read-only).
pygame.Window.keyboard_grabbed	—	Get if the keyboard shortcuts are captured by the window (read-only).
pygame.Window.focused	—	Get if the window is focused (read-only).
pygame.Window.title	—	Get or set the window title.
pygame.Window.resizable	—	Get or set whether the window is resizable.
pygame.Window.borderless	—	Gets or sets whether the window is borderless.
pygame.Window.always_on_top	—	Get or set whether the window is always on top.
pygame.Window.id	—	Get the unique window ID (read-only).
pygame.Window.mouse_rect	—	Get or set the mouse confinement rectangle of the window.
pygame.Window.size	—	Get or set the window size in pixels.
pygame.Window.minimum_size	—	Get or set the minimum size of the window's client area.
pygame.Window.maximum_size	—	Get or set the maximum size of the window's client area.
pygame.Window.position	—	Get or set the window position in screen coordinates.
pygame.Window.opacity	—	Get or set the window opacity, between 0.0 (fully transparent) and 1.0 (fully opaque).
pygame.Window.opengl	—	Get if the window supports OpenGL.
pygame.Window.utility	—	Get if the window is an utility window (read-only).
pygame.Window.from_display_module	—	Create a Window object using window data from display module.
pygame.Window.get_surface	—	Get the window surface.
pygame.Window.flip	—	Update the display surface to the window.
pygame.Window.set_windowed	—	Enable windowed mode (exit fullscreen).
pygame.Window.set_fullscreen	—	Enter fullscreen.
pygame.Window.destroy	—	Destroy the window.
pygame.Window.hide	—	Hide the window.
pygame.Window.show	—	Show the window.
pygame.Window.focus	—	Set the window to be focused.
pygame.Window.restore	—	Restore the size and position of a minimized or maximized window.
pygame.Window.maximize	—	Maximize the window.
pygame.Window.minimize	—	Minimize the window.
pygame.Window.set_icon	—	Set the window icon.
pygame.Window.set_modal_for	—	Set the window as a modal for a parent window.
pygame.Window.flash	—	Flash a window to demand attention from the user.

The Window class (formerly known as _sdl2.video.Window), is a newly published feature of pygame-ce 2.5.2. This class allows for programs to drive multiple windows on-screen at once, something not possible with the pygame.display.set_mode()Initialize a window or screen for display. API. Not everything possible with pygame.displayPygame module to control the display window and screen. is possible yet in the Window API, but the new window class will continue to be developed, and we're excited to share the new functionality this class offers.

Parameters:

title (str) -- The title of the window.
size ((int, int)) -- The size of the window, in screen coordinates.
position ((int, int) or int) -- A tuple specifying the window position, or WINDOWPOS_CENTERED, or WINDOWPOS_UNDEFINED.
fullscreen (bool) -- Create a fullscreen window using the window size as the resolution (videomode change).
fullscreen_desktop (bool) -- Create a fullscreen window using the current desktop resolution.
opengl (bool) -- Create a window with support for an OpenGL context.
vulkan (bool) -- Create a window with support for a Vulkan instance.
hidden (bool) -- Create a hidden window.
borderless (bool) -- Create a window without borders.
resizable (bool) -- Create a resizable window.
minimized (bool) -- Create a mimized window.
maximized (bool) -- Create a maximized window.
mouse_grabbed (bool) -- Create a window with grabbed mouse input.
keyboard_grabbed (bool) -- Create a window with grabbed keyboard input.
input_focus (bool) -- Create a window with input focus.
mouse_focus (bool) -- Create a window with mouse focus.
allow_high_dpi (bool) -- Create a window in high-DPI mode if supported.
mouse_capture (bool) -- Create a window that has the mouse captured (unrelated to INPUT_GRABBED).
always_on_top (bool) -- Create a window that is always presented above others.
utility (bool) -- Create a window that doesn't appear in the task bar.

Event behavior if one Window is created: When the close button is pressed, the QUIT event will be sent to the event queue.

import pygame

window = pygame.Window()

while True:
for event in pygame.event.get():
    if event.type == pygame.QUIT:
        pygame.quit()
        raise SystemExit

Event behavior if multiple windows are created: When the close button is pressed, a WINDOWCLOSE event is sent. You need to explicitly destroy the window. Note that the event QUIT will only be sent if all windows have been destroyed.

import pygame

window1 = pygame.Window(position=(0,100))
window2 = pygame.Window(position=(700,100))

while True:
for event in pygame.event.get():
    if event.type == pygame.WINDOWCLOSE:
        id = event.window.id
        print(f"WINDOWCLOSE event sent to Window #{id}.")
        event.window.destroy()

    if event.type == pygame.QUIT:
        print(f"Last window is destroyed. QUIT event was sent.")
        pygame.quit()
        raise SystemExit

New in pygame-ce 2.4.0.

Changed in pygame-ce 2.5.0: when opengl is True, the Window has an OpenGL context created by pygame

Changed in pygame-ce 2.5.1: Window is now a base class, allowing subclassing

grab_mouse: bool¶

Get or set the window's mouse grab mode.

grab_mouse -> bool

When this attribute is set to True, the window will try to confine the mouse cursor to itself.

Note this only set the "mode" of grab. The mouse may be confined to another window depending on the window focus. To get if the mouse is currently restricted to this window, please use mouse_grabbed.

See also

mouse_grabbed

New in pygame-ce 2.4.0.

grab_keyboard: bool¶

Get or set the window's keyboard grab mode.

grab_keyboard -> bool

When this attribute is set to True, the window will try to capture system keyboard shortcuts like Alt+Tab or the Meta/Super key.

This attribute only set the "mode" of grab. The keyboard may be captured by another window depending on the window focus. To get if keyboard is currently captured by this window, please use keyboard_grabbed.

Note that not all system keyboard shortcuts can be captured by applications (one example is Ctrl+Alt+Del on Windows).

When keyboard grab is enabled, pygame will continue to handle Alt+Tab when the window is full-screen to ensure the user is not trapped in your application. If you have a custom keyboard shortcut to exit fullscreen mode, you may suppress this behavior with an environment variable, e.g. os.environ["SDL_ALLOW_ALT_TAB_WHILE_GRABBED"] = "0".

This attribute requires SDL 2.0.16+.

See also

keyboard_grabbed

New in pygame-ce 2.4.0.

property mouse_grabbed: bool¶

Get if the mouse cursor is confined to the window (**read-only**).

mouse_grabbed -> bool

Get if the mouse cursor is currently grabbed and confined to the window.

Roughly equivalent to this expression:

win.grab_mouse and (win is get_grabbed_window())

See also

grab_mouse

New in pygame-ce 2.4.0.

property keyboard_grabbed: bool¶

Get if the keyboard shortcuts are captured by the window (**read-only**).

keyboard_grabbed -> bool

Get if the keyboard shortcuts are currently grabbed and captured by the window.

Roughly equivalent to this expression:

win.grab_keyboard and (win is get_grabbed_window())

This attribute requires SDL 2.0.16+.

See also

grab_keyboard

New in pygame-ce 2.4.0.

property focused: bool¶

Get if the window is focused (**read-only**).

focused -> bool

Get if the window is currently focused. The same result can be achieved using the WINDOWFOCUSGAINED and WINDOWFOCUSLOST events.

Use focus() to focus and raise the window.

New in pygame-ce 2.5.2.

title: str¶: Get or set the window title.

title -> str

An empty string means that no title is set.

resizable: bool¶: Get or set whether the window is resizable.

resizable -> bool

borderless: bool¶: Gets or sets whether the window is borderless.

borderless -> bool

Note

You can't change the border state of a fullscreen window.

always_on_top: bool¶: Get or set whether the window is always on top.

always_on_top -> bool

Setting the always-on-top mode requires SDL 2.0.16+.

New in pygame-ce 2.3.1.

property id: int¶: Get the unique window ID (**read-only**).

id -> int

property mouse_rect: pygame.rect.Rect | None¶

Get or set the mouse confinement rectangle of the window.

mouse_rect -> Optional[Rect]

Setting this attribute to a rect-like object confines the cursor to the specified area of this window.

This attribute can be None, meaning that there is no mouse rect.

Note that this does NOT grab the cursor, it only defines the area a cursor is restricted to when the window has mouse focus.

New in pygame-ce 2.4.0.

property size: tuple[int, int]¶: Get or set the window size in pixels.

size -> tuple[int, int]

property minimum_size: tuple[int, int]¶

Get or set the minimum size of the window's client area.

minimum_size -> tuple[int, int]

Initial value in most cases is (0, 0). If from_display_module() was used to create the window and pygame.display.set_mode()Initialize a window or screen for display. was called with the SCALED flag, the initial value is the size used in that call.

Raises a ValueError if negative values are provided or if the width or height provided are greater than set maximum width or height respectively. Unless maximum size is (0, 0) (initial value).

See also

maximum_size.

New in pygame-ce 2.4.0.

property maximum_size: tuple[int, int]¶

Get or set the maximum size of the window's client area.

maximum_size -> tuple[int, int]

Initial value is (0, 0).

Raises a ValueError if negative values are provided or if the width or height provided are less than set minimum width or height respectively.

See also

minimum_size.

New in pygame-ce 2.4.0.

property position: tuple[int, int]¶: Get or set the window position in screen coordinates.

position -> tuple[int, int]

The position may be a tuple of (x, y) coordinates or WINDOWPOS_CENTERED or WINDOWPOS_UNDEFINED. The origin is the topleft of the main display.

opacity: float¶: Get or set the window opacity, between 0.0 (fully transparent) and 1.0 (fully opaque).

opacity -> float

property opengl: bool¶: Get if the window supports OpenGL.

opengl -> bool

True if the Window has an OpenGL context associated with it, False otherwise

New in pygame-ce 2.5.0.

property utility: bool¶: Get if the window is an utility window (**read-only**).

utility -> bool

True if the window doesn't appear in the task bar, False otherwise. This only works for X11 and Windows, for other platforms, creating Window(utility=True) won't change anything.

New in pygame-ce 2.5.3.

classmethod from_display_module()¶

Create a Window object using window data from display module.

from_display_module() -> Window

DON'T USE THIS! If you want to draw to a surface and use the window API, use Window.get_surface() and Window.flip().

Create a Window object that uses the same window data from the pygame.displayPygame module to control the display window and screen. module, created upon calling pygame.display.set_mode()Initialize a window or screen for display..

Deprecated since pygame-ce 2.4.0.

get_surface()¶

Get the window surface.

get_surface() -> Surface

Returns a "display surface" for this Window. The surface returned is analogous to the surface returned by pygame.display.set_mode()Initialize a window or screen for display..

This method allows software rendering (classic pygame rendering) on top of the Window API. This method should not be called when using hardware rendering (coming soon).

Similarly to the "display surface" returned by pygame.displayPygame module to control the display window and screen., this surface will change size with the Window, and will become invalid after the Window's destruction.

See also

flip()

New in pygame-ce 2.4.0.

flip()¶

Update the display surface to the window.

flip() -> None

Update pixel data from memory to be displayed in the window. This is the Window class equivalent of pygame.display.flip()Update the full display Surface to the screen..

With get_surface() this method allows software rendering (classic pygame rendering) flipping pixel data from an associated surface in memory to be displayed in the window. Alternatively, when this window has an associated OpenGL context, this method will instead perform a GL buffer swap to the window.

Here is a runnable example of using get_surface and flip:

import pygame

win = pygame.Window()
surf = win.get_surface()  # get the window surface

while True:
   for event in pygame.event.get():
      if event.type == pygame.QUIT:
            pygame.quit()
            raise SystemExit

   # draw something on the surface
   surf.fill("red")

   win.flip()  # update the surface to the window

New in pygame-ce 2.4.0.

set_windowed()¶: Enable windowed mode (exit fullscreen).

set_windowed() -> None

See also

set_fullscreen()

set_fullscreen()¶

Enter fullscreen.

set_fullscreen(desktop=False) -> None

Parameters:: desktop (bool) -- If True, use the current desktop resolution. If False, change the fullscreen resolution to the window size.

See also

set_windowed().

destroy()¶

Destroy the window.

destroy() -> None

Destroys the internal window data of this Window object. This method is called automatically when this Window object is garbage collected, so there usually aren't any reasons to call it manually.

Other methods that try to manipulate that window data will raise an error.

hide()¶: Hide the window.

hide() -> None

show()¶: Show the window.

show() -> None

focus()¶

Set the window to be focused.

focus(input_only=False) -> None

Raises the window above other windows and sets the input focus.

Parameters:: input_only -- if True, the window will be given input focus but may be completely obscured by other windows. Only supported on X11. This has been deprecated and may be removed in a future version.

Deprecated since pygame-ce 2.5.3: input_only argument

restore()¶: Restore the size and position of a minimized or maximized window.

restore() -> None

maximize()¶: Maximize the window.

maximize() -> None

minimize()¶: Minimize the window.

minimize() -> None

set_icon()¶

Set the window icon.

set_icon(icon, /) -> None

Parameters:: surface (Surface) -- A Surface to use as the icon.

set_modal_for()¶

Set the window as a modal for a parent window.

set_modal_for(parent, /) -> None

Parameters:: parent (Window) -- The parent window.

Note

This function is only supported on X11.

flash()¶

Flash a window to demand attention from the user.

flash(operation, /) -> None

Parameters:: operation (int) -- The flash operation.

Supported flash operations are:

pygame.FLASH_CANCEL: Cancel the current flash state if present
pygame.FLASH_BRIEFLY: Flash for a short amount of time to get attention
pygame.FLASH_UNTIL_FOCUSED: Keep flashing until the window is focused

Window flashing requires SDL 2.0.16+. A pygame.errorstandard pygame exception exception will be raised otherwise.

Note

This function is only supported on Windows, X11, Wayland and Cocoa (MacOS). A pygame.errorstandard pygame exception exception will be raised if it's not supported therefore it's advised to wrap it in a try block.

import pygame
window = pygame.Window()

try:
    window.flash(pygame.FLASH_BRIEFLY)
except pygame.error:
    print("Window flashing not supported")

New in pygame-ce 2.5.2.

Edit on GitHub

pygame-ce documentation