EventLoop Class

Inheritance diagram of EventLoop

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.

Constructor:

__init__()

Methods:

dispatch_event(event_type, *args) Dispatch a single event to the attached handlers.
enter_blocking() Called by pyglet internal processes when the operating system is about to block due to a user interaction.
event(*args) Function decorator for an event handler.
exit() Safely exit the event loop at the end of the current iteration.
exit_blocking() Called by pyglet internal processes when the blocking operation completes.
idle() Called during each iteration of the event loop.
pop_handlers() Pop the top level of event handlers off the stack.
push_handlers(*args, **kwargs) Push a level onto the top of the handler stack, then attach zero or more event handlers.
register_event_type(name) Register an event type with the dispatcher.
remove_handler(name, handler) Remove a single event handler.
remove_handlers(*args, **kwargs) Remove event handlers from the event stack.
run() Begin processing events, scheduled functions and window updates.
set_handler(name, handler) Attach a single event handler.
set_handlers(*args, **kwargs) Attach one or more event handlers to the top level of the handler stack.
sleep(timeout) Wait for some amount of time, or until the has_exit flag is set or exit is called.

Events:

on_enter() The event loop is about to begin.
on_exit() The event loop is about to exit.
on_window_close(window) A window was closed.

Attributes:

event_types Type: list
has_exit Flag indicating if the event loop will exit in the next iteration.

Methods

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

Note

Since pyglet 1.2

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

EventLoop.exit_blocking()

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

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

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

Note

Since pyglet 1.2

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

Events

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

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

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

EventLoop.event_types = ['on_window_close', 'on_enter', 'on_exit']
EventLoop.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

Inherited members

Methods

EventLoop.dispatch_event(event_type, *args)

Dispatch a single event to the attached handlers.

The event is propagated to all handlers from from the top of the stack until one returns EVENT_HANDLED. This method should be used only by EventDispatcher implementors; applications should call the dispatch_events method.

Since pyglet 1.2, the method returns EVENT_HANDLED if an event handler returned EVENT_HANDLED or EVENT_UNHANDLED if all events returned EVENT_UNHANDLED. If no matching event handlers are in the stack, False is returned.

Parameters:
  • event_type (str) – Name of the event.
  • args (sequence) – Arguments to pass to the event handler.
Return type:

bool or None

Returns:

(Since pyglet 1.2) EVENT_HANDLED if an event handler returned EVENT_HANDLED; EVENT_UNHANDLED if one or more event handlers were invoked but returned only EVENT_UNHANDLED; otherwise False. In pyglet 1.1 and earler, the return value is always None.

EventLoop.event(*args)

Function decorator for an event handler.

Usage:

win = window.Window()

@win.event
def on_resize(self, width, height):
    # ...

or:

@win.event('on_resize')
def foo(self, width, height):
    # ...
EventLoop.pop_handlers()

Pop the top level of event handlers off the stack.

EventLoop.push_handlers(*args, **kwargs)

Push a level onto the top of the handler stack, then attach zero or more event handlers.

If keyword arguments are given, they name the event type to attach. Otherwise, a callable’s __name__ attribute will be used. Any other object may also be specified, in which case it will be searched for callables with event names.

classmethod EventLoop.register_event_type(name)

Register an event type with the dispatcher.

Registering event types allows the dispatcher to validate event handler names as they are attached, and to search attached objects for suitable handlers.

Parameters:name (str) – Name of the event to register.
EventLoop.remove_handler(name, handler)

Remove a single event handler.

The given event handler is removed from the first handler stack frame it appears in. The handler must be the exact same callable as passed to set_handler, set_handlers or push_handlers; and the name must match the event type it is bound to.

No error is raised if the event handler is not set.

Parameters:
  • name (str) – Name of the event type to remove.
  • handler (callable) – Event handler to remove.
EventLoop.remove_handlers(*args, **kwargs)

Remove event handlers from the event stack.

See push_handlers for the accepted argument types. All handlers are removed from the first stack frame that contains any of the given handlers. No error is raised if any handler does not appear in that frame, or if no stack frame contains any of the given handlers.

If the stack frame is empty after removing the handlers, it is removed from the stack. Note that this interferes with the expected symmetry of push_handlers and pop_handlers.

EventLoop.set_handler(name, handler)

Attach a single event handler.

Parameters:
  • name (str) – Name of the event type to attach to.
  • handler (callable) – Event handler to attach.
EventLoop.set_handlers(*args, **kwargs)

Attach one or more event handlers to the top level of the handler stack.

See push_handlers for the accepted argument types.

Table Of Contents

Previous topic

run Function

Next topic

PlatformEventLoop Class