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

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.
    • 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.
    • 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.
    • icon_size int Desired icon size in px.
    • 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.
    • destroy func Function to run when notification is destroyed.
    • preset table Table with any of the above parameters. Note: Any parameters specified directly in args will override ones defined in the preset.
    • replaces_id int Replace the notification with the given ID.
    • 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.
    • actions table Mapping that maps a string to a callback when this action is selected.

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
  • 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.
config.defaults
Defaults for naughty.notify .

Fields:

  • timeout int (default 5)
  • text string (default "")
  • screen int Defaults to awful.screen.focused.
  • 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.2