Module signal
Simple signal / observer pattern implementation for Lua.
No dependency. Optional dependency: LÖVE to hook into LÖVE events.
The returned module also acts as a global SignalRegistry, so you can call the :bind, :emit, etc. methods directly on the module
if you don’t need to isolate your signals in separate registries.
Usage:
local signal = require("ubiquitousse.signal")
-- Bind a function to a "hit" signal
signal:bind("hit", function(enemy)
print(enemy.." was hit!")
end)
-- Somewhere else in your code: will call every function bound to "hit" signal with "invader" argument
signal:emit("hit", "invader")
-- We also provides a predefined SignalRegistry (signal.event) which emit signals on LÖVE callbacks
-- You can initialize it with:
signal.registerEvents()
signal.event:bind("update", function(dt) print("called every update") end)
signal.event:bind("keypressed", function(key, scancode) print("pressed key "..key) end)
-- etc., for every LÖVE callback
Module
| new () | Creates and return a new SignalRegistry. |
| group () | Creates and return a new SignalGroup. |
| event | SignalRegistry which will be used to bind signals that need to be called on LÖVE events; other ubiquitousse modules may bind to this registry if avaible. |
| registerEvents () | Call this function to hook signal.event signals to LÖVE events. |
SignalRegistry objects
| SignalRegistry.signals | Map of signals to list of listeners. |
| SignalRegistry.chained | List of registries chained to this registry. |
| SignalRegistry:bind (name, fn) | Bind a function to a signal name. |
| SignalRegistry:has (name, fn) | Returns true if fn is bound to the signal. |
| SignalRegistry:unbind (name, fn) | Unbind a function from a signal name. |
| SignalRegistry:unbindPattern (pat, fn) | Unbind a function from every signal whose name match the pattern. |
| SignalRegistry:clear (name) | Remove every bound function to a signal name. |
| SignalRegistry:clearPattern (pat) | Remove every bound function to every signal whose name match the pattern. |
| SignalRegistry:emit (name, ...) | Emit a signal, i.e. |
| SignalRegistry:emitPattern (pat, ...) | Emit to every signal whose name match the pattern. |
| SignalRegistry:chain (registry) | Chain another regsitry to this registry. |
| SignalRegistry:unchain (registry) | Unchain a specific registry from the registry chaining list. |
SignalGroup objects
| SignalGroup.paused | Indicate if the signal group if currently paused or not. |
| SignalGroup.binds | List of triplets in the group. |
| SignalGroup:bind (registry, name, fn) | Bind a function to a signal name in the given registry. |
| SignalGroup:clear () | Remove every bound triplet in the group. |
| SignalGroup:pause () | Pause the group. |
| SignalGroup:resume () | Resume the group. |
Module
- new ()
-
Creates and return a new SignalRegistry.
Returns:
- group ()
-
Creates and return a new SignalGroup.
Returns:
- event
-
SignalRegistry which will be used to bind signals that need to be called on LÖVE events; other ubiquitousse modules may bind to this registry
if avaible.
For example, every ubiquitousse module with a “update” function will bind it to the “update” signal in the registry; you can then call this signal on each game update to update every ubiquitousse module easily.
You will need to call registerEvents for the signal to be called on LÖVE callbacks automatically (otherwise you will have to emit the events from the LÖVE callbacks manually).
List of signals available: “displayrotated”, “draw”, “load”, “lowmemory”, “quit”, “update”, “directorydropped”, “filedropped”, “focus”, “mousefocus”, “resize”, “visible”, “keypressed”, “keyreleased”, “textedited”, “textinput”, “mousemoved”, “mousepressed”, “mousereleased”, “wheelmoved”, “gamepadaxis”, “gamepadpressed”, “gamepadreleased”, “joystickadded”, “joystickaxis”, “joystickhat”, “joystickpressed”, “joystickreleased”, “joystickremoved”, “touchmoved”, “touchpressed”, “touchreleased”.
Type:
SignalRegistry - registerEvents ()
-
Call this function to hook signal.event signals to LÖVE events.
This means overriding every existing LÖVE callback. If a callback is already defined, the new one will call the old function along with the signal:emit.
Requires:
-
love
SignalRegistry objects
A SignalRegistry is a separate ubiquitousse.signal instance: its signals will be independant from other registries.
- SignalRegistry.signals
-
Map of signals to list of listeners.
Type:
{["name"]={fn,[fn]=1,...}} - SignalRegistry.chained
-
List of registries chained to this registry.
Type:
{registry, ... } - SignalRegistry:bind (name, fn)
-
Bind a function to a signal name.
Parameters:
- name string the name of the signal
- fn function the function to bind to the signal
- SignalRegistry:has (name, fn)
-
Returns true if fn is bound to the signal.
Parameters:
- name string the name of the signal
- fn function the function
- SignalRegistry:unbind (name, fn)
-
Unbind a function from a signal name.
Parameters:
- name string the name of the signal
- fn function the function to unbind to the signal
- SignalRegistry:unbindPattern (pat, fn)
-
Unbind a function from every signal whose name match the pattern.
Parameters:
- pat string Lua pattern string
- fn function the function to unbind to the signals
- SignalRegistry:clear (name)
-
Remove every bound function to a signal name.
Parameters:
- name string the name of the signal
- SignalRegistry:clearPattern (pat)
-
Remove every bound function to every signal whose name match the pattern.
Parameters:
- pat string Lua string pattern
- SignalRegistry:emit (name, ...)
-
Emit a signal, i.e. call every function bound to it, with the given arguments.
Parameters:
- name string the name of the signal
- ... arguments to pass to the functions bound to this signal
- SignalRegistry:emitPattern (pat, ...)
-
Emit to every signal whose name match the pattern.
Parameters:
- pat string Lua pattern string
- ... arguments to pass to the functions bound to each signal
- SignalRegistry:chain (registry)
-
Chain another regsitry to this registry.
I.e., after an event is emitted in this registry it will be automatically emitted in the other registry.
Several registries can be chained to a single registry.
Parameters:
- registry SignalRegistry
- SignalRegistry:unchain (registry)
-
Unchain a specific registry from the registry chaining list.
Will error if the regsitry is not in the chaining list.
Parameters:
- registry SignalRegistry
SignalGroup objects
A SignalGroup is a list of (registry, signal name, function) triplets. When the group is active, all of these triplets will bind the specified signal name to the specified function in the specified registry. When the group is paused, all of these triplets are unbound.
This can be used to maintain a list of signal bindings where every one should be either disabled or enabled at the same time. For example you may maintain a signal group of signals you want to be emitted when your game is running, and disabled when the game is paused (like inputs, update, simulation step, etc. signals).
- SignalGroup.paused
-
Indicate if the signal group if currently paused or not.
Type:
boolean - SignalGroup.binds
-
List of triplets in the group.
Type:
{{registry, "signal name", function}, ... } - SignalGroup:bind (registry, name, fn)
-
Bind a function to a signal name in the given registry.
This handles binding the function on its own; you do not need to call SignalRegistry:bind manually.
If the group is paused, this will not bind the function immediately but only on the next time this group is resumed (as expected).
Parameters:
- registry SignalRegistry to bind the signal in
- name string the name of the signal
- fn function the function to bind to the signal
- SignalGroup:clear ()
- Remove every bound triplet in the group.
- SignalGroup:pause ()
- Pause the group. The signals bound to this group will be disabled in their given registries.
- SignalGroup:resume ()
- Resume the group. The signals bound to this group will be enabled in their given registries.