AddEventHandler

This template is no longer in use as it results in poor readability. This function will add an event handler. An event handler is a function that will be called when the event it's attached to is triggered. See event system for more information on how the event system works.

Event handlers are functions that are called automatically when a particular event happens. Each event specifies a specific set of variables that are passed to the event handler and can be read by your function. Each event also has two special 'hidden' (global) variables source (the element that caused the event to happen) and this (the element that the event handler is attached to).

It is important to remember that events pass up and down the element tree. An event triggered on the root element is triggered on every element in the tree. An event triggered on any other element is triggered on it's ancestors (it's parent element and it's parent's parents etc) and it's children, grandchildren and great-grandchildren. You can use the getPropagated argument to specify if you wish your handler to receive events that have propagated up or down the tree.

Syntax

bool addEventHandler ( string eventName, element attachedTo, function handlerFunction, [bool getPropagated = true] )    

Required Arguments

• eventName: The name of the event you want to attach the handler function to.
• attachedTo: The element you wish to attach the handler to. The handler will only be called when the event it is attached to is triggered for this element, or one of its children. Often, this can be the root element (meaning the handler will be called when the event is triggered for any element).
• handlerFunction: The handler function you wish to call when the event is triggered. This function will be passed all of the event's parameters as arguments, but it isn't required that it takes all of them.

Optional Arguments

• getPropagated: A boolean representing whether the handler will be triggered if the event was propagated down the tree, and not triggered directly on attachedTo (that is, handlers attached with this argument set to false will only be triggered if source == this).

Returns

Returns true if the event handler was attached successfully. Returns false if the specified event could not be found or any parameters were invalid.

Example

Click to collapse [-]

Server

This serverside example sends a message to everyone in the server when a player spawns.

-- get the root element
rootElement = getRootElement()
-- define our handler function
function onSpawnpointUseHandler ( thePlayer )
	-- get the player's name
	local playerName = getClientName( thePlayer )
	-- output in the chat box that they've spawned
	outputChatBox ( playerName .. " has spawned!" )
end
-- add the defined onSpawnpointUseHandler function as a handler to the onSpawnPointUse event (triggered when any player spawns at a spawnpoint)
addEventHandler( "onSpawnpointUse", rootElement, onSpawnpointUseHandler )

See Also

• addEvent
• addEventHandler
• cancelEvent
• cancelLatentEvent
• getEventHandlers
• getLatentEventHandles
• getLatentEventStatus
• removeEventHandler
• triggerEvent
• wasEventCancelled