Event: Difference between revisions
>Legend26 |
>Legend26 update |
||
Line 1: | Line 1: | ||
An Event is a special kind of Roblox Object. It provides a way for user-defined functions to be called when something happens in the | An Event is a special kind of Roblox Object. It provides a way for user-defined functions to be called when something happens in the game. | ||
==Methods== | ==Methods== | ||
Events have these methods: | Events have these methods: | ||
{|class="wikitable" style="width: 100%" | |||
! Method !! Description !! Notes | |||
|- | |||
| connect([[function]] handler)||Establishes a function to be called whenever the event occurs. || | |||
|- | |||
| connectFirst([[function]] handler)||Same as connect except handler functions gets called ''before'' any other handler.||'''Protected''' | |||
|- | |||
| connectLast([[function]] handler)||Same as connect except handler functions gets called ''after'' all the other handlers.||'''Protected''' | |||
|- | |||
| wait()||Pauses the script until the event is fired and returns any arguments the event returns.|| | |||
|- | |||
| disconnect([[function]] handler)||Disconnects the specified handler function. Use Connection:disconnect() instead.||'''Deprecated''' | |||
|} | |||
== Usage == | == Usage == | ||
Take the example of the [[Touched (Event)|Touched]] event of Part: | Take the example of the [[Touched (Event)|Touched]] event of the Part instance: | ||
{{:Touched (Event)}} | {{:Touched (Event)}} | ||
{{clear floats}} | {{clear floats}} | ||
The | The Top of the event box tells you that it is an event named "Touched" which has arguments "Instance otherPart". The middle section explains when the event will fire and why. The last section lists the objects that have this event. | ||
The last section lists | |||
We use this information to create a | We use this information on the event to create a connection to an event line in our script. | ||
Traditionally, such functions are called "handlers" and are named on{Event Name}: | Traditionally, such functions are called "handlers" and are named on{Event Name}: | ||
{{example|1= | |||
<code lua> | |||
function onTouched() | |||
--code | |||
end | |||
</code> | |||
}} | |||
The arguments that will be passed by the event are given by the name of the event. In this case it is "Instance otherPart". This means that "otherPart" will be passed and the type of otherPart will be an instance (which all Parts are). | |||
To allow our function to use that, we defined it as: | |||
<code lua> | |||
function onTouched(otherPart) | |||
--code | |||
end | |||
</code> | |||
Finally, we can use the connection method of events to bind our function to the event. | |||
<code lua> | |||
part.Touched:connect(onTouched) | |||
</code> | |||
Here's an example using the Touched event of a Part object. | |||
{{Example| | |||
<code lua> | |||
local part = game.Workspace.Part -- your part here | |||
function onTouched(otherPart) | |||
otherPart.Transparency = 1 -- make part that was touched invisible | |||
part.BrickColor = BrickColor.Random() -- give this part a new random color | |||
end | |||
part.Touched:connect(onTouched) -- call onTouched each time something touches | |||
</code> | |||
Here we are giving "otherPart" as an argument to the event handler, onTouched. When the ''part'' is touched, the part that touches ''part'' will turn invisible and ''part'' will become a different color. | |||
}} | |||
== Advanced Usage == | |||
Any function name is valid: | |||
{{example| | |||
<code lua> | |||
function blah() | |||
print("In event") | |||
end | |||
part.Changed:connect(blah) | |||
</code> | |||
}} | |||
{{ | Using anonymous functions in connect is common and results in slightly shorter code. This can be useful if you only need to connect a function to an event once. | ||
< | {{example| | ||
<code lua> | |||
part.Touched:connect(function(otherPart) | |||
otherPart.Transparency = 1 | |||
part.BrickColor = BrickColor.Random() | |||
end) -- ends the anonymous function and the ''connect'' method call. | |||
</code> | |||
}} | |||
You can also use anonymous functions to change the arguments: | |||
{{example| | |||
<code lua> | |||
player.Chatted:connect(function(message, recipient) | |||
onChatted(player, message) -- new arguments need to match onChatted function call | |||
end) | |||
</code> | |||
}} | |||
Connections can be created at any time, even inside of event functions: | |||
{{example| | |||
<code lua> | |||
function onChatted(player, message) | |||
print(player .. " said " .. message) | |||
end | |||
function onPlayerAdded(player) | |||
player.Chatted:connect(function(message, recipient) | |||
onChatted(player, message) | |||
end) | |||
end | |||
game.Players.PlayerAdded:connect(onPlayerAdded) | |||
</ | </code> | ||
}} | }} | ||
== Limitations == | == Limitations == | ||
Connections are | Connections are automatically disconnected if: | ||
* The event handler generates an error before the first wait() call. | * The event handler generates an error before the first wait() call. | ||
* The script itself is removed or reparented. | * The script itself is removed or reparented. | ||
* The object | * The object the event relates to is destroyed with the [[Destroy_(Method)|Destroy]] method. | ||
'''Note''': The connect method does not check that the argument is a valid function. If you misspell the name or otherwise give an invalid function you'll get an error when the event next triggers: | '''Note''': The connect method does not check that the argument is a valid function. If you misspell the name or otherwise give an invalid function you'll get an error when the event next triggers: | ||
Line 88: | Line 123: | ||
Notice that the error has no script reference or line number. This is because it comes from Roblox itself inside the Event generation code. | Notice that the error has no script reference or line number. This is because it comes from Roblox itself inside the Event generation code. | ||
= | =Connections= | ||
The connection object is a special object returned by the connect methods of an Event. | |||
== Methods == | |||
Connections have one method: | |||
{|class="wikitable" | |||
! Method !! Description | |||
|- | |||
| diconnect()||Disconnects the connection from the event. | |||
|} | |||
== Properties == | == Properties == | ||
Connections have one property: | |||
{|class="wikitable" | |||
! Property !! Description | |||
|- | |||
| [[Bool]] connected||True if the connection is connected to an event. Otherwise false. | |||
|} |
Revision as of 22:50, 22 January 2012
An Event is a special kind of Roblox Object. It provides a way for user-defined functions to be called when something happens in the game.
Methods
Events have these methods:
Method | Description | Notes |
---|---|---|
connect(function handler) | Establishes a function to be called whenever the event occurs. | |
connectFirst(function handler) | Same as connect except handler functions gets called before any other handler. | Protected |
connectLast(function handler) | Same as connect except handler functions gets called after all the other handlers. | Protected |
wait() | Pauses the script until the event is fired and returns any arguments the event returns. | |
disconnect(function handler) | Disconnects the specified handler function. Use Connection:disconnect() instead. | Deprecated |
Usage
Take the example of the Touched event of the Part instance:
Touched ( BasePart otherPart ) | |
Description | Fired when another object comes in contact with this object. |
---|---|
Member of: | BasePart |
The Top of the event box tells you that it is an event named "Touched" which has arguments "Instance otherPart". The middle section explains when the event will fire and why. The last section lists the objects that have this event.
We use this information on the event to create a connection to an event line in our script.
Traditionally, such functions are called "handlers" and are named on{Event Name}:
function onTouched()
--code
end
The arguments that will be passed by the event are given by the name of the event. In this case it is "Instance otherPart". This means that "otherPart" will be passed and the type of otherPart will be an instance (which all Parts are).
To allow our function to use that, we defined it as:
function onTouched(otherPart)
--code
end
Finally, we can use the connection method of events to bind our function to the event.
part.Touched:connect(onTouched)
Here's an example using the Touched event of a Part object.
Advanced Usage
Any function name is valid:
function blah()
print("In event")
end
part.Changed:connect(blah)
Using anonymous functions in connect is common and results in slightly shorter code. This can be useful if you only need to connect a function to an event once.
You can also use anonymous functions to change the arguments:
player.Chatted:connect(function(message, recipient)
onChatted(player, message) -- new arguments need to match onChatted function call
end)
Connections can be created at any time, even inside of event functions:
function onChatted(player, message)
print(player .. " said " .. message)
end
function onPlayerAdded(player)
player.Chatted:connect(function(message, recipient)
onChatted(player, message)
end)
end
game.Players.PlayerAdded:connect(onPlayerAdded)
Limitations
Connections are automatically disconnected if:
- The event handler generates an error before the first wait() call.
- The script itself is removed or reparented.
- The object the event relates to is destroyed with the Destroy method.
Note: The connect method does not check that the argument is a valid function. If you misspell the name or otherwise give an invalid function you'll get an error when the event next triggers:
Fri Apr 23 21:50:48 2010 - attempt to call a nil value Fri Apr 23 21:50:48 2010 -
Notice that the error has no script reference or line number. This is because it comes from Roblox itself inside the Event generation code.
Connections
The connection object is a special object returned by the connect methods of an Event.
Methods
Connections have one method:
Method | Description |
---|---|
diconnect() | Disconnects the connection from the event. |
Properties
Connections have one property:
Property | Description |
---|---|
Bool connected | True if the connection is connected to an event. Otherwise false. |