# `Drafter.Event.Manager`
[🔗](https://github.com/jaman/drafter/blob/main/lib/drafter/event/manager.ex#L1)

Fans events out from the terminal driver to the processes that want them.

One manager exists per session. Producers cast events to it; it delivers each one
to every subscriber whose filter accepts it, as the message
`{:tui_event, event}`. The event shapes are the ones listed in `Drafter.Event`.

    Drafter.Event.Manager.subscribe(self(), &Drafter.Event.key_event?/1)
    receive do
      {:tui_event, {:key, key}} -> key
    end

A subscriber is monitored and dropped when it exits, so unsubscribing on shutdown
is not required. Subscribing the same pid twice replaces its filter.

The `:app_pid` given at start receives every deliverable event regardless of the
subscriber list.

`{:bracketed_paste, _}` is withheld unless `Drafter.Clipboard.paste_enabled?/0`
returns true; every other event is always deliverable.

Functions without an explicit manager argument resolve it through
`Drafter.Session.Context` under the `:event_manager` key, so they address the
caller's own session.

# `event_filter`

```elixir
@type event_filter() :: (Drafter.Event.t() -> boolean()) | :all
```

# `subscriber`

```elixir
@type subscriber() :: pid()
```

# `subscription`

```elixir
@type subscription() :: {subscriber(), event_filter()}
```

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `drain_queue`

```elixir
@spec drain_queue() :: :ok
```

Always returns `:ok` immediately. Retained for callers in the runtime loop.

# `send_event`

```elixir
@spec send_event(Drafter.Event.t()) :: :ok
```

Deliver `event` to this session's subscribers.

Asynchronous; use `sync/0` to wait for delivery.

# `send_events`

```elixir
@spec send_events([Drafter.Event.t()]) :: :ok
```

Deliver each of `events` in order to this session's subscribers.

Asynchronous; use `sync/0` to wait for delivery.

# `start_link`

```elixir
@spec start_link(keyword()) :: GenServer.on_start()
```

Start a manager.

Options:

  * `:name` — registered name, default `Drafter.Event.Manager`. Pass `nil` to
    start it unregistered, which is what a session other than the local terminal
    does.
  * `:app_pid` — a process that receives every deliverable event without
    subscribing.

# `subscribe`

```elixir
@spec subscribe(pid(), event_filter()) :: :ok
```

Subscribe `subscriber_pid` to this session's manager.

Defaults to the calling process and to the `:all` filter. See `subscribe_to/3`
for the filter contract.

# `subscribe_to`

```elixir
@spec subscribe_to(pid() | atom(), pid(), event_filter()) :: :ok
```

Subscribe `subscriber_pid` to `manager`, for a manager that is not registered
under this module's name.

`filter` is `:all` (the default) or a one-argument function returning `true` for
the events to deliver. A filter that raises is treated as no match. The
subscriber is monitored; a second subscription for the same pid replaces its
filter.

# `sync`

```elixir
@spec sync() :: :ok
```

Returns once every event cast before this call has been dispatched.

A synchronous round trip through the manager, so it orders after earlier casts
from the same caller. Call it before observing a subscriber's state to be sure
the events sent to it have been delivered.

# `sync`

```elixir
@spec sync(pid() | atom()) :: :ok
```

As `sync/0`, for a manager that is not globally registered.

# `unsubscribe`

```elixir
@spec unsubscribe(pid()) :: :ok
```

Stop delivering events to `subscriber_pid`, defaulting to the calling process.

Unnecessary when the subscriber is exiting; the monitor removes it.

---

*Consult [api-reference.md](api-reference.md) for complete listing*