TermUI.Focus (TermUI v0.2.0)

View Source

Focus event utilities for terminal window focus tracking.

Provides escape sequences and utilities for detecting when the terminal window gains or loses system focus. This enables optimization opportunities like pausing animations when backgrounded.

Usage

# Enable focus reporting
IO.write(Focus.enable())

# Check if focus reporting is supported
if Focus.supported?() do
  IO.write(Focus.enable())
end

# Disable focus reporting
IO.write(Focus.disable())

Summary

Functions

disable()

Returns escape sequence to disable focus reporting.

enable()

Returns escape sequence to enable focus reporting.

gained_sequence()

Returns the focus gained sequence.

lost_sequence()

Returns the focus lost sequence.

parse(arg1)

Parses input to detect focus events.

supported?()

Checks if focus reporting is likely supported.

Functions

disable()

@spec disable() :: String.t()

Returns escape sequence to disable focus reporting.

enable()

@spec enable() :: String.t()

Returns escape sequence to enable focus reporting.

gained_sequence()

@spec gained_sequence() :: String.t()

Returns the focus gained sequence.

lost_sequence()

@spec lost_sequence() :: String.t()

Returns the focus lost sequence.

parse(arg1)

@spec parse(String.t()) :: {:focus, :gained | :lost} | nil

Parses input to detect focus events.

Returns {:focus, :gained}, {:focus, :lost}, or nil if not a focus event.

supported?()

@spec supported?() :: boolean()

Checks if focus reporting is likely supported.

This is a heuristic check based on terminal type. Many modern terminals support focus reporting but don't advertise it.

Known supporting terminals:

  • xterm (with allowWindowOps)
  • iTerm2
  • Alacritty
  • Kitty
  • WezTerm
  • foot
  • GNOME Terminal
  • Windows Terminal