# Module: `naughty`

Notification library.

For more details on how to create notifications, see naughty.notification.

To send notifications from the terminal, use `notify-send`.

### Info:

- Copyright: 2008 koniu
- Originally authored by: koniu <gkusnierz@gmail.com>
  (Full contributors list available on our github project)

## Static module functions

naughty.destroy_all_notifications (screens, reason) -> true or nil | Destroy all notifications on given screens. |
naughty.get_by_id (id) -> naughty.notification or nil | Get notification by ID |
naughty.connect_signal (name, func) | Connect a global signal on the module. |
naughty.emit_signal (name, ...) | Emit a module signal. |
naughty.disconnect_signal (name, func) -> boolean | Disconnect a signal from a source. |

## Object properties

suspended | boolean | The global suspension state. |
expiration_paused | boolean | Do not allow notifications to auto-expire. |
active | table | A table with all active notifications. |
has_display_handler | boolean | True when there is a handler connected to request::display. |
auto_reset_timeout | boolean | If the timeout needs to be reset when a property changes. |
image_animations_enabled | boolean | Enable or disable naughty ability to claim to support animations. |
persistence_enabled | boolean | Enable or disable the persistent notifications. |

## Signals

request::display_error | Emitted when an error occurred and requires attention. |
added | Emitted when a notification is created. |
destroyed | Emitted when a notification is destroyed. |
request::display | Emitted when a notification has to be displayed. |
request::preset | Emitted when a notification needs pre-display configuration. |
request::action_icon | Emitted when an action requires an icon it doesn't know. |
request::icon | Emitted when a notification icon could not be loaded. |
request::screen | Emitted when the screen is not defined or being removed. |

## Request handlers

naughty.default_screen_handler () | The default handler for request::screen. |
naughty.client_icon_handler () | Request handler to get the icon using the clients icons. |
naughty.icon_path_handler () | Request handler to get the icon using the image or path. |
naughty.icon_clear_handler () | Request handler for clearing the icon when asked by ie, DBus. |

## Deprecated functions

naughty.is_suspended () | Notification state. | Deprecated
naughty.suspend () | Suspend notifications. | Deprecated
naughty.resume () | Resume notifications. | Deprecated
naughty.toggle () | Toggle notification state. | Deprecated
naughty.destroy (notification, reason, keep_visible) | Destroy notification by notification object | Deprecated
naughty.getById (id) | Get notification by ID | Deprecated
naughty.reset_timeout (notification, new_timeout) | Set new notification timeout. | Deprecated
naughty.replace_text (notification, new_title, new_text) | Replace title and text of an existing notification. | Deprecated
naughty.notify {[args]} | Create a notification. | Deprecated

## Tables

naughty.config | Naughty configuration - a table containing common popup settings. |
naughty.config.presets | Notification presets for naughty.notify. |
naughty.config.defaults | Defaults for naughty.notify. |
naughty.notification_closed_reason | The reason why a notification is to be closed. |

## Static module functions

🔗 naughty.destroy_all_notifications (screens, reason) -> true or nil
  Destroy all notifications on given screens.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  screens |  | table | Table of screens on which notifications should be destroyed. If nil, destroy notifications on all screens.
  reason |  | naughty.notification_closed_reason | Reason for closing notifications.

  ### Returns:

  true or nil True if all notifications were successfully destroyed, nil otherwise.

  ### See also:

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

🔗 naughty.get_by_id (id) -> naughty.notification or nil
  Get notification by ID

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  id |  | integer | ID of the notification

  ### Returns:

  naughty.notification or nil notification object if it was found, nil otherwise
🔗 naughty.connect_signal (name, func)
  Connect a global signal on the module.

  Functions connected to this signal source will be executed when any module object emits the signal.

  It is also used for some generic module signals such as request::display.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | The name of the signal
  func |  | function | The function to attach

  ### Usage:

      naughty.connect_signal(\"added\", function(notif)
         -- do something
      end)

🔗 naughty.emit_signal (name, ...)
  Emit a module signal.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | The signal name.
  ... |  |  | The signal callback arguments

🔗 naughty.disconnect_signal (name, func) -> boolean
  Disconnect a signal from a source.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | The name of the signal
  func |  | function | The attached function

  ### Returns:

  boolean If the disconnection was successful

## Object properties

🔗 suspended boolean · 1 signal · 1 signal
  The global suspension state.

  When suspended, no notification widget should interrupt the user. This is useful when watching movies or doing presentations.

  ### Constraints:

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

  Click to display more

  ### Emit signals:

  - added

  ### Emit signals:

  - `property::suspended` When the suspended value changes.
  - `self` naughty The object which changed (useful when connecting many object to the same callback).
  - `new_value` suspended The new value affected to the property.
🔗 expiration_paused boolean · 1 signal
  Do not allow notifications to auto-expire.

  When navigating the notifications, for example on mouse over or when keyboard navigation is enabled, it is very annoying when notifications just vanish.

  ### Constraints:

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

  Click to display more

  ### Emit signals:

  - `property::expiration_paused` When the expiration_paused value changes.
  - `self` naughty The object which changed (useful when connecting many object to the same callback).
  - `new_value` expiration_paused The new value affected to the property.
🔗 active table · 1 signal
  A table with all active notifications.

  Please note that this list is kept up-to-date even in suspended mode.

  ### Constraints:

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

  Click to display more

  ### Emit signals:

  - `property::active` When the active value changes.
  - `self` naughty The object which changed (useful when connecting many object to the same callback).
🔗 has_display_handler boolean
  True when there is a handler connected to request::display.

  Note that using the legacy notifications is deprecated.

  ### Constraints:

  Default value | : If rc.lua has a `request::display` section, this will be `true`. Otherwise it is `false` and the legacy notification will be used.
  Valid values | : `true` or `false`.

🔗 auto_reset_timeout boolean · 1 signal
  If the timeout needs to be reset when a property changes.

  This is the global variant of the naughty.notification auto_reset_timeout property.

  ### 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 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.
🔗 image_animations_enabled boolean · 1 signal
  Enable or disable naughty ability to claim to support animations.

  When this is true, applications which query naughty feature support will see that animations are supported. Note that there is *very little* support for this and enabling it will cause bugs.

  ### Constraints:

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

  Click to display more

  ### Emit signals:

  - `property::image_animations_enabled` When the image_animations_enabled value changes.
  - `self` naughty The object which changed (useful when connecting many object to the same callback).
  - `new_value` image_animations_enabled The new value affected to the property.
🔗 persistence_enabled boolean · 1 signal
  Enable or disable the persistent notifications.

  This is very annoying when using naughty.layout.box popups, but tolerable when using naughty.list.notifications.

  Note that enabling this **does nothing** in naughty itself. The timeouts are still honored and notifications still destroyed. It is the user responsibility to disable the dismiss timer. However, this tells the applications that notification persistence is supported so they might stop using systray icons for the sake of displaying or other changes like that.

  ### Constraints:

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

  Click to display more

  ### Emit signals:

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

## Signals

🔗 request::display_error
  Emitted when an error occurred and requires attention.

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  message |  | string | The error message.
  startup |  | boolean | If the error occurred during the initial loading of rc.lua (and thus caused the fallback to kick in).

🔗 added
  Emitted when a notification is created.

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  notification |  | naughty.notification | The notification object

🔗 destroyed
  Emitted when a notification is destroyed.

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  notification |  | naughty.notification | The notification object

🔗 request::display
  Emitted when a notification has to be displayed.

  To add a handler, use:

  naughty.connect_signal("request::display", function(notification, args) -- do something end)

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  notification |  | table | The naughty.notification object.
  context |  | string | Why is the signal sent.
  args |  | table | Any arguments passed to the naughty.notify function, including, but not limited to, all naughty.notification properties.

🔗 request::preset
  Emitted when a notification needs pre-display configuration.

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  notification |  | table | The naughty.notification object.
  context |  | string | Why is the signal sent.
  args |  | table | Any arguments passed to the naughty.notify function, including, but not limited to, all naughty.notification properties.

🔗 request::action_icon
  Emitted when an action requires an icon it doesn't know.

  The implementation should look in the icon theme for an action icon or provide something natively.

  If an icon is found, the handler must set the icon property on the `action` object to a path or a gears.surface.

  There is no implementation by default. To use the XDG-icon, the common implementation will be:

  naughty.connect_signal("request::action_icon", function(a, context, hints) a.icon = menubar.utils.lookup_icon(hints.id) end)

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  action |  | naughty.action | The action.
  context |  | string | The context.
  hints |  | table |

🔗 request::icon
  Emitted when a notification icon could not be loaded.

  When an icon is passed in some "encoded" formats, such as XDG icon names or network URLs, AwesomeWM will not attempt to load it. If you wish to see the icon displayed, you must provide an handler. It is highly recommended for handler to only set `n.icon` when they *found* the icon. That way multiple handlers can be attached for multiple protocols.

  The `context` argument is the origin of the icon to decode. If an handler only supports one if them, it should check the `context` and return if it doesn't handle it. The currently valid contexts are:

  * app_icon * clients * path * image * images * dbus_clear

  For example, an implementation which uses the `app_icon` to perform an XDG icon lookup will look like:

  naughty.connect_signal("request::icon", function(n, context, hints) if context ~= "app_icon" then return end

  local path = menubar.utils.lookup_icon(hints.app_icon) or menubar.utils.lookup_icon(hints.app_icon:lower())

  if path then n.icon = path end end)

  The `images` context has no handler. It is part of the specification to handle animations. This is not supported by default.

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  n |  | notification | The notification.
  context |  | string | The source of the icon to look for.
  hints |  | table | The hints.
  app_icon |  | string | The name of the icon to look for.
  path |  | string | The path of the icon.
  image |  | string | The path or pixmap of the icon.

  ### See also:

  naughty.icon_path_handler | Request handler to get the icon using the image or path. | request handlers
  naughty.client_icon_handler | Request handler to get the icon using the clients icons. | request handlers

🔗 request::screen
  Emitted when the screen is not defined or being removed.

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  notification |  | table | The naughty.notification object. This is currently either "new" or "removed".
  context |  | string | Why is the signal sent.

## Request handlers

🔗 naughty.default_screen_handler ()
  The default handler for request::screen.

  It selects `awful.screen.focused()`.

🔗 naughty.client_icon_handler ()
  Request handler to get the icon using the clients icons.
🔗 naughty.icon_path_handler ()
  Request handler to get the icon using the image or path.
🔗 naughty.icon_clear_handler ()
  Request handler for clearing the icon when asked by ie, DBus.

## Deprecated functions

🔗 naughty.is_suspended ()
  Notification state.

  This function is deprecated, use naughty.suspended.

🔗 naughty.suspend ()
  Suspend notifications.

  This function is deprecated, use `naughty.suspended = true`.

🔗 naughty.resume ()
  Resume notifications.

  This function is deprecated, use `naughty.suspended = false`.

🔗 naughty.toggle ()
  Toggle notification state.

  This function is deprecated, use `naughty.suspended = not naughty.suspended`.

🔗 naughty.destroy (notification, reason, keep_visible)
  Destroy notification by notification object This function is deprecated in favor of `notification:destroy(reason, keep_visible)`.

  ### Parameters:

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

  ### Returns:

  True if the popup was successfully destroyed, nil otherwise
🔗 naughty.getById (id)
  Get notification by ID

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  id |  | integer | ID of the notification

  ### Returns:

  naughty.notification or nil notification object if it was found, nil otherwise
🔗 naughty.reset_timeout (notification, new_timeout)
  Set new notification timeout.

  This function is deprecated, use `notification:reset_timeout(new_timeout)`.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  notification |  | notification | Notification object, which timer is to be reset.
  new_timeout |  | number | Time in seconds after which notification disappears.

🔗 naughty.replace_text (notification, new_title, new_text)
  Replace title and text of an existing notification.

  This function is deprecated, use `notification.message = new_text` and `notification.title = new_title`

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  notification |  | notification | Notification object, which contents are to be replaced.
  new_title |  | string | New title of notification. If not specified, old title remains unchanged.
  new_text |  | string | New text of notification. If not specified, old text remains unchanged.

  ### Returns:

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

  This function is deprecated, create notification objects instead:

  local notif = naughty.notification(args)

  ### Parameters:

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

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  args |  | table | The argument table containing any of the arguments below. | Not applicable
  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 | integer | Delay in seconds after which hovered popup disappears. | Undefined
  screen | Optional | integer or screen | Target screen for the notification. | `awful.screen.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 | Notification font. | ``beautiful.notification_font` or `beautiful.font` or `awesome.font``
  icon | Optional | string | 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 | string | 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
  replaces_id | Optional | integer | Replace the notification with the given ID. | 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:

  optional table The notification object, or nil in case a notification was not displayed.

  ### Usage:

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

## Tables

🔗 naughty.config
  Naughty configuration - a table containing common popup settings.

  The callback has the follwing format:

  naughty.config.notify_callback = function(args) args.text = 'prefix: ' .. args.text return args end

  ### Fields:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  padding | Optional | integer | Space between popups and edge of the workarea. | `beautiful.xresources.apply_dpi(4)`
  spacing | Optional | integer | Spacing between popups. | `beautiful.xresources.apply_dpi(1)`
  icon_dirs | Optional | table | List of directories that will be checked by `getIcon()`. | `{"/usr/share/pixmaps/"}`
  icon_formats | Optional | table | List of formats that will be checked by `getIcon()`. | `{ "png"`
  notify_callback | Optional | function | Callback used to modify or reject notifications, e.g. To reject a notification return `nil` from the callback. If the notification is a freedesktop notification received via DBUS, you can access the freedesktop hints via `args.freedesktop_hints` if any where specified. | Undefined
  presets |  | table | Notification presets. See `config.presets`. | Not applicable
  defaults |  | table | Default values for the params to `naughty.notification{}`. These can optionally be overridden by specifying a preset. See `config.defaults`. | Not applicable

🔗 naughty.config.presets
  Notification presets for naughty.notify. This holds presets for different purposes. A preset is a table of any parameters for `naughty.notification{}`, overriding the default values (naughty.config.defaults).

  You have to pass a reference of a preset in your `naughty.notification{}` as the preset argument.

  The presets `"low"`, `"normal"` and `"critical"` are used for notifications over DBUS.

  ### Fields:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  low |  | table | The preset for notifications with low urgency level. | Not applicable
  timeout | Optional | integer |  | `5`
  normal | Optional | table | The default preset for every notification without a preset that will also be used for normal urgency level. | `{}`
  ok |  | table |  | Not applicable
  bg | Optional | string |  | `"#00bb00"`
  fg | Optional | string |  | `"#ffffff"`
  timeout | Optional | integer |  | `5`
  critical |  | table | The preset for notifications with a critical urgency level. | Not applicable
  bg | Optional | string |  | `"#ff0000"`
  fg | Optional | string |  | `"#ffffff"`
  timeout | Optional | integer |  | `0`
  info |  | table |  | Not applicable
  bg | Optional | string |  | `"#0000ff"`
  fg | Optional | string |  | `"#ffffff"`
  timeout | Optional | integer |  | `5`
  warn |  | table |  | Not applicable
  bg | Optional | string |  | `"#ffaa00"`
  fg | Optional | string |  | `"#00000"`
  timeout | Optional | integer |  | `5`

🔗 naughty.config.defaults
  Defaults for naughty.notify.

  ### Fields:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  timeout | Optional | integer |  | `5`
  text | Optional | string |  | `""`
  screen | Optional | integer |  | `awful.screen.focused()`
  ontop | Optional | boolean |  | `true`
  margin | Optional | integer |  | `beautiful.xresources.apply_dpi(5)`
  border_width | Optional | integer |  | `beautiful.xresources.apply_dpi(1)`
  position | Optional | string |  | `"top_right"`

🔗 naughty.notification_closed_reason
  The reason why a notification is to be closed.

  See [the specification](https://specifications.freedesktop.org/notification-spec/latest/protocol.html#id-1.10.4.2.4) for more details.

  ### Fields:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  too_many_on_screen | Optional | number |  | `-2`
  silent | Optional | number |  | `-1`
  expired | Optional | number |  | `1`
  dismissed_by_user | Optional | number |  | `2`
  dismissed_by_command | Optional | number |  | `3`
  undefined | Optional | number |  | `4`

generated by LDoc 1.5.0