System-defined functions, EVENT_xxx("event_argument_name") can be used to access the data associated with a received LSL Event.
Certain code segments do not execute within the event handler of the originating event that triggered them. Therefore direct access to the event's arguments in those situations is not possible by directly referring to the argument name. In these situations, one of the following functions must be used to access the events arguments:
- EVENT_INT(string arg_name): Returns the integer argument, named arg_name.
- EVENT_FLT(string arg_name): Returns the float argument, named arg_name.
- EVENT_VEC(string arg_name): Returns the vector argument, named arg_name.
- EVENT_ROT(string arg_name): Returns the rotation argument, named arg_name.
- EVENT_KEY(string arg_name): Returns the key argument, named arg_name.
- EVENT_STR(string arg_name): Returns the string argument, named arg_name.
- EVENT_LST(string arg_name): Returns the list argument, named arg_name. The value returned is a list corresponding to the list argument, however as the list's elements have been converted to strings, they must be extracted using llList2String and explicitly cast to the correct type.
The following cases require the use of the above functions in order to access the data of the most recently received event:
- State Entry and Exit Action code.
- Custom Global functions and State Functions.
- Incoming and outgoing continuing transition's Transition Action code.
- Choice Point outgoing transitions.
►NOTE: Outgoing transitions of a Choice Point with only a single incoming transition (with a defined event) do not require the use of the EVENT_xxx functions to access the event's arguments. The argument names can be referenced directly!
►If a transition has a defined event then the arguments can always be referenced directly in your code.
In the following model a Choice Point is used to examine the result of an authorization request. In the Guard Condition of the link_message transition the argument str is referenced directly, while in the Entry Action of state Processing, the EVENT_STR function is used to access the argument named sender_num within the link_message event.
Event data is automatically saved in the global variable EventData every time an event is received. This is done by saving the arguments together with their names as elements of a list. For example, the following code is generated to save the data associated with the link_message event.
EventData = ["%%sender_num",sender_num,"%%num",num,"%%str",str,"%%id",id];
The code for each access function is included as part of the header code for each generated script if it has been called within the generated code.
►Note that it is also possible to bypass the EVENT_XXX functions and directly index into the EventData global variable.
To do this use the appropriate llList2XXX LSL function passing EventData and 2*(argument index)+1. For example taking the event dataserver (key queryid, string data), in order to directly access the data argument (i.e., index 1) from the EventData variable, you can use: llList2String(EventData,(2*1)+1).
The EventData global variable is automatically cleared after the processing of each event.
Event arguments can always be directly accessed within transitions originating from a Simple State without using the EVENT_XXX functions. However if the transition is moved to another state or modeling component, this may no longer be the case.
If the argument name is not found within the saved EventData list, then the default value for the datatype will be returned.