AddEventHandler: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
(39 intermediate revisions by 17 users not shown)
Line 1: Line 1:
__NOTOC__  
__NOTOC__  
{{Server client function}}
{{Note_box|It is strongly advised that you do not use the same name for your handler function as the event name, as this can lead to confusion if multiple handler functions are used.}}
{{Note_box|It is strongly advised that you do not use the same name for your handler function as the event name, as this can lead to confusion if multiple handler functions are used.}}
This function will add an [[event]] handler. An event handler is a function that will be called when an event is triggered. See [[event system]] for more information on how the event system works.
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 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. The following global variables are available for use in handler functions:
*'''source''': the element that triggered the event
*'''this''': the element that the event handler is attached to
*'''sourceResource''': the resource that triggered the event
*'''sourceResourceRoot''': the root element of the resource that triggered the event
*'''client''': the client that triggered the event using [[triggerServerEvent]]. Not set if the event was not triggered from a client.
{{New_feature|3|1.0|
*'''eventName''': the name of the event which triggered the handler function.
}}
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 its ancestors (its parent element and its parent's parent etc) and its 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.
The order in which event handlers are triggered is undefined, you should not rely on one event handler being executed before another.
{{Note|See [[Script security]] for tips on preventing cheaters when using events and element data}}
{{Note|See [[Event_Source_Element|Event Source Element]] for a descriptive visualization of the event system handling an event trigger.}}
==Syntax==  
==Syntax==  
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
bool addEventHandler ( string eventName, element attachedTo, function functionName )     
bool addEventHandler ( string eventName, element attachedTo, function handlerFunction [, bool getPropagated = true, string priority = "normal" ] )     
</syntaxhighlight>  
</syntaxhighlight>  


Line 11: Line 27:
*'''eventName:''' The name of the [[event]] you want to attach the handler function to.
*'''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).
*'''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).
*'''functionName:''' The name of the handler function you wish to call. This function should have the correct number of parameters defined for the event you are using, but it isn't required that it takes all of them. Function name IS NOT a string, so you shouldn't use "".
*'''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 or up the [[element tree]] (starting from the source), and not triggered directly on attachedTo (that is, handlers attached with this argument set to ''false'' will only be triggered if ''source == this'').
{{New_feature|3.0131|1.3.1|
*'''priority :''' A string representing the trigger order priority relative to other event handlers of the same name. Possible values are:
**'''"high"'''
**'''"normal"'''
**'''"low"'''
''It is also possible to add finer priority control by appending a positive or negative number to the priority string. For example (in priority order for reference): "high+4" "high" "high-1" "normal-6" "normal-7" "low+1" "low" "low-1"''
'''Important note:''' Anything bound to a specific element will be run before other handlers that are bound to something higher in the element tree (like root) This means that "high+10" bound to root won't trigger before "normal" bound directly to an element.
}}


===Returns===
===Returns===
Returns ''true'' if the event handler was attached successfully. Returns ''false'' if the event specified could not be found or the ''attachedTo'' [[element]] specified is invalid.
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==
==Example==
This example sends a message to everyone in the server when a player spawns.
<section name="Server" class="server" show="true">
This serverside example sends a message to everyone in the server when a player spawns.
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
-- Get the root element
-- define our handler function
rootElement = getRootElement ()
function onPlayerSpawnHandler ( )
-- Define our handler function
-- get the player's name, source is the player because he was spawned
function onSpawnpointUseHandler(thePlayer)
local playerName = getPlayerName( source )
-- Get the player's name
-- output in the chat box that they've spawned
local playerName = getClientName( thePlayer )
outputChatBox ( playerName .. " has spawned!" )
-- Output in the chat box that they've spawned
outputChatBox ( playerName .. "has spawned!" )
end
end
addEventHandler( "onPlayerSpawn", root, onPlayerSpawnHandler ) -- root is a predefined global variable for getRootElement()
</syntaxhighlight>
</syntaxhighlight>
-- Add an event handler to the onSpawnPointUse event (triggered when a player spawns at a spawnpoint). You must add a handler '''only''' after function definition.
</section>
addEventHandler ( "onSpawnpointUse", rootElement, onSpawnpointUseHandler )
 
==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.03795|Added priority argument}}


==See Also==
==See Also==
{{Event_functions}}
{{Event_functions}}
[[ru:addEventHandler]]

Revision as of 01:49, 7 April 2018

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 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. The following global variables are available for use in handler functions:

  • source: the element that triggered the event
  • this: the element that the event handler is attached to
  • sourceResource: the resource that triggered the event
  • sourceResourceRoot: the root element of the resource that triggered the event
  • client: the client that triggered the event using triggerServerEvent. Not set if the event was not triggered from a client.
  • eventName: the name of the event which triggered the handler function.

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 its ancestors (its parent element and its parent's parent etc) and its 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.

The order in which event handlers are triggered is undefined, you should not rely on one event handler being executed before another.

[[{{{image}}}|link=|]] Note: See Script security for tips on preventing cheaters when using events and element data
[[{{{image}}}|link=|]] Note: See Event Source Element for a descriptive visualization of the event system handling an event trigger.

Syntax

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

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 or up the element tree (starting from the source), and not triggered directly on attachedTo (that is, handlers attached with this argument set to false will only be triggered if source == this).
  • priority : A string representing the trigger order priority relative to other event handlers of the same name. Possible values are:
    • "high"
    • "normal"
    • "low"

It is also possible to add finer priority control by appending a positive or negative number to the priority string. For example (in priority order for reference): "high+4" "high" "high-1" "normal-6" "normal-7" "low+1" "low" "low-1" Important note: Anything bound to a specific element will be run before other handlers that are bound to something higher in the element tree (like root) This means that "high+10" bound to root won't trigger before "normal" bound directly to an element.

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.

-- define our handler function
function onPlayerSpawnHandler ( )
	-- get the player's name, source is the player because he was spawned
	local playerName = getPlayerName( source )
	-- output in the chat box that they've spawned
	outputChatBox ( playerName .. " has spawned!" )
end

addEventHandler( "onPlayerSpawn", root, onPlayerSpawnHandler ) -- root is a predefined global variable for getRootElement()

Changelog

Version Description
1.3.0-9.03795 Added priority argument

See Also