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:

Static module functions

naughty.destroy_all_notifications (screens, reason) -> true or nil Destroy all notifications on given screens.
naughty.get_by_id (id) -> naughty.notification or nil Get notification by ID
naughty.connect_signal (name, func) Connect a global signal on the module.
naughty.emit_signal (name, ...) Emit a module signal.
naughty.disconnect_signal (name, func) -> boolean Disconnect a signal from a source.

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

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

Deprecated functions

naughty.is_suspended () Notification state. Deprecated
naughty.suspend () Suspend notifications. Deprecated
naughty.resume () Resume notifications. Deprecated
naughty.toggle () Toggle notification state. Deprecated
naughty.destroy (notification, reason, keep_visible) Destroy notification by notification object Deprecated
naughty.getById (id) Get notification by ID Deprecated
naughty.reset_timeout (notification, new_timeout) Set new notification timeout. Deprecated
naughty.replace_text (notification, new_title, new_text) Replace title and text of an existing notification. Deprecated
naughty.notify {[args]} Create a notification. Deprecated

Tables

naughty.config Naughty configuration - a table containing common popup settings.
naughty.config.presets Notification presets for naughty.notify.
naughty.config.defaults Defaults for naughty.notify.
naughty.notification_closed_reason The reason why a notification is to be closed.


Static module functions

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

Parameters:

Name Type(s) Description
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:

notification_closed_reason The reason why a notification is to be closed. tables
🔗 naughty.get_by_id (id) -> naughty.notification or nil
Get notification by ID

Parameters:

Name Type(s) Description
id integer ID of the notification

Returns:

    naughty.notification or nil notification object if it was found, nil otherwise
🔗 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 Type(s) Description
name string The name of the signal
func function The function to attach

Usage:

    naughty.connect_signal(\"added\", function(notif)
       -- do something
    end)
🔗 naughty.emit_signal (name, ...)
Emit a module signal.

Parameters:

Name Type(s) Description
name string The signal name.
... The signal callback arguments
🔗 naughty.disconnect_signal (name, func) -> boolean
Disconnect a signal from a source.

Parameters:

Name Type(s) Description
name string The name of the signal
func function The attached function

Returns:

    boolean If the disconnection was successful

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.

Constraints:

Default value : false
Valid values : true or false.

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

Constraints:

Default value : false
Valid values : true or false.

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

Constraints:

Default value : {}
Table content : A list of naughty.notification objects.

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.

Note that using the legacy notifications is deprecated.

Constraints:

Default value : If rc.lua has a request::display section, this will be true. Otherwise it is false and the legacy notification will be used.
Valid values : true or false.
🔗 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.

Constraints:

Default value : true
Valid values : true or false.

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.

Constraints:

Default value : false
Valid values : true or false.

Click to display more

Emit signals:

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

Constraints:

Default value : false
Valid values : true or false.

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

Signals

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

Arguments:

Name Type(s) Description
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:

Name Type(s) Description
notification naughty.notification The notification object
🔗 destroyed
Emitted when a notification is destroyed.

Arguments:

Name Type(s) Description
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:

Name Type(s) Description
notification table The naughty.notification object.
context string Why is the signal sent.
args table Any arguments passed to the naughty.notify function, including, but not limited to, all naughty.notification properties.
🔗 request::preset
Emitted when a notification needs pre-display configuration.

Arguments:

Name Type(s) Description
notification table The naughty.notification object.
context string Why is the signal sent.
args table Any arguments passed to the naughty.notify function, including, but not limited to, all naughty.notification properties.
🔗 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:

Name Type(s) Description
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:

Name Type(s) Description
n notification The notification.
context string The source of the icon to look for.
hints table 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:

naughty.icon_path_handler Request handler to get the icon using the image or path. request handlers
naughty.client_icon_handler Request handler to get the icon using the clients icons. request handlers
🔗 request::screen
Emitted when the screen is not defined or being removed.

Arguments:

Name Type(s) Description
notification table The naughty.notification object. This is currently either "new" or "removed".
context string Why is the signal sent.

Request handlers

🔗 naughty.default_screen_handler ()
The default handler for request::screen.

It selects awful.screen.focused().

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

Deprecated functions

🔗 naughty.is_suspended ()
Notification state.

This function is deprecated, use naughty.suspended.

🔗 naughty.suspend ()
Suspend notifications.

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

🔗 naughty.resume ()
Resume notifications.

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

🔗 naughty.toggle ()
Toggle notification state.

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

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

Parameters:

Name Type(s) Description Default value
notification naughty.notification Notification object to be destroyed Not applicable
reason string One of the reasons from notification_closed_reason Not applicable
keep_visible Optional boolean If true, keep the notification visible false

Returns:

    True if the popup was successfully destroyed, nil otherwise
🔗 naughty.getById (id)
Get notification by ID

Parameters:

Name Type(s) Description
id integer ID of the notification

Returns:

    naughty.notification or nil notification object if it was found, nil otherwise
🔗 naughty.reset_timeout (notification, new_timeout)
Set new notification timeout.

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

Parameters:

Name Type(s) Description
notification notification Notification object, which timer is to be reset.
new_timeout number Time in seconds after which notification disappears.
🔗 naughty.replace_text (notification, new_title, new_text)
Replace title and text of an existing notification.

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

Parameters:

Name Type(s) Description
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 {[args]}

Create a notification.

This function is deprecated, create notification objects instead:

local notif = naughty.notification(args)

Parameters:

Note: This deprecated functions uses named parameters calling convention. It means you call it with {} and omit the parantheses. For example, calling this will all default argument would be notify{}. This is a Lua shortcut syntax equivalent to notify({}). args is only a placeholder name for the "lone table argument" used in named parameters calls.
Name Type(s) Description Default value
args table The argument table containing any of the arguments below. Not applicable
text Optional string Text of the notification. ""
title Optional string Title of the notification. Undefined
timeout Optional int Time in seconds after which popup expires. Set 0 for no timeout. 5
hover_timeout Optional int Delay in seconds after which hovered popup disappears. Undefined
screen Optional integer or screen Target screen for the notification. awful.screen.focused()
position Optional string Corner of the workarea displaying the popups. Values: "top_right", "top_left", "bottom_left", "bottom_right", "top_middle", "bottom_middle", "middle". "top_right"
ontop Optional bool Boolean forcing popups to display on top. true
height Optional int Popup height. `beautiful.notification_height` or auto
width Optional int Popup width. `beautiful.notification_width` or auto
font Optional string Notification font. `beautiful.notification_font` or `beautiful.font` or `awesome.font`
icon Optional string Path to icon. Undefined
icon_size Optional int Desired icon size in px. Undefined
fg Optional string Foreground color. `beautiful.notification_fg` or `beautiful.fg_focus` or `'#ffffff'`
bg Optional string Background color. `beautiful.notification_fg` or `beautiful.bg_focus` or `'#535d6c'`
border_width Optional int Border width. `beautiful.notification_border_width` or 1
border_color Optional string Border color. `beautiful.notification_border_color` or `beautiful.border_color_active` or `'#535d6c'`
shape Optional gears.shape Widget shape. `beautiful.notification_shape`
opacity Optional gears.opacity Widget opacity. `beautiful.notification_opacity`
margin Optional gears.margin Widget margin. `beautiful.notification_margin`
run Optional function 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. Undefined
destroy Optional function Function to run when notification is destroyed. Undefined
preset Optional table Table with any of the above parameters. Note: Any parameters specified directly in args will override ones defined in the preset. Undefined
replaces_id Optional integer Replace the notification with the given ID. Undefined
callback Optional function 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. Undefined
actions Optional table A list of naughty.actions. Undefined
ignore_suspend Optional bool If set to true this notification will be shown even if notifications are suspended via naughty.suspend. 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

🔗 naughty.config

Naughty configuration - a table containing common popup settings.

The callback has the follwing format:

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

Fields:

Name Type(s) Description Default value
padding Optional integer Space between popups and edge of the workarea. beautiful.xresources.apply_dpi(4)
spacing Optional integer Spacing between popups. beautiful.xresources.apply_dpi(1)
icon_dirs Optional table List of directories that will be checked by getIcon(). {"/usr/share/pixmaps/"}
icon_formats Optional table List of formats that will be checked by getIcon(). { "png"
notify_callback Optional function Callback used to modify or reject notifications, e.g. 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. Undefined
presets table Notification presets. See config.presets. Not applicable
defaults table Default values for the params to naughty.notification{}. These can optionally be overridden by specifying a preset. See config.defaults. Not applicable
🔗 naughty.config.presets
Notification presets for naughty.notify. This holds presets for different purposes. A preset is a table of any parameters for naughty.notification{}, overriding the default values (naughty.config.defaults).

You have to pass a reference of a preset in your naughty.notification{} as the preset argument.

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

Fields:

Name Type(s) Description Default value
low table The preset for notifications with low urgency level. Not applicable
timeout Optional integer 5
normal Optional table The default preset for every notification without a preset that will also be used for normal urgency level. {}
ok table Not applicable
bg Optional string "#00bb00"
fg Optional string "#ffffff"
timeout Optional integer 5
critical table The preset for notifications with a critical urgency level. Not applicable
bg Optional string "#ff0000"
fg Optional string "#ffffff"
timeout Optional integer 0
info table Not applicable
bg Optional string "#0000ff"
fg Optional string "#ffffff"
timeout Optional integer 5
warn table Not applicable
bg Optional string "#ffaa00"
fg Optional string "#00000"
timeout Optional integer 5
🔗 naughty.config.defaults
Defaults for naughty.notify.

Fields:

Name Type(s) Description Default value
timeout Optional integer 5
text Optional string ""
screen Optional integer awful.screen.focused()
ontop Optional boolean true
margin Optional integer beautiful.xresources.apply_dpi(5)
border_width Optional integer beautiful.xresources.apply_dpi(1)
position Optional string "top_right"
🔗 naughty.notification_closed_reason
The reason why a notification is to be closed.

See the specification for more details.

Fields:

Name Type(s) Description Default value
too_many_on_screen Optional number -2
silent Optional number -1
expired Optional number 1
dismissed_by_user Optional number 2
dismissed_by_command Optional number 3
undefined Optional number 4
generated by LDoc 1.4.6