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:

Copyright: 2008 koniu
Originally authored by: koniu <gkusnierz@gmail.com>
(Full contributors list available on our github project)

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

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

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:

added

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:

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:

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:

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.

Arguments:

notification table The naughty.notification object. This is currently either "new" or "removed".
context string Why is the signal sent.

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

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

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

awesome

Contents

Libraries

Core components

Input handling

Declarative rules

Widgets

Widget containers

Widget layouts

Popups and bars

Utility libraries

Theme related libraries

Client tiling

Sample files

Classes

Documentation

Module: naughty

Info:

Functions

Static module functions

Object properties

Signals

Request handlers

Deprecated functions

Tables

Functions

Parameters:

Usage:

Parameters:

Parameters:

Returns:

Static module functions

Parameters:

Returns:

See also:

Parameters:

Returns:

Object properties

Emit signals:

Emit signals:

Emit signals:

Emit signals:

Emit signals:

Emit signals:

Emit signals:

Signals

Arguments:

Arguments:

Arguments:

Arguments:

Arguments:

Arguments:

Arguments:

See also:

Arguments:

Request handlers

Deprecated functions

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Parameters:

Returns:

Parameters:

Returns:

Usage:

Tables

Fields:

Fields:

Fields:

Fields:

Fields:

Module: `naughty`