pygame2.sdl.event – SDL event wrapper

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.

Module Functions

pygame2.sdl.event.clear([events]) → None

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.

pygame2.sdl.event.get([events]) → [:class:`Event`, :class:`Event`, ... ]

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.

pygame2.sdl.event.get_app_state() → int

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.

pygame2.sdl.event.get_blocked() → [int, int, ...]

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.

pygame2.sdl.event.get_filter() → object

Gets the currently set filter hook method.

Gets the filter hook method set previously by set_filter().

pygame2.sdl.event.peek([events]) → bool

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.

pygame2.sdl.event.peep(num, action, mask[, events]) → int or [:class:`Event`, ...]

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

pygame2.sdl.event.poll() → :class:`Event`

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.

pygame2.sdl.event.pump() → None

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.

pygame2.sdl.event.push(event) → None

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.

pygame2.sdl.event.set_blocked(type) → None

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).

pygame2.sdl.event.set_filter(filterhook) → 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.

Note

Events pushed onto the event queue using push() or peep() do not get passed through the filter.

pygame2.sdl.event.state(type, state) → int

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).

pygame2.sdl.event.wait() → :class:`Event`

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.

Event

class pygame2.sdl.event.Event(type, dict) → Event

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

Attributes

Event.name
Gets the name of the Event.
Event.type
Gets the type id of the Event.