pygame documentation | || Home || Help Contents || || pygame || cdrom || constants || display || draw || event || || font || image || joystick || key || mixer || mixer_music || || mouse || movie || sndarray || surfarray || time || transform || || CD || Channel || Clock || Font || Joystick || Movie || || Rect || Sound || Surface || || color || cursors || sprite ||

## pygame.event

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 stack of Event objects, there are a variety of ways to access the data on the queue. 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.
Also know that you will not receive any events from a joystick device, until you have initialized that individual joystick from the joystick module.

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.
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
MOUSEBUTTONDOWN | pos, button
JOYAXISMOTION | joy, axis, value
JOYBALLMOTION | joy, ball, rel
JOYHATMOTION | joy, hat, value
JOYBUTTONUP | joy, button
JOYBUTTONDOWN | joy, button
VIDEORESIZE | size
VIDEOEXPOSE | none
USEREVENT | code

Event | - create new event object
clear | - remove all of an event type from the queue
event_name | - name for event type
get | - get all of an event type from the queue
get_blocked | - checks if an event is being blocked
get_grab | - query the state of input grabbing
peek | - query if any of event types are waiting
poll | - get an available event
post | - place an event on the queue
pump | - update the internal messages
set_allowed | - allows certain events onto the queue
set_blocked | - blocks certain events from the queue
set_grab | - grab all input events
wait | - wait for an event

Event
`pygame.event.Event(type, [dict], [keyword_args]) -> Event`

Creates a new event object. The type should be one of SDL's event numbers, or above USEREVENT. The given dictionary contains the keys that will be members of the new event.
Also, instead of passing a dictionary to create the event members, you can pass keyword arguments that will become the attributes of the new event.

clear
`pygame.event.clear([type]) -> None`

Pass this a type of event to discard, and it will remove all matching event types from the queue. If no types are passed, this will remove all the events from the queue. You may also optionally pass a sequence of event types. For example, to remove all the mouse motion events from the queue, you would call, 'pygame.event.clear(MOUSEMOTION)'.

event_name
`pygame.event.event_name(event type) -> string`

Returns the standard SDL name for an event type. Mainly helpful for debugging, when trying to determine what the type of an event is.

get
`pygame.event.get([type]) -> list of Events`

Pass this a type of event that you are interested in, and it will return a list of all matching event types from the queue. If no types are passed, this will return all the events from the queue. You may also optionally pass a sequence of event types. For example, to fetch all the keyboard events from the queue, you would call, 'pygame.event.get([KEYDOWN,KEYUP])'.

get_blocked
`pygame.event.get_blocked(type) -> boolean`

This returns a true value if the given event type is being blocked from the queue. You can optionally pass a sequence of event types, and it will return TRUE if any of the types are blocked.

get_grab
`pygame.event.get_grab() -> bool`

Returns true if the input is currently grabbed to your application.

peek
`pygame.event.peek([type]) -> bool`

Pass this a type of event that you are interested in, and it will return true if there are any of that type of event on the queue. If no types are passed, this will return the next event on the queue without removing it. You may also optionally pass a sequence of event types. For example, to find if any keyboard events are on the queue, you would call, 'pygame.event.peek([KEYDOWN,KEYUP])'.

poll
`pygame.event.poll() -> Event`

Returns next event on queue. If there is no event waiting on the queue, this will return an event with type NOEVENT.

post
`pygame.event.post(Event) -> None`

This will post your own event objects onto the event queue. You can past any event type you want, but some care must be taken. For example, if you post a MOUSEBUTTONDOWN event to the queue, it is likely any code receiving the event will excpect the standard MOUSEBUTTONDOWN attributes to be available, like 'pos' and 'button'.

pump
`pygame.event.pump() -> None`

For each frame of your game, you will need to make some sort of call to the event queue. This ensures your program can internally interact with the rest of the operating system. If you are not using other event functions in your game, you should call pump() to allow pygame to handle internal actions.
There are important things that must be dealt with internally in the event queue. The main window may need to be repainted. Certain joysticks must be polled for their values. If you fail to make a call to the event queue for too long, the system may decide your program has locked up.

set_allowed
`pygame.event.set_allowed(type) -> None`

By default, all events will appear from the queue. After you have blocked some event types, you can use this to re-enable them. You can optionally pass a sequence of event types.
You can pass None and this will allow no events on the queue.

set_blocked
`pygame.event.set_blocked(type) -> None`

By default, all events will appear from the queue. This will allow you to prevent event types from appearing on the queue. You can optionally pass a sequence of event types.
You can pass None and this will allow all events on the queue.

set_grab
`pygame.event.set_grab(bool) -> None`

Grabs all mouse and keyboard input for the display. Grabbing the input is not neccessary to receive keyboard and mouse events, but it ensures all input will go to your application. It also keeps the mouse locked inside your window. Set the grabbing on or off with the boolean argument. It is best to not always grab the input, since it prevents the end user from doing anything else on their system.

wait
`pygame.event.wait() -> Event`

Returns the current event on the queue. If there are no messages waiting on the queue, this will not return until one is available. Sometimes it is important to use this wait to get events from the queue, it will allow your application to idle when the user isn't doing anything with it.