Brodgar client

hafen.event: The Bus and the Message Streams

Subscribe to something the client does instead of polling for it. A client-wide fact is on the bus. A message stream any widget can produce is for when there is no widget or control to hold.

local subscription = hafen.event():on("GobAdded", function(gob)
  hafen.log():write("appeared: " .. (gob:name() or "?"))
end)
subscription:off()

Method	Returns	Permission	Description
`hafen.event():on(key, fn)`	`Sub`	Unprotected	Run `fn(...)` each time `key` fires.
`subscription:key()`	`string`	Unprotected	What this subscription was registered under: the event key, the message name, the command name.
`subscription:off()`	the `Sub`	Unprotected	Unsubscribe. Idempotent, and done for you on reload or disable.

Rule	Detail
Every `:on` in the API hands back a `Sub`	The bus and the message streams. A widget or a mouse grab. A console command. A hotkey. A connection or a voice link. Waiting for a widget. A `Sub` answers `:key()` and `:off()` and nothing else. Another name raises at the line that wrote it.
Subscribe once	In the file body or in `Load`. The subscription is owned by your addon and released when it reloads or is disabled.
Fired from the change	Nothing on this bus is polled: every event fires from the change itself, not from a scan of what differs since the last frame.
Several handlers	Two handlers on one key both fire, in registration order. `off()` on one leaves the other. A handler that errors is logged and breaks neither your other handlers nor the client. One that fails the client itself (stack, memory) stops your addon.
The bus keys are a closed set	A name not in the catalogue throws at the line that wrote it: `hafen.event():on("GobAdded ", fn)` raises `unknown event 'GobAdded ' — see the catalogue`.
The streams are open	A message name is protocol the server can introduce, so the message streams accept any key, and `*` is the whole stream.
What reaches the server	Intercepting an outbound action: `event:resend()` and `event:send(table)` need the `widget.send` permission, the key `widget:send` needs. Subscribing and cancelling are unprotected.

Read what you are listening to

Method	Returns	Permission	Description
`hafen.event():count(filter)`	`number`	Unprotected	How many of your subscriptions are live here.
`hafen.event():list(filter)`	`Sub[]`	Unprotected	Those subscriptions.

hafen.log():write("listening on " .. hafen.event():count() .. " keys")
for _, subscription in ipairs(hafen.event():list(function(candidate) return candidate:key() == "GobAdded" end)) do
  subscription:off()
end

Rule	Detail
Scope	The bus and the two message streams, in that order, over your addon’s subscriptions alone. A string `filter` is a substring match on `subscription:key()`. A function filter is called with each `Sub`.
Identity	The members are the `Sub`s `:on` handed you, so `==` finds the one you hold. An ended one is gone from the next read.
Not here	A subscription on a widget or a mouse grab belongs to that widget and dies with it.

Pages

Page	Covers
The catalogue	Every key `:on` accepts: your addon’s own life, the sessions under it, the world, the character, the rosters, your own entities.
The message streams	`hafen.event():action()` and `hafen.event():message()`: a message leaving for the server, and an update arriving from it.

Brodgar client

hafen.event: The Bus and the Message Streams

Subscribe

Read what you are listening to

Pages

See Also