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.
Call the Window constructor to create a new window:
from pyglet.window import Window
win = Window(width=640, height=480)
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()
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()
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 = window.get_platform().get_default_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.
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])
Window
(width=None, height=None, caption=None, resizable=False, style=None, fullscreen=False, visible=True, vsync=True, display=None, screen=None, config=None, context=None, mode=None)¶Bases: pyglet.event.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 switch_to, to make it the current OpenGL context. If you use only one window in the application, there is no need to do this.
Methods
activate
()¶Attempt to restore keyboard focus to the window.
Depending on the window manager or operating system, this may not be successful. For example, on Windows XP an application is not allowed to “steal” focus from another application. Instead, the window’s taskbar icon will flash, indicating it requires attention.
clear
()¶Clear the window.
This is a convenience method for clearing the color and depth buffer. The window must be the active context (see switch_to).
close
()¶Close the window.
After closing the window, the GL context will be invalid. The window instance cannot be reused once closed (see also set_visible).
The pyglet.app.EventLoop.on_window_close event is dispatched on pyglet.app.event_loop when this method is called.
dispatch_event
(*args)¶dispatch_events
()¶Poll the operating system event queue for new events and call attached event handlers.
This method is provided for legacy applications targeting pyglet 1.0, and advanced applications that must integrate their event loop into another framework.
Typical applications should use pyglet.app.run.
draw_mouse_cursor
()¶Draw the custom mouse cursor.
If the current mouse cursor has drawable
set, this method
is called before the buffers are flipped to render it.
This method always leaves the GL_MODELVIEW
matrix as current,
regardless of what it was set to previously. No other GL state
is affected.
There is little need to override this method; instead, subclass
MouseCursor
and provide your own
draw()
method.
flip
()¶Swap the OpenGL front and back buffers.
Call this method on a double-buffered window to update the visible display with the back buffer. The contents of the back buffer is undefined after this operation.
Windows are double-buffered by default. This method is called
automatically by EventLoop after the on_draw()
event.
get_location
()¶Return the current position of the window.
Return type: | (int, int) |
---|---|
Returns: | The distances of the left and top edges from their respective edges on the virtual desktop, in pixels. |
get_size
()¶Return the current size of the window.
The window size does not include the border or title bar.
Return type: | (int, int) |
---|---|
Returns: | The width and height of the window, in pixels. |
get_system_mouse_cursor
(name)¶Obtain a system mouse cursor.
Use set_mouse_cursor to make the cursor returned by this method
active. The names accepted by this method are the CURSOR_*
constants defined on this class.
Parameters: | name (str) – Name describing the mouse cursor to return. For example,
CURSOR_WAIT , CURSOR_HELP , etc. |
---|---|
Return type: | MouseCursor |
Returns: | A mouse cursor which can be used with set_mouse_cursor. |
maximize
()¶Maximize the window.
The behaviour of this method is somewhat dependent on the user’s display setup. On a multi-monitor system, the window may maximize to either a single screen or the entire virtual desktop.
minimize
()¶Minimize the window.
set_caption
(caption)¶Set the window’s caption.
The caption appears in the titlebar of the window, if it has one, and in the taskbar on Windows and many X11 window managers.
Parameters: | caption (str or unicode) – The caption to set. |
---|
set_exclusive_keyboard
(exclusive=True)¶Prevent the user from switching away from this window using keyboard accelerators.
When enabled, this feature disables certain operating-system specific key combinations such as Alt+Tab (Command+Tab on OS X). This can be useful in certain kiosk applications, it should be avoided in general applications or games.
Parameters: | exclusive (bool) – If True, exclusive keyboard is enabled, otherwise it is disabled. |
---|
set_exclusive_mouse
(exclusive=True)¶Hide the mouse cursor and direct all mouse events to this window.
When enabled, this feature prevents the mouse leaving the window. It
is useful for certain styles of games that require complete control of
the mouse. The position of the mouse as reported in subsequent events
is meaningless when exclusive mouse is enabled; you should only use
the relative motion parameters dx
and dy
.
Parameters: | exclusive (bool) – If True, exclusive mouse is enabled, otherwise it is disabled. |
---|
set_fullscreen
(fullscreen=True, screen=None, mode=None, width=None, height=None)¶Toggle to or from fullscreen.
After toggling fullscreen, the GL context should have retained its state and objects, however the buffers will need to be cleared and redrawn.
If width and height are specified and fullscreen is True, the screen may be switched to a different resolution that most closely matches the given size. If the resolution doesn’t match exactly, a higher resolution is selected and the window will be centered within a black border covering the rest of the screen.
Parameters: |
|
---|
set_icon
(*images)¶Set the window icon.
If multiple images are provided, one with an appropriate size will be selected (if the correct size is not provided, the image will be scaled).
Useful sizes to provide are 16x16, 32x32, 64x64 (Mac only) and 128x128 (Mac only).
Parameters: | images (sequence of pyglet.image.AbstractImage) – List of images to use for the window icon. |
---|
set_location
(x, y)¶Set the position of the window.
Parameters: |
|
---|
set_maximum_size
(width, height)¶Set the maximum size of the window.
Once set, the user will not be able to resize the window larger than the given dimensions. There is no way to remove the maximum size constraint on a window (but you could set it to a large value).
The behaviour is undefined if the maximum size is set smaller than the current size of the window.
The window size does not include the border or title bar.
Parameters: |
|
---|
set_minimum_size
(width, height)¶Set the minimum size of the window.
Once set, the user will not be able to resize the window smaller than the given dimensions. There is no way to remove the minimum size constraint on a window (but you could set it to 0,0).
The behaviour is undefined if the minimum size is set larger than the current size of the window.
The window size does not include the border or title bar.
Parameters: |
|
---|
set_mouse_cursor
(cursor=None)¶Change the appearance of the mouse cursor.
The appearance of the mouse cursor is only changed while it is within this window.
Parameters: | cursor (MouseCursor) – The cursor to set, or None to restore the default cursor. |
---|
set_mouse_platform_visible
(platform_visible=None)¶Set the platform-drawn mouse cursor visibility. This is called automatically after changing the mouse cursor or exclusive mode.
Applications should not normally need to call this method, see set_mouse_visible instead.
Parameters: | platform_visible (bool or None) – If None, sets platform visibility to the required visibility for the current exclusive mode and cursor type. Otherwise, a bool value will override and force a visibility. |
---|
set_mouse_visible
(visible=True)¶Show or hide the mouse cursor.
The mouse cursor will only be hidden while it is positioned within this window. Mouse events will still be processed as usual.
Parameters: | visible (bool) – If True, the mouse cursor will be visible, otherwise it will be hidden. |
---|
set_size
(width, height)¶Resize the window.
The behaviour is undefined if the window is not resizable, or if it is currently fullscreen.
The window size does not include the border or title bar.
Parameters: |
|
---|
set_visible
(visible=True)¶Show or hide the window.
Parameters: | visible (bool) – If True, the window will be shown; otherwise it will be hidden. |
---|
switch_to
()¶Make this window the current OpenGL rendering context.
Only one OpenGL context can be active at a time. This method sets the current window’s context to be current. You should use this method in preference to pyglet.gl.Context.set_current, as it may perform additional initialisation functions.
Events
on_activate
()¶The window was activated.
This event can be triggered by clicking on the title bar, bringing it to the foreground; or by some platform-specific method.
When a window is “active” it has the keyboard focus.
on_close
()¶The user attempted to close the window.
This event can be triggered by clicking on the “X” control box in the window title bar, or by some other platform-dependent manner.
The default handler sets has_exit to True
. In pyglet 1.1, if
pyglet.app.event_loop is being used, close is also called,
closing the window immediately.
on_context_lost
()¶The window’s GL context was lost.
When the context is lost no more GL methods can be called until it is recreated. This is a rare event, triggered perhaps by the user switching to an incompatible video mode. When it occurs, an application will need to reload all objects (display lists, texture objects, shaders) as well as restore the GL state.
on_context_state_lost
()¶The state of the window’s GL context was lost.
pyglet may sometimes need to recreate the window’s GL context if the window is moved to another video device, or between fullscreen or windowed mode. In this case it will try to share the objects (display lists, texture objects, shaders) between the old and new contexts. If this is possible, only the current state of the GL context is lost, and the application should simply restore state.
on_deactivate
()¶The window was deactivated.
This event can be triggered by clicking on another application window. When a window is deactivated it no longer has the keyboard focus.
on_draw
()¶The window contents must be redrawn.
The EventLoop will dispatch this event when the window should be redrawn. This will happen during idle time after any window events and after any scheduled functions were called.
The window will already have the GL context, so there is no need to call switch_to. The window’s flip method will be called after this event, so your event handler should not.
You should make no assumptions about the window contents when this event is triggered; a resize or expose event may have invalidated the framebuffer since the last time it was drawn.
New in version 1.1.
on_expose
()¶A portion of the window needs to be redrawn.
This event is triggered when the window first appears, and any time the contents of the window is invalidated due to another window obscuring it.
There is no way to determine which portion of the window needs redrawing. Note that the use of this method is becoming increasingly uncommon, as newer window managers composite windows automatically and keep a backing store of the window contents.
on_hide
()¶The window was hidden.
This event is triggered when a window is minimised or (on Mac OS X) hidden by the user.
on_key_press
(symbol, modifiers)¶A key on the keyboard was pressed (and held down).
In pyglet 1.0 the default handler sets has_exit to True
if
the ESC
key is pressed.
In pyglet 1.1 the default handler dispatches the on_close()
event if the ESC
key is pressed.
Parameters: |
|
---|
on_key_release
(symbol, modifiers)¶A key on the keyboard was released.
Parameters: |
|
---|
on_mouse_drag
(x, y, dx, dy, buttons, modifiers)¶The mouse was moved with one or more mouse buttons pressed.
This event will continue to be fired even if the mouse leaves the window, so long as the drag buttons are continuously held down.
Parameters: |
|
---|
on_mouse_enter
(x, y)¶The mouse was moved into the window.
This event will not be trigged if the mouse is currently being dragged.
Parameters: |
|
---|
on_mouse_leave
(x, y)¶The mouse was moved outside of the window.
This event will not be trigged if the mouse is currently being dragged. Note that the coordinates of the mouse pointer will be outside of the window rectangle.
Parameters: |
|
---|
on_mouse_motion
(x, y, dx, dy)¶The mouse was moved with no buttons held down.
Parameters: |
|
---|
on_mouse_press
(x, y, button, modifiers)¶A mouse button was pressed (and held down).
Parameters: |
|
---|
on_mouse_release
(x, y, button, modifiers)¶A mouse button was released.
Parameters: |
|
---|
on_mouse_scroll
(x, y, scroll_x, scroll_y)¶The mouse wheel was scrolled.
Note that most mice have only a vertical scroll wheel, so scroll_x is usually 0. An exception to this is the Apple Mighty Mouse, which has a mouse ball in place of the wheel which allows both scroll_x and scroll_y movement.
Parameters: |
|
---|
on_move
(x, y)¶The window was moved.
Parameters: |
|
---|
on_resize
(width, height)¶The window was resized.
The window will have the GL context when this event is dispatched; there is no need to call switch_to in this handler.
Parameters: |
|
---|
on_show
()¶The window was shown.
This event is triggered when a window is restored after being minimised, or after being displayed for the first time.
on_text
(text)¶The user input some text.
Typically this is called after on_key_press()
and before
on_key_release()
, but may also be called multiple times if the key
is held down (key repeating); or called without key presses if
another input method was used (e.g., a pen input).
You should always use this method for interpreting text, as the key symbols often have complex mappings to their unicode representation which this event takes care of.
Parameters: | text (unicode) – The text entered by the user. |
---|
on_text_motion
(motion)¶The user moved the text input cursor.
Typically this is called after on_key_press()
and before
on_key_release()
, but may also be called multiple times if the key
is help down (key repeating).
You should always use this method for moving the text input cursor (caret), as different platforms have different default keyboard mappings, and key repeats are handled correctly.
The values that motion can take are defined in
pyglet.window.key
:
Parameters: | motion (int) – The direction of motion; see remarks. |
---|
on_text_motion_select
(motion)¶The user moved the text input cursor while extending the selection.
Typically this is called after on_key_press()
and before
on_key_release()
, but may also be called multiple times if the key
is help down (key repeating).
You should always use this method for responding to text selection
events rather than the raw on_key_press()
, as different platforms
have different default keyboard mappings, and key repeats are
handled correctly.
The values that motion can take are defined in pyglet.window.key
:
Parameters: | motion (int) – The direction of selection motion; see remarks. |
---|
Attributes
caption
¶The window caption (title). Read-only.
Type: | str |
---|
config
¶A GL config describing the context of this window. Read-only.
Type: | pyglet.gl.Config |
---|
context
¶The OpenGL context attached to this window. Read-only.
Type: | pyglet.gl.Context |
---|
fullscreen
¶True if the window is currently fullscreen. Read-only.
Type: | bool |
---|
has_exit
= False¶height
¶The height of the window, in pixels. Read-write.
Type: | int |
---|
invalid
= True¶resizeable
¶True if the window is resizable. Read-only.
Type: | bool |
---|
screen
¶The screen this window is fullscreen in. Read-only.
Type: | Screen |
---|
style
¶The window style; one of the WINDOW_STYLE_*
constants.
Read-only.
Type: | int |
---|
visible
¶True if the window is currently visible. Read-only.
Type: | bool |
---|
vsync
¶True if buffer flips are synchronised to the screen’s vertical retrace. Read-only.
Type: | bool |
---|
width
¶The width of the window, in pixels. Read-write.
Type: | int |
---|
Class attributes: cursor names
CURSOR_CROSSHAIR
= ‘crosshair’¶CURSOR_DEFAULT
= None¶CURSOR_HAND
= ‘hand’¶CURSOR_HELP
= ‘help’¶CURSOR_NO
= ‘no’¶CURSOR_SIZE
= ‘size’¶CURSOR_SIZE_DOWN
= ‘size_down’¶CURSOR_SIZE_DOWN_LEFT
= ‘size_down_left’¶CURSOR_SIZE_DOWN_RIGHT
= ‘size_down_right’¶CURSOR_SIZE_LEFT
= ‘size_left’¶CURSOR_SIZE_LEFT_RIGHT
= ‘size_left_right’¶CURSOR_SIZE_RIGHT
= ‘size_right’¶CURSOR_SIZE_UP
= ‘size_up’¶CURSOR_SIZE_UP_DOWN
= ‘size_up_down’¶CURSOR_SIZE_UP_LEFT
= ‘size_up_left’¶CURSOR_SIZE_UP_RIGHT
= ‘size_up_right’¶CURSOR_TEXT
= ‘text’¶CURSOR_WAIT
= ‘wait’¶CURSOR_WAIT_ARROW
= ‘wait_arrow’¶Class attributes: window styles
WINDOW_STYLE_BORDERLESS
= ‘borderless’¶WINDOW_STYLE_DEFAULT
= None¶WINDOW_STYLE_DIALOG
= ‘dialog’¶WINDOW_STYLE_TOOL
= ‘tool’¶Display
¶A display device supporting one or more screens.
Use Platform.get_display or Platform.get_default_display to obtain an instance of this class. Use a display to obtain Screen instances.
Warning
Deprecated. Use pyglet.canvas.Display.
get_default_screen
()¶Get the default screen as specified by the user’s operating system preferences.
Return type: | Screen |
---|
get_screens
()¶Get the available screens.
A typical multi-monitor workstation comprises one Display with multiple Screen s. This method returns a list of screens which can be enumerated to select one for full-screen display.
For the purposes of creating an OpenGL config, the default screen will suffice.
Return type: | list of Screen |
---|
get_windows
()¶Get the windows currently attached to this display.
Return type: | sequence of Window |
---|
Platform
¶Operating-system-level functionality.
The platform instance can only be obtained with get_platform. Use the platform to obtain a Display instance.
Warning
Deprecated. Use pyglet.canvas.Display
get_default_display
()¶Get the default display device.
Warning
Deprecated. Use pyglet.canvas.get_display.
Return type: | Display |
---|
get_display
(name)¶Get a display device by name.
This is meaningful only under X11, where the name is a
string including the host name and display number; for example
"localhost:1"
.
On platforms other than X11, name is ignored and the default display is returned. pyglet does not support multiple multiple video devices on Windows or OS X. If more than one device is attached, they will appear as a single virtual device comprising all the attached screens.
Warning
Deprecated. Use pyglet.canvas.get_display.
Parameters: | name (str) – The name of the display to connect to. |
---|---|
Return type: | Display |
FPSDisplay
(window)¶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:
window = pyglet.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. Different text can be substituted by overriding the
set_fps method. The display can be set to update more or less often
by setting the update_period attribute.
Variables: | label (Label) – The text label displaying the framerate. |
---|
draw
()¶Draw the label.
The OpenGL state is assumed to be at default values, except that the MODELVIEW and PROJECTION matrices are ignored. At the return of this method the matrix mode will be MODELVIEW.
set_fps
(fps)¶Set the label text for the given FPS estimation.
Called by update every update_period seconds.
Parameters: | fps (float) – Estimated framerate of the window. |
---|
update
()¶Records a new data point at the current time. This method is called automatically when the window buffer is flipped.
update_period
= 0.25¶Time in seconds between updates.
Type: | float |
---|
MouseCursor
¶An abstract mouse cursor.
draw
(x, y)¶Abstract render method.
The cursor should be drawn with the “hot” spot at the given coordinates. The projection is set to the pyglet default (i.e., orthographic in window-space), however no other aspects of the state can be assumed.
Parameters: |
|
---|
drawable
= True¶Indicates if the cursor is drawn using OpenGL. This is True for all mouse cursors except system cursors.
DefaultMouseCursor
¶Bases: pyglet.window.MouseCursor
The default mouse cursor #sed by the operating system.
ImageMouseCursor
(image, hot_x=0, hot_y=0)¶Bases: pyglet.window.MouseCursor
A user-defined mouse cursor created from an image.
Use this class to create your own mouse cursors and assign them to windows. There are no constraints on the image size or format.
draw
(x, y)¶drawable
= True¶MouseCursorException
¶The root exception for all mouse cursor-related errors.
NoSuchConfigException
¶An exception indicating the requested configuration is not available.
NoSuchDisplayException
¶An exception indicating the requested display is not available.
WindowException
¶The root exception for all window-related errors.