# 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) | Destroy notification by notification object
getById (id) | Get notification by ID
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.

## 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)
  Destroy notification by notification object
  - notification Notification object to be destroyed
  - reason One of the reasons from notificationClosedReason

  ### Returns:

  True if the popup was successfully destroyed, nil otherwise
getById (id)
  Get notification by ID
  - id ID of the notification

  ### Returns:

  notification object if it was found, nil otherwise
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 int Time in seconds after which popup expires. Set 0 for no timeout. (default 5)
    - hover_timeout int 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 bool Boolean forcing popups to display on top. (default true)
    - height int Popup height. (default auto)
    - width int Popup width. (default auto)
    - font string Notification font. (default beautiful.font or awesome.font)
    - icon string Path to icon. (optional)
    - icon_size int Desired icon size in px. (optional)
    - fg string Foreground color. (default `beautiful.fg_focus` or `'#ffffff'`)
    - bg string Background color. (default `beautiful.bg_focus` or `'#535d6c'`)
    - border_width int Border width. (default 1)
    - border_color string Border color. (default `beautiful.border_focus` or `'#535d6c'`)
    - 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)

  ### 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 })

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

    (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.4.6 Last updated 2017-01-20 01:17:18