The Event Listener Module

The Eventlistener wraps pygames event-loop.

The Core method is the listen() method. It gathers the events that have piled up in pygame so far and processes them acording to handler functions. This allows for a main-loop free script design, which is more suited for experimental paradigms. In a typical experiment the script just waits for a userinput and does nothing, or only a very few things in between. Approaching this need with a main event-loop requires the implementation of some sort of statemachine, which again requires quite some code.

The EventListener enables one to write scripts in a time-linear manner, and only dab into local event-loops whenever neccessary throught the listen-function.

There are a few pre-implemented methods, which cover most of those use-cases in the developement of experimental paradigms.

• wait_for_keypress() will return once a key was pressed n times.

• wait_for_keys_timed_out() will wait for one of multiple possible keys,

  but return after the given timeout in an y case

• and wait_for_seconds will simply wait the given time, but in the mean-time run what ever handlers were passed to the EventListener.

By default, there is one permanent handler, which will call exit(1) when Ctrl + c is pressed.

class pyparadigm.eventlistener.EventConsumerInfo

Can be returned by event-handler functions to communicate with the listener. For Details see EventListener

class pyparadigm.eventlistener.EventListener(permanent_handlers=None, use_ctrl_c_handler=True)

Parameters:

• permanent_handlers (iterable) – iterable of permanent handlers
• use_ctrl_c_handler (Bool) – specifies whether a handler that quits the script when ctrl + c is pressed should be used

group(group)

sets current mouse proxy group and returns self. Enables lines like el.group(1).wait_for_keys(…)

listen(*temporary_handlers)

When listen() is called all queued pygame.Events will be passed to all registered listeners. There are two ways to register a listener:

1. as a permanent listener, that is always executed for every event. These

   are registered by passing the handler-functions during construction

2. as a temporary listener, that will only be executed during the current

   call to listen(). These are registered by passing the handler functions as arguments to listen()

When a handler is called it can provoke three different reactions through its return value.

1. It can return EventConsumerInfo.DONT_CARE in which case the EventListener

   will pass the event to the next handler in line, or go to the next event, if the last handler was called.

2. It can return EventConsumerInfo.CONSUMED in which case the event will not

   be passed to following handlers, and the next event in line will be processed.

3. It can return anything else (including None, which will be returned if no

   return value is specified) in this case the listen()-method will return the result of the handler.

Therefore all permanent handlers should usually return EventConsumerInfo.DONT_CARE

listen_until_return(*temporary_handlers, timeout=0, sleeptime=0)

Calls listen repeatedly until listen returns something else than None. Then returns listen’s result. If timeout is not zero listen_until_return stops after timeout seconds and returns None.

mouse_area(handler, group=0, ident=None)

Adds a new MouseProxy for the given group to the EventListener.mouse_proxies dict if it is not in there yet, and returns the (new) MouseProxy. In listen() all entries in the current group of mouse_proxies are used.

wait_for_keys(*keys, timeout=0, sleeptime=0)

Waits until one of the specified keys was pressed, and returns which key was pressed.

Parameters:

• keys (iterable) – iterable of integers of pygame-keycodes, or simply multiple keys passed via multiple arguments
• timeout (float) – number of seconds to wait till the function returns

Returns:

The keycode of the pressed key, or None in case of timeout

Return type:

int

wait_for_keys_modified(*keys, modifiers_to_check={1, 2, 3, 64, 128, 192, 256, 512, 768, 1024, 2048, 3072, 4096, 8192, 16384}, timeout=0, sleeptime=0.001)

The same as wait_for_keys, but returns a frozen_set which contains the pressed key, and the modifier keys.

Parameters:modifiers_to_check – iterable of modifiers for which the function will check whether they are pressed

wait_for_n_keypresses(key, n=1)

Waits till one key was pressed n times.

Parameters:

• key (int) – the key to be pressed as defined by pygame. E.g. pygame.K_LEFT for the left arrow key
• n (int) – number of repetitions till the function returns

wait_for_seconds(seconds, sleeptime=0.001)

basically time.sleep() but in the mean-time the permanent handlers are executed

wait_for_unicode_char(ignored_chars=None, timeout=0, sleeptime=0.001)

Returns a str that contains the single character that was pressed. This already respects modifier keys and keyboard layouts. If timeout is not none and no key is pressed within the specified timeout, None is returned. If a key is ingnored_chars it will be ignored. As argument for irgnored_chars any object that has a __contains__ method can be used, e.g. a string, a set, a list, etc

class pyparadigm.eventlistener.MouseProxy(handler: Callable[[int, int], int], ident=None)

has a _draw method so that it can be used with surface_composition.compose(). When “rendered” it simply saves the own coordinates and then renders its child. The listener method can then be used with EventListener.listen() to execute the provided handler when the mouse interacts with the area. The handler gets the event type, pygame.MOUSEBUTTONUP, pygame.MOUSEBUTTONDOWN and pygame.MOUSEMOTION and the relative coordinates within the area. For unique identification along all MouseProxies the ident paramenter is used. If ident is None (the default) it is set to id(handler)

pyparadigm.eventlistener.is_left_click(event)

checks whether the provided pygame event is a left mouse click