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 <[email protected]>
(Full contributors list available on our github project)

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

Parameters:

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

Returns:

naughty.notification or nil

🔗 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

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:

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

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

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.

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

🔗 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	integer	Time in seconds after which popup expires. Set 0 for no timeout.	`5`
hover_timeout	Optional	integer	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	boolean	Boolean forcing popups to display on top.	`true`
height	Optional	integer	Popup height.	`beautiful.notification_height` or auto
width	Optional	integer	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	integer	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	integer	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	boolean	If set to true this notification will be shown even if notifications are suspended via naughty.suspend.	`false`

Returns:

optional table

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)	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)	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`

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

awesome

Contents

Libraries

Core components

Input handling

Declarative rules

Widgets

Widget containers

Widget layouts

Popups and bars

Utility libraries

Theme related libraries

Sample files

Classes

Documentation

Module: naughty

Info:

Static module functions

Object properties

Signals

Request handlers

Deprecated functions

Tables

Static module functions

Parameters:

Returns:

See also:

Parameters:

Returns:

Parameters:

Usage:

Parameters:

Parameters:

Returns:

Object properties

Constraints:

Emit signals:

Emit signals:

Constraints:

Emit signals:

Constraints:

Emit signals:

Constraints:

Constraints:

Emit signals:

Constraints:

Emit signals:

Constraints:

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:

Module: `naughty`