niri

Documentation

Overview

Package niri talks to a running niri compositor over its JSON IPC socket ($NIRI_SOCKET). Unlike River and other wlroots compositors, niri exposes no Wayland status protocol — workspace and window state arrives as a stream of newline-delimited JSON events on a unix socket, and actions (e.g. switching workspace) are one-shot JSON requests.

A single process-wide reader goroutine maintains the shared state and wakes every subscribed bar module on change, mirroring the shared-subscription idiom used by the River title module. Modules read state through the accessors here; they never touch the socket directly.

Index

• func Available() bool
• func FocusWorkspace(id uint64) error
• func FocusedTitleOn(output string) string
• func Subscribe(fn func()) (unsubscribe func())
• type Workspace
  • func WorkspacesFor(output string) []Workspace
  • func (w Workspace) Label() string
  • func (w Workspace) Occupied() bool

Functions

func Available

func Available() bool

Available reports whether a niri IPC socket is configured. False when not running under niri (or niri started without exposing $NIRI_SOCKET).

func FocusWorkspace

func FocusWorkspace(id uint64) error

FocusWorkspace issues a focus-workspace action targeting the workspace with the given global id.

func FocusedTitleOn

func FocusedTitleOn(output string) string

FocusedTitleOn returns the focused window's title if that window lives on the given output connector, else "". niri has a single global focus, so at most one output shows a title at a time.

func Subscribe

func Subscribe(fn func()) (unsubscribe func())

Subscribe registers fn to be invoked on every state change and ensures the event-stream reader is running. It returns an unsubscribe func. When niri is unavailable the reader is not started and fn never fires.

Types

type Workspace

type Workspace struct {
	ID             uint64  `json:"id"`
	Idx            int     `json:"idx"`
	Name           *string `json:"name"`
	Output         string  `json:"output"` // connector name, e.g. "DP-2"
	IsUrgent       bool    `json:"is_urgent"`
	IsActive       bool    `json:"is_active"`  // active workspace on its output
	IsFocused      bool    `json:"is_focused"` // the single globally-focused workspace
	ActiveWindowID *uint64 `json:"active_window_id"`
}

Workspace mirrors a niri IPC workspace object. niri workspaces are dynamic: they appear and disappear, are numbered per-output by Idx (1-based), and may carry an optional Name.

func WorkspacesFor

func WorkspacesFor(output string) []Workspace

WorkspacesFor returns the workspaces on the given output connector, sorted by per-output index. Caller must not mutate the result.

func (Workspace) Label

func (w Workspace) Label() string

Label returns the user-visible workspace label: its Name when set, else its per-output index.

func (Workspace) Occupied

func (w Workspace) Occupied() bool

Occupied reports whether the workspace holds at least one window.