Module: awful.screenshot

Take screenshots of clients, screens, geometry and export to files or widgets.

Common keybindings

This example setups keybinding for the "Print Screen" key. Shift means interactive, Control means delayed and Mod4 (Super) means current client only. This example also creates convinient notifications.

local function saved_screenshot(args)
    local ss = awful.screenshot(args)

    local function notify(self)
        naughty.notification {
            title     = self.file_name,
            message   = "Screenshot saved",
            icon      = self.surface,
            icon_size = 128,
        }
    end

    if args.auto_save_delay > 0 then
        ss:connect_signal("file::saved", notify)
    else
        notify(ss)
    end

    return ss
end

local function delayed_screenshot(args)
    local ss = saved_screenshot(args)
    local notif = naughty.notification {
        title   = "Screenshot in:",
        message = tostring(args.auto_save_delay) .. " seconds"
    }

    ss:connect_signal("timer::tick", function(_, remain)
        notif.message = tostring(remain) .. " seconds"
    end)

    ss:connect_signal("timer::timeout", function()
        if notif then notif:destroy() end
    end)

    return ss
end

client.connect_signal("request::default_keybindings", function()
    awful.keyboard.append_client_keybindings({
        awful.key({modkey}, "Print",
            function (c) saved_screenshot { auto_save_delay = 0, client = c } end ,
            {description = "take client screenshot", group = "client"}),
        awful.key({modkey, "Shift"}, "Print",
            function (c) saved_screenshot { auto_save_delay = 0, interactive = true, client = c } end ,
            {description = "take interactive client screenshot", group = "client"}),
        awful.key({modkey, "Control"}, "Print",
            function (c) delayed_screenshot { auto_save_delay = 5, client = c } end ,
            {description = "take screenshot in 5 seconds", group = "client"}),
        awful.key({modkey, "Shift", "Control"}, "Print",
            function (c) delayed_screenshot { auto_save_delay = 5, interactive = true, client = c } end ,
            {description = "take interactive screenshot in 5 seconds", group = "client"}),
    })
end)

awful.keyboard.append_global_keybindings({
    awful.key({}, "Print",
        function () saved_screenshot { auto_save_delay = 0 } end ,
        {description = "take screenshot", group = "client"}),
    awful.key({"Shift"}, "Print",
        function () saved_screenshot { auto_save_delay = 0, interactive = true } end ,
        {description = "take interactive screenshot", group = "client"}),
    awful.key({"Control"}, "Print",
        function () delayed_screenshot { auto_save_delay = 5 } end ,
        {description = "take screenshot in 5 seconds", group = "client"}),
    awful.key({"Shift", "Control"}, "Print",
        function () delayed_screenshot { auto_save_delay = 5, interactive = true } end ,
        {description = "take interactive screenshot in 5 seconds", group = "client"}),
})

Convert to widgets

This example creates and Alt+Tab like popup with client images. Note that it might display black rectangles if you are not using a compositing manager such as picom.

awful.popup {
    widget = awful.widget.tasklist {
        screen   = screen[1],
        filter   = awful.widget.tasklist.filter.allscreen,
        buttons  = tasklist_buttons,
        style    = {
            shape = gears.shape.rounded_rect,
            align = "center"
        },
        layout   = {
            spacing   = 5,
            row_count = 1,
            layout    = wibox.layout.grid.horizontal
        },
        widget_template = {
            {
                {
                    id            = "screenshot",
                    margins       = 4,
                    forced_height = 128,
                    forced_width  = 240,
                    widget        = wibox.container.margin,
                },
                {
                    id     = "text_role",
                    forced_height = 20,
                    forced_width  = 240,
                    widget = wibox.widget.textbox,
                },
                widget = wibox.layout.fixed.vertical
            },
            id              = "background_role",
            widget          = wibox.container.background,
            create_callback = function(self, c) --luacheck: no unused
                local ss = awful.screenshot {
                    client = c,
                }
                ss:refresh()
                local ib = ss.content_widget
                ib.valign = "center"
                ib.halign = "center"
                self:get_children_by_id("screenshot")[1].widget = ib
            end,
        },
    },
    border_color = "#777777",
    border_width = 2,
    ontop        = true,
    placement    = awful.placement.centered,
    shape        = gears.shape.rounded_rect
}

Info:

Constructors

awful.screenshot {[args]} Screenshot constructor - it is possible to call this directly, but it is.

Object properties

directory string Get screenshot directory property.
prefix string Get screenshot prefix property.
file_path string Get screenshot file path.
file_name string Get screenshot file name.
date_format string The date format used in the default suffix.
cursor string The cursor used in interactive mode.
interactive boolean Use the mouse to select an area (snipping tool).
screen screen or nil Get screenshot screen.
client client or nil Get screenshot client.
geometry table Get screenshot geometry.
surface nil or image Get screenshot surface. Read only
surfaces table Get screenshot surfaces. Read only
minimum_size nil or integer or table Set a minimum size to save a screenshot.
frame_color color or nil The interactive frame color.
frame_shape shape or nil The interactive frame shape.
reject_buttons table Define which mouse button exit the interactive snipping mode.
accept_buttons table Mouse buttons used to save the screenshot when using the interactive snipping mode.
keygrabber awful.keygrabber The awful.keygrabber object used for the accept and reject keys. Read only
selected_geometry nil or table The current interactive snipping mode seletion. Read only
auto_save_delay integer or nil Number of seconds before auto-saving (or entering the interactive snipper).
auto_save_tick_duration number Duration between the "timer::tick" signals when using auto_save_delay.
content_widget wibox.widget.imagebox Export this screenshot as an wibox.widget.imagebox instead of a file. Read only

Object methods

:awful.screenshot.refresh () -> table Take new screenshot(s) now.
:awful.screenshot.save (file_path) Save screenshot.
:awful.screenshot.accept () -> boolean Save and exit the interactive snipping mode.
:awful.screenshot.reject (reason) Exit the interactive snipping mode without saving.

Signals

snipping::start Emitted when the interactive snipping starts.
snipping::success Emitted when the interactive snipping succeed.
snipping::cancelled Emitted when the interactive snipping is cancelled.
timer::started Emitted when the auto_save_delay timer starts.
timer::tick Emitted after each elapsed second when auto_save_delay is set.
timer::timeout Emitted when the auto_save_delay timer stops.
file::saved Emitted when a the screenshot is saved.

Theme variables

beautiful.screenshot_frame_color color The screenshot interactive frame color.
beautiful.screenshot_frame_shape shape The screenshot interactive frame shape.


Constructors

🔗 awful.screenshot {[args]}
Screenshot constructor - it is possible to call this directly, but it is. recommended to use the helper constructors, such as awful.screenshot.root

Parameters:

Note: This constructors uses named parameters calling convention. It means you call it with {} and omit the parantheses. For example, calling this will all default argument would be awful.screenshot{}. This is a Lua shortcut syntax equivalent to awful.screenshot({}). args is only a placeholder name for the "lone table argument" used in named parameters calls.
Name Type(s) Description
args Optional table
directory Optional string Get screenshot directory property.
prefix Optional string Get screenshot prefix property.
file_path Optional string Get screenshot file path.
file_name Optional string Get screenshot file name.
screen Optional awful.screenshot.screen Get screenshot screen.
date_format Optional string The date format used in the default suffix.
cursor Optional string The cursor used in interactive mode.
interactive Optional boolean Rather than take a screenshot of an object, use the mouse to select an area.
client Optional awful.screenshot.client Get screenshot client.
geometry Optional table Get screenshot geometry.
frame_color Optional color The frame color.

Object properties

🔗 directory string · 1 signal
Get screenshot directory property.

Constraints:

Default value : os.getenv("HOME")

Click to display more

Emit signals:

  • property::directory When the directory value changes.
    • self awful.screenshot The object which changed (useful when connecting many object to the same callback).
    • new_value directory The new value affected to the property.
🔗 prefix string · 1 signal
Get screenshot prefix property.

Constraints:

Default value : "Screenshot-"

Click to display more

Emit signals:

  • property::prefix When the prefix value changes.
    • self awful.screenshot The object which changed (useful when connecting many object to the same callback).
    • new_value prefix The new value affected to the property.
🔗 file_path string · 1 signal
Get screenshot file path.

Constraints:

Default value : self.directory..self.prefix..os.date()..".png"

See also:

awful.screenshot.file_name

Click to display more

Emit signals:

  • property::file_path When the file_path value changes.
    • self awful.screenshot The object which changed (useful when connecting many object to the same callback).
    • new_value file_path The new value affected to the property.
🔗 file_name string · 1 signal
Get screenshot file name.

Constraints:

Default value : self.prefix..os.date()..".png"

See also:

awful.screenshot.file_path

Click to display more

Emit signals:

  • property::file_name When the file_name value changes.
    • self awful.screenshot The object which changed (useful when connecting many object to the same callback).
    • new_value file_name The new value affected to the property.
🔗 date_format string · 1 signal
The date format used in the default suffix.

Constraints:

Default value : "%Y%m%d%H%M%S"

See also:

wibox.widget.textclock Display the time (and date) in a text box. module

Click to display more

Emit signals:

  • property::date_format When the date_format value changes.
    • self awful.screenshot The object which changed (useful when connecting many object to the same callback).
    • new_value date_format The new value affected to the property.
🔗 cursor string · 1 signal
The cursor used in interactive mode.

Constraints:

Default value : "crosshair"

Click to display more

Emit signals:

  • property::cursor When the cursor value changes.
    • self awful.screenshot The object which changed (useful when connecting many object to the same callback).
    • new_value cursor The new value affected to the property.
🔗 interactive boolean · 1 signal
Use the mouse to select an area (snipping tool).

Constraints:

Default value : false
Valid values : true or false.

Click to display more

Emit signals:

  • property::interactive When the interactive value changes.
    • self awful.screenshot The object which changed (useful when connecting many object to the same callback).
    • new_value interactive The new value affected to the property.
🔗 screen screen or nil · 1 signal
Get screenshot screen.

Constraints:

Default value : nil
Type description:
screen : A valid screen object such as retured by awful.screen.focused() or mouse.screen.
integer : A screen global id. Avoid using this since they are unsorted.
string : The "primary" value is also valid.

See also:

mouse.screen The screen under the cursor (mouse) object properties
screen.focused Get the focused screen. (screen) static module functions
screen.primary The primary screen. (screen) fields

Click to display more

Emit signals:

  • property::screen When the screen value changes.
    • self awful.screenshot The object which changed (useful when connecting many object to the same callback).
    • new_value screen The new value affected to the property.
🔗 client client or nil · 1 signal
Get screenshot client.

Constraints:

Default value : nil
Valid values : The client.

See also:

mouse.current_client Get the client currently under the mouse cursor. (mouse) object properties
client.focus Emitted when a client gains focus. (client) signals

Click to display more

Emit signals:

  • property::client When the client value changes.
    • self awful.screenshot The object which changed (useful when connecting many object to the same callback).
    • new_value client The new value affected to the property.
🔗 geometry table · 1 signal
Get screenshot geometry.

Constraints:

Table keys:
x (number)
y (number)
width (number)
height (number)

Click to display more

Emit signals:

  • property::geometry When the geometry value changes.
    • self awful.screenshot The object which changed (useful when connecting many object to the same callback).
    • new_value geometry The new value affected to the property.
🔗 surface nil or image · read only
Get screenshot surface.

If none, or only one of: screen, client or geometry is provided, then this screenshot object will have a single target image. While specifying multiple target isn't recommended, you can use the surfaces properties to access them.

Note that this is empty until either save or refresh is called.

Constraints:

Default value : nil if the screenshot hasn't been taken yet, a gears.surface compatible image otherwise.
Type description:
string : Interpreted as a path to an image file.
string : A valid SVG content.
cairo : A cairo image surface: Directly used as-is.
librsvg : A librsvg handle object: Directly used as-is.
nil : Unset the image.

See also:

awful.screenshot.surfaces
🔗 surfaces table · read only
Get screenshot surfaces.

When multiple methods are enabled for the same screenshot, then it will have multiple images. This property exposes each image individually.

Note that this is empty until either save or refresh is called. Also note that you should make multiple awful.screenshot objects rather than put multiple targets in the same object.

Constraints:

Default value : {}
Table keys:
root (image) : The screenshot of all screens. This is the default if none of client, screen or geometry` have been set.
client (image) : The surface for the client property.
screen (image) : The surface for the screen property.
geometry (image) : The surface for the geometry property.

See also:

awful.screenshot.surface
🔗 minimum_size nil or integer or table · 1 signal
Set a minimum size to save a screenshot.

When the screenshot is very small (like 1x1 pixels), it is probably a mistake. Rather than save useless files, set this property to auto-reject tiny images.

Constraints:

Default value : {width=3
Type description:
nil : No minimum size.
integer : Same minimum size for the height and width.
table: : Different size for the height and width.
width (integer)
height (integer)
Negative allowed : false

Click to display more

Emit signals:

  • property::minimum_size When the minimum_size value changes.
    • self awful.screenshot The object which changed (useful when connecting many object to the same callback).
    • new_value minimum_size The new value affected to the property.
🔗 frame_color color or nil · 1 signal · 1 theme variable
The interactive frame color.

Constraints:

Default value : beautiful.awful_screenshot_frame_color
Type description:
string : An hexadecimal color code, such as "#ff0000" for red.
string : A color name, such as "red".
table : A gradient table.
cairo.pattern : Any valid Cairo pattern.
cairo.pattern : A texture build from an image by gears.color.create_png_pattern
nil : Fallback to the current value of beautiful.screenshot_frame_color.

Click to display more

Emit signals:

  • property::frame_color When the frame_color value changes.
    • self awful.screenshot The object which changed (useful when connecting many object to the same callback).
    • new_value frame_color The new value affected to the property.

Consumed theme variables:

Theme variable Usage
beautiful.screenshot_frame_colorFallback when frame_color isn't set.
🔗 frame_shape shape or nil · 1 signal · 1 theme variable
The interactive frame shape.

Constraints:

Default value : beautiful.awful_screenshot_frame_shape
Type description:
gears.shape : Like gears.shape.circle
function: : This can be used for custom shapes or to set parameters of existing shapes.
Function prototype:
Parameters:
cr (cairo.context) : A Cairo context
width (number) : The area width.
height (number) : The area height.
Return : The function returns nothing.
nil : Fallback to the current value of beautiful.screenshot_frame_shape.

Click to display more

Emit signals:

  • property::frame_shape When the frame_shape value changes.
    • self awful.screenshot The object which changed (useful when connecting many object to the same callback).
    • new_value frame_shape The new value affected to the property.

Consumed theme variables:

Theme variable Usage
beautiful.screenshot_frame_shapeFallback when frame_shape isn't set.
🔗 reject_buttons table · 1 signal
Define which mouse button exit the interactive snipping mode.

Constraints:

Default value : {awful.button({}
Table content : A list of awful.button objects.

See also:

awful.screenshot.accept_buttons

Click to display more

Emit signals:

  • property::reject_buttons When the reject_buttons value changes.
    • self awful.screenshot The object which changed (useful when connecting many object to the same callback).
    • new_value reject_buttons The new value affected to the property.
🔗 accept_buttons table · 1 signal
Mouse buttons used to save the screenshot when using the interactive snipping mode.

Constraints:

Default value : {awful.button({}
Table content : A list of awful.button objects.

See also:

awful.screenshot.reject_buttons

Click to display more

Emit signals:

  • property::accept_buttons When the accept_buttons value changes.
    • self awful.screenshot The object which changed (useful when connecting many object to the same callback).
    • new_value accept_buttons The new value affected to the property.
🔗 keygrabber awful.keygrabber · read only
The awful.keygrabber object used for the accept and reject keys.

This can be used to add new keybindings to the interactive snipper mode. For examples, this can be used to change the saving path or add some annotations to the image.

Constraints:

Default value : Autogenerated.
🔗 selected_geometry nil or table · 1 signal · read only
The current interactive snipping mode seletion.

Constraints:

Table keys:
x (integer)
y (integer)
width (integer)
height (integer)
surface (image)
method (string) : Either "root", "client", "screen" or "geometry".

Click to display more

Emit signals:
🔗 auto_save_delay integer or nil · 1 signal
Number of seconds before auto-saving (or entering the interactive snipper).

You can use 0 to auto-save immediatly.

Constraints:

Default value : nil
Type description:
nil : Do not auto-save.
Unit : second
Negative allowed : false

Click to display more

Emit signals:

  • property::auto_save_delay When the auto_save_delay value changes.
    • self awful.screenshot The object which changed (useful when connecting many object to the same callback).
    • new_value auto_save_delay The new value affected to the property.
🔗 auto_save_tick_duration number · 1 signal
Duration between the "timer::tick" signals when using auto_save_delay.

Constraints:

Default value : 1.0
Unit : second
Negative allowed : false

Click to display more

Emit signals:
🔗 content_widget wibox.widget.imagebox · read only
Export this screenshot as an wibox.widget.imagebox instead of a file.

This can be used to place the screenshot in a wibox, awful.popup or awful.wibar. Note that this isn't a live view of the object, you have to call :refresh() to update the content.

Note that it only makes sense when only 1 surface is exported by the screenhot. If that doesn't work for your use case, consider making multiple awful.screenshot objects.

Constraints:

Default value : Autogenerated on first access.

Object methods

🔗 :awful.screenshot.refresh () -> table
Take new screenshot(s) now.

Returns:

    table A table with the method name as key and the images as value.

See also:

awful.screenshot.save Save screenshot. object methods
🔗 :awful.screenshot.save (file_path) · 1 signal
Save screenshot.

Parameters:

Name Type(s) Description Default value
file_path Optional string Optionally override the file path. self.file_path

See also:

awful.screenshot.refresh Take new screenshot(s) now. object methods

Click to display more

Emit signals:
🔗 :awful.screenshot.accept () -> boolean · 2 signals
Save and exit the interactive snipping mode.

Returns:

    boolean true if the screenshot were save, false otherwise. It can be false because the selection is below minimum_size or because there is nothing to save (so selection).

Click to display more

Emit signals:
🔗 :awful.screenshot.reject (reason) · 1 signal
Exit the interactive snipping mode without saving.

Parameters:

Name Type(s) Description Default value
reason Optional string or nil The reason why it was rejected. This is passed to the "snipping::cancelled" signal. nil

Click to display more

Emit signals:

Signals

🔗 snipping::start
Emitted when the interactive snipping starts.

Arguments:

Name Type(s) Description
self awful.screenshot
🔗 snipping::success
Emitted when the interactive snipping succeed.

Arguments:

Name Type(s) Description
self awful.screenshot
🔗 snipping::cancelled
Emitted when the interactive snipping is cancelled.

Arguments:

Name Type(s) Description
self awful.screenshot
reason string Either "mouse_button", "key", "no_selection" or "too_small".
🔗 timer::started
Emitted when the auto_save_delay timer starts.

Arguments:

Name Type(s) Description
self awful.screenshot
🔗 timer::tick
Emitted after each elapsed second when auto_save_delay is set.

Arguments:

Name Type(s) Description
self awful.screenshot
remaining integer Number of seconds remaining.
🔗 timer::timeout
Emitted when the auto_save_delay timer stops.

This is before the screenshot is taken. If you need to hide notifications or other element, it has to be done using this signal.

Arguments:

Name Type(s) Description
self awful.screenshot
🔗 file::saved
Emitted when a the screenshot is saved.

This can be due to :save() being called, the interactive mode finishing or auto_save_delay timing out.

Arguments:

Name Type(s) Description
self awful.screenshot The screenshot.
file_path string The path.
method Optional string or nil The method associated with the file_path. This can be root, geometry, client or screen.

Theme variables

🔗 beautiful.screenshot_frame_color color
The screenshot interactive frame color.
Click to display more

Used by:
🔗 beautiful.screenshot_frame_shape shape
The screenshot interactive frame shape.
Click to display more

Used by:
generated by LDoc 1.5.0