User Guide - Reactions

This theoretical section explains what is a ThorPy reaction. You will also find many examples (this one for instance) and a tutorial showing how to use the reactions mechanism.

What is a ThorPy reaction

(The following paragraph is borrowed from the tutorial on reactions):
What is a reaction in the context of a ThorPy code? The answer is : a reaction to an event define what happens when this event occurs. Therefore, a reaction is defined by:

the event to which it reacts;
the function that is called when this event occurs - we call it the reaction function;
the parameters that are passed to the reaction function;

In fact, we are going to add one more thing to a reaction: a way to better filter the event. Indeed, in pygame, events have attribute - for example, pygame.MOUSEBUTTONDOWN event has the attribute button which contains the id of the button clicked. So, in addition to the event to which the reaction reacts, you may want to precise the arguments required for this event (for instance imagine that you want to capture left click only). Of course, you can also filter the event manually in the reaction function, by checking the event attributes with a cascade of if statements.

Creating a reaction

The following code instantiates a Reaction.

thorpy.Reaction(reacts_to,       #the event to which the reaction reacts
                reac_func,       #the reaction function
                event_args=None, #attributes dict of the event for filtering
                params=None,     #parameters of the reaction function
                reac_name=None)  #name of the reaction

All arguments except reacts_to and reac_func are optionals. The former has to be a pygame event, i.e either a built-in pygame event like pygame.MOUSEBUTTONDOWN, either thorpy.constants.THORPY_EVENT which is in fact an alias for pygame.USEREVENT, either any other pygame's user event that you have defined. reac_func, in the other hand, can be any function, provided its first argument must be the pygame event in question, and that any other non-optional following arguments are specified in the attribute params of the reaction, which is a dictionary. Note that if you declare a thorpy.ConstantReaction instead of a simple reaction, the only difference is that the reaction function does not depend on the event and therefore take no event as argument.

As said above, event_args is a dictionary that can be used for filtering the event by specifying the value of some attributes of the event. params is a dictionary containing the parameters that the reaction function will take (in addition to the event argument in the case of a standard reaction). Finally, you can also choose a name for the reaction in order to retrieve it more easily.

ThorPy events

Having a look to pygame documentation, you will observe that user event id begins at the value pygame.USEREVENT. More precisely, according to pygame doc, 'All events have a type identifier. This event type is in between the values of NOEVENT and NUMEVENTS. All user defined events can have the value of USEREVENT or higher. It is recommended make sure your event id’s follow this system'. Unfortunately, checking the value of USEREVENT and NUMEVENT, you will note that there is only a few type identifier (typically 8) that users can actually use. For this reason, we decided to organize ThorPy's specific events as follow:

All ThorPy events actually share the same pygame type identifiants, which is thorpy.constants.THORPY_EVENT = pygame.USEREVENT. Therefore, be aware that if you create your own events, they should begin at pygame.USEREVENT+1.
To discern ThorPy's events from each other, you have to check the attribute id of the event.
This list of ThorPy events summarize the events posted by ThorPy.

Note also that except thorpy.constants.EVENT_TIME, all thorpy events possess an attribute el containing the element from which the event comes.