9
9
| :sl:`pygame module for interacting with events and queues`
11
Pygame handles all it's event messaging through an event queue. The routines in
11
Pygame handles all its event messaging through an event queue. The routines in
12
12
this module help you manage that event queue. The input queue is heavily
13
13
dependent on the pygame display module. If the display has not been initialized
14
14
and a video mode not set, the event queue will not really work.
16
The queue is a regular queue of Event objects, there are a variety of ways to
17
access the events it contains. From simply checking for the existance of
18
events, to grabbing them directly off the stack.
16
The queue is a regular queue of :class:`pygame.event.EventType` event objects,
17
there are a variety of ways to access the events it contains. From simply
18
checking for the existence of events, to grabbing them directly off the stack.
20
20
All events have a type identifier. This event type is in between the values of
21
21
``NOEVENT`` and ``NUMEVENTS``. All user defined events can have the value of
41
41
Joysticks will not send any events until the device has been initialized.
43
An Event object contains an event type and a readonly set of member data. The
44
Event object contains no method functions, just member data. Event objects are
45
retrieved from the pygame event queue. You can create your own new events with
46
the ``pygame.event.Event()`` function.
43
An ``EventType`` event object contains an event type identifier and a set of
44
member data. The event object contains no method functions, just member data.
45
EventType objects are retrieved from the pygame event queue. You can create
46
your own new events with the ``pygame.event.Event()`` function.
48
48
Your program must take steps to keep the event queue from overflowing. If the
49
49
program is not clearing or getting all events off the queue at regular
50
50
intervals, it can overflow. When the queue overflows an exception is thrown.
52
All Event objects contain an event type identifier in the ``Event.type``
53
member. You may also get full access to the Event's member data through the
54
``Event.dict`` method. All other member lookups will be passed through to the
55
Event's dictionary values.
52
All EventType instances have an event type identifier, accessible as the
53
``EventType.type`` property. You may also get full access to the event object's
54
attributes through the ``EventType.__dict__`` attribute. All other member
55
lookups will be passed through to the object's dictionary values.
57
While debugging and experimenting, you can print the Event objects for a quick
57
While debugging and experimenting, you can print an event object for a quick
58
58
display of its type and members. Events that come from the system will have a
59
guaranteed set of member items based on the type. Here is a list of the Event
60
members that are defined with each type.
59
guaranteed set of member items based on the type. Here is a list of the
60
event attributes defined with each event type.
126
126
.. function:: poll
128
128
| :sl:`get a single event from the queue`
129
| :sg:`poll() -> Event`
129
| :sg:`poll() -> EventType instance`
131
131
Returns a single event from the queue. If the event queue is empty an event
132
132
of type ``pygame.NOEVENT`` will be returned immediately. The returned event
137
137
.. function:: wait
139
139
| :sl:`wait for a single event from the queue`
140
| :sg:`wait() -> Event`
140
| :sg:`wait() -> EventType instance`
142
142
Returns a single event from the queue. If the queue is empty this function
143
143
will wait until one is created. The event is removed from the queue once it
169
169
Remove all events or events of a specific type from the queue. This has the
170
170
same effect as ``pygame.event.get()`` except nothing is returned. This can
171
be slightly more effecient when clearing a full event queue.
171
be slightly more efficient when clearing a full event queue.
173
173
.. ## pygame.event.clear ##
259
259
later be retrieved from the other queue functions.
261
261
This is usually used for placing ``pygame.USEREVENT`` events on the queue.
262
Although any type of event can be placed, if using the sytem event types
262
Although any type of event can be placed, if using the system event types
263
263
your program should be sure to create the standard attributes with
264
264
appropriate values.
268
268
.. function:: Event
270
270
| :sl:`create a new event object`
271
| :sg:`Event(type, dict) -> Event`
272
| :sg:`Event(type, **attributes) -> Event`
271
| :sg:`Event(type, dict) -> EventType instance`
272
| :sg:`Event(type, **attributes) -> EventType instance`
274
274
Creates a new event with the given type. The event is created with the given
275
275
attributes and values. The attributes can come from a dictionary argument
276
with string keys, or from keyword arguments. The event object exposes its
277
dictionary as attribute __dict__, and also as dict for backward
280
Attributes type, __dict__, and dict are readonly. Other attributes are
281
mutable. There are no methods attached to an Event object.
276
with string keys, or from keyword arguments.
280
| :sl:`pygame object for representing SDL events`
282
A Python object that represents an SDL event. User event instances are
283
created with an `Event` function call. The `EventType` type is not directly
284
callable. `EventType` instances support attribute assignment and deletion.
288
| :sl:`SDL event type identifier.`
291
Read only. Predefined event identifiers are `QUIT` and `MOUSEMOTION`, for
292
example. For user created event objects, this is the `type` argument
293
passed to :func:`pygame.event.Event`.
295
.. attribute:: __dict__
297
| :sl:`Event object attribute dictionary`
298
| :sg:`__dict__ -> dict`
300
Read only. The event type specific attributes of an event. As an example,
301
this would contain the `unicode`, `key`, and `mod` attributes of a
302
`KEYDOWN` event. The `dict` attribute is a synonym, for backward
283
305
Mutable attributes are new to Pygame 1.9.2.
added
removed
docs/reST/ref/event.rst
