pygame / docs / reST / ref / event.rst


Pygame handles all its 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 :class:`pygame.event.EventType` event objects, there are a variety of ways to access the events it contains. From simply checking for the existence 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 EventType event object contains an event type identifier and a set of member data. The event object contains no method functions, just member data. EventType 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 EventType instances have an event type identifier, accessible as the EventType.type property. You may also get full access to the event object's attributes through the EventType.__dict__ attribute. All other member lookups will be passed through to the object's dictionary values.

While debugging and experimenting, you can print an event object 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 attributes defined with each event 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.

A Python object that represents an SDL event. User event instances are created with an Event function call. The EventType type is not directly callable. EventType instances support attribute assignment and deletion.

Mutable attributes are new to Pygame 1.9.2.