Dispatching events manually

Earlier versions of pyglet and certain other windowing toolkits such as PyGame and SDL require the application developer to write their own event loop. This "manual" event loop is usually just an inconvenience compared to pyglet.app.run, but can be necessary in some situations when combining pyglet with other toolkits.

A simple event loop usually has the following form:

while True:
    pyglet.clock.tick()

    for window in pyglet.app.windows:
        window.switch_to()
        window.dispatch_events()
        window.dispatch_event('on_draw')
        window.flip()

The dispatch_events method checks the window's operating system event queue for user input and dispatches any events found. The method does not wait for input -- if ther are no events pending, control is returned to the program immediately.

The call to pyglet.clock.tick() is required for ensuring scheduled functions are called, including the internal data pump functions for playing sounds and video.

Developers are strongly discouraged from writing pyglet applications with event loops like this:

• The EventLoop class provides plenty of hooks for most toolkits to be integrated without needing to resort to a manual event loop.
• Because EventLoop is tuned for specific operating systems, it is more responsive to user events, and continues calling clock functions while windows are being resized, and (on Mac OS X) the menu bar is being tracked.
• It is difficult to write a manual event loop that does not consume 100% CPU while still remaining responsive to user input.

The capability for writing manual event loops remains for legacy support and extreme circumstances.