TriggerEvent: Difference between revisions
No edit summary |
No edit summary |
||
| Line 1: | Line 1: | ||
__NOTOC__ | __NOTOC__ | ||
{{Server client function}} | |||
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. | ||
| Line 21: | Line 22: | ||
Returns ''true'' if the event was triggered successfully. This may involve calling no handlers (if none have been attached to the event), it will still be considered successful. Returns ''false'' if the arguments are invalid or the event could not be found. | Returns ''true'' if the event was triggered successfully. This may involve calling no handlers (if none have been attached to the event), it will still be considered successful. Returns ''false'' if the arguments are invalid or the event could not be found. | ||
If you want to check if the event was cancelled (using [[cancelEvent]]) use [[ | If you want to check if the event was cancelled (using [[cancelEvent]]) use [[wasEventCanceled]]. | ||
==Example== | ==Example== | ||
| Line 31: | Line 32: | ||
-- Add a new event called onSpecialEvent | -- Add a new event called onSpecialEvent | ||
addEvent ( "onSpecialEvent", "text" ) | addEvent ( "onSpecialEvent", "text" ) | ||
-- Define our handler function | -- Define our handler function | ||
function specialEventHandler ( text ) | function specialEventHandler ( text ) | ||
outputChatBox ( text ) | outputChatBox ( text ) | ||
end | end | ||
-- Add the event handler | |||
addEventHandler ( "onSpecialEvent", rootElement, specialEventHandler ) | |||
</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 ( "onSpecialEvent", rootElement, "test" ) | |||
</syntaxhighlight> | </syntaxhighlight> | ||
==See Also== | ==See Also== | ||
{{Event_functions}} | {{Event_functions}} | ||
Revision as of 17:18, 15 August 2007
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.
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 true if the event was triggered successfully. This may involve calling no handlers (if none have been attached to the event), it will still be considered successful. Returns false if the arguments are invalid or the event could not be found.
If you want to check if the event was cancelled (using cancelEvent) use wasEventCanceled.
Example
If you define a new custom event as follows:
-- Get the root map element rootElement = getRootElement () -- Add a new event called onSpecialEvent addEvent ( "onSpecialEvent", "text" ) -- Define our handler function function specialEventHandler ( text ) outputChatBox ( text ) end -- Add the event handler addEventHandler ( "onSpecialEvent", rootElement, specialEventHandler )
You can then trigger this event later on using:
triggerEvent ( "onSpecialEvent", rootElement, "test" )
See Also
- addEvent
- addEventHandler
- cancelEvent
- cancelLatentEvent
- getCancelReason
- getEventHandlers
- getLatentEventHandles
- getLatentEventStatus
- removeEventHandler
- triggerEvent
- triggerClientEvent
- triggerLatentClientEvent
- wasEventCancelled