Event functions

Author: omar-o22

functions/Event/addEvent.yaml

@@ -1,8 +1,8 @@
 # Scraped from: https://wiki.multitheftauto.com/wiki/AddEvent
 shared:
   name: addEvent
-  description: This function allows you to register a custom [event](/wiki/Event "Event").
-    Custom events function exactly like the built\-in events. See [event system](/wiki/Event_system
+  description: This function allows you to register a custom [event](/reference/Event_System "Event").
+    Custom events function exactly like the built\-in events. See [event system](/reference/Event_System
     "Event system") for more information on the event system.
   parameters:
   - name: eventName
@@ -11,19 +11,14 @@ shared:
   - name: allowRemoteTrigger
     type: bool
     description: A boolean specifying whether this event can be called remotely using
-      triggerClientEvent / triggerServerEvent or not.
+      [triggerClientEvent](/reference/triggerClientEvent "TriggerClientEvent") / [triggerServerEvent](/reference/triggerServerEvent "TriggerServerEvent") or not.
     default: 'false'
   examples:
   - path: examples/addEvent-1.lua
     description: This example will define a new event calledonSpecialEvent.
-    side: server
-  - path: examples/addEvent-2.lua
-    description: 'You can then trigger this event later on using:'
-    side: server
   returns:
     values:
     - type: bool
       name: value
     description: Returns true if the event was added successfully, false if the event
       was already added.
-  requires_review: true

functions/Event/addEventHandler.yaml

@@ -1,22 +1,22 @@
 # Scraped from: https://wiki.multitheftauto.com/wiki/AddEventHandler
 shared:
   name: addEventHandler
-  description: This function will add an [event](/wiki/Event "Event") handler. An
+  description: This function will add an [event](/reference/Event_System "Event System") handler. An
     event handler is a function that will be called when the event it's attached to
-    is triggered. See [event system](/wiki/Event_system "Event system") for more information
+    is triggered. See [event system](/reference/Event_System "Event System") for more information
     on how the event system works.
   parameters:
   - name: eventName
     type: string
-    description: 'The name of the event you want to attach the handler function to.
-      Note: The maximum allowed length is 100 ASCII characters (that is, English letters
-      and numerals)'
+    description: 'The name of the [event](/reference/Event_System "Event System") you want to attach the handler function to.
+      **Note: The maximum allowed length is 100 ASCII characters (that is, English letters
+      and numerals)**'
   - name: attachedTo
     type: element
-    description: The element you wish to attach the handler to. The handler will only
+    description: The [element](/reference/Element "Element") you wish to attach the handler to. The handler will only
       be called when the event it is attached to is triggered for this element, or
       one of its children. Often, this can be the root element (meaning the handler
-      will be called when the event is triggered for any element).
+      will be called when the event is triggered for *any* element).
   - name: handlerFunction
     type: function
     description: The handler function you wish to call when the event is triggered.
@@ -25,14 +25,19 @@ shared:
   - name: propagate
     type: bool
     description: A boolean representing whether the handler will be triggered if the
-      event was propagated down or up the element tree (starting from the source),
+      event was propagated down or up the [element tree](/reference/Element_tree "Element tree") (starting from the source),
       and not triggered directly on attachedTo (that is, handlers attached with this
       argument set to false will only be triggered if source == this ). In GUI events
       you will probably want to set this to false .
     default: 'true'
   - name: priority
     type: string
-    description: MISSING_PARAM_DESC
+    description: | 
+      A string representing the trigger order priority relative to other event handlers of the same name. Possible values are:
+
+      "high"
+      "normal"
+      "low"
     default: '"normal"'
   examples:
   - path: examples/addEventHandler-1.lua
@@ -52,15 +57,15 @@ shared:
       On the same note, for multiple reasons, it isn't a good idea to export the same
       functions that you use locally as remote event handlers.
   - type: info
-    content: See Event Source Element for a descriptive visualization of the event
+    content: See [Event Source Element](/reference/Event_Source_Element "Event Source Element") for a descriptive visualization of the event
       system handling an event trigger.
   - type: important
-    content: See Script security for how-to prevent cheaters from abusing event system
-      and element data .
+    content: See [Script security](/Script_security "Script security") for how-to prevent cheaters from abusing [event system](/reference/Event_System "Event system")
+      and [element data](/reference/Element_data "Element data").
   - type: important
     content: Anything bound to a specific element will be run before other handlers
       that are bound to something higher in the element tree (like root) This means
-      that "high+10" bound to root won't trigger before "normal" bound directly to
+      that "high+10" bound to root **won't** trigger before "normal" bound directly to
       an element.
   - type: info
     content: Due to the additional set of global variables, the event-trigger specific
@@ -73,4 +78,3 @@ shared:
       the same issues. It is recommended to adapt a good-natured distancing principle
       between code meant to run from local logic in separation to code meant to run
       from remote logic.
-  requires_review: true

functions/Event/cancelEvent.yaml

@@ -1,22 +1,23 @@
 # Scraped from: https://wiki.multitheftauto.com/wiki/CancelEvent
-client:
+shared:
   name: cancelEvent
   description: 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](/wiki/OnPickupUse "OnPickupUse")
+    walk over a pickup, by canceling the [onPickupUse](/reference/onPickupUse "OnPickupUse")
     event.
   parameters: []
-  examples:
-  - path: examples/cancelEvent-2.lua
-    description: This example prevents any damage to a player clientside by makingcancelEventan
-      event handler for theonClientPlayerDamageevent.
-    side: client
   returns:
     values:
     - type: bool
       name: value
     description: Always returns true .
-  requires_review: true
+
+client:
+  examples:
+  - path: examples/cancelEvent-2.lua
+    description: This example prevents any damage to a player clientside by making **cancelEvent** an
+      event handler for the [onClientPlayerDamage](/reference/onClientPlayerDamage "OnClientPlayerDamage") event.
+
 server:
   name: cancelEvent
   description: This function is used to stop the automatic internal handling of events,
@@ -26,19 +27,17 @@ server:
   parameters:
   - name: cancel
     type: bool
-    description: MISSING_PARAM_DESC
+    description: True to cancel, false to uncancel.
     default: 'true'
   - name: reason
     type: string
-    description: MISSING_PARAM_DESC
+    description: The reason for cancelling the event.
     default: '""'
   examples:
   - path: examples/cancelEvent-1.lua
     description: This example stops the player from entering a vehicle.
-    side: server
   returns:
     values:
     - type: bool
       name: value
     description: Always returns true .
-  requires_review: true

functions/Event/cancelLatentEvent.yaml

@@ -1,11 +1,11 @@
 # Scraped from: https://wiki.multitheftauto.com/wiki/CancelLatentEvent
-client:
+shared:
   name: cancelLatentEvent
   description: Stops a latent event from completing
   parameters:
   - name: handle
     type: int
-    description: A handle previous got from getLatentEventHandles .
+    description: A handle previous got from [getLatentEventHandles](/reference/getLatentEventHandles "GetLatentEventHandles").
   examples:
   - path: examples/cancelLatentEvent-1.lua
     description: ''
@@ -19,7 +19,7 @@ client:
       name: value
     description: Returns a true if the latent event was successfully cancelled, or
       false if it was not
-  requires_review: true
+
 server:
   name: cancelLatentEvent
   description: Stops a latent event from completing
@@ -29,7 +29,7 @@ server:
     description: The player who is receiving the event.
   - name: handle
     type: int
-    description: A handle previous got from getLatentEventHandles .
+    description: A handle previous got from [getLatentEventHandles](/reference/getLatentEventHandles "GetLatentEventHandles").
   examples:
   - path: examples/cancelLatentEvent-2.lua
     description: ''
@@ -43,4 +43,3 @@ server:
       name: value
     description: Returns a true if the latent event was successfully cancelled, or
       false if it was not
-  requires_review: true

functions/Event/examples/addEvent-1.lua

@@ -7,4 +7,8 @@ function specialEventHandler ( text )
 end
 
 -- Add it as a handler for our event
-addEventHandler ( "onSpecialEvent", root, specialEventHandler )
+addEventHandler ( "onSpecialEvent", root, specialEventHandler )
+
+-- You can then trigger this event later on using:
+triggerEvent ( "onSpecialEvent", root, "test" )
+-- This will cause the handler to be triggered, so "test" will be output to the chatbox.

functions/Event/examples/addEvent-2.lua

@@ -1,4 +1,4 @@
 function onVehicleStartEnter()
-   cancelEvent()
+    cancelEvent()
 end
 addEventHandler("onVehicleStartEnter", root, onVehicleStartEnter)

functions/Event/examples/cancelEvent-1.lua

@@ -1,5 +1,5 @@
--- CLIENT SIDE:
-
+-- *****************************************************************************
+-- CLIENT CODE
 local lastTriggerd = false 
 
 addCommandHandler("trigger",function()
@@ -12,8 +12,8 @@ addCommandHandler("trigger",function()
 	lastTriggerd = #getLatentEventHandles() -- set the lastTriggerd with the id for last event triggerd
 end)
 
--- SERVER SIDE:
-
+-- *****************************************************************************
+-- SERVER CODE
 addEvent("LatentEventsCheck",true)
 addEventHandler("LatentEventsCheck",root,function (thePlayer)
 	outputChatBox("Latent trigger done from: " .. getPlayerName(thePlayer), root,math.random(255),0,0) 

functions/Event/examples/getLatentEventHandles-1.lua

@@ -1,3 +1,12 @@
+-- *****************************************************************************
+-- SERVER CODE
+ greetingCommand ( playerSource, commandName )
+    triggerClientEvent ( playerSource, "onGreeting", playerSource, "Hello World!" )
+end
+addCommandHandler ( "greet", greetingCommand )
+
+-- *****************************************************************************
+-- CLIENT CODE
 function greetingHandler ( message )
     outputChatBox ( "The server says: " .. message )
 end

functions/Event/examples/triggerClientEvent-1.lua

@@ -1,4 +1,23 @@
-function greetingCommand ( playerSource, commandName )
-    triggerClientEvent ( playerSource, "onGreeting", playerSource, "Hello World!" )
+-- *****************************************************************************
+-- SERVER CODE
+function greetingCommandOne ( playerSource, commandName, playerName )
+    if playerName then
+        local thePlayer = getPlayerFromName ( playerName )
+        if thePlayer then
+            triggerClientEvent ( thePlayer, "onGreeting", thePlayer, "Hello World!" )
+        else
+            -- invalid player name specified
+        end
+    else
+        -- No player name specified
+    end 
 end
-addCommandHandler ( "greet", greetingCommand )
+addCommandHandler ( "greet_one", greetingCommandOne )
+
+-- *****************************************************************************
+-- CLIENT CODE
+function greetingHandler ( message )
+    outputChatBox ( "The server says: " .. message )
+end
+addEvent( "onGreeting", true )
+addEventHandler( "onGreeting", localPlayer, greetingHandler )