Skip to main content
Version: 2.1

screen

A screen is a logical display area with tags, clients, and wibars. Enabling an output creates its screen. Disabling it removes that screen.

Deviations from AwesomeWM​

SomeWM adds output scaling and an output link. DPI properties come from AwesomeWM’s awful.screen API.

APISomeWM behaviorWhy
screen.scale somewm-onlyRead/write fractional scale (0.1–10.0).Sets the Wayland output scale.
screen.output somewm-onlyAssociated output object.Configure the connector independently of the screen’s lifetime.
property::scale signal somewm-onlyFires when an output scale changes.Driven by user or somewm-client screen scale.

Accessing Screens​

-- Primary screen
local s = screen.primary

-- Currently focused screen
local s = awful.screen.focused()

-- Iterate all screens
for s in screen do
print(s.index, s.geometry.width)
end

-- Get screen by index (1-based)
local s = screen[1]

-- Total screen count
local count = screen.count()

Properties​

Lifetime​

screen.valid is false after removal. On an invalid screen, every other property access raises invalid object, and screen[s] returns nil. Check valid before using a retained screen reference.

Geometry & Layout​

PropertyTypeAccessDescription
geometrytablereadScreen bounds {x, y, width, height} in logical pixels
workareatablereadUsable area after panels/struts {x, y, width, height}
indexnumberread1-based screen index
paddingtableread/writeManual padding {top, right, bottom, left}
inspector somewm-onlybooleanread/writeOpen or close the live tree inspector

somewm.inspector​

require("somewm.inspector") controls the inspector and its shared theme.

FunctionBehaviour
toggle(s)Toggle s.inspector and return its new value. Defaults to awful.screen.focused()
restyle()Re-read inspector theme variables for open panels. Opening a panel also applies them

Output Information​

PropertyTypeAccessDescription
outputstablereadPhysical output info (see below)
output somewm-onlyoutput/nilreadAssociated output object
content somewm-onlyimagereadCaptured screen content, used by awful.screenshot
namestringread/writeUser-assignable screen name

In 2.1, outputs is an array, unlike AwesomeWM’s name-keyed table:

-- Example outputs table
local outputs = {
[1] = {
name = "DP-1",
mm_width = 600, -- Physical width in millimeters
mm_height = 340, -- Physical height in millimeters
viewport_id = 1,
}
}

Scaling & DPI​

PropertyTypeAccessDescription
scale somewm-onlynumberread/writeOutput scale factor (0.1 to 10.0)
dpinumberread/writeDPI used by Lua widgets. Can be overridden independently of output scale
minimum_dpinumberreadLowest DPI across outputs
maximum_dpinumberreadHighest DPI across outputs
preferred_dpinumberreadRecommended DPI for this screen
-- Get current scale
print(screen.primary.scale) -- e.g., 1.5

-- Set fractional scale for HiDPI display
screen.primary.scale = 1.5

-- Check DPI
print(screen.primary.dpi) -- e.g., 144

When you change scale, the geometry and workarea update to reflect logical pixel dimensions. For example, a 3840x2160 display at scale 2.0 reports geometry of 1920x1080.

Tags & Clients​

PropertyTypeAccessDescription
tagstablereadAll tags on this screen
selected_tagstablereadCurrently visible tags
selected_tagtagreadFirst selected tag (or nil)
clientstablereadAll clients on this screen
tiled_clientstablereadVisible clients excluding floating, fullscreen, and maximized clients

Methods​

Screen Management​

-- Get total screen count
local count = screen.count()

-- Get the workarea
local geo = s:get_bounding_geometry({
honor_workarea = true,
})

-- Swap two screen indices, if a second screen exists
if screen[2] then screen[1]:swap(screen[2]) end

In 2.1, s:get_bounding_geometry() honours honor_workarea but ignores honor_padding and margins. It also ignores tag, parent, and bounding_rect, unlike the upstream Lua helper.

Virtual Screens​

screen.fake_add() creates a Lua screen object and emits added, but it does not create a monitor-backed layout area in 2.1. Clients moved there are hidden and wibars cannot attach to it. It cannot split a monitor into working virtual screens.

MethodResult
screen.fake_add(x, y, width, height)Create and return a screen object
s:fake_resize(x, y, width, height)Change its geometry
s:fake_remove()Remove it

These methods create no output or monitor. Use a nested compositor to test code that creates fake screens.

Signals​

SignalArgumentsDescription
addedsNew screen connected
removedsScreen disconnected
list(none)Screen list changed
primary_changedsPrimary screen changed
property::geometrys, old_geometryScreen geometry changed
property::workareas, old_workareaWorkarea changed (panel added/removed)
property::scalesOutput scale changed somewm-only
property::outputssOutput metadata changed
property::indexsScreen index changed
property::inspectorsInspector visibility changed

Compositor-generated geometry and scale notifications are queued. Clay updates the workarea after layout and queues property::workarea. See signal dispatch.

Example: React to Scale Changes​

screen.connect_signal("property::scale", function(s)
print("Screen " .. s.index .. " scale is now " .. s.scale)
end)

Example: Handle Monitor Hotplug​

Use multi-monitor configuration to create tags and bars in request::desktop_decoration. Adding a second tag-creation handler to the default config creates duplicate tags.

Common Patterns​

Auto-Scale Based on Resolution​

screen.geometry is already scaled. For automatic scaling, use output modes or connector names as described in fractional scaling.

Get Screen Under Mouse​

local s = mouse.screen

Find Screen by Output Name​

local o = output.get_by_name("HDMI-A-1")
local s = o and o.screen

See Also​