Skip to main content
Version: 2.1

The Object Model

Outputs describe connected displays. Screens hold tags and panels. Tags select which application windows are visible, and widgets provide the content of panels, popups and titlebars.

The Core Objects​

Output somewm-only​

An output represents a display connector such as HDMI-A-1 or eDP-1. It exposes hardware information and display settings, including mode, position, scale and enabled state.

Disabling an output removes its screen but keeps the output object. Re-enabling it creates a screen again. Disconnecting the display invalidates the output object.

for o in output do
print(o.name, o.make, o.enabled)
end

Use output.get_by_name("HDMI-A-1") to find a connector. o.screen is its active screen, or nil when disabled.

Screen​

A screen represents an active display area, including a virtual output in a nested session. s.geometry gives its logical position and size. s.workarea excludes reserved panel space.

s.tags lists its tags, and s.selected_tags lists those currently shown. screen.primary identifies the primary screen. awful.screen.focused() selects a screen using the focus policy.

Tag​

A tag is a label assigned to clients on a screen. A client can have several tags, and a screen can display several selected tags at once. Each tag belongs to one screen.

t:view_only() selects one tag. awful.tag.viewtoggle(t) toggles its selection without clearing the others. Layout settings such as master_width_factor belong to tags.

Client​

A client represents a managed application window. It has a screen, tag membership and properties such as name, class, floating, minimized and fullscreen.

Client content is the application-drawn part of the window, including application-drawn decorations but excluding SomeWM titlebars and borders. The content area is the rectangle allocated to it. The client frame includes the content, SomeWM titlebars and border.

SomeWM presents Wayland client content through a surface tree, the main surface and its subsurfaces. A buffer supplies pixel data to a surface. A surface or buffer is not the whole client frame.

c:geometry() includes SomeWM titlebar space and excludes the border. It is not the content area.

client.get() lists managed clients. client.focus is the client selected for keyboard focus, or nil. Layer-shell panels and launchers are separate surfaces, not clients.

local c = client.focus
if c then
print(c.name, c.screen.index)
for _, t in ipairs(c:tags()) do
print(t.name)
end
end

Client layout order, visual stacking and focus history are separate.

Wibox and Wibar​

A wibox is a compositor-owned window containing a widget. An awful.wibar attaches a wibox to a screen edge and normally reserves space in the workarea. An awful.popup sizes and positions a wibox around its content.

Widget​

Custom widgets can compose built-in widgets, supply a Clay description, or display an image surface. Widgets describe content and sizing rules. Clay computes layout, and SomeWM renders the result. See Widgets in SomeWM 2.1 for the supported approaches.

Widgets compose by nesting content inside containers and layouts:

TypePurposeExamples
ContentDisplay text, images or valuestextbox, imagebox, progressbar
ContainerWrap a childbackground, margin, constraint
LayoutArrange childrenfixed, flex, align
local wibox = require("wibox")
local greeting = wibox.widget {
{
{
text = "Hello",
widget = wibox.widget.textbox,
},
margins = 8,
widget = wibox.container.margin,
},
bg = "#333333",
widget = wibox.container.background,
}

Assign greeting to a wibox's widget property to display it. The widget tutorial covers creating and updating widgets.

The Hierarchy​

An enabled output has a screen. The screen owns tags and may have wibars. Clients belong to a screen and can share several of its tags. Wibars and other wiboxes contain widget trees.

Tags therefore do not form an exclusive parent-child tree of windows. The same client can appear in several tag lists.

Focus vs Selection​

TermMeaning
Focused clientThe client selected to receive keyboard input
Selected tagA tag whose clients are shown on its screen
Stacking orderWhich overlapping window appears in front

Selecting tags changes visibility. Focusing a client and raising it are separate operations, although activation helpers can request both.

Focus flow​

The compositor checks input handlers and keybindings before forwarding unhandled events to the focused application. Keygrabbers, session locks and layer-shell surfaces can receive input instead of a client.

Common Operations​

ActionAPI
Select one tagt:view_only()
Toggle a tag's visibilityawful.tag.viewtoggle(t)
Move a client to a tagc:move_to_tag(t)
Move a client to a screenc:move_to_screen(s)
Request that a client closec:kill()
Toggle floatingc.floating = not c.floating
Focus the next client in client orderawful.client.focus.byidx(1)
Focus the next screenawful.screen.focus_relative(1)

Accessing Objects​

Starting pointRelated objects
Globalclient.get(), client.focus, screen.primary, output.get_by_name(name)
Client cc.screen, c:tags(), c.first_tag
Screen ss.output, s.tags, s.selected_tags, s.clients
Tag tt.screen, t:clients(), t.layout

Signals: Reacting to Changes​

Objects emit signals for events such as request::manage, focus, property::name and property::selected. Handlers receive the emitting object for instance signals. Global signals have their own argument lists. See Signals.

Basics puts these objects together in a configuration.