TriggerEvent: Difference between revisions
Jump to navigation
Jump to search
No edit summary |
|||
| (10 intermediate revisions by 9 users not shown) | |||
| Line 3: | Line 3: | ||
This function will trigger a named [[event]] on a specific [[element]] in the [[element tree]]. See [[event system]] for more information on how the event system works. | This function will trigger a named [[event]] on a specific [[element]] in the [[element tree]]. See [[event system]] for more information on how the event system works. | ||
You should avoid triggering events on the [[root element]] unless you really need to. Doing this triggers the event on every element in the element tree, which is potentially very CPU intensive. Use as specific (i.e. low down the tree) element as you can. | You can use the value returned from this function to determine if the event was cancelled by one of the event handlers. You should determine what your response (if any) to this should be based on the event's purpose. Generally, cancelling an event should prevent any further code being run that is dependent on whatever triggered that event. For example, if you have an ''onFlagCapture'' event, cancelling it would be expected to prevent the flag being able to be captured. Similarly, if you have ''onPlayerKill'' as an event you trigger, canceling it would either be expected to prevent the player being killed from dying or at least prevent the player from getting a score for it. | ||
{{Note|You should avoid triggering events on the [[root element]] unless you really need to. Doing this triggers the event on every element in the element tree, which is potentially very CPU intensive. Use as specific (i.e. low down the tree) element as you can.}} | |||
{{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"> | ||
| Line 21: | Line 22: | ||
===Returns=== | ===Returns=== | ||
* Returns '''nil''' if the arguments are invalid or the event could not be found. | * Returns '''nil''' if the arguments are invalid or the event could not be found. | ||
* Returns '''true''' if the event was triggered successfully, and was not cancelled using [[cancelEvent]]. | * Returns '''true''' if the event was triggered successfully, and ''was not'' cancelled using [[cancelEvent]]. | ||
* Returns '''false''' if the event was triggered successfully, and was | * Returns '''false''' if the event was triggered successfully, and ''was'' cancelled using [[cancelEvent]]. | ||
==Example== | ==Example== | ||
If you define a new custom event as follows: | If you define a new custom event as follows: | ||
<syntaxhighlight lang="lua"> | <syntaxhighlight lang="lua"> | ||
function onCustomEvent(chatMessage) | |||
outputChatBox(chatMessage) | |||
function | |||
outputChatBox ( | |||
end | end | ||
-- | addEvent("onCustomEvent", false) -- set to false, so this event won't be called from counter side - important security measure | ||
addEventHandler ( " | addEventHandler("onCustomEvent", root, onCustomEvent) | ||
</syntaxhighlight> | </syntaxhighlight> | ||
You can then trigger this event later on using: | You can then trigger this event later on using: | ||
<syntaxhighlight lang="lua"> | <syntaxhighlight lang="lua"> | ||
triggerEvent ( " | triggerEvent("onCustomEvent", resourceRoot, "Hello, world!") | ||
</syntaxhighlight> | </syntaxhighlight> | ||
==See Also== | ==See Also== | ||
{{Event_functions}} | {{Event_functions}} | ||
[[ru:triggerEvent]] | |||
Latest revision as of 19:35, 8 April 2024
This function will trigger a named event on a specific element in the element tree. See event system for more information on how the event system works.
You can use the value returned from this function to determine if the event was cancelled by one of the event handlers. You should determine what your response (if any) to this should be based on the event's purpose. Generally, cancelling an event should prevent any further code being run that is dependent on whatever triggered that event. For example, if you have an onFlagCapture event, cancelling it would be expected to prevent the flag being able to be captured. Similarly, if you have onPlayerKill as an event you trigger, canceling it would either be expected to prevent the player being killed from dying or at least prevent the player from getting a score for it.
Syntax
bool triggerEvent ( string eventName, element baseElement, [ var argument1, ... ] )
Required Arguments
- eventName: The name of the event you wish to trigger
- baseElement: The element you wish to trigger the event on. See event system for information on how this works.
Optional Arguments
NOTE: When using optional arguments, you might need to supply all arguments before the one you wish to use. For more information on optional arguments, see optional arguments.
- argument1: The first argument that the event handler expects should be added after the baseElement variable.
- NOTE: This function can have more than one of these arguments specified, once for each argument the event handler is expecting.
Returns
- Returns nil if the arguments are invalid or the event could not be found.
- Returns true if the event was triggered successfully, and was not cancelled using cancelEvent.
- Returns false if the event was triggered successfully, and was cancelled using cancelEvent.
Example
If you define a new custom event as follows:
function onCustomEvent(chatMessage)
outputChatBox(chatMessage)
end
addEvent("onCustomEvent", false) -- set to false, so this event won't be called from counter side - important security measure
addEventHandler("onCustomEvent", root, onCustomEvent)
You can then trigger this event later on using:
triggerEvent("onCustomEvent", resourceRoot, "Hello, world!")