pygame debug patch / docs / reST / ref / event.rst

Full commit


Pygame handles all it's event messaging through an event queue. The routines in this module help you manage that event queue. The input queue is heavily dependent on the pygame display module. If the display has not been initialized and a video mode not set, the event queue will not really work.

The queue is a regular queue of Event objects, there are a variety of ways to access the events it contains. From simply checking for the existance of events, to grabbing them directly off the stack.

All events have a type identifier. This event type is in between the values of NOEVENT and NUMEVENTS. All user defined events can have the value of USEREVENT or higher. It is recommended make sure your event id's follow this system.

To get the state of various input devices, you can forego the event queue and access the input devices directly with their appropriate modules; mouse, key, and joystick. If you use this method, remember that pygame requires some form of communication with the system window manager and other parts of the platform. To keep pygame in synch with the system, you will need to call pygame.event.pump() to keep everything current. You'll want to call this function usually once per game loop.

The event queue offers some simple filtering. This can help performance slightly by blocking certain event types from the queue, use the pygame.event.set_allowed() and pygame.event.set_blocked() to work with this filtering. All events default to allowed.

The event subsystem should be called from the main thread. If you want to post events into the queue from other threads, please use the fastevent package.

Joysticks will not send any events until the device has been initialized.

An Event object contains an event type and a readonly set of member data. The Event object contains no method functions, just member data. Event objects are retrieved from the pygame event queue. You can create your own new events with the pygame.event.Event() function.

Your program must take steps to keep the event queue from overflowing. If the program is not clearing or getting all events off the queue at regular intervals, it can overflow. When the queue overflows an exception is thrown.

All Event objects contain an event type identifier in the Event.type member. You may also get full access to the Event's member data through the Event.dict method. All other member lookups will be passed through to the Event's dictionary values.

While debugging and experimenting, you can print the Event objects for a quick display of its type and members. Events that come from the system will have a guaranteed set of member items based on the type. Here is a list of the Event members that are defined with each type.

QUIT             none
ACTIVEEVENT      gain, state
KEYDOWN          unicode, key, mod
KEYUP            key, mod
MOUSEMOTION      pos, rel, buttons
MOUSEBUTTONUP    pos, button
JOYAXISMOTION    joy, axis, value
JOYBALLMOTION    joy, ball, rel
JOYHATMOTION     joy, hat, value
JOYBUTTONUP      joy, button
JOYBUTTONDOWN    joy, button
VIDEORESIZE      size, w, h
USEREVENT        code

Events support equality comparison. Two events are equal if they are the same type and have identical attribute values. Inequality checks also work.