Pygame SDL event wrapper module. The event module manages the SDL related event system and allows one to receive, send and manipulate events.
The event module is the main messaging system for SDL windows and uses a queue to deal with events such as mouse and keyboard input, window state changes or user-defined ones.
Clears the event queue from certain event types.
Clears the event queue from certain event types. If no argument is passed, all current events are removed from the queue. Otherwise the argument can be a sequence or a bitmask combination of event types to clear.
Gets events from the event queue.
Gets the current events from the event queue. If no argument is passed, all currently available events are received from the event queue and returned as list. Otherwise, the argument can be a sequence or a bitmask combination of event types to receive from the queue.
If no matching events are found on the queue, an empty list will be returned.
Gets the current application state.
Gets the current application state. This will be a bitmask combination of the APPMOUSEFOCUS, APPINPUTFOCUS or APPACTIVE masks, indicating whether the application currently is active and has the mouse and keyboard input focus.
Gets a list of currently blocked event types.
Gets a list of currently blocked event types. Events having the matching type will not be processed by the event queue.
Gets the currently set filter hook method.
Gets the filter hook method set previously by set_filter().
Checks, whether certain event types are currently on the queue.
Checks, whether certain event types are currently on the queue. If no argument is passed, this method simply checks, if there is any event on the event queue. Otherwise, the argument can be a sequence or a bitmask combination of event types to check for. In case one event is found, which corresponds to the requested type(s), True is returned.
Checks the event queue for events and optionally returns them.
This is an advanced event queue querying and manipulation method. It allows to inspect the event queue, to receive events from it or to add events.
TODO
Gets a single event from the event queue.
Returns a single event from the queue. If the event queue is empty, None will be returned. If an event is available and returned, it will be removed from the queue.
Pumps the event queue, forcing it to gather pending events from devices.
This gathers all pending events and input information from devices and places them on the event queue.
It only has to be called, if you use peep() or a filter hook without using another event function or no other event function at all.
Places a new event at the end of the event queue.
This is usually used for placing user defined events on the event queue. You also can push user created device events on the queue, but this will not change the state of the device itself.
Blocks a single or multiple event types.
This will block a single or multiple event types from being processed by the event system and thus will exactly behave like :func:`state`(type, :const:`IGNORE`).
In case other event types are already blocked, the block for them will be reset.
To remove the block for all events, call set_blocked(None).
Sets up a filter hook for events.
This sets up a filter to process all events before they are posted to the event queue. In order to process events correctly, the filterhook must return True or False, indicating whether the event processd by it, is allowed to be placed on the event queue or not. It has to take a single argument, which will be the event to process.
def example_filter_hook (event):
if event.type == ... and ...:
# The event matches a certain scheme, do not allow it.
return False
# Any other event may pass.
return True
In case the QUITEVENT is processed by the event filter, returning True will cause the SDL window to be closed, otherwise, the window will remain open, if possible.
Sets the processing state of an event type.
This allows you to set the processing state of an event type. If the state is set to IGNORE, events matching type will be automatically dropped from the event queue and not be filtered. This will behave similar to set_blocked(). If state is set to ENABLE, events matching type will be processed normally. If state is set to QUERY, this will return the current processing state of the specified event type (ENABLE or IGNORE).
Waits indefinitely for the next available event.
This is a blocking method, that only returns, if an event occurs on the event queue. Once an event occurs, it will be returned to the caller and removed from the queue. While the program is waiting it will sleep in an idle state.
Creates a new event to be used in the event messaging system.
The type can be one of the valid SDL event type constants. Each event carries a certain set of attributes, which are only available for that event within the event object.
Event type | Attributes |
---|---|
ACTIVEEVENT | state: The activation state. This will
be APPMOUSEFOCUS for the mouse focus,
APPINPUTFOCUS for keyboard input focus
and APPACTIVE on iconifying (gain = 0)
or restoring (gain = 1) the window.
gain: 1 on gain, 0 on loss
|
KEYDOWN | state: will always be PRESSED
scancode: The hardware scancode
sym: same as key
key: The sdl constant of the key (e.g.
K_a, K_TAB, ...)
mod: The currently pressed modifier
keys (e.g. KMOD_SHIFT)
unicode: The unicode represenation of
the key.
|
KEYUP | state: will always be RELEASED
scancode: The hardware scancode
sym: same as key
key: The sdl constant of the key (e.g.
K_a, K_TAB, ...)
mod: The currently pressed modifier
keys (e.g. KMOD_SHIFT)
unicode: The unicode represenation of
the key.
|
MOUSEMOTION | state: Bit-wise combination of the
button states (see buttons)
x: The current x-coordinate on the
window.
y: The current y-coordinate on the
window.
xrel: relative motion in x direction
since the last event poll
yrel: relative motion in y direction
since the last event poll
pos: The x/y coordinate as tuple
rel: the relative x/y motion as tuple
buttons: 3-value tuple containing the
mouse button states for the first three
mouse buttons. Each of the values is
either True or False, indicating
whether the button is pressed or not
|
MOUSEBUTTONDOWN | state: will always be PRESSED
x: The current x-coordinate on the
window.
y: The current y-coordinate on the
window.
pos: The x/y coordinate as tuple
button: The pressed button (will be
either BUTTON_LEFT, BUTTON_MIDDLE or
BUTTON_RIGHT
|
MOUSEBUTTONUP | state: will always be RELEASED
x: The current x-coordinate on the
window.
y: The current y-coordinate on the
window.
pos: The x/y coordinate as tuple
button: The pressed button (will be
either BUTTON_LEFT, BUTTON_MIDDLE or
BUTTON_RIGHT
|
JOYAXISMOTION | which: The device index of the
joystick
joy: same as which
axis: The joystick axis index
value: The current position of the
axis (between -32768 and 32767)
|
JOYBALLMOTION | which: The device index of the
joystick
joy: same as which
ball: The trackball index
xrel: The relative motion in x
direction since the last event poll
yrel: The relative motion in y
direction since the last event poll
rel: The relative x/y motion as tuple
|
JOYHATMOTION | which: The device index of the
joystick
joy: same as which
hat: The hat index
value: The current hat position as
bit-wise combination (e.g. HAT_LEFTUP)
|
JOYBUTTONDOWN | which: The device index of the
joystick
joy: same as which
button: The button index
state: wil always be PRESSED
|
JOYBUTTONUP | which: The device index of the
joystick
joy: same as which
button: The button index
state: Will always be RELEASED
|
VIDEORESIZE | w: The width to resize to
h: The height to resize to
size: The width and height as tuple
|
VIDEOEXPOSE | no attributes |
QUIT | no attributes |
Some events have special or system-dependent attributes.
Event type | Attributes |
---|---|
SYSWMEVENT | hwnd, msg, wparam, lparam for Windows
event for X11
no attributes for others
|
For user-defined events, there is the special USEREVENT type (and above). User-defined events can carry their own type, which must be in the range [USEREVENT, (NUMEVENTS - 1)]. If they are sent from pygame code directly, they do not carry specific attributes, just those given to them by the passed dictionary.
If they come from another system (e.g. 3rd party library), they might carry the following attributes:
Event type | Attributes |
---|---|
USEREVENT | code, data1, data2 |