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()

Begin processing events, scheduled functions and window updates.

This method returns when has_exit is set to True.

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

exit()

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

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

sleep(timeout)

Wait for some amount of time, or until the has_exit flag is set or exit() is called.

This method is thread-safe.

Parameters:timeout (float) – Time to wait, in seconds.

New in version 1.2.

Return type:bool Returns:True if the has_exit flag is set, otherwise False.

Events

on_enter()

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.

on_exit()

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).

on_window_close(window)

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.

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.

See:exit Type:bool

Methods (internal)

enter_blocking()

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.

New in version 1.2.

exit_blocking()

Called by pyglet internal processes when the blocking operation completes. See enter_blocking().

idle()

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:float Returns:The number of seconds before the idle method should be called again, or None to block for user input.

class PlatformEventLoop

Abstract class, implementation depends on platform.

New in version 1.2.

dispatch_posted_events()

Immediately dispatch all pending events.

Normally this is called automatically by the runloop iteration.

is_running()

Return True if the event loop is currently processing, or False if it is blocked or not activated.

Return type:bool

notify()

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 afterwards.

post_event(dispatcher, event, *args)

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.

Parameters:

• dispatcher (EventDispatcher) – Dispatcher to process the event.
• event (str) – Event name.
• args (sequence) – Arguments to pass to the event handlers.

set_timer(func, interval)

start()

step(timeout=None)

TODO:in mac/linux: return True if didn’t time out

stop()

class WeakSet

Set of objects, referenced weakly.

Adding an object to this set does not prevent it from being garbage collected. Upon being garbage collected, the object is automatically removed from the set.

add(value)

pop()

remove(value)

Functions

run()

Begin processing events, scheduled functions and window updates.

This is a convenience function, equivalent to:

pyglet.app.event_loop.run()

exit()

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()

Attributes

displays = <pyglet.app.WeakSet object>

Set of all open displays. Instances of pyglet.canvas.Display are automatically added to this set upon construction. The set uses weak references, so displays are removed from the set when they are no longer referenced.

Warning

Deprecated. Use pyglet.canvas.get_display().

Type:WeakSet

event_loop = <pyglet.app.base.EventLoop object>

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.

platform_event_loop = <pyglet.app.base.PlatformEventLoop object>

Abstract class, implementation depends on platform.

New in version 1.2.

windows = <pyglet.app.WeakSet object>

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