Event Handler

DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT

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)

An inline function definition would look like this:

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

Explanation: This Registers the Function "HandleTick" as Handler for the Timer named "MyCoolestTimer", and it is called whenever this specific timer fires.
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.