pyglet.window

Submodules

Details

Windowing and user-interface events.

This module allows applications to create and display windows with an OpenGL context. Windows can be created with a variety of border styles or set fullscreen.

You can register event handlers for keyboard, mouse and window events. For games and kiosks you can also restrict the input to your windows, for example disabling users from switching away from the application with certain key combinations or capturing and hiding the mouse.

Getting started

Call the Window constructor to create a new window:

from pyglet.window import Window
win = Window(width=960, height=540)

Attach your own event handlers:

@win.event
def on_key_press(symbol, modifiers):
    # ... handle this event ...

Place drawing code for the window within the Window.on_draw event handler:

@win.event
def on_draw():
    # ... drawing code ...

Call pyglet.app.run to enter the main event loop (by default, this returns when all open windows are closed):

from pyglet import app
app.run()

Creating a game window

Use set_exclusive_mouse() to hide the mouse cursor and receive relative mouse movement events. Specify fullscreen=True as a keyword argument to the Window constructor to render to the entire screen rather than opening a window:

win = Window(fullscreen=True)
win.set_exclusive_mouse()

Working with multiple screens

By default, fullscreen windows are opened on the primary display (typically set by the user in their operating system settings). You can retrieve a list of attached screens and select one manually if you prefer. This is useful for opening a fullscreen window on each screen:

display = pyglet.display.get_display()
screens = display.get_screens()
windows = []
for screen in screens:
    windows.append(window.Window(fullscreen=True, screen=screen))

Specifying a screen has no effect if the window is not fullscreen.

Specifying the OpenGL context properties

Each window has its own context which is created when the window is created. You can specify the properties of the context before it is created by creating a “template” configuration:

from pyglet import gl
# Create template config
config = gl.Config()
config.stencil_size = 8
config.aux_buffers = 4
# Create a window using this config
win = window.Window(config=config)

To determine if a given configuration is supported, query the screen (see above, “Working with multiple screens”):

configs = screen.get_matching_configs(config)
if not configs:
    # ... config is not supported
else:
    win = window.Window(config=configs[0])

Classes

class Window

Bases: EventDispatcher

Platform-independent application window.

A window is a “heavyweight” object occupying operating system resources. The “client” or “content” area of a window is filled entirely with an OpenGL viewport. Applications have no access to operating system widgets or controls; all rendering must be done via OpenGL.

Windows may appear as floating regions or can be set to fill an entire screen (fullscreen). When floating, windows may appear borderless or decorated with a platform-specific frame (including, for example, the title bar, minimize and close buttons, resize handles, and so on).

While it is possible to set the location of a window, it is recommended that applications allow the platform to place it according to local conventions. This will ensure it is not obscured by other windows, and appears on an appropriate screen for the user.

To render into a window, you must first call its switch_to() method to make it the active OpenGL context. If you use only one window in your application, you can skip this step as it will always be the active context.

Methods

Events

Attributes

aspect_ratio: The aspect ratio of the window. Read-Only.

caption: The window caption (title). Read-only.

config: A GL config describing the context of this window. Read-only.

context: The OpenGL context attached to this window. Read-only.

display: The display this window belongs to. Read-only.

dpi

DPI values of the Window.

Read only.

fullscreen: True if the window is currently fullscreen. Read-only.

has_exit: bool = False

height: The height of the window, in pixels. Read-write.

invalid: bool = True

projection

The OpenGL window projection matrix. Read-write.

This matrix is used to transform vertices when using any of the built-in drawable classes. view is done first, then projection.

The default projection matrix is orthographic (2D), but a custom Mat4 instance can be set. Alternatively, you can supply a flat tuple of 16 values.

(2D), but can be changed to any 4x4 matrix desired. :see: Mat4.

resizeable: True if the window is resizable. Read-only.

scale

The scale of the window factoring in DPI.

Read only.

screen: The screen this window is fullscreen in. Read-only.

size: The size of the window. Read-Write.

style: The window style; one of the WINDOW_STYLE_* constants. Read-only.

view

The OpenGL window view matrix. Read-write.

This matrix is used to transform vertices when using any of the built-in drawable classes. view is done first, then projection.

The default view is an identity matrix, but a custom Mat4 instance can be set. Alternatively, you can supply a flat tuple of 16 values.

viewport

The Window viewport.

The Window viewport, expressed as (x, y, width, height).

visible: True if the window is currently visible. Read-only.

vsync: True if buffer flips are synchronised to the screen’s vertical retrace. Read-only.

width: The width of the window, in pixels. Read-write.

Class attributes: cursor names

CURSOR_CROSSHAIR: str = 'crosshair'

CURSOR_DEFAULT = None

CURSOR_HAND: str = 'hand'

CURSOR_HELP: str = 'help'

CURSOR_NO: str = 'no'

CURSOR_SIZE: str = 'size'

CURSOR_SIZE_DOWN: str = 'size_down'

CURSOR_SIZE_DOWN_LEFT: str = 'size_down_left'

CURSOR_SIZE_DOWN_RIGHT: str = 'size_down_right'

CURSOR_SIZE_LEFT: str = 'size_left'

CURSOR_SIZE_LEFT_RIGHT: str = 'size_left_right'

CURSOR_SIZE_RIGHT: str = 'size_right'

CURSOR_SIZE_UP: str = 'size_up'

CURSOR_SIZE_UP_DOWN: str = 'size_up_down'

CURSOR_SIZE_UP_LEFT: str = 'size_up_left'

CURSOR_SIZE_UP_RIGHT: str = 'size_up_right'

CURSOR_TEXT: str = 'text'

CURSOR_WAIT: str = 'wait'

CURSOR_WAIT_ARROW: str = 'wait_arrow'

Class attributes: window styles

WINDOW_STYLE_BORDERLESS: str = 'borderless'

WINDOW_STYLE_DEFAULT: None = None

WINDOW_STYLE_DIALOG: str = 'dialog'

WINDOW_STYLE_OVERLAY: str = 'overlay'

WINDOW_STYLE_TOOL: str = 'tool'

WINDOW_STYLE_TRANSPARENT: str = 'transparent'

classmethod __new__(*args, **kwargs)

class FPSDisplay

Bases: object

Display of a window’s framerate.

This is a convenience class to aid in profiling and debugging. Typical usage is to create an FPSDisplay for each window, and draw the display at the end of the windows’ on_draw() event handler:

from pyglet.window import Window, FPSDisplay

window = Window()
fps_display = FPSDisplay(window)

@window.event
def on_draw():
    # ... perform ordinary window drawing operations ...

    fps_display.draw()

The style and position of the display can be modified via the label attribute. The display can be set to update more or less often by setting the update_period attribute.

label: Label: The text label displaying the framerate.

update_period = 0.25: Time in seconds between updates.

class MouseCursor

An abstract mouse cursor.

gl_drawable: bool = True: Indicates if the cursor is drawn using OpenGL, or natively.

hw_drawable: bool = False

class DefaultMouseCursor

Bases: MouseCursor

The default mouse cursor set by the operating system.

__init__()

classmethod __new__(*args, **kwargs)

class ImageMouseCursor

Bases: MouseCursor

A user-defined mouse cursor created from an image.

Use this class to create your own mouse cursors and assign them to windows. Cursors can be drawn by OpenGL, or optionally passed to the OS to render natively. There are no restrictions on cursors drawn by OpenGL, but natively rendered cursors may have some platform limitations (such as color depth, or size). In general, reasonably sized cursors will render correctly

Exceptions

class MouseCursorException

The root exception for all mouse cursor-related errors.

__init__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

class NoSuchConfigException

An exception indicating the requested configuration is not available.

__init__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

class NoSuchDisplayException

An exception indicating the requested display is not available.

__init__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

class WindowException

The root exception for all window-related errors.

__init__(*args, **kwargs)

classmethod __new__(*args, **kwargs)