Skip to main content
Version: 2.2 (dev)

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() splits an output into independent screens. Each virtual screen gets its own bars, tags, layouts and workarea, and clients tile inside it. Use it to carve one wide monitor into columns.

MethodResult
screen.fake_add(x, y, width, height)Create and return a screen covering that rectangle
s:fake_resize(x, y, width, height)Change a screen's geometry, real or virtual
s:fake_remove()Remove a virtual screen. Its clients move to the screen under their center
-- Split screen 1 into three equal columns
local s = screen[1]
local g = s.geometry
local third = math.floor(g.width / 3)
s:fake_resize(g.x, g.y, third, g.height)
screen.fake_add(g.x + third, g.y, third, g.height)
screen.fake_add(g.x + 2 * third, g.y, g.width - 2 * third, g.height)

Coordinates are in output space. fake_add emits added and list immediately, so an awful.screen.connect_for_each_screen handler runs for the new screen and builds its bar.

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​