pyglet.app

Application-wide functionality.

Applications

Most applications need only call run() after creating one or more windows to begin processing events. For example, a simple application consisting of one window is:

import pyglet

win = pyglet.window.Window()
pyglet.app.run()

Events

To handle events on the main event loop, instantiate it manually. The following example exits the application as soon as any window is closed (the default policy is to wait until all windows are closed):

event_loop = pyglet.app.EventLoop()

@event_loop.event
def on_window_close(window):
    event_loop.exit()

New in version 1.1.

Classes

class EventLoop

The main run loop of the application.

Calling run begins the application event loop, which processes operating system events, calls pyglet.clock.tick() to call scheduled functions and calls pyglet.window.Window.on_draw() and pyglet.window.Window.flip() to update window contents.

Applications can subclass EventLoop and override certain methods to integrate another framework’s run loop, or to customise processing in some other way. You should not in general override run(), as this method contains platform-specific code that ensures the application remains responsive to the user while keeping CPU usage to a minimum.

Methods

run(interval: float | None = 0.016666666666666666) → None

Begin processing events, scheduled functions and window updates.

This method enters into the main event loop and, if the interval argument is not changed, schedules calling the pyglet.window.Window.draw() method. You can change the interval argument to suit your needs.

Parameters:: interval (float | None) – Windows redraw interval, in seconds (framerate). If interval == 0, windows will redraw as fast as possible. This can saturate a CPU core, so do not do this unless GPU bound. If interval is None, pyglet will not schedule calls to the pyglet.window.Window.draw() method. Users must schedule this themselves for each Window (or call it on-demand). This allows setting a custom framerate per window, or changing framerate during runtime (see example in the documentation).
Return type:: None

This method returns when has_exit is set to True. IE: when exit() is called.

Developers are discouraged from overriding the run method, as the implementation is platform-specific.

exit() → None

Safely exit the event loop at the end of the current iteration.

This method is a thread-safe equivalent for setting has_exit to True. All waiting threads will be interrupted (see sleep()).

Return type:: None

sleep(timeout: float) → bool

Wait for some amount of time.

Waits until the has_exit flag is set or exit() is called.

This method is thread-safe.

Parameters:: timeout (float) – Time to sleep, in seconds.
Return type:: bool

New in version 1.2.

Events

on_enter() → None

The event loop is about to begin.

This is dispatched when the event loop is prepared to enter the main run loop, and represents the last chance for an application to initialise itself.

Return type:: None

on_exit() → None

The event loop is about to exit.

After dispatching this event, the run() method returns (the application may not actually exit if you have more code following the run() invocation).

Return type:: None

on_window_close(window: Window) → None

A window was closed.

This event is dispatched when a window is closed. It is not dispatched if the window’s close button was pressed but the window did not close.

The default handler calls exit() if no more windows are open. You can override this handler to base your application exit on some other policy.

Return type:: None

Attributes

has_exit

Flag indicating if the event loop will exit in the next iteration.

When set, all waiting threads are interrupted.

:see sleep():

Thread-safe since pyglet 1.2.

Methods (internal)

enter_blocking() → None

Called by pyglet internal processes when the operating system is about to block due to a user interaction.

For example, this is common when the user begins resizing or moving a window.

This method provides the event loop with an opportunity to set up an OS timer on the platform event loop, which will continue to be invoked during the blocking operation.

The default implementation ensures that idle() continues to be called as documented. :rtype: None

New in version 1.2.

static exit_blocking() → None

Called by pyglet internal processes when the blocking operation completes.

See:: enter_blocking().
Return type:: None

idle() → None | float

Called during each iteration of the event loop.

The method is called immediately after any window events (i.e., after any user input). The method can return a duration after which the idle method will be called again. The method may be called earlier if the user creates more input events. The method can return None to only wait for user events.

For example, return 1.0 to have the idle method called every second, or immediately after any user events.

The default implementation dispatches the pyglet.window.Window.on_draw() event for all windows and uses pyglet.clock.tick() and pyglet.clock.get_sleep_time() on the default clock to determine the return value.

This method should be overridden by advanced users only. To have code execute at regular intervals, use the pyglet.clock.schedule() methods.

Return type:: None | float
Returns:: The number of seconds before the idle method should be called again, or None to block for user input.

__init__() → None

__new__(**kwargs)

class PlatformEventLoop

Abstract class, implementation depends on platform.

New in version 1.2.

__init__() → None

dispatch_posted_events() → None

Immediately dispatch all pending events.

Normally this is called automatically by the runloop iteration.

Return type:: None

is_running() → bool

If the event loop is currently processing.

True if running, or False if it is blocked or not activated.

Return type:: bool

notify() → None

Notify the event loop that something needs processing.

If the event loop is blocked, it will unblock and perform an iteration immediately. If the event loop is running, another iteration is scheduled for immediate execution afterward.

Return type:: None

post_event( dispatcher: EventDispatcher, event: str, *args: Any, ) → None

Post an event into the main application thread.

The event is queued internally until the run() method’s thread is able to dispatch the event. This method can be safely called from any thread.

If the method is called from the run() method’s thread (for example, from within an event handler), the event may be dispatched within the same runloop iteration or the next one; the choice is nondeterministic.

Return type:: None

set_timer(func: Callable, interval: float) → None

Return type:: None

start() → None

Return type:: None

step(timeout: None | float = None) → None

Return type:: None

stop() → None

Return type:: None

Functions

run(interval: float | None = 0.016666666666666666) → None

Begin processing events, scheduled functions and window updates.

This is a convenience function, equivalent to:

pyglet.app.event_loop.run()

Return type:: None

exit() → None

Exit the application event loop.

Causes the application event loop to finish, if an event loop is currently running. The application may not necessarily exit (for example, there may be additional code following the run invocation).

This is a convenience function, equivalent to:

event_loop.exit()

Return type:: None

Attributes

event_loop = <pyglet.app.base.EventLoop object>: The global event loop. Applications can replace this with their own subclass of EventLoop before calling EventLoop.run().

platform_event_loop = <pyglet.app.base.PlatformEventLoop object>: Abstract class, implementation depends on platform.

New in version 1.2.

windows = set(): Set of all open windows (including invisible windows). Instances of pyglet.window.Window are automatically added to this set upon construction. The set uses weak references, so windows are removed from the set when they are no longer referenced or are closed explicitly.

Exceptions

class AppException

__init__(*args, **kwargs)

__new__(**kwargs)