CancelEvent: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
No edit summary
 
mNo edit summary
 
(26 intermediate revisions by 15 users not shown)
Line 1: Line 1:
{{Needs_Checking|I'm making assumptions here.. [[User:Erorr404|Erorr404]]}}
__NOTOC__
{{Server client function}}
This function is used to stop the automatic internal handling of events, for example this can be used to prevent an item being given to a player when they walk over a pickup, by canceling the [[onPickupUse]] event.
 
[[cancelEvent]] does not have an effect on all events, see the individual event's pages for information on what happens when the event is canceled. [[cancelEvent]] does not stop further event handlers from being called, as the order of event handlers being called is undefined in many cases. Instead, you can see if the currently active event has been cancelled using [[wasEventCancelled]].
 
The use of cancelEvent outside of an event handler has no effect.


__NOTOC__
If you implement your own custom events and want to handle them being cancelled, you should call [[wasEventCancelled]] to check after your call to [[triggerEvent]].
This function is used to stop events from occuring when they otherwise would. When a player walks over a pickup for example, this function can stop them from getting it. cancelEvent is not compatible with all events.


==Syntax==  
==Syntax==  
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
bool cancelEvent ( [ bool cancel = true, string reason = "" ] ) 
</syntaxhighlight>
</section>
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
bool cancelEvent ()   
bool cancelEvent ()   
</syntaxhighlight>
</syntaxhighlight>
</section>


===Usage===
===Optional Arguments===  
cancelEvent must be called from inside an event handler (a function that is called when an event is triggered).
{{OptionalArg}}
 
*'''cancel:''' True to cancel, false to uncancel.
Here is a list of compatible events:
*'''reason:''' The reason for cancelling the event.
* onVehicleStartEnter


===Returns===
===Returns===
Returns ''true'' if the event was canceled successfully, ''false'' if the event is incompatible.
Always returns ''true''.


==Example==  
==Example==  
This example stops the player ''huntedPlayer'' from entering a vehicle:
<section name="Example 1 - Server" class="server" show="true">
This example stops the player from entering a vehicle.
<syntaxhighlight lang="lua">
function onVehicleStartEnter()
  cancelEvent()
end
addEventHandler("onVehicleStartEnter", root, onVehicleStartEnter)
</syntaxhighlight>
</section>
<section name="Example 2 - Client" class="client" show="true">
This example prevents any damage to a player clientside by making [[cancelEvent]] an event handler for the [[onClientPlayerDamage]] event.
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
-- call 'stopVehicleEntry' whenever hunterPlayer is about to enter a vehicle:
function onClientPlayerDamage()
addEventHandler ( "onVehicleStartEnter", huntedPlayer, "stopVehicleEntry" )
cancelEvent()
function stopVehicleEntry ( theplayer, seat, jacked )
  cancelEvent () -- stop the event from occuring
end
end
addEventHandler("onClientPlayerDamage", root, onClientPlayerDamage)
</syntaxhighlight>
</syntaxhighlight>
</section>


==See Also==
==See Also==
{{Event functions}}
{{Event functions}}
[[ru:cancelEvent]]

Latest revision as of 11:23, 8 June 2022

This function is used to stop the automatic internal handling of events, for example this can be used to prevent an item being given to a player when they walk over a pickup, by canceling the onPickupUse event.

cancelEvent does not have an effect on all events, see the individual event's pages for information on what happens when the event is canceled. cancelEvent does not stop further event handlers from being called, as the order of event handlers being called is undefined in many cases. Instead, you can see if the currently active event has been cancelled using wasEventCancelled.

The use of cancelEvent outside of an event handler has no effect.

If you implement your own custom events and want to handle them being cancelled, you should call wasEventCancelled to check after your call to triggerEvent.

Syntax

Click to collapse [-]
Server
bool cancelEvent ( [ bool cancel = true, string reason = "" ] )
Click to collapse [-]
Client
bool cancelEvent ()

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.

  • cancel: True to cancel, false to uncancel.
  • reason: The reason for cancelling the event.

Returns

Always returns true.

Example

Click to collapse [-]
Example 1 - Server

This example stops the player from entering a vehicle. 

function onVehicleStartEnter()
   cancelEvent()
end
addEventHandler("onVehicleStartEnter", root, onVehicleStartEnter)
Click to collapse [-]
Example 2 - Client

This example prevents any damage to a player clientside by making cancelEvent an event handler for the onClientPlayerDamage event. 

function onClientPlayerDamage()
	cancelEvent()
end
addEventHandler("onClientPlayerDamage", root, onClientPlayerDamage)

See Also

Retrieved from "https://wiki.multitheftauto.com/wiki/CancelEvent?oldid=75035"