User Guide - Reactions
This theoretical section explains what is a ThorPy reaction. You will also find in examples and tutorials many different ways to use the reactions.
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;
pygame.MOUSEBUTTONDOWNevent has the attribute
buttonwhich 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 reactionThe following code instantiates a Reaction.
1 2 3 4 5
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
reac_func are optionals. The former has to be a pygame event, i.e either a built-in pygame event like
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.
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:
thorpy.constants.THORPY_EVENT = pygame.USEREVENT. Therefore, be aware that if you create your own events, they should begin at
To discern ThorPy's events from each other, you have to check the attribute
idof 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.