Guppy.Window behaviour (guppy v0.2.0)

Copy Markdown View Source

Minimal LiveView-style per-window process abstraction for Guppy.

Modules that use Guppy.Window own one native window per process. Guppy opens the window with the module's initial IR, routes native events back into the process, and rerenders automatically after window state changes.

The window struct is the primary state carrier, similar to a socket-like view state.

Required callbacks:

Optional callbacks:

Modules may also define handle_info(message, window) without marking it as a Guppy.Window callback; Guppy routes ordinary process messages there by convention.

Missing optional handlers and unmatched handler clauses are treated as no-op handlers that skip rerendering. use Guppy.Window also defines child_spec/1, so window modules can be supervised directly.

Summary

Types

callback_result()
t()

Callbacks

handle_event(t, map, t)
mount(term, t)
render(t)

Functions

assign(window, attrs)

Puts many assigns on the window from a map or keyword list.

assign(window, key, value)

Puts one assign on the window.

focus(server, timeout \\ 5000)

Asks a running window process to activate/focus its native window.

handle_window_message(module, message, state)
init_window(module, arg, opts \\ [])
put_private(window, key, value)

Puts framework-private state on the window; not for app data.

put_window_opts(window, opts)

Merges native window options applied when the window opens; see the "Window options" section of the README for the supported keys.

reopen_retry_delay_ms(attempt)

Returns the reopen retry delay for a failed-reopen attempt count.

state(server)

Returns the Guppy.Window struct of a running window process.

update(window, key, fun)

Updates one assign with a function of its current value.

view_id(server)

Returns the native view id of a running window process.

Types

callback_result()

@type callback_result() ::
  {:noreply, t()} | {:noreply, t(), :skip_render} | {:stop, term(), t()}

t()

@type t() :: %Guppy.Window{
  assigns: map(),
  private: map(),
  view_id: pos_integer() | nil
}

Callbacks

handle_event(t, map, t)

(optional) 
@callback handle_event(String.t(), map(), t()) :: callback_result()

mount(term, t)

@callback mount(term(), t()) :: {:ok, t()} | {:stop, term()}

render(t)

@callback render(t()) :: term()

Functions

assign(window, attrs)

Puts many assigns on the window from a map or keyword list.

assign(window, key, value)

Puts one assign on the window.

focus(server, timeout \\ 5000)

Asks a running window process to activate/focus its native window.

handle_window_message(module, message, state)

init_window(module, arg, opts \\ [])

put_private(window, key, value)

Puts framework-private state on the window; not for app data.

put_window_opts(window, opts)

Merges native window options applied when the window opens; see the "Window options" section of the README for the supported keys.

reopen_retry_delay_ms(attempt)

Returns the reopen retry delay for a failed-reopen attempt count.

Delays double from 50ms and cap at 5000ms so a persistently failing runtime is not hammered with reopen attempts.

state(server)

Returns the Guppy.Window struct of a running window process.

Reads the process state via :sys.get_state/1, so it is intended for tests and debugging rather than hot paths.

update(window, key, fun)

Updates one assign with a function of its current value.

view_id(server)

Returns the native view id of a running window process.

Reads the process state via :sys.get_state/1, so it is intended for tests and debugging rather than hot paths.