TriggerClientEvent: Difference between revisions
| Line 27: | Line 27: | ||
==Example== | ==Example== | ||
This example shows how you can pass a simple "Hello World" message from the server to the client using an event. | |||
'''Client:''' | |||
<syntaxhighlight lang="lua"> | <syntaxhighlight lang="lua"> | ||
addEvent("onGreeting") | |||
addEventHandler("onGreeting", getRootElement(), "greetingHandler") | |||
function greetingHandler ( message ) | |||
outputChatBox ( "The server says: " .. message ) | |||
end | |||
</syntaxhighlight> | </syntaxhighlight> | ||
'''Server:''' | |||
<syntaxhighlight lang="lua"> | |||
addCommandHandler ( "greet", "greetingCommand" ) | |||
function greetingCommand ( source, commandName ) | |||
triggerClientEvent ( "onGreeting", getRootElement(), "Hello World!" ) | |||
end | |||
</syntaxhighlight> | |||
When the command "greet" is executed (by typing it in the server console or the player's console), the server's ''greetingCommand'' function is called. This triggers the client side event ''onGreeting'' with the string ''"Hello World!"''. This event is then handled by the ''greetingHandler'' function client side which then displays the message. | |||
==See Also== | ==See Also== | ||
{{Event_functions}} | {{Event_functions}} | ||
[[Category:Incomplete]] | [[Category:Incomplete]] | ||
Revision as of 00:37, 15 June 2007
This function triggers an event on clients. This is the primary means of passing information between the server and the client. Clients have a similar triggerServerEvent function that can do the reverse. You can treat this function as if it was an asynchronous function call, using triggerServerEvent to pass back any returned information if necessary.
Almost any data types can be passed as expected, including elements and complex nested tables. Special data types like xmlNodes will not be able to be passed as they do not necessarily have a valid representation on the client.
Events are sent reliably, so clients will receive them, but there may be (but shouldn't be) a significant delay before they are received. You should take this into account when using them.
Keep in mind the bandwidth issues when using events - don't pass a large list of arguments unless you really need to. It is marginally more efficient to pass one large event than two smaller ones.
Syntax
bool triggerClientEvent ( [element triggerFor=getRootElement()], string name, element theElement, [arguments...] )
Required Arguments
- name: The name of the event to trigger client side. You should register this event with addEvent and add at least one event handler using addEventHandler.
- theElement: The element that is the source of the event. This could be another player, or if this isn't relevant, use the root element.
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.
- triggerFor: The event will be triggered on all players that are children of the specified element. By default this is the root element, and hence the event is triggered on all elements. If you specify a single player it will just be triggered for that player.
- arguments...: A list of arguments to trigger with the event. You can pass any lua data type (except functions). You can also pass elements.
Returns
Returns true if the event trigger has been sent, false if invalid arguments were specified.
Example
This example shows how you can pass a simple "Hello World" message from the server to the client using an event. Client:
addEvent("onGreeting")
addEventHandler("onGreeting", getRootElement(), "greetingHandler")
function greetingHandler ( message )
outputChatBox ( "The server says: " .. message )
end
Server:
addCommandHandler ( "greet", "greetingCommand" )
function greetingCommand ( source, commandName )
triggerClientEvent ( "onGreeting", getRootElement(), "Hello World!" )
end
When the command "greet" is executed (by typing it in the server console or the player's console), the server's greetingCommand function is called. This triggers the client side event onGreeting with the string "Hello World!". This event is then handled by the greetingHandler function client side which then displays the message.