Event system

Table of Contents

• Event
  • options
    • SHORTCIRCUIT
  • subscribe
  • isSubscribed
  • unsubscribe
  • unsubscribeAll
  • dispatch
• Subscription
  • unsubscribe
  • addTeardown
  • isClosed
  • openUntil

 

Event

Event class that allows to easily create events - or 'hooks', as we tend to call them.

Unlike hooks, events are not cleaned up by default when loading, so if you define your own event, you have to take care of removing subscriptions when it makes sense in your case (eg. mission is over, or a UI dialog closed, etc.). See also Subscription:openUntil.

 

Event options

Events can be created with options passed to the event constructor. Example:

local myEvent = Event({ [Event.SHORTCIRCUIT] = true })

Event.SHORTCIRCUIT

When this event option is true, the event allows its subscribers to shortcircuit processing by returning true, preventing subscribers that come after from being notified of that particular event dispatch.

Example:

local myEvent = Event({ [Event.SHORTCIRCUIT] = true })
myEvent:subscribe(function()
  LOG("subscriber 1 notified")
  return true
end)
myEvent:subscribe(function()
  LOG("subscriber 2 notified")
end)
myEvent:dispatch()

-- The above will only print 'subscriber 1 notified'

 

Event:subscribe

Argument name	Type	Description
fn	function	Function that will be notified when this event is dispatched. Its argument list should match the events own.

Subscribes a function to this event; this call is analogous to modApi:add__Hook() in old hooks API.

Returns a subscription object that can be used to cancel the subscription, preventing the function from being called anymore.

Example:

local myEvent = Event()
myEvent:subscribe(function(arg1, arg2, arg3)
    LOG("myEvent has been fired with args:", arg1, arg2, arg3)
end)

myEvent:dispatch(1, 2, 3)

 

Event:isSubscribed

Argument name	Type	Description
subscription	Subscription or function	Subscription to check

Returns true if the specified subscription is subscribed to this event, false otherwise.

local myEvent = Event()
local fn = function() end
local sub = myEvent:subscribe(fn)

LOG("is subscribed?", myEvent:isSubscribed(sub))
LOG("is subscribed?", myEvent:isSubscribed(fn))

 

Event:unsubscribe

Argument name	Type	Description
subscription	Subscription or function	Subscription to cancel

See Subscription:unsubscribe().

 

Event:unsubscribeAll

Unsubscribes all subscriptions from this event. See Subscription:unsubscribe().

 

Event:dispatch

Argument name	Type	Description
...	any	Any number of any arguments.

Fires this event, notifying all subscribers and passing all arguments that have been passed to this function to them. Arguments are passed as-is without any cloning or protection, so if you pass a table, and one subscriber modifies it, the changes will propagate to subsequent subscribers.

Example:

local myEvent = Event()
myEvent:subscribe(function(arg1, arg2, arg3)
    LOG("myEvent has been fired with args:", arg1, arg2, arg3)
end)

myEvent:dispatch(1, 2, 3)

 

Subscription

Represents an active event subscription, ie. a function that will be invoked when an event is fired. Can be used to cancel the subscription, thus preventing the function from being invoked anymore.

 

Subscription:unsubscribe

Cancels the subscription, preventing its associated function from being invoked when the event is fired. Fires and then cleans up all teardown functions defined on the subscription.

Example:

local myEvent = Event()
local sub = myEvent:subscribe(function() ... end)

sub:unsubscribe()

 

Subscription:addTeardown

Argument name	Type	Description
fn	function	Teardown function.

Adds a function that will be invoked when this subscription is cancelled. This can be useful for some complex scenarios, where excessive cleanup is required.

Example:

local myEvent = Event()
local sub = myEvent:subscribe(function() ... end)
sub:addTeardown(function()
  LOG("myEvent subscriber has been unsubscribed!")
end)

sub:unsubscribe()

 

Subscription:isClosed

Returns true if this subscription has been cancelled, and its function will no longer be invoked when the event is fired.

 

Subscription:openUntil

Unsubscribes this Subscription the next time the event passed in argument is triggered. Useful for automated cleanup of events, when you don't want to manually manage subscriptions.

Example:

local myEvent = Event()
local resetEvent = Event()
myEvent:subscribe(function() LOG("myEvent has been fired") end)
  :addTeardown(function() LOG("myEvent has been unsubscribed") end)
  :openUntil(resetEvent)

resetEvent:dispatch()