Skip to main content
Version: 2.2 (dev)

awful.screenshot

Screenshot capture with support for full screen, screen, client, geometry, and interactive region selection.

Upstream documentation: awful.screenshot

Usage​

local awful = require("awful")

-- Full screen screenshot
local s = awful.screenshot()
s:refresh()
s:save()

-- Interactive region selection
local s = awful.screenshot({ interactive = true })
s:refresh()
-- User draws a rectangle, screenshot auto-saves on release

Constructor​

local s = awful.screenshot({ screen = screen.primary })
ArgumentTypeDefaultDescription
interactivebooleanfalseEnable mouse-driven region selection
screenscreennilCapture a specific screen
clientclientnilCapture client content without compositor titlebars or borders
geometrytablenilCapture a specific {x, y, width, height} region
directorystring$HOMESave directory
prefixstring"Screenshot-"Filename prefix
file_pathstringautoOverride full file path
file_namestringautoOverride filename (within directory)
date_formatstring"%Y%m%d%H%M%S"Date format for auto-generated filenames
cursorstring"crosshair"Cursor shape during interactive mode
frame_colorcolor"#ff0000"Selection rectangle color
frame_shapeshaperectangleSelection rectangle shape
auto_save_delayintegernilDelay before automatic capture. Leave unset for manual capture, or use 0 to capture immediately
auto_save_tick_durationnumber1.0Seconds between timer::tick signals
minimum_sizetable/integer{width=3, height=3}Minimum selection size (rejects smaller)
accept_buttonstable{awful.button({}, 1)}Mouse buttons to confirm selection
reject_buttonstable{awful.button({}, 3)}Mouse buttons to cancel selection
accept_keystable{awful.key({}, "Return")}Keys to accept selection
reject_keystable{awful.key({}, "Escape")}Keys to cancel selection

Use one of screen, client, or geometry. With none set, capture uses root.content() for the entire desktop. A nil client, including an absent client.focus, therefore captures the desktop. Coordinates are logical pixels.

Methods​

refresh()​

Captures the screenshot. In interactive mode, this also starts the snipping overlay.

local surfaces = s:refresh()

Returns a table of {method = surface} pairs.

save(file_path)​

Writes a PNG. The directory must already exist. In 2.1, save() does not check Cairo’s write status, so neither its return nor file::saved proves that the file exists.

s:save()                    -- Use default path
s:save("/tmp/shot.png") -- Override path

In interactive mode, save() is called automatically after accept().

accept()​

Confirms the interactive selection and saves the screenshot. Called automatically when the user releases the accept button.

local accepted = s:accept()

Returns false if the selection is below minimum_size or empty. Outside interactive mode it returns true without saving.

reject(reason)​

Cancels the interactive selection without saving.

s:reject()               -- Manual cancel
s:reject("mouse_button") -- With reason

Properties​

Read-only​

PropertyTypeDescription
surfaceimageThe captured screenshot surface
surfacestableAll captured surfaces keyed by method
selected_geometrytableCurrent selection {x, y, width, height, surface, method}
content_widgetwibox.widget.imageboxThe screenshot as an imagebox widget
keygrabberawful.keygrabberThe keygrabber used in interactive mode

Read-write​

PropertyTypeDescription
directorystringSave directory
prefixstringFilename prefix
file_pathstringFull file path
file_namestringFilename within directory
date_formatstringDate format suffix
cursorstringInteractive cursor shape
interactivebooleanInteractive mode toggle
frame_colorcolorSelection rectangle color
frame_shapeshapeSelection rectangle shape
minimum_sizetable/integerMinimum selection dimensions
auto_save_delayintegerDelay before capture. Setting nil raises an error in 2.1
auto_save_tick_durationnumberSeconds between timer ticks, set before starting the delay
accept_buttonstableConfirm buttons
reject_buttonstableCancel buttons
accept_keys, reject_keystableAccept and cancel key bindings

Signals​

SignalArgumentsDescription
snipping::startselfInteractive overlay is shown
snipping::successselfSelection accepted, immediately before save()
snipping::cancelledself, reasonSelection cancelled (reason: "mouse_button", "key", "no_selection", "too_small", or "reject_called")
file::savedself, file_path, methodPNG write attempted. The Cairo status is not checked
timer::startedselfAuto-save delay timer started
timer::tickself, remainingTimer tick (seconds remaining)
timer::timeoutselfTimer expired, capture starting

Writable properties emit property::<name> with the new value. Interactive selection also emits property::selected_geometry.

Theme Variables​

VariableDefaultDescription
beautiful.screenshot_frame_color"#ff0000"Default selection rectangle color
beautiful.screenshot_frame_shapegears.shape.rectangleDefault selection shape

Interactive Mode Internals​

refresh() captures the image, shows an overlay, and starts mouse and keyboard grabbers. Releasing the accept button or pressing Return crops and saves the selection. Escape or the reject button cancels it.

The overlay displays a saved capture while Clay positions the selection rectangle. See capture behaviour for logical coordinates and output scaling.

Examples​

Programmatic Screenshot​

-- Screenshot of a specific screen
local s = awful.screenshot({ screen = screen.primary })
s:refresh()
s:save("/tmp/screen.png")

Client Screenshot​

-- Screenshot of the focused client
local c = assert(client.focus, "No focused client")
local s = awful.screenshot({ client = c })
s:refresh()
s:save("/tmp/window.png")

Geometry Screenshot​

-- Screenshot of a specific region
local s = awful.screenshot({ geometry = { x = 100, y = 100, width = 500, height = 300 } })
s:refresh()
s:save("/tmp/region.png")

Widget Integration​

-- Display screenshot in a wibox
local s = awful.screenshot({ screen = screen.primary })
s:refresh()

local popup = awful.popup {
widget = s.content_widget,
placement = awful.placement.centered,
visible = true,
}

See Also​