# 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({ group = "client", awful.key({modkey}, "Print", function (c) saved_screenshot { auto_save_delay = 0, client = c } end , {description = "take client screenshot"}), awful.key({modkey, "Shift"}, "Print", function (c) saved_screenshot { auto_save_delay = 0, interactive = true, client = c } end , {description = "take interactive client screenshot"}), awful.key({modkey, "Control"}, "Print", function (c) delayed_screenshot { auto_save_delay = 5, client = c } end , {description = "take screenshot in 5 seconds"}), 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"}), }) end) awful.keyboard.append_global_keybindings({ group = "client", awful.key({}, "Print", function () saved_screenshot { auto_save_delay = 0 } end , {description = "take screenshot"}), awful.key({"Shift"}, "Print", function () saved_screenshot { auto_save_delay = 0, interactive = true } end , {description = "take interactive screenshot"}), awful.key({"Control"}, "Print", function () delayed_screenshot { auto_save_delay = 5 } end , {description = "take screenshot in 5 seconds"}), awful.key({"Shift", "Control"}, "Print", function () delayed_screenshot { auto_save_delay = 5, interactive = true } end , {description = "take interactive screenshot in 5 seconds"}), })

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:

- Copyright: 2021 Brian Sobulefsky
- Originally authored by: Brian Sobulefsky <brian.sobulefsky@protonmail.com>
  (Full contributors list available on our github project)

## 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](../theme_related_libraries/gears.color.html).
  cairo.pattern | : Any valid [Cairo pattern](https://cairographics.org/manual/cairo-cairo-pattern-t.html).
  cairo.pattern | : A texture build from an image by [gears.color.create\_png\_pattern](../theme_related_libraries/gears.color.html#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_color | Fallback 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](https://cairographics.org/manual/cairo-cairo-t.html)
  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_shape | Fallback 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:

  - `property::selected_geometry` When the selected_geometry value changes.
  - `self` awful.screenshot The object which changed (useful when connecting many object to the same callback).
  - `new_value` selected_geometry The new value affected to the property.
🔗 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:

  - `property::auto_save_tick_duration` When the auto_save_tick_duration value changes.
  - `self` awful.screenshot The object which changed (useful when connecting many object to the same callback).
  - `new_value` auto_save_tick_duration The new value affected to the property.
🔗 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:

  - saved
🔗 :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:

  - snipping::cancelled
  - snipping::success
🔗 :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:

  - snipping::cancelled

## 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:

  - frame_color The interactive frame color.
🔗 beautiful.screenshot_frame_shape shape
  The screenshot interactive frame shape.
  Click to display more

  ### Used by:

  - frame_shape The interactive frame shape.

generated by LDoc 1.5.0