evts—connect inputs with callbacks

class bmode

Contains Button modes.

DOWN = 1

UP = 2

HELD = 4

REPEAT = 8

DBLCLICK = 16

evt_component_names = {0: (), 1: ('button',), 2: ('neg', 'pos'), 4: ('left', 'right', 'up', 'down')}

{n_components: component_names} for event components, giving a sequence of component names corresponding to their indices for an event’s number of components.

class BaseEvent

Bases: engine.evt.inputs.Input

Abstract event base class.

Subclasses must implement methods Event.add(), Event.rm(), and either Event.gen_cb_args() or respond().

components = 0

Like Input.components—the number of components the event can handle.

device = 'evt'

eh

Containing EventHandler, or None.

cb(*cbs) → self

Add any number of callbacks to cbs.

For all event types, if a callback is determined not to be able to take arguments, it is not passed any.

rm_cbs(*cbs) → self

Remove any number of callbacks from cbs.

Missing items are ignored.

respond(changed)

Handle inputs and call callbacks.

Parameters:changed – whether any inputs changed in any way.

Called by the containing EventHandler, and guaranteed to be called every time the handler is updated (which should happen every frame).

inp_down(i, component)

Used by subclasses to handle ButtonInput instances.

Parameters:

• i – the calling input.
• component – the input’s component that has been toggled down.

inp_up(i, component)

Used by subclasses to handle ButtonInput instances.

Parameters:

• i – the calling input.
• component – the input’s component that has been toggled up.

class Event(*inps)

Bases: engine.evt.evts.BaseEvent

Connects inputs and callbacks.

Takes any number of inputs like add().

This event type calls callbacks with a single pygame.event.Event instance, once for each event gathered by the inputs.

inputs = None

{input: (evt_components, input_components)} (see add()).

add(*inps) → new_inputs

Add inputs to this event.

Returns:a list of inputs that weren’t already registered with this event.

Takes any number of inputs or (input, evt_components = None, input_components = None) tuples.

• evt_components is a sequence of the component indices (or a single component index) of this event that this input provides data for. Defaults to every component, in order. Instead of indices, components can also be names from evt_component_names.
• input_components is a sequence of the component indices of (or a single component index) of the input to match up to evt_components. Defaults to every component of the input, in order.

If there is a mismatch in numbers of components, ValueError is raised.

rm(*inps)

Remove inputs from this event.

Takes any number of Input instances and ignores missing items.

input_valid(i)

Check if the given input is valid for this event type.

gen_cb_args(changed)

Generate sets of arguments to call callbacks with.

Parameters:changed – whether any inputs changed in any way.

This is implemented as an iterator, with each value a sequence of arguments to pass to each callback. Guaranteed to be called whenever BaseEvent.respond() is.

class MultiEvent(inps, *args, **kw)

Bases: engine.evt.evts.BaseEvent

Base class for generating multiples of Event subclasses.

Parameters:

• inps – a sequence of inputs as taken as arguments by Event.
• args – positional arguments to pass to every sub-event on instantiation.
• kw – keyword arguments to pass to every sub-event.

Subclasses must define a child attribute giving the class that this is to be a multiple of, and a multiple attribute giving the number of sub-events to wrap. They should take note of the behaviour of gen_cb_args(), possibly wrapping it.

evts = None

A list of sub-events, in order of the components they map to.

inputs

eh

Containing EventHandler, or None.

gen_cb_args(changed)

Event.gen_cb_args().

Argument lists are returned for each event, with the event’s index inserted as the first argument.

class Button(*items[, initial_delay][, repeat_delay][, dbl_click_time])

Bases: engine.evt.evts.Event, engine.evt.inputs.ButtonInput

Button event. Also acts as a ButtonInput.

Parameters:

• items – each item is either an input as taken by Event, or a button mode (one of bmode.DOWN, bmode.UP, bmode.HELD and bmode.REPEAT) or a bitwise-OR of button modes.
• initial_delay – if the bmode.REPEAT mode is given, this is the initial delay in seconds before a button starts repeating while held.
• repeat_delay – like initial_delay, the time between repeats in seconds.
• dbl_click_time – if the bmode.DBLCLICK mode is given, this is the maximum delay in seconds between down events for a double-click event to be registered.

Callbacks are called with {mode: count} for each mode given, where count is the number of occurrences of events corresponding to that mode that have happened within the last frame.

The count for bmode.HELD is only ever 0 or 1, and indicates whether the button was held at the end of the frame.

The count for bmode.REPEAT may only be > 1 if either repeat rate is greater than the current framerate.

The count for bmode.DBLCLICK may only be > 1 if at least 3 down events are registered within a frame.

name = 'button'

components = 1

modes = None

A bitwise-OR of all button modes passed to the constructor.

initial_delay = None

As passed to the constructor.

repeat_delay = None

As passed to the constructor.

dbl_click_time = None

As passed to the constructor.

class Button2(*items[, initial_delay][, repeat_delay][, dbl_click_time])

Bases: engine.evt.evts.MultiEvent

A 2-component version of Button.

Callbacks are called with (button, evts), where button is the button this applies to (0 or 1) and evts is the argument passed by Button.

name = 'button2'

child

alias of Button

multiple = 2

class Button4(*items[, initial_delay][, repeat_delay][, dbl_click_time])

Bases: engine.evt.evts.Button2

A 4-component version of Button.

Callbacks are called with (axis, dirn, evts), where we treat the 4 buttons as being (left, up, right, down). axis corresponds to the x or y axis (0 (left, right) or 1) and dirn gives the button’s direction (-1 (left, up) or 1). evts is the argument passed by Button.

name = 'button4'

multiple = 4

gen_cb_args(changed)

Event.gen_cb_args().

Argument lists are returned for each event, with the event’s index inserted as the first argument.

class Axis(*inps[, thresholds])

Bases: engine.evt.evts.Event, engine.evt.inputs.AxisInput

Axis event. Also acts as an AxisInput.

Parameters:

• inps – inputs as taken by Event.
• thresholds – to act as a button input, as taken by AxisInput.

The magnitude of the axis position for a button is 1 if it is held, else 0.

Callbacks are called every frame with the current axis position (after summing over each registered input and restricting to -1 <= x <= 1).

name = 'axis'

components = 2

class Axis2(*inps)

Bases: engine.evt.evts.MultiEvent

A double Axis.

Callbacks are called every frame with a list of axis positions for each of the two axes.

name = 'axis2'

child

alias of Axis

multiple = 2

class RelAxis(*inps[, bdy][, thresholds])

Bases: engine.evt.evts.Event, engine.evt.inputs.RelAxisInput

Relative axis event. Also acts as a RelAxisInput.

Parameters:

• inps – inputs as taken by Event.
• bdy – to act as an axis input, as taken by RelAxisInput.
• thresholds – as taken by AxisInput.

Each input is scaled by a positive number (see add() for details).

The magnitude of the relative position for an axis is its position, and for a button is 1 if it is held, else 0.

Callbacks are called with the total, scaled relative change over all inputs registered with this event.

name = 'relaxis'

components = 2

input_scales = None

{scale: input} (see add()).

add(*inps)

Event.add().

Inputs are (scale = 1, input, evt_components = None, input_components = None), where scale is a positive number to scale the relative axis’s position by before calling callbacks.

class RelAxis2(*inps)

Bases: engine.evt.evts.MultiEvent

A double RelAxis.

Callbacks are called every frame with a list of positions for each of the two relative axes.

name = 'relaxis2'

child

alias of RelAxis

multiple = 2