pygame / docs / ref / pygame_event.html

Full commit
<body bgcolor=#dddddd text=#333377 link=#7777bb vlink=#7777bb>

<table border=0 width=100% cellpadding=0 cellspacing=0 bgcolor=#f5f5f5><tr valign=top>
<td rowspan=2><table border=0 cellpadding=5 cellspacing=0 bgcolor=#333377>
<tr height=86 align=left><td valign=middle><font color=#ffffff size=+5>
	<a href=../index.html><font size=+5 color=#ffffff><i><b>
<td valign=middle><tt><font color=#dddddd><br>
</td></tr></table></td><td width=100% align=center valign=middle>

	<a href=>Home</a> &nbsp;||&nbsp;
	<a href=../index.html>Help Contents</a> &nbsp;||

|| <a href=CD.html>CD</a> || 
<a href=Channel.html>Channel</a> || 
<a href=Font.html>Font</a> || 
<a href=Joystick.html>Joystick</a> || 
<a href=Rect.html>Rect</a> || 
<a href=Sound.html>Sound</a> || 
<a href=Surface.html>Surface</a> ||<br>
|| <a href=pygame.html>pygame</a> || 
<a href=pygame_cdrom.html>cdrom</a> || 
<a href=pygame_constants.html>constants</a> || 
<a href=pygame_display.html>display</a> || 
<a href=pygame_event.html>event</a> || 
<a href=pygame_font.html>font</a> || 
<a href=pygame_image.html>image</a> ||<br>
|| <a href=pygame_joystick.html>joystick</a> || 
<a href=pygame_key.html>key</a> || 
<a href=pygame_mixer.html>mixer</a> || 
<a href=pygame_mixer_music.html>mixer_music</a> || 
<a href=pygame_mouse.html>mouse</a> || 
<a href=pygame_surfarray.html>surfarray</a> || 
<a href=pygame_time.html>time</a> ||<br>

<h2 align=center>pygame.event</h2>
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 opened that joystick from the joystick
module.<p>&nbsp;</p>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.


<tr><td><a href=#event_name>event_name</a></td><td> -
name for event type</td></tr>

<tr><td><a href=#get>get</a></td><td> -
get all of an event type from the queue</td></tr>

<tr><td><a href=#new_event>new_event</a></td><td> -
create new event object</td></tr>

<tr><td><a href=#peek>peek</a></td><td> -
query if any of event types are waiting</td></tr>

<tr><td><a href=#poll>poll</a></td><td> -
get an available event</td></tr>

<tr><td><a href=#post>post</a></td><td> -
place an event on the queue</td></tr>

<tr><td><a href=#pump>pump</a></td><td> -
update the internal messages</td></tr>

<tr><td><a href=#set_allowed>set_allowed</a></td><td> -
allows certain events onto the queue</td></tr>

<tr><td><a href=#set_blocked>set_blocked</a></td><td> -
blocks certain events from the queue</td></tr>

<tr><td><a href=#set_grab>set_grab</a></td><td> -
grab all input events</td></tr>

<tr><td><a href=#wait>wait</a></td><td> -
wait for an event</td></tr>



<a name=event_name><font size=+2><b>event_name
</b></font><br><font size=+1><tt>
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

<a name=get><font size=+2><b>get
</b></font><br><font size=+1><tt>
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])'.

<a name=new_event><font size=+2><b>new_event
</b></font><br><font size=+1><tt>
pygame.event.new_event(type, dict) -> Event
Creates a new event object. The type should be one
of SDL's event numbers, or above USER_EVENT. The
given dictionary contains a list of readonly
attributes that will be members of the event

<a name=peek><font size=+2><b>peek
</b></font><br><font size=+1><tt>
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 true if any events are
on the queue. 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])'.

<a name=poll><font size=+2><b>poll
</b></font><br><font size=+1><tt>
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.

<a name=post><font size=+2><b>post
</b></font><br><font size=+1><tt> -> None
This will place an event onto the queue. This is most useful for
putting your own USEREVENT's onto the queue.

<a name=pump><font size=+2><b>pump
</b></font><br><font size=+1><tt>
pygame.event.pump() -> None
Pumping the message queue is important if you are not getting
events off the message queue. The pump will allow pyGame to
communicate with the window manager, which helps keep your
application responsive, as well as updating the state for various
input devices.

<a name=set_allowed><font size=+2><b>set_allowed
</b></font><br><font size=+1><tt>
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.

<a name=set_blocked><font size=+2><b>set_blocked
</b></font><br><font size=+1><tt>
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.

<a name=set_grab><font size=+2><b>set_grab
</b></font><br><font size=+1><tt>
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.

<a name=wait><font size=+2><b>wait
</b></font><br><font size=+1><tt>
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.