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

naughty.connect_signal (name, func) Connect a global signal on the module.
emit_signal (name, ...) Emit a module signal.
naughty.disconnect_signal (name, func) Disconnect a signal from a source.

Static module functions

naughty.destroy_all_notifications (screens, reason) -> true or nil Destroy all notifications on given screens.
naughty.get_by_id (id) -> () Get notification by ID

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

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

Deprecated functions

naughty.is_suspended [deprecated] Notification state.
naughty.suspend [deprecated] Suspend notifications.
naughty.resume [deprecated] Resume notifications.
naughty.toggle [deprecated] Toggle notification state.
naughty.destroy [deprecated] Destroy notification by notification object
naughty.getById [deprecated] Get notification by ID
naughty.reset_timeout [deprecated] Set new notification timeout.
naughty.replace_text [deprecated] Replace title and text of an existing notification.
naughty.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
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 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 module signal.

Parameters:

  • name string The signal name.
  • ... The signal callback arguments
naughty.disconnect_signal (name, func)
Disconnect a signal from a source.

Parameters:

  • name string The name of the signal
  • func function The attached function

Returns:

    boolean If the disconnection was successful

Static module functions

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

Parameters:

  • 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:

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

Parameters:

  • id ID of the notification

Returns:

    notification object if it was found, nil otherwise

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.

Click to display more

Emit signals:

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

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

Signal:

  • property::active

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

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.

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

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 boolean The new value affected to the property.

Signals

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

Arguments:

  • 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:

  • notification naughty.notification The notification object
destroyed
Emitted when a notification is destroyed.

Arguments:

  • 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:

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

Arguments:

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:

  • 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:

  • n notification The notification.
  • context string The source of the icon to look for.
  • hints 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:

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

Arguments:

Request handlers

default_screen_handler
The default handler for request::screen.

It selects awful.screen.focused().

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

Deprecated functions

naughty.is_suspended [deprecated]
Notification state.

This function is deprecated, use naughty.suspended.

naughty.suspend [deprecated]
Suspend notifications.

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

naughty.resume [deprecated]
Resume notifications.

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

naughty.toggle [deprecated]
Toggle notification state.

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

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

Parameters:

  • notification Notification object to be destroyed
  • reason One of the reasons from notification_closed_reason
  • keep_visible If true, keep the notification visible (default false)

Returns:

    True if the popup was successfully destroyed, nil otherwise
naughty.getById [deprecated]
Get notification by ID

Parameters:

  • id ID of the notification

Returns:

    notification object if it was found, nil otherwise
naughty.reset_timeout [deprecated]
Set new notification timeout.

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

Parameters:

  • notification notification Notification object, which timer is to be reset.
  • new_timeout number Time in seconds after which notification disappears.
naughty.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

Parameters:

  • 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 [deprecated]

Create a notification.

This function is deprecated, create notification objects instead:

local notif = naughty.notification(args)

Parameters:

  • 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", "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_color_active` 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)

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

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