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:

Functions

connect_signal (name, func) Connect a global signal on the notification engine.
emit_signal (name, ...) Emit a notification signal.
disconnect_signal (name, func) Disconnect a signal from a source.
destroy_all_notifications (screens, reason) Destroy all notifications on given screens.
get_by_id (id) Get notification by ID

Object properties

suspended The global suspension state.
expiration_paused Do not allow notifications to auto-expire.

Signals

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.

Deprecated functions

is_suspended [deprecated] Notification state.
suspend [deprecated] Suspend notifications.
resume [deprecated] Resume notifications.
toggle [deprecated] Toggle notification state.
destroy [deprecated] Destroy notification by notification object
getById [deprecated] Get notification by ID
reset_timeout [deprecated] Set new notification timeout.
replace_text [deprecated] Replace title and text of an existing notification.
notify [deprecated] 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.
notification_closed_reason The reason why a notification is to be closed.
notifications Index of notifications per screen and position.


Functions

Methods
connect_signal (name, func)
Connect a global signal on the notification engine.

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

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

  • name string The name of the signal
  • func function The function to attach

Usage:

    naughty.connect_signal("added", function(notif)
       -- do something
    end)
emit_signal (name, ...)
Emit a notification signal.
  • name string The signal name.
  • ... The signal callback arguments
disconnect_signal (name, func)
Disconnect a signal from a source.
  • name string The name of the signal
  • func function The attached function

Returns:

    boolean If the disconnection was successful
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.notification_closed_reason Reason for closing notifications.

Returns:

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

See also:

get_by_id (id)
Get notification by ID
  • id ID of the notification

Returns:

    notification object if it was found, nil otherwise

Object properties

suspended
The global suspension state.

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

Type:

  • boolean
expiration_paused
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.

Type:

  • boolean (default false)

Signals

added
Emitted when a notification is created.

Arguments:

destroyed
Emitted when a notification is destroyed.

Arguments:

request::display

Emitted when a notification has to be displayed.

To add an handler, use:

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

Arguments:

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

Arguments:

Deprecated functions

is_suspended [deprecated]
Notification state.

This function is deprecated, use naughty.suspended.

suspend [deprecated]
Suspend notifications.

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

resume [deprecated]
Resume notifications.

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

toggle [deprecated]
Toggle notification state.

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

destroy [deprecated]
Destroy notification by notification object This function is deprecated in favor of notification:destroy(reason, keep_visible).

param:

getById [deprecated]
Get notification by ID

param:

  • id ID of the notification
reset_timeout [deprecated]
Set new notification timeout.

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

param:

  • notification notification Notification object, which timer is to be reset.
  • new_timeout number Time in seconds after which notification disappears.
replace_text [deprecated]
Replace title and text of an existing notification.

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

param:

notify [deprecated]

Create a notification.

This function is deprecated, create notification objects instead:

local notif = naughty.notification(args)

param:

  • 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 `beautiful.notification_height` or auto)
    • width int Popup width. (default `beautiful.notification_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 int 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 int 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.notification_closed_reason.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 A list of naughty.actions. (optional)
    • ignore_suspend bool If set to true this notification will be shown even if notifications are suspended via naughty.suspend. (default false)

Usage:

    naughty.notify({ title = "Achtung!", message = "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
    

    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.
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")
notification_closed_reason
The reason why a notification is to be closed. See the specification for more details.

Fields:

  • silent number
  • expired number
  • dismissed_by_user number
  • dismissed_by_command number
  • undefined number
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 2030-01-01 00:00:00