# Module: `naughty.notification`

Notification manipulation class.

This class creates individual notification objects that can be manipulated to extend the default behavior.

This class doesn't define the actual widget, but is rather intended as a data object to hold the properties. All examples assume the default widgets, but the whole implementation can be replaced.

### Info:

- Copyright: 2008 koniu,2017 Emmanuel Lepage Vallee
- Originally authored by: Emmanuel Lepage Vallee
  (Full contributors list available on our github project)

## Constructors

naughty.notification {[args]} | Create a notification. |

## Object properties

title | string | Title of the notification. |
timeout | number | Time in seconds after which popup expires. |
urgency | string | The notification urgency level. |
category | string or nil | The notification category. |
resident | boolean | True if the notification should be kept when an action is pressed. |
hover_timeout | number or nil | Delay in seconds after which hovered popup disappears. |
screen | screen | Target screen for the notification. |
position | string or nil | Corner of the workarea displaying the popups. |
ontop | boolean | Boolean forcing popups to display on top. |
height | number or nil | Popup height. |
width | number or nil | Popup width. |
font | font or nil | Notification font. |
icon | image or nil | "All in one" way to access the default image or icon. |
icon_size | integer or nil | Desired icon size in px. |
app_icon | string or nil | The icon provided in the app_icon field of the DBus notification. |
image | image or nil | The notification image. |
images | nil or table | The notification (animated) images. |
fg | color or nil | Foreground color. |
bg | color or nil | Background color. |
border_width | number or nil | Border width. |
border_color | string or nil | Border color. |
shape | shape or nil | Widget shape. |
opacity | number or nil | Widget opacity. |
margin | number or table or nil | Widget margin. |
preset | table or nil | Table with any of the above parameters. |
callback | function or nil | Function that will be called with all arguments. |
actions | table | A table containing strings that represents actions to buttons. |
ignore | boolean | Ignore this notification, do not display. |
suspended | boolean | Tell if the notification is currently suspended (read only). |
is_expired | boolean | If the notification is expired. |
auto_reset_timeout | boolean | If the timeout needs to be reset when a property changes. |
clients | table | A list of clients associated with this notification. |
max_width | number or nil | The maximum popup width. |
app_name | string or nil | The application name specified by the notification. |
widget_template | template or nil | The widget template used to represent the notification. |

## Deprecated object properties

text | string | Text of the notification. | Deprecated
run | function | Function to run on left click. | Deprecated
destroy | function | Function to run when notification is destroyed. | Deprecated

## Object methods

:destroy (reason, keep_visible) -> boolean | Destroy notification by notification object. |
:reset_timeout (new_timeout) | Set new notification timeout. |
:append_actions (new_actions) | Add more actions to the notification. |
:grant (permission, context) | Grant a permission for a notification. |
:deny (permission, context) | Deny a permission for a notification |
:emit_signal (name, ...) | Emit a signal. | Inherited from gears.object
:connect_signal (name, func) | Connect to a signal. | Inherited from gears.object
:weak_connect_signal (name, func) | Connect to a signal weakly. | Inherited from gears.object

## Signals

destroyed | Emitted when the notification is destroyed. |

## Theme variables

beautiful.notification_font | string or lgi.Pango.FontDescription | Notifications font. |
beautiful.notification_bg | color | Notifications background color. |
beautiful.notification_fg | color | Notifications foreground color. |
beautiful.notification_border_width | int | Notifications border width. |
beautiful.notification_border_color | color | Notifications border color. |
beautiful.notification_shape | gears.shape | Notifications shape. |
beautiful.notification_opacity | int | Notifications opacity. |
beautiful.notification_margin | int | The margins inside of the notification widget (or popup). |
beautiful.notification_width | int | Notifications width. |
beautiful.notification_height | int | Notifications height. |
beautiful.notification_spacing | number | The spacing between the notifications. |

## Constructors

🔗 naughty.notification {[args]}
  Create a notification.

  ### 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 `naughty.notification{}`. This is a Lua shortcut syntax equivalent to `naughty.notification({})`. `args` is only a placeholder name for the "lone table argument" used in named parameters calls.

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  args | Optional | table | The argument table containing any of the arguments below. | `{}`
  text | Optional | string | Text of the notification. | `""`
  title | Optional | string | Title of the notification. | Undefined
  timeout | Optional | integer | Time in seconds after which popup expires. Set 0 for no timeout. | `5`
  hover_timeout | Optional | number | Delay in seconds after which hovered popup disappears. | Undefined
  screen | Optional | integer or screen | Target screen for the notification. | `focused`
  position | Optional | string | Corner of the workarea displaying the popups. Values: `"top_right"`, `"top_left"`, `"bottom_left"`, `"bottom_right"`, `"top_middle"`, `"bottom_middle"`, `"middle"`. | `"top_right"`
  ontop | Optional | boolean | Boolean forcing popups to display on top. | `true`
  height | Optional | integer | Popup height. | ``beautiful.notification_height` or auto`
  width | Optional | integer | Popup width. | ``beautiful.notification_width` or auto`
  font | Optional | string or lgi.Pango.FontDescription | Notification font. | ``beautiful.notification_font` or `beautiful.font` or `awesome.font``
  icon | Optional | image | Path to icon. | Undefined
  icon_size | Optional | integer | Desired icon size in px. | Undefined
  fg | Optional | string | Foreground color. | ``beautiful.notification_fg` or `beautiful.fg_focus` or `'#ffffff'``
  bg | Optional | string | Background color. | ``beautiful.notification_fg` or `beautiful.bg_focus` or `'#535d6c'``
  border_width | Optional | integer | Border width. | ``beautiful.notification_border_width` or 1`
  border_color | Optional | gears.color | Border color. | ``beautiful.notification_border_color` or `beautiful.border_color_active` or `'#535d6c'``
  shape | Optional | gears.shape | Widget shape. | `beautiful.notification_shape`
  opacity | Optional | gears.opacity | Widget opacity. | `beautiful.notification_opacity`
  margin | Optional | gears.margin | Widget margin. | `beautiful.notification_margin`
  run | Optional | function | Function to run on left click. The notification object will be passed to it as an argument. You need to call e.g. `notification.die(naughty.notification_closed_reason.dismissedByUser)` from there to dismiss the notification yourself. | Undefined
  destroy | Optional | function | Function to run when notification is destroyed. | Undefined
  preset | Optional | table | Table with any of the above parameters. Note: Any parameters specified directly in args will override ones defined in the preset. | Undefined
  callback | Optional | function | Function that will be called with all arguments. The notification will only be displayed if the function returns true. Note: this function is only relevant to notifications sent via dbus. | Undefined
  actions | Optional | table | A list of naughty.actions. | Undefined
  ignore_suspend | Optional | boolean | If set to true this notification will be shown even if notifications are suspended via naughty.suspend. | `false`

  ### Returns:

  naughty.notification A new notification object.

  ### Usage:

      naughty.notification {
          title   = "Achtung!",
          message = "You're idling", timeout = 0
      }

  Click to display more

  ### Consumed theme variables:

  Theme variable | Usage
  --- | ---
  beautiful.notification_height |
  beautiful.notification_width |
  beautiful.notification_font |
  beautiful.font |
  beautiful.notification_fg |
  beautiful.fg_focus |
  beautiful.bg_focus |
  beautiful.notification_border_width |
  beautiful.notification_border_color |
  `beautiful.border_color_active` |
  beautiful.notification_shape |
  beautiful.notification_opacity |
  beautiful.notification_margin |

## Object properties

🔗 title string · 1 signal
  Title of the notification.

  ### Constraints:

  Default value | : `""`

  Click to display more

  ### Emit signals:

  - `property::title` When the title value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` title The new value affected to the property.
🔗 timeout number · 1 signal
  Time in seconds after which popup expires. Set 0 for no timeout.

  ### Constraints:

  Default value | : If unspecified, it can come from either the notification itself, the presets or the `ruled.notification` rules.
  Unit | : second
  Negative allowed | : false

  Click to display more

  ### Emit signals:

  - `property::timeout` When the timeout value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` timeout The new value affected to the property.
🔗 urgency string · 1 signal
  The notification urgency level.

  ### Constraints:

  Default value | : `"normal"`
  Valid values:
  `"low"`
  `"normal"`
  `"critical"`

  Click to display more

  ### Emit signals:

  - `property::urgency` When the urgency value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` urgency The new value affected to the property.
🔗 category string or nil · 1 signal
  The notification category.

  The category should be named using the `x-vendor.class.name` naming scheme or use one of the default categories:

  Name | Description
  --- | ---
  device | A generic device-related notification that doesn't fit into any other category.
  device.added | A device, such as a USB device, was added to the system.
  device.error | A device had some kind of error.
  device.removed | A device, such as a USB device, was removed from the system.
  email | A generic e-mail-related notification that doesn't fit into any other category.
  email.arrived | A new e-mail notification.
  email.bounced | A notification stating that an e-mail has bounced.
  im | A generic instant message-related notification that doesn't fit into any other category.
  im.error | An instant message error notification.
  im.received | A received instant message notification.
  network | A generic network notification that doesn't fit into any other category.
  network.connected | A network connection notification, such as successful sign-on to a network service. This should not be confused with device.added for new network devices.
  network.disconnected | A network disconnected notification. This should not be confused with device.removed for disconnected network devices.
  network.error | A network-related or connection-related error.
  presence | A generic presence change notification that doesn't fit into any other category, such as going away or idle.
  presence.offline | An offline presence change notification.
  presence.online | An online presence change notification.
  transfer | A generic file transfer or download notification that doesn't fit into any other category.
  transfer.complete | A file transfer or download complete notification.
  transfer.error | A file transfer or download error.

  ### Constraints:

  Default value | : `nil`

  Click to display more

  ### Emit signals:

  - `property::category` When the category value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` category The new value affected to the property.
🔗 resident boolean · 1 signal
  True if the notification should be kept when an action is pressed.

  By default, invoking an action will destroy the notification. Some actions, like the "Snooze" action of alarm clock, will cause the notification to be updated with a date further in the future.

  ### Constraints:

  Default value | : `false`
  Valid values | : `true` or `false`.

  Click to display more

  ### Emit signals:

  - `property::resident` When the resident value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` resident The new value affected to the property.
🔗 hover_timeout number or nil · 1 signal
  Delay in seconds after which hovered popup disappears.

  ### Constraints:

  Default value | : `nil`
  Unit | : second
  Negative allowed | : false

  Click to display more

  ### Emit signals:

  - `property::hover_timeout` When the hover_timeout value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` hover_timeout The new value affected to the property.
🔗 screen screen · 1 signal
  Target screen for the notification.

  ### Constraints:

  Default value | : `awful.screen.preferred()`
  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.

  Click to display more

  ### Emit signals:

  - `property::screen` When the screen value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` screen The new value affected to the property.
🔗 position string or nil · 1 signal
  Corner of the workarea displaying the popups.

  for _, pos in ipairs { "top_left" , "top_middle" , "top_right", "bottom_left", "bottom_middle", "bottom_right", } do for i=1, 3 do naughty.notification { position = pos, title = pos .. " " .. i, message = ever_longer_messages(i) } end end

  ### Constraints:

  Default value | : `beautiful.notification_position`
  Valid values:
  `"top_right"`
  `"top_left"`
  `"bottom_left"`
  `"bottom_right"`
  `"top_middle"`
  `"bottom_middle"`
  `"middle"`

  ### See also:

  awful.placement.next_to | Move a drawable to a relative position next to another one. (awful.placement) | static module functions

  Click to display more

  ### Emit signals:

  - `property::position` When the position value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` position The new value affected to the property.

  ### Consumed theme variables:

  Theme variable | Usage
  --- | ---
  `beautiful.notification_position` |

🔗 ontop boolean
  Boolean forcing popups to display on top.

  ### Constraints:

  Default value | : `false`
  Valid values | : `true` or `false`.

🔗 height number or nil · 1 signal · 1 theme variable
  Popup height.

  for _, pos in ipairs { "top_left" , "top_middle" , "top_right", "bottom_left", "bottom_middle", "bottom_right", } do for i=1, 2 do naughty.notification { position = pos, title = pos .. " " .. i, width = 50*i, height = 50*i, message = "This is a very, very, very, ".. "very, very very long message", } end end

  ### Constraints:

  Default value | : `beautiful.naughty_notification_height`
  Type description:
  nil | : Fallback to the current value of `beautiful.notification_height`.
  Unit | : pixel
  Negative allowed | : false

  ### See also:

  width | Popup width. | object properties

  Click to display more

  ### Emit signals:

  - `property::height` When the height value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` height The new value affected to the property.

  ### Consumed theme variables:

  Theme variable | Usage
  --- | ---
  beautiful.notification_height | Fallback when height isn't set.

🔗 width number or nil · 1 signal · 1 theme variable
  Popup width.

  ### Constraints:

  Default value | : `beautiful.naughty_notification_width`
  Type description:
  nil | : Fallback to the current value of `beautiful.notification_width`.
  Unit | : pixel
  Negative allowed | : false

  ### See also:

  height | Popup height. | object properties

  Click to display more

  ### Emit signals:

  - `property::width` When the width value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` width The new value affected to the property.

  ### Consumed theme variables:

  Theme variable | Usage
  --- | ---
  beautiful.notification_width | Fallback when width isn't set.

🔗 font font or nil · 1 signal
  Notification font.

  ### Constraints:

  Default value | : `beautiful.notification_font`
  Type description:
  string | : A Pango [font description](../widgets/wibox.widget.textbox.html#font).
  string | : An [XFT string](https://wiki.archlinux.org/title/X_Logical_Font_Description), such as `"-*-dejavu sans mono-medium-r-normal--*-80-*-*-*-*-iso10646-1"`.

  ### See also:

  wibox.widget.textbox.font | Set a textbox font. (wibox.widget.textbox) | object properties

  ### Usage:

      local text = [[An <b>important</b>;<i>notification</i>;]]

      require("naughty").notification {
          title        = "Hello world!",
          text         = text,
          icon         = beautiful.icon,
          bg           = "#0000ff",
          fg           = "#ff0000",
          font         = "verdana 14",
          border_width = 1,
          border_color = "#ff0000"
      }

  Click to display more

  ### Emit signals:

  - `property::font` When the font value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` font The new value affected to the property.

  ### Consumed theme variables:

  Theme variable | Usage
  --- | ---
  beautiful.notification_font |

🔗 icon image or nil · 1 signal
  "All in one" way to access the default image or icon.

  A notification can provide a combination of an icon, a static image, or if enabled, a looping animation. Add to that the ability to import the icon information from the client or from a `.desktop` file, there is multiple conflicting sources of "icons".

  On the other hand, the vast majority of notifications don't multiple or ambiguous sources of icons. This property will pick the first of the following.

  * The image. * The app_icon. * The icon from a client with `normal` type. * The icon of a client with `dialog` type.

  ### Constraints:

  Default value | : `nil`
  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:

  app_icon | The icon provided in the app_icon field of the DBus notification. | object properties
  image | The notification image. | object properties

  Click to display more

  ### Emit signals:

  - `property::icon` When the icon value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` icon The new value affected to the property.
🔗 icon_size integer or nil · 1 signal
  Desired icon size in px.

  ### Constraints:

  Default value | : `beautiful.notification_icon_size`
  Unit | : pixel
  Negative allowed | : false

  Click to display more

  ### Emit signals:

  - `property::icon_size` When the icon_size value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` icon_size The new value affected to the property.

  ### Consumed theme variables:

  Theme variable | Usage
  --- | ---
  `beautiful.notification_icon_size` |

🔗 app_icon string or nil · 1 signal
  The icon provided in the app_icon field of the DBus notification.

  This should always be either the URI (path) to an icon or a valid XDG icon name to be fetched from the theme.

  ### Constraints:

  Default value | : `nil`

  Click to display more

  ### Emit signals:

  - `property::app_icon` When the app_icon value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` app_icon The new value affected to the property.
🔗 image image or nil · 1 signal
  The notification image.

  This is usually provided as a gears.surface object. The image is used instead of the app_icon by notification assets which are auto-generated or stored elsewhere than the filesystem (databases, web, Android phones, etc).

  ### Constraints:

  Default value | : `nil`
  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.

  Click to display more

  ### Emit signals:

  - `property::image` When the image value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` image The new value affected to the property.
🔗 images nil or table · 1 signal
  The notification (animated) images.

  Note that calling this without first setting naughty.image_animations_enabled to true will throw an exception.

  Also note that there is *zero* support for this anywhere else in naughty and very, very few applications support this.

  This exists purely to comply with the specification.

  ### Constraints:

  Default value | : `nil`
  Table content | : A list of `image`s.

  Click to display more

  ### Emit signals:

  - `property::images` When the images value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` images The new value affected to the property.
🔗 fg color or nil · 1 signal · 1 theme variable
  Foreground color.

  -- A notification popup using the default widget_template. naughty.connect_signal("request::display", function(n) naughty.layout.box {notification = n} end) -- Notifications as widgets for any wibox/awful.wibar/awful.popup some_wibar.widget = naughty.list.notifications {} for _, color in ipairs {"#ff0000", "#00ff00", "#0000ff"} do naughty.notification { title = "A ".. color .." notification", message = "Message", fg = color, } end

  ### Constraints:

  Default value | : `beautiful.naughty_notification_fg`
  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.notification_fg`.

  ### See also:

  title | Title of the notification. | object properties
  gears.color | This module simplifies the creation of cairo pattern objects. | module

  Click to display more

  ### Emit signals:

  - `property::fg` When the fg value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` fg The new value affected to the property.

  ### Consumed theme variables:

  Theme variable | Usage
  --- | ---
  beautiful.notification_fg | Fallback when fg isn't set.

🔗 bg color or nil · 1 signal
  Background color.

  -- A notification popup using the default widget_template. naughty.connect_signal("request::display", function(n) naughty.layout.box {notification = n} end) -- Notifications as widgets for any wibox/awful.wibar/awful.popup some_wibar.widget = naughty.list.notifications {} for _, color in ipairs {"#ff0000", "#00ff00", "#0000ff"} do naughty.notification { title = "A ".. color .." notification", bg = color, } end

  ### Constraints:

  Default value | : `beautiful.notification_bg`
  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)

  ### See also:

  title | Title of the notification. | object properties
  gears.color | This module simplifies the creation of cairo pattern objects. | module

  Click to display more

  ### Emit signals:

  - `property::bg` When the bg value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` bg The new value affected to the property.

  ### Consumed theme variables:

  Theme variable | Usage
  --- | ---
  beautiful.notification_bg |

🔗 border_width number or nil · 1 signal · 1 theme variable
  Border width.

  ### Constraints:

  Default value | : `beautiful.notification_border_width or 0`
  Type description:
  nil | : Fallback to the current value of `beautiful.notification_border_width`.
  Unit | : pixel
  Negative allowed | : false

  Click to display more

  ### Emit signals:

  - `property::border_width` When the border_width value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` border_width The new value affected to the property.

  ### Consumed theme variables:

  Theme variable | Usage
  --- | ---
  beautiful.notification_border_width |

  ### Consumed theme variables:

  Theme variable | Usage
  --- | ---
  beautiful.notification_border_width | Fallback when border_width isn't set.

🔗 border_color string or nil · 1 signal
  Border color.

  -- A notification popup using the default widget_template. naughty.connect_signal("request::display", function(n) naughty.layout.box {notification = n} end) -- Notifications as widgets for any wibox/awful.wibar/awful.popup some_wibar.widget = naughty.list.notifications {} for bw, color in ipairs {"#ff0000", "#00ff00", "#0000ff"} do naughty.notification { title = "A ".. color .." notification", border_color = color, border_width = bw*2, } end

  Please note that only string (like `#ff0000`) are supported.

  ### Constraints:

  Default value | : `beautiful.notification_border_color`

  ### See also:

  gears.color | This module simplifies the creation of cairo pattern objects. | module

  Click to display more

  ### Emit signals:

  - `property::border_color` When the border_color value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` border_color The new value affected to the property.

  ### Consumed theme variables:

  Theme variable | Usage
  --- | ---
  beautiful.notification_border_color |

🔗 shape shape or nil · 1 signal
  Widget shape.

  Note that when using a custom `request::display` handler or `naughty.rules`, choosing between multiple shapes depending on the content can be done using expressions like:

  -- The notification object is called `n` shape = #n.actions > 0 and gears.shape.rounded_rect or gears.shape.rounded_bar,

  -- A notification popup using the default widget_template. naughty.connect_signal("request::display", function(n) naughty.layout.box {notification = n} end) -- Notifications as widgets for any wibox/awful.wibar/awful.popup some_wibar.widget = naughty.list.notifications {} local shapes = { gears.shape.octogon, gears.shape.rounded_rect, gears.shape.rounded_bar } for idx=1, 3 do naughty.notification { title = "A notification", border_color = "#0000ff", border_width = idx*2, shape = shapes[idx], } end

  local text = [[An important; notification; ]] local shapes = { gears.shape.rounded_rect, gears.shape.hexagon, gears.shape.octogon, function(cr, w, h) return gears.shape.infobubble(cr, w, h, 20, 10, w/2 - 10) end } for _, s in ipairs(shapes) do naughty.notify { title = "Hello world!", text = text, icon = beautiful.icon, shape = s, border_width = 3, border_color = beautiful.bg_highlight, margin = 15, } end

  ### Constraints:

  Default value | : `beautiful.notification_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.

  Click to display more

  ### Emit signals:

  - `property::shape` When the shape value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` shape The new value affected to the property.

  ### Consumed theme variables:

  Theme variable | Usage
  --- | ---
  beautiful.notification_shape |

🔗 opacity number or nil · 1 signal
  Widget opacity.

  ### Constraints:

  Default value | : `beautiful.notification_opacity`
  Unit | : Gradient beween 0.0 (transparent) and 1.0 (opaque).
  Minimum value | : 0.0
  Maximum value | : 1.0

  Click to display more

  ### Emit signals:

  - `property::opacity` When the opacity value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` opacity The new value affected to the property.

  ### Consumed theme variables:

  Theme variable | Usage
  --- | ---
  beautiful.notification_opacity |

🔗 margin number or table or nil · 1 signal
  Widget margin.

  -- A notification popup using the default widget_template. naughty.connect_signal("request::display", function(n) naughty.layout.box {notification = n} end) -- Notifications as widgets for any wibox/awful.wibar/awful.popup some_wibar.widget = naughty.list.notifications { base_layout = wibox.widget { spacing = beautiful.notification_spacing, layout = wibox.layout.fixed.horizontal }, } for margin = 10, 20, 5 do naughty.notification { title = "A notification", margin = margin, border_width = 1, border_color = "#ff0000", } end

  ### Constraints:

  Default value | : `beautiful.notification_margin`
  Type description:
  number | : A single value for all sides.
  table: | : A different value for all sides.
  top (number)
  bottom (number)
  left (number)
  right (number)
  Unit | : pixel
  Negative allowed | : false

  ### See also:

  shape | Widget shape. | object properties

  Click to display more

  ### Emit signals:

  - `property::margin` When the margin value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` margin The new value affected to the property.
🔗 preset table or nil · 1 signal
  Table with any of the above parameters. args will override ones defined in the preset.

  ### Constraints:

  Default value | : `nil`

  Click to display more

  ### Emit signals:

  - `property::preset` When the preset value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` preset The new value affected to the property.
🔗 callback function or nil · 1 signal
  Function that will be called with all arguments. The notification will only be displayed if the function returns true. Note: this function is only relevant to notifications sent via dbus.

  ### Constraints:

  Default value | : `nil`
  Function prototype:
  Parameters:
  legacy_data (table)
  appname (string)
  replaces_id (number)
  app_icon (string)
  title (string)
  message (string)
  actions (table)
  hints (table)
  expire (number)
  Return | : The function returns nothing.

  Click to display more

  ### Emit signals:

  - `property::callback` When the callback value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` callback The new value affected to the property.
🔗 actions table · 1 signal
  A table containing strings that represents actions to buttons.

  The table key (a number) is used by DBus to set map the action.

  ### Constraints:

  Default value | : `{}`
  Table content | : A list of naughty.action objects.

  Click to display more

  ### Emit signals:

  - `property::actions` When the actions value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` actions The new value affected to the property.
🔗 ignore boolean · 1 signal
  Ignore this notification, do not display.

  Note that this property has to be set in a preset or in a `request::preset` handler.

  ### Constraints:

  Default value | : `false`
  Valid values | : `true` or `false`.

  Click to display more

  ### Emit signals:

  - `property::ignore` When the ignore value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` ignore The new value affected to the property.
🔗 suspended boolean · 1 signal
  Tell if the notification is currently suspended (read only).

  This is always equal to naughty.suspended

  ### Constraints:

  Default value | : `false`
  Valid values | : `true` or `false`.

  ### See also:

  naughty.suspended | The global suspension state. (naughty) | object properties

  Click to display more

  ### Emit signals:

  - `property::suspended` When the suspended value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` suspended The new value affected to the property.
🔗 is_expired boolean · 1 signal
  If the notification is expired.

  ### Constraints:

  Default value | : This becomes `true` either then `:destroy()` is called or if the `timeout` expires.
  Valid values | : `true` or `false`.

  ### See also:

  naughty.expiration_paused | Do not allow notifications to auto-expire. (naughty) | object properties

  Click to display more

  ### Emit signals:

  - `property::is_expired` When the is_expired value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` is_expired The new value affected to the property.
🔗 auto_reset_timeout boolean · 1 signal
  If the timeout needs to be reset when a property changes.

  By default it fallsback to naughty.auto_reset_timeout, which itself is true by default.

  ### Constraints:

  Default value | : `true`
  Valid values | : `true` or `false`.

  Click to display more

  ### Emit signals:

  - `property::auto_reset_timeout` When the auto_reset_timeout value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` auto_reset_timeout The new value affected to the property.
🔗 clients table
  A list of clients associated with this notification.

  When used with DBus notifications, this returns all clients sharing the PID of the notification sender. Note that this is highly unreliable. Applications that use a different process to send the notification or applications (and scripts) calling the `notify-send` command wont have any client.

  ### Constraints:

  Default value | : `{}`
  Table content | : A list of client objects.

🔗 max_width number or nil · 1 signal · 1 theme variable
  The maximum popup width.

  Some notifications have overlong message, cap them to this width. Note that this is ignored by naughty.list.notifications because it delegate this decision to the layout.

  ### Constraints:

  Default value | : `500`
  Type description:
  nil | : Fallback to the current value of `beautiful.notification_max_width`.
  Unit | : pixel
  Negative allowed | : false

  Click to display more

  ### Emit signals:

  - `property::max_width` When the max_width value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` max_width The new value affected to the property.

  ### Consumed theme variables:

  Theme variable | Usage
  --- | ---
  `beautiful.notification_max_width` | Fallback when max_width isn't set.

🔗 app_name string or nil · 1 signal
  The application name specified by the notification.

  This can be anything. It is usually less relevant than the clients property, but can sometime be specified for remote or headless notifications. In these case, it helps to triage and detect the notification from the rules.

  ### Constraints:

  Default value | : `nil`

  Click to display more

  ### Emit signals:

  - `property::app_name` When the app_name value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` app_name The new value affected to the property.
🔗 widget_template template or nil · 1 signal
  The widget template used to represent the notification.

  Some notifications, such as chat messages or music applications are better off with a specialized notification widget.

  ### Constraints:

  Default value | : `nil`
  Type description:
  table | : A table containing a widget tree definition. WARNING: This is really a table and **NOT** a widget object. Use the `widget = come.class.here` to define the topmost class rather than construct an instance.

  Click to display more

  ### Emit signals:

  - `property::widget_template` When the widget_template value changes.
  - `self` naughty.notification The object which changed (useful when connecting many object to the same callback).
  - `new_value` widget_template The new value affected to the property.

## Deprecated object properties

🔗 text string
  Text of the notification.

  This exists only for the pre-AwesomeWM v4.4 new notification implementation. Please always use title.

  ### See also:

  title | Title of the notification. | object properties

🔗 run function
  Function to run on left click.

  Use the signals rather than this.

  ### See also:

  destroyed | Emitted when the notification is destroyed. | signals

🔗 destroy function
  Function to run when notification is destroyed.

  Use the signals rather than this.

  ### See also:

  destroyed | Emitted when the notification is destroyed. | signals

## Object methods

🔗 :destroy (reason, keep_visible) -> boolean · 1 signal
  Destroy notification by notification object.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  reason |  | string | One of the reasons from `notification_closed_reason` | Not applicable
  keep_visible | Optional | boolean | If true, keep the notification visible | `false`

  ### Returns:

  boolean True if the popup was successfully destroyed, false otherwise.

  ### See also:

  naughty.notification_closed_reason | The reason why a notification is to be closed. (naughty) | tables

  Click to display more

  ### Emit signals:

  - destroyed
  - `reason` `integer` The reason.
  - `keep_visible` `boolean` If the notification should be kept.
🔗 :reset_timeout (new_timeout)
  Set new notification timeout.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  new_timeout |  | number | Time in seconds after which notification disappears.

🔗 :append_actions (new_actions)
  Add more actions to the notification.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  new_actions |  | table |

🔗 :grant (permission, context)
  Grant a permission for a notification.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  permission |  | string | The permission name (just the name, no `request::`).
  context |  | string | The reason why this permission is requested.

  ### See also:

  awful.permissions | Default implementation of the various requests handers. | module

🔗 :deny (permission, context)
  Deny a permission for a notification

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  permission |  | string | The permission name (just the name, no `request::`).
  context |  | string | The reason why this permission is requested.

  ### See also:

  awful.permissions | Default implementation of the various requests handers. | module

🔗 :emit_signal (name, ...) · Inherited from gears.object
  Emit a signal.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | The name of the signal.
  ... |  |  | Extra arguments for the callback functions. Each connected function receives the object as first argument and then any extra arguments that are given to emit_signal().

🔗 :connect_signal (name, func) · Inherited from gears.object
  Connect to a signal.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | The name of the signal.
  func |  | function | The callback to call when the signal is emitted.

🔗 :weak_connect_signal (name, func) · Inherited from gears.object
  Connect to a signal weakly.

  This allows the callback function to be garbage collected and automatically disconnects the signal when that happens.

  **Warning:** Only use this function if you really, really, really know what you are doing.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | The name of the signal.
  func |  | function | The callback to call when the signal is emitted.

## Signals

🔗 destroyed
  Emitted when the notification is destroyed.

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  reason |  | number | Why it was destroyed
  keep_visible |  | boolean | If it was kept visible.

  ### See also:

  naughty.notification_closed_reason | The reason why a notification is to be closed. (naughty) | tables

## Theme variables

🔗 beautiful.notification_font string or lgi.Pango.FontDescription
  Notifications font.
  Click to display more

  ### Used by:

  - naughty.notification Create a notification.
  - naughty.notification Create a notification.
  - font Notification font.
  - font Notification font.
  - naughty.widget.message Create a new naughty.widget.message.
  - naughty.widget.title Create a new naughty.widget.title.
🔗 beautiful.notification_bg color
  Notifications background color.
  Click to display more

  ### Used by:

  - bg Background color.
  - bg Background color.
🔗 beautiful.notification_fg color
  Notifications foreground color.
  Click to display more

  ### Used by:

  - naughty.notification Create a notification.
  - naughty.notification Create a notification.
  - naughty.widget.message Create a new naughty.widget.message.
  - naughty.widget.title Create a new naughty.widget.title.
  - fg Foreground color.
🔗 beautiful.notification_border_width int
  Notifications border width.
  Click to display more

  ### Used by:

  - naughty.notification Create a notification.
  - naughty.notification Create a notification.
  - border_width Border width.
  - border_width Border width.
  - `naughty.container.background` Create a new naughty.container.background.
  - border_width Border width.
🔗 beautiful.notification_border_color color
  Notifications border color.
  Click to display more

  ### Used by:

  - naughty.notification Create a notification.
  - naughty.notification Create a notification.
  - border_color Border color.
  - border_color Border color.
  - `naughty.container.background` Create a new naughty.container.background.
🔗 beautiful.notification_shape gears.shape
  Notifications shape.

  ### See also:

  gears.shape | Module dedicated to gather common shape painters. | module

  Click to display more

  ### Used by:

  - naughty.notification Create a notification.
  - naughty.notification Create a notification.
  - shape Widget shape.
  - shape Widget shape.
  - `naughty.container.background` Create a new naughty.container.background.
🔗 beautiful.notification_opacity int
  Notifications opacity.
  Click to display more

  ### Used by:

  - naughty.notification Create a notification.
  - naughty.notification Create a notification.
  - opacity Widget opacity.
  - opacity Widget opacity.
🔗 beautiful.notification_margin int
  The margins inside of the notification widget (or popup).
  Click to display more

  ### Used by:

  - naughty.notification Create a notification.
  - naughty.notification Create a notification.
🔗 beautiful.notification_width int
  Notifications width.
  Click to display more

  ### Used by:

  - naughty.notification Create a notification.
  - naughty.notification Create a notification.
  - width Popup width.
🔗 beautiful.notification_height int
  Notifications height.
  Click to display more

  ### Used by:

  - naughty.notification Create a notification.
  - naughty.notification Create a notification.
  - height Popup height.
🔗 beautiful.notification_spacing number
  The spacing between the notifications.

  ### See also:

  gears.surface | Utilities to integrate and manipulate Cairo drawing surfaces. | module

  Click to display more

  ### Used by:

  - `base_layout` A `wibox.layout` to be used to place the entries.

generated by LDoc 1.5.0