inputs—filtered subsets of Pygame events

UNFILTERABLE = <engine.evt.inputs._Unfilterable object>

A value that an Input cannot filter for.

mod_devices = {'evt': ('evt',), 'kbd': ('kbd',), 'mouse': ('kbd', 'mouse'), 'pad': ('pad',)}

{device: allowed_mod_devices} for ButtonInput instances. An input for device device may only have modifiers with device in allowed_mod_devices.

device_init_handlers = {'pad': <function _init_pad>}

{device: init_fn} giving initialisation functions to initialise devices where possible. These functions take the Input.device_id to initialise for, or no argument to initialise for all devices of this type, and should return a sequence of device IDs that have been successfully initialised.

class mbtn

Contains mouse button aliases.

LEFT = 1

MIDDLE = 2

RIGHT = 3

UP = 4

DOWN = 5

class Input(*pgevts)

Bases: object

Base class for handling input events. Does nothing by itself.

Parameters:pgevts – Pygame event IDs to listen for.

If a subclass has a pgevts attribute, this is a list of events to add to the argument at initialisation.

Comparing inputs for equality compares filters only (so inputs of different types may be equal).

components = 0

Number of components (‘directions’/’button-likes’) represented by this input.

device = None

The string device name that this input type corresponds to (see inputs_by_name).

invalid_device_id = -1

A value that the device ID will never take (see device_id).

provides = None

An {id: provided} dict of ‘interfaces’ this input provides, with keys 'button', 'axis', 'relaxis'.

device_var = None

Variable representing the current device ID; may be a string as a variable name, or None. See also EventHandler.assign_devices()).

evt = None

An Event instance that contains this input, or None.

filters = None

A {pgevt_attr: val} dict that represents how events are filtered before being passed to this input (see filter()).

eh

EventHandler for evt, or None.

filter(attr, *vals, refilter = False) → self

Filter events passed to this input.

Parameters:

• attr – Pygame event attribute to filter by.
• vals – allowed values of the given attribute for filtered events.
• refilter – if True, replace previous filtering by attr with the given vals, else add to the values already filtered by.

unfilter(attr, *vals)

Remove filtering by the given attribute.

Parameters:

• attr – Pygame event attribute to modify filtering for.
• vals – values to remove filtering for. If none are given, all filtering by attr is removed.

device_id

The particular device that this input captures input for.

May be True, in which case all such devices work through this input.

May be None, in which case no input will be registered; this is done by filtering by invalid_device_id.

Subclasses may set an attribute device_id_attr, in which case setting this attribute filters using device_id_attr as the event attribute and the set value as the attribute value to filter by. If a subclass does not provide device_id_attr and does not override the setter, this operation raises TypeError.

handle(pgevt)

Called by EventHandler with a pygame.event.Event.

The passed event matches filters.

Returns:whether anything in the input’s state changed.

normalise()

Determine and set the input’s current state, if any.

This implementation does nothing.

class BasicInput(*pgevts)

Bases: engine.evt.inputs.Input

An input that handles raw Pygame events.

Parameters:pgevts – Pygame event IDs to listen for.

pgevts = None

Pygame event IDs as passed to the constructor.

reset()

Clear cached Pygame events.

Called by the owning Event.

class ButtonInput([button, ]*mods)

Bases: engine.evt.inputs.Input

Abstract base class representing a button-like action (Input subclass).

Parameters:

• button – button ID to listen for. To use this, subclasses must set a button_attr property to filter by that Pygame event attribute with this ID as the value. Otherwise, they must implement filtering themselves.
• mods – inputs to use as modifiers. Each may be a ButtonInput, a sequence of them, or (input, component) giving the component of the input to use (from 0 to input.components - 1).

Subclasses must have a device in mod_devices, which restricts allowed devices of modifiers.

components = 1

is_mod = None

Whether this input is acting as a modifier.

used_components = None

{container: components} for each container (such as an Event, or another ButtonInput as a modifier). components is a sequence of the components of this input that the container uses.

button = None

The button ID this input represents, as taken by the constructor.

mods_active()

Whether modifiers for this button are held.

held(container)

A list of the held state of this button for each component.

Each item is a bool that corresponds to the component in the same position in used_components for the given container.

down(component=0, evt=True)

Set the given component’s button state to down.

Parameters:evt – whether to let the containing event know about this.

up(component=0, evt=True)

Set the given component’s button state to up.

Parameters:evt – whether to let the containing event know about this.

set_held(held, evts=False, component=0)

Set the held state of the button on the given component.

Parameters:evts – whether to trigger button down/up events if the held state changes.

handle(pgevt)

Input.handle().

If a subclass has a down_pgevts attribute, this sets the button down on component 0 for Pygame events with IDs in this list, and up on component 0 for all other events. Otherwise, it does nothing.

class KbdKey(key, *mods)

Bases: engine.evt.inputs.ButtonInput

Keyboard key.

Parameters:key – the key code (required).

device = 'kbd'

name = 'key'

pgevts = (2, 3)

button_attr = 'key'

down_pgevts = (2,)

class MouseButton(button, *mods)

Bases: engine.evt.inputs.ButtonInput

Mouse button.

The button argument is required, and is the mouse button ID.

device = 'mouse'

name = 'button'

pgevts = (5, 6)

button_attr = 'button'

down_pgevts = (5,)

class PadButton(device_id, button, *mods)

Bases: engine.evt.inputs.ButtonInput

Gamepad button.

Parameters:

• device_id – the gamepad’s device ID, either a variable (device_var) or a non-string ID (device_id).
• button – as taken by ButtonInput.
• mods – as taken by ButtonInput.

device = 'pad'

name = 'button'

pgevts = (10, 11)

device_id_attr = 'joy'

button_attr = 'button'

down_pgevts = (10,)

class AxisInput([axis][, thresholds], *mods)

Bases: engine.evt.inputs.ButtonInput

Abstract base class representing 2-component axes.

Parameters:

• axis – axis ID to listen for. To use this, subclasses must set an axis_attr property to filter by that Pygame event attribute with this ID as the value, and with an attribute giving the axis’s value. Otherwise, they must implement filtering themselves.
• thresholds –

  required if the axis is to act as a button. For each axis (that is, for each pair of Input.components), this list has two elements: down followed by up, positive numbers giving the magnitude of the value of the axis in either direction that triggers a button down or up event. For example, a 2-component axis might have (.6, .4).

  A subclass with more than 2 components may pass a length-2 sequence here, which is expanded by assuming the same thresholds for each axis.

• mods – as taken by ButtonInput. Only used if this axis is treated as a button.

Subclasses must have an even number of components.

components = 2

axis = None

Axis ID, as passed to the constructor.

thresholds = None

As passed to the constructor.

pos

Sequence of positions for each axis.

deadzone

Axis value magnitude below which the value is mapped to 0; defaults to 0.

Above this value, the mapped value increases linearly from 0.

axis_motion(axis, apos)

Signal a change in axis position.

Parameters:

• axis – the index of the axis to modify (a 2-component AxisInput has one axis, with index 0).
• apos – the new axis position (-1 <= apos <= 1).

handle(pgevt)

ButtonInput.handle().

If a subclass has an axis_val_attr attribute, the value of this attribute in pgevt is used as a list of axis positions (or just one, if a number). Otherwise, this method does nothing.

class PadAxis(device_id, axis, [thresholds, ]*mods)

Bases: engine.evt.inputs.AxisInput

Gamepad axis.

Parameters:

• device_id – the gamepad’s device ID, either a variable (device_var) or a non-string ID (device_id).
• axis – as taken by AxisInput.
• thresholds – as taken by AxisInput.
• mods – as taken by ButtonInput.

device = 'pad'

name = 'axis'

device_id_attr = 'joy'

pgevts = (7,)

axis_attr = 'axis'

axis_val_attr = 'value'

class PadHat(device_id, axis, [thresholds, ]*mods)

Bases: engine.evt.inputs.AxisInput

Gamepad hat.

Parameters:

• device_id – the gamepad’s device ID, either a variable (device_var) or a non-string ID (device_id).
• hat – the hat ID to listen for.
• thresholds – as taken by AxisInput.
• mods – as taken by ButtonInput.

components = 4

device = 'pad'

name = 'hat'

device_id_attr = 'joy'

pgevts = (9,)

axis_attr = 'hat'

axis_val_attr = 'value'

class RelAxisInput([relaxis][, bdy][, thresholds], *mods)

Bases: engine.evt.inputs.AxisInput

Abstract base class representing 2-component relative axes.

Parameters:

• relaxis – axis ID to listen for. To use this, subclasses must set a relaxis_attr property to filter by that Pygame event attribute with this ID as the value, and with an attribute giving the axis’s value. Otherwise, they must implement filtering themselves.
• bdy – required if the relative axis is to act as an axis or a button. For each axis (each 2 components), this sequence contains a positive number giving the maximum magnitude of the axis. The normalised axis position is then obtained by dividing by this value. May be a single number instead of a one-item sequence.
• thresholds – as taken by AxisInput. Only used if this relative axis is treated as an axis, and required if it is to act as a button.
• mods – as taken by ButtonInput. Only used if this relative axis is treated as a button.

A relative axis is one where events convey a change in the axis’s value, rather than its absolute position. Subclasses must have an even number of components.

Note that using the same component of an instance of a subclass for two different events (or using the same component twice for a single MultiEvent) is not supported, and behaviour in this case is undefined.

components = 2

rel = None

The change in each component since last reset().

relaxis = None

Axis ID, as passed to the constructor.

bdy = None

As taken by the constructor.

relaxis_motion(relaxis, rpos)

handle(pgevt)

AxisInput.handle().

If a subclass has an relaxis_val_attr attribute, the value of this attribute in pgevt is used as a list of axis changes (or just one, if a number). Otherwise, this method does nothing.

reset(*components)

Reset values in rel to 0 for the given components.

Called by the owning Event.

If no components are given, reset in all components.

class MouseAxis([bdy][, thresholds], *mods)

Bases: engine.evt.inputs.RelAxisInput

Represents both mouse axes.

Arguments are as taken by RelAxisInput.

components = 4

device = 'mouse'

name = 'axis'

pgevts = (4,)

relaxis_val_attr = 'rel'

mod = <engine.evt.inputs._mod object>

Contains objects that act as specific keyboard modifiers: CTRL, SHIFT, ALT, META.