Module naughty - awesome API documentation

# Module `naughty`

Notification library

### Info:

- Copyright: 2008 koniu
- Author: koniu <gkusnierz@gmail.com>

## Functions

is_suspended () | Notification state
suspend () | Suspend notifications
resume () | Resume notifications
toggle () | Toggle notification state
destroy (notification, reason[, keep_visible=false]) | Destroy notification by notification object
destroy_all_notifications (screens, reason) | Destroy all notifications on given screens.
getById (id) | Get notification by ID
get_next_notification_id () | Increase notification ID by one
reset_timeout (notification, new_timeout) | Set new notification timeout.
replace_text (notification, new_title, new_text) | Replace title and text of an existing notification.
notify (args) | Create a notification.

## Theme variables

beautiful.notification_font | Notifications font.
beautiful.notification_bg | Notifications background color.
beautiful.notification_fg | Notifications foreground color.
beautiful.notification_border_width | Notifications border width.
beautiful.notification_border_color | Notifications border color.
beautiful.notification_shape | Notifications shape.
beautiful.notification_opacity | Notifications opacity.
beautiful.notification_margin | Notifications margin.
beautiful.notification_width | Notifications width.
beautiful.notification_height | Notifications height.
beautiful.notification_max_width | Notifications maximum width.
beautiful.notification_max_height | Notifications maximum height.
beautiful.notification_icon_size | Notifications icon size.

## Tables

config | Naughty configuration - a table containing common popup settings.
config.presets | Notification presets for naughty.notify.
config.defaults | Defaults for naughty.notify.
notifications | Index of notifications per screen and position.

## Functions

Methods

is_suspended ()
  Notification state
suspend ()
  Suspend notifications
resume ()
  Resume notifications
toggle ()
  Toggle notification state
destroy (notification, reason[, keep_visible=false])
  Destroy notification by notification object
  - notification Notification object to be destroyed
  - reason One of the reasons from notificationClosedReason
  - keep_visible If true, keep the notification visible (default false)

  ### Returns:

  True if the popup was successfully destroyed, nil otherwise
destroy_all_notifications (screens, reason)
  Destroy all notifications on given screens.
  - screens table Table of screens on which notifications should be destroyed. If nil, destroy notifications on all screens.
  - reason naughty.notificationClosedReason Reason for closing notifications.

  ### Returns:

  true or nil True if all notifications were successfully destroyed, nil otherwise.
getById (id)
  Get notification by ID
  - id ID of the notification

  ### Returns:

  notification object if it was found, nil otherwise
get_next_notification_id ()
  Increase notification ID by one
reset_timeout (notification, new_timeout)
  Set new notification timeout.
  - notification notification Notification object, which timer is to be reset.
  - new_timeout number Time in seconds after which notification disappears.

  ### Returns:

  None.
replace_text (notification, new_title, new_text)
  Replace title and text of an existing notification.
  - 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.
notify (args)
  Create a notification.
  - args The argument table containing any of the arguments below.
    - text string Text of the notification. (default "")
    - title string Title of the notification. (optional)
    - timeout integer Time in seconds after which popup expires. Set 0 for no timeout. (default 5)
    - hover_timeout integer Delay in seconds after which hovered popup disappears. (optional)
    - screen integer or screen Target screen for the notification. (default focused)
    - position string Corner of the workarea displaying the popups. Values: `"top_right"`, `"top_left"`, `"bottom_left"`, `"bottom_right"`, `"top_middle"`, `"bottom_middle"`. (default "top_right")
    - ontop boolean Boolean forcing popups to display on top. (default true)
    - height integer Popup height. (default `beautiful.notification_height` or auto)
    - width integer Popup width. (default `beautiful.notification_width` or auto)
    - max_height integer Popup maximum height. (default `beautiful.notification_max_height` or auto)
    - max_width integer Popup maximum width. (default `beautiful.notification_max_width` or auto)
    - font string Notification font. (default `beautiful.notification_font` or `beautiful.font` or `awesome.font`)
    - icon string Path to icon. (optional)
    - icon_size integer Desired icon size in px. (optional)
    - fg string Foreground color. (default `beautiful.notification_fg` or `beautiful.fg_focus` or `'#ffffff'`)
    - bg string Background color. (default `beautiful.notification_fg` or `beautiful.bg_focus` or `'#535d6c'`)
    - border_width integer Border width. (default `beautiful.notification_border_width` or 1)
    - border_color string Border color. (default `beautiful.notification_border_color` or `beautiful.border_focus` or `'#535d6c'`)
    - shape gears.shape Widget shape. (default `beautiful.notification_shape`)
    - opacity gears.opacity Widget opacity. (default `beautiful.notification_opacity`)
    - margin gears.margin Widget margin. (default `beautiful.notification_margin`)
    - run func 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.notificationClosedReason.dismissedByUser)` from there to dismiss the notification yourself. (optional)
    - destroy func Function to run when notification is destroyed. (optional)
    - preset table Table with any of the above parameters. Note: Any parameters specified directly in args will override ones defined in the preset. (optional)
    - replaces_id int Replace the notification with the given ID. (optional)
    - callback func 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. (optional)
    - actions table Mapping that maps a string to a callback when this action is selected. (optional)
    - ignore_suspend boolean If set to true this notification will be shown even if notifications are suspended via naughty.suspend. (default false)

  ### Returns:

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

  ### Usage:

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

## Theme variables

beautiful.notification_font
  Notifications font.

  ### Type:

  - notification_font string or lgi.Pango.FontDescription
beautiful.notification_bg
  Notifications background color.

  ### Type:

  - notification_bg color
beautiful.notification_fg
  Notifications foreground color.

  ### Type:

  - notification_fg color
beautiful.notification_border_width
  Notifications border width.

  ### Type:

  - notification_border_width int
beautiful.notification_border_color
  Notifications border color.

  ### Type:

  - notification_border_color color
beautiful.notification_shape
  Notifications shape.

  ### Type:

  - notification_shape gears.shape (optional)

  ### See also:

  gears.shape
beautiful.notification_opacity
  Notifications opacity.

  ### Type:

  - notification_opacity int (optional)
beautiful.notification_margin
  Notifications margin.

  ### Type:

  - notification_margin int
beautiful.notification_width
  Notifications width.

  ### Type:

  - notification_width int
beautiful.notification_height
  Notifications height.

  ### Type:

  - notification_height int
beautiful.notification_max_width
  Notifications maximum width.

  ### Type:

  - notification_max_width int
beautiful.notification_max_height
  Notifications maximum height.

  ### Type:

  - notification_max_height int
beautiful.notification_icon_size
  Notifications icon size.

  ### Type:

  - notification_icon_size int

## Tables

config
  Naughty configuration - a table containing common popup settings.

  ### Fields:

  - padding int Space between popups and edge of the workarea. (default apply_dpi(4))
  - spacing int Spacing between popups. (default apply_dpi(1))
  - icon_dirs table List of directories that will be checked by `getIcon()`. (default {"/usr/share/pixmaps/"})
  - icon_formats table List of formats that will be checked by `getIcon()`. (default { "png")
  - notify_callback function Callback used to modify or reject notifications, e.g.

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

    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. (optional)

  - presets table Notification presets. See config.presets.
  - defaults table Default values for the params to `notify()`. These can optionally be overridden by specifying a preset. See config.defaults.
config.presets
  Notification presets for naughty.notify. This holds presets for different purposes. A preset is a table of any parameters for `notify()`, overriding the default values (`naughty.config.defaults`).

  You have to pass a reference of a preset in your `notify()` as the `preset` argument.

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

  ### Fields:

  - low The preset for notifications with low urgency level.
    - timeout int (default 5)
  - normal table The default preset for every notification without a preset that will also be used for normal urgency level. (default empty)
  - critical The preset for notifications with a critical urgency level.
    - bg string (default "#ff0000")
    - fg string (default "#ffffff")
    - timeout string (default 0)
config.defaults
  Defaults for naughty.notify.

  ### Fields:

  - timeout int (default 5)
  - text string (default "")
  - screen int Defaults to `awful.screen.focused`. (optional)
  - ontop boolean (default true)
  - margin int (default apply_dpi(5))
  - border_width int (default apply_dpi(1))
  - position string (default "top_right")
notifications
  Index of notifications per screen and position. See config table for valid 'position' values. Each element is a table consisting of:

  ### Fields:

  - box Wibox object containing the popup
  - height Popup height
  - width Popup width
  - die Function to be executed on timeout
  - id Unique notification id based on a counter

generated by LDoc 1.5.0 Last updated 2024-12-21 21:41:42