Skip to content

Lua Conventions

This page defines the terms used across the EasyBar Lua docs.

Widget

A widget is one Lua file loaded by EasyBar from your widgets directory.

That file can create one node or many nodes. It can also keep local state, run commands, subscribe to events, and update its own nodes over time.

Node

A node is one renderable unit in the EasyBar runtime.

Examples:

  • an item
  • a group
  • a row
  • a column
  • a popup
  • a slider

Node kinds are listed in Node Kinds.

Handle

A handle is the object returned by easybar.add(...).

You keep the handle in a local variable and call methods on it later:

  • node:set(...)
  • node:get()
  • node:remove()
  • node:subscribe(...)

See Functions.

Built-in

A built-in is a native widget configured in config.toml under [builtins.*].

Built-ins are not Lua widgets, even when they resemble the same kind of visual element.

See Built-ins Vs Lua.

Group

A group is a node kind used to give multiple child nodes one shared container.

Use it when several items should share:

  • one background
  • one border
  • one padding box
  • one popup owner
  • one overall layout block

See Grouping.

A popup is extra content attached to a parent node.

Popup child nodes target a position of popup.<parent-id>. The parent node controls whether the popup is visible through popup.drawing.

See Popups.

Event

An event is a runtime signal that can trigger widget logic.

Examples:

  • app switch
  • space change
  • volume change
  • mouse enter
  • mouse click
  • slider preview

Events are exposed through easybar.events.*. Event names and payloads are documented in Events.

Agent

An agent is a helper process used for permission-sensitive or platform-specific data collection, such as calendar or network state.

Agents are configured in config.toml and feed data back into EasyBar events and native widgets.

See Agents and Internals / Agents.

Runtime

The runtime is the host machinery that loads widget files, creates nodes, dispatches events, and applies updates between the Lua side and the native app.

See Runtime Control and Lua Runtime Overview.

Mental model

The shortest accurate mental model is:

  1. a widget file creates nodes
  2. EasyBar returns handles
  3. your code stores those handles
  4. events and timers trigger updates
  5. set(...) mutates current node state

If you are just getting started, continue with First Widget.