pygame.event

pygame documentation

|| Home || Help Contents ||

|| pygame || cdrom || constants || cursor || display || draw ||
|| event || font || image || joystick || key || mixer ||
|| mixer_music || mouse || movie || sndarray || surfarray || time ||
|| transform ||

|| CD || Channel || Clock || Font || Joystick || Movie ||
|| Overlay || 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 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.

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

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

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

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

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

pump()

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

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

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.