This page documents the
signal module, which is responsible for event handling in Dolmen.
Dolmen provides an event handling mechanism known as signal/slot. A signal corresponds to a unique identifier which can be triggered when an event occurs, for instance when a button is clicked. A signal can be associated with any number of functions called slots, which may or may not return a value. Whenever a signal is emitted, all the slots which are connected to it are executed (in an unspecified order).
This mechanism is used throughout Dolmen, as it provides hooks which plugins can use to react to events triggered by the program. For example, a signal is emitted whenever a file is loaded, which can be used to add custom metadata to each file, among other things.
Application Programming Interface
Create and return a new signal identifier (id). Each id is guaranteed to be unique, such that two different calls to
new will never yield the same id.
If you need to store an id for subsequent use, store it in a (preferably local) variable.
local my_event = signal.new() -- Do something with my_event...
id to function
slot. The slot can take any number of arguments, and can return a value.
local e = signal.new() local f = function(name) print("Hold the door, " .. name) end signal.connect(e, f) -- Print "Hold the door, Hodor" to the standard output signal.emit(e, "Hodor")
id from function
slot are not connected, this function does nothing.
local e = signal.new() local f = function(name) print("Hold the door, " .. name) end signal.connect(evt, f) -- Print "Hold the door, Hodor" to the standard output signal.emit(e, "Hodor") signal.disconnect(e, f) -- Do nothing since e and f are no longer connected signal.emit(e, "Hodor")
id, followed by any number of arguments. The arguments are forwarded to all the slots which are connected to this signal (if any).
Following Lua's function call conventions, if the slot receives less arguments than it expects, missing arguments have the value
nil; if it receives more arguments than expected, additional arguments are ignored.
This function collects all the return values from the slots it called into a table, which it returns to the caller. (Keep in mind that if a slot doesn't explicitly return a value, its
return value is
local e = signal.new() local f1 = function(arg1) print("f1 received a " .. type(arg1)) end local f2 = function(arg1, arg2) print("f2 received a " .. type(arg1) " and a " .. type(arg2)) end signal.connect(e, f1) signal.connect(e, f2) -- Print "f1 received a number" and "f2 received a number and a string" signal.emit(e, 3.14, "pi")
Note: the order in which slots are called is unspecified. In general, it will correspond to the order in which they were registered, but this should not be relied upon.