Event Handler

Definition

An Event Handler is a function registered in a special way to be called when certain things (events) happen.

Official Documentation

Official Events Documentation: [Events]

Registering an EventHandler

• Registering a function as EventHandler in its general abstract form is:

RegisterEventHandler( (EventType)mEvent, (string)mEventIdentifier, (function)mEventHandler) 

The registered function can also be declared inline:

RegisterEventHandler( (EventType)mEvent, (string)mEventIdentifier, 
         function(...) 
              -- Do Stuff -- 
         end
) 

mEvent can be one of the following events:

EventType. + LoadedFromBackup, Destroyed,  CreatedObject,  ModuleAttached,  Timer,  Message,  EnterView,  LeaveView,  RequestPickUp,  RequestDrop,  RequestEquip,  ContainerItemAdded,  ContainerItemRemoved,  ItemEquipped,  ItemUnequipped,  StartMoving,  Arrived,  Use, PlayerSpeech, ClientUserCommand,  ClientObjectCommand,  ClientTargetAnyObjResponse, ClientTargetGameObjResponse,  ClientTargetLocResponse,  ContextMenuResponse, DynamicWindowResponse, UserLogout, GlobalVarUpdateResult

Example:

RegisterEventHandler(EventType.Timer, "MyCoolestTimer", HandleTick)

Explanation: This Registers the Function "HandleTick" as Handler for the Timer named "MyCoolestTimer", and it is called whenever this specific timer fires.

An inline function definition for this timer would look like this:

RegisterEventHandler(EventType.Timer, "MyCoolestTimer", 
     function()
          print("MyCoolestTimer just fired")
     end
)

E.G. this:FireTimer("MyCoolestTimer") would fire the timer and thus call the "HandleTick" function. You can optionally pass data to an event when triggering it and thus give this data to the Event Handler.
E.G: in the last Example we could have called this:FireTimer("MyCoolestTimer",{name="MyData",content="Stuff"}) which would pass a table to the timer and the handler. If the handler can handle this data depends on its definition.
Also: Some events pass default data to the handlers, it is necessary to know which events pass which data. You can find this information in the official documentation.

Declaring EventHandlers

As you could see above, the functions handling the triggered events can be declared externally or inline inside the RegisterEventHandler function.
Whatever you do: To let these functions do something meaningful they usually need to get some data and thus the following rule applies:

A function definition for an EventHandler, be it declared inline or externally must declare its parameters in a way which is predefined by the type of the event it is handling. Handlers for Timer Events have different parameters than Handlers for Message or CreatedObject events. Otherwise errors occur or the function simply has no data available.

Check the official documentation to find out about these parameters If we want to use a timer like this:

 this:FireTimer("MyCoolTimer", {name="Stuff", data = "Moar Stuff"} )

we have to declare the Handler accordingly either inline:

RegisterEventHandler(EventType.Timer, "MyCoolTimer", 
   function(data) 
      -- tostring is used for handling nil values and numbers or table data properly
      print(tostring(data.name).." is the name and "..tostring(data.data).." is the data")
   end
)

Or externally:

function HandleCoolTimer(data)
      -- tostring is used for handling nil values and numbers or table data properly
      print(tostring(data.name).." is the name and "..tostring(data.data).." is the data")
end

RegisterEventHandler(EventType.Timer, "MyCoolTimer", HandleCoolTimer )