Event system - itb-community/ITB-ModLoader GitHub Wiki
Table of Contents
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()