Module Event

Copilot's event library.

Class Action

Action:new(callback[, flags]) Constructor
Action:setEnabled(value) Enables or disables the action.
Action:isThreadRunning() Returns true if the callback was configured to be run as a coroutine and is running now.
Action:removeEventRef(refType, ...) Use this you want to disable the effect of stopOn for one of the predefined actions in copilot.actions
Action:stopCurrentThread() If the action was configured to be run as a coroutine, stops the execution of the currently running coroutine immediately.
Action:stopOn(...)
Action:addCleanup(callback) Can be used when the action can be stopped - the callback will be executed when the action is stopped.
Action:setLogMsg(msg) Add log info that will be logged when the action is started or stopped

Class Event

Event:new([args]) Constructor
Event:addAction(...)
Event:addOneOffAction(...) Same as addAction but the action will be removed from event's action list after it's executed once.
Event:removeAction(action)
Event:trigger(...) Triggers the event which in turn executes all actions (if they are enabled).
Event.waitForEvent(event[, returnFunction=false]) Waits for an event or returns a function that tells whether the event was signaled.
Event.waitForEventWithTimeout(timeout, event) Waits for the event or until the timeout is elapsed.
Event.waitForEvents(events[, waitForAll=false][, returnFunction=false]) Same as waitForEvent but for multiple events
Event.waitForEventsWithTimeout(timeout, events[, waitForAll=false]) Waits for multiple events or until the timeout is elapsed.
Event.fromKeyPress(key) Constructs an event from a key press.
Event.fromTextMenu(title, prompt, items[, timeout=0]) Constructs an event from a TextMenu.
Event:setActionOrder(action) Sets order of the event's actions relative to each other.

Class SingleEvent

SingleEvent:addAction(...) Same as Event:addAction, but if the event has already been signaled, the action will execute immediately.
SingleEvent:trigger(...) Same as Event:trigger, but does nothing after being called once.


Class Action

Action:new(callback[, flags])
Constructor

Parameters:

  • callback function
  • flags string 'runAsCoroutine' (optional)
Action:setEnabled(value)
Enables or disables the action.

Parameters:

  • value bool True to enable the action, false to disable.
Action:isThreadRunning()
Returns true if the callback was configured to be run as a coroutine and is running now.
Action:removeEventRef(refType, ...)
Use this you want to disable the effect of stopOn for one of the predefined actions in copilot.actions

Parameters:

Usage:

    copilot.actions.preflight:removeEventRef('stop', copilot.events.enginesStarted)
Action:stopCurrentThread()
If the action was configured to be run as a coroutine, stops the execution of the currently running coroutine immediately.
Action:stopOn(...)

Parameters:

  • ... One or more events. If the 'runAsCoroutine' flag was passed to the constructor, the callback coroutine will be stopped when these events are triggered.

Returns:

    self

Usage:

    myAction:stopOn(copilot.events.takeoffAborted, copilot.events.takeoffCancelled)
Action:addCleanup(callback)
Can be used when the action can be stopped - the callback will be executed when the action is stopped.

Parameters:

  • callback function

Returns:

    self
Action:setLogMsg(msg)
Add log info that will be logged when the action is started or stopped

Parameters:

Returns:

    self

Class Event

Event:new([args])
Constructor

Parameters:

  • args A table containing the following fields:
    • action Function or Action or array of either that will be executed when the event is triggered.
      If it's an array of functions, each function can optionally be followed by string 'runAsCoroutine'.
      Actions can also be added to an existing event via addAction. (optional)
    • logMsg string Message that will be logged when the event is triggered. (optional)

Usage:

    local event1 = Event:new {
 action = function() print "test action" end,
 logMsg = "test event"
}

local event2 = Event:new {
 action = {
   function() while true do print "coroutine 1" coroutine.yield() end, 'runAsCourutine',
   function() while true do print "coroutine 2" coroutine.yield() end, 'runAsCourutine'
 },
 logMsg = "test event with coroutine actions"
}
Event:addAction(...)

Parameters:

  • ... Either a function with the optional flag 'runAsCoroutine' as the second argument or an Action.

Returns:

    The added Action.

Usage:

    myEvent:addAction(function() end, 'runAsCoroutine')
Event:addOneOffAction(...)
Same as addAction but the action will be removed from event's action list after it's executed once.

Parameters:

  • ...
Event:removeAction(action)

Parameters:

  • action An Action that was added to this event.

Returns:

    self

Usage:

    local myAction = myEvent:addAction(function() end)
myEvent:removeAction(myAction)
Event:trigger(...)
Triggers the event which in turn executes all actions (if they are enabled).

Parameters:

  • ... Any number of arguments that will be passed to each listener as the event's payload (following the first argument, which is always the event itself)
Event.waitForEvent(event[, returnFunction=false])
Waits for an event or returns a function that tells whether the event was signaled.

Parameters:

  • event Event
  • returnFunction bool (default false)

Returns:

    If returnFunction is false, waitForEvent waits for the event itself and returns you its payload. If returnFunction is true, waitForEvent returns a function that returns:
    1. Boolean that indicates whether the event was signaled
    2. Function that returns the event's payload.

Usage:

    Event.waitForEvent(copilot.events.landing)
Event.waitForEventWithTimeout(timeout, event)
Waits for the event or until the timeout is elapsed.

Parameters:

  • timeout int Timeout in milliseconds
  • event Event

Returns:

  1. True if the event was signaled or Event.TIMEOUT
  2. Function that returns the event's payload.
Event.waitForEvents(events[, waitForAll=false][, returnFunction=false])
Same as waitForEvent but for multiple events

Parameters:

  • events table Array of Event's.
  • waitForAll bool (default false)
  • returnFunction bool (default false)

Returns:

  1. If returnFunction is false:

    • If waitForall is true: Table with events as keys and functions that return their payload as values.
    • If waitForAll is false: The first event that was signaled, a function that returns its payload and the event's array index.

    If returnFunction is true, a function that returns the following values:

    • If waitForall is true:
      1. Boolean that indicates whether all events were signaled.
      2. Table with events as keys and functions that return their payload as values.
    • If waitForAll is false:
      1. An event that was signaled or nil.
      2. Function that returns the signaled event's payload.
  2. Only when returnFunction and waitForAll are false: Function that returns the signaled event's payload.
Event.waitForEventsWithTimeout(timeout, events[, waitForAll=false])
Waits for multiple events or until the timeout is elapsed.

Parameters:

  • timeout int Timeout in milliseconds
  • events Array of Event's
  • waitForAll bool Whether to wait for any event or all events to be signaled. (default false)

Returns:

  1. If waitForAll is true: Table with events as keys and functions that return their payload as values or Event.TIMEOUT
    If waitForAll is false: The first event that was signaled or Event.TIMEOUT
  2. If waitForAll is false: Function that returns the signaled event's payload.
  3. If waitForAll is false: Array index of the event
Event.fromKeyPress(key)
Constructs an event from a key press.

Parameters:

Returns:

    Event
Event.fromTextMenu(title, prompt, items[, timeout=0])
Constructs an event from a TextMenu. The menu is shown immediately.

Parameters:

  • title string The title of the menu
  • prompt string The message that is displayed between the title and the items. Empty string is allowed.
  • items table Array of strings representing the menu items
  • timeout int The menu's timeout. 0 means infinite timeout. (default 0)

Returns:

    An SingleEvent. The event will produce the following payload values:

    1. The result. One of these:
      • TextMenuResult.OK
      • TextMenuResult.Replaced
      • TextMenuResult.Removed
      • TextMenuResult.Timeout
    2. The index of the selected item.
    3. The selected item as a string.
Event:setActionOrder(action)
Sets order of the event's actions relative to each other.

Parameters:

  • action An Action which will serve as an anchor for positioning other actions in front or after it.

Returns:

    A table with four functions: 'front', 'back', 'before' and 'after. 'Before' and 'after' take a variable number of Action's. All four functions optionally take a boolean as the last parameter which defaults to true if omitted. If the last parameter is true and both the anchor action and the other actions are coroutines, the coroutines will not be run simultaneously.

    An error will be thrown if there is a cycle in the ordering.

Usage:

    local event = Event:new()

local second = event:addAction(function() print "second" end)
local first = event:addAction(function() print "first" end)
local fourth = event:addAction(function() print "fourth" end)
local third = event:addAction(function() print "third" end)

event:trigger()
 -- second
 -- first
 -- fourth
 -- third

print "--------------------------------------------------"

event:setActionOrder(first):before(second)
event:setActionOrder(second):before(third)
event:setActionOrder(third):before(fourth)

 --[[
Another possibility:

event:setActionOrder(first):front()
event:setActionOrder(fourth):back()
event:setActionOrder(second):after(first):before(third)

]]

event:trigger()

 -- first
 -- second
 -- third
 -- fourth

print "--------------------------------------------------"

event = event:new()

second = event:addAction(function()
  for _ = 1, 4 do coroutine.yield() end
  print "second"
end, "runAsCoroutine")

first = event:addAction(function()
  for _ = 1, 5 do coroutine.yield() end
  print "first"
end, "runAsCoroutine")

fourth = event:addAction(function()
  print "fourth"
end, "runAsCoroutine")

third = event:addAction(function()
  for _ = 1, 3 do coroutine.yield() end
  print "third"
end, "runAsCoroutine")

event:setActionOrder(second):before(third):after(first)
event:setActionOrder(third):before(fourth)

event:trigger()

 -- first
 -- second
 -- third
 -- fourth

Class SingleEvent

An Event that can be signaled only once
SingleEvent:addAction(...)
Same as Event:addAction, but if the event has already been signaled, the action will execute immediately.

Parameters:

  • ...
SingleEvent:trigger(...)
Same as Event:trigger, but does nothing after being called once.

Parameters:

  • ...
generated by LDoc 1.4.6 Last updated 2021-11-11 17:10:49