Module: `naughty.notification`

A notification object.

This class creates individual notification objects that can be manipulated to extend the default behavior.

This class doesn't define the actual widget, but is rather intended as a data object to hold the properties. All examples assume the default widgets, but the whole implementation can be replaced.

Usage example

Info:

Copyright: 2008 koniu,2017 Emmanuel Lepage Vallee
Originally authored by: Emmanuel Lepage Vallee
(Full contributors list available on our github project)

Constructors

naughty.notification (args[, opt=""])

Create a notification.

Object properties

title	string	Title of the notification.
timeout	number	Time in seconds after which popup expires.
urgency	string	The notification urgency level.
category	string or nil	The notification category.
resident	boolean	True if the notification should be kept when an action is pressed.
hover_timeout	number	Delay in seconds after which hovered popup disappears.
screen	screen	Target screen for the notification.
position	string	Corner of the workarea displaying the popups.
ontop	boolean	Boolean forcing popups to display on top.
height	number	Popup height.
width	number	Popup width.
font	string	Notification font.
icon	string or surface	"All in one" way to access the default image or icon.
icon_size	number	Desired icon size in px.
app_icon	string	The icon provided in the app_icon field of the DBus notification.
image	string or surface	The notification image.
images	nil or table	The notification (animated) images.
fg	string or color or pattern	Foreground color.
bg	string or color or pattern	Background color.
border_width	number	Border width.
border_color	string	Border color.
shape	gears.shape	Widget shape.
opacity	number	Widget opacity.
margin	number or table	Widget margin.
preset	table	Table with any of the above parameters.
callback	function	Function that will be called with all arguments.
actions	table	A table containing strings that represents actions to buttons.
ignore	boolean	Ignore this notification, do not display.
suspended	boolean	Tell if the notification is currently suspended (read only).
is_expired	boolean	If the notification is expired.
auto_reset_timeout	boolean	If the timeout needs to be reset when a property changes.
clients	table	A list of clients associated with this notification.
max_width	number	The maximum popup width.
app_name	string	The application name specified by the notification.
widget_template	table	The widget template used to represent the notification.

Deprecated object properties

text	string	Text of the notification.
run	function	Function to run on left click.
destroy	function	Function to run when notification is destroyed.

Object methods

:destroy (reason[, keep_visible=false]) -> boolean	Destroy notification by notification object.
:reset_timeout (new_timeout)	Set new notification timeout.
:append_actions (new_actions)	Add more actions to the notification.
:grant (permission, context)	Grant a permission for a notification.
:deny (permission, context)	Deny a permission for a notification
:emit_signal (name, ...)	Emit a signal.	Inherited from gears.object
:connect_signal (name, func)	Connect to a signal.	Inherited from gears.object
:weak_connect_signal (name, func)	Connect to a signal weakly.	Inherited from gears.object

Signals

destroyed

Emitted when the notification is destroyed.

Theme variables

beautiful.notification_font	string or lgi.Pango.FontDescription	Notifications font.
beautiful.notification_bg	color	Notifications background color.
beautiful.notification_fg	color	Notifications foreground color.
beautiful.notification_border_width	int	Notifications border width.
beautiful.notification_border_color	color	Notifications border color.
beautiful.notification_shape	gears.shape	Notifications shape.
beautiful.notification_opacity	int	Notifications opacity.
beautiful.notification_margin	int	The margins inside of the notification widget (or popup).
beautiful.notification_width	int	Notifications width.
beautiful.notification_height	int	Notifications height.
beautiful.notification_spacing	number	The spacing between the notifications.

Constructors

naughty.notification (args[, opt=""])

Create a notification.

Parameters:

args The argument table containing any of the arguments below.
- 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)
- 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)
opt string =beautiful.notification_border_color or beautiful.border_color_active or '#535d6c'] args.border_color Border color.

Returns:

optional table

Usage:

naughty.notify({ title = "Achtung!", message = "You're idling", timeout = 0 })

Object properties

title string · 1 signal

Title of the notification.

Usage example

Click to display more

Emit signals:

property::title When the title value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value title The new value affected to the property.

timeout number · 1 signal

Time in seconds after which popup expires. Set 0 for no timeout.
Click to display more

Emit signals:

property::timeout When the timeout value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value timeout The new value affected to the property.

urgency string · 1 signal

The notification urgency level.

The default urgency levels are:

low
normal
critical

Click to display more

Emit signals:

property::urgency When the urgency value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value string The new value affected to the property.

category string or nil · 1 signal

The notification category.

The category should be named using the x-vendor.class.name naming scheme or use one of the default categories:

Name	Description
device	A generic device-related notification that doesn't fit into any other category.
device.added	A device, such as a USB device, was added to the system.
device.error	A device had some kind of error.
device.removed	A device, such as a USB device, was removed from the system.
email	A generic e-mail-related notification that doesn't fit into any other category.
email.arrived	A new e-mail notification.
email.bounced	A notification stating that an e-mail has bounced.
im	A generic instant message-related notification that doesn't fit into any other category.
im.error	An instant message error notification.
im.received	A received instant message notification.
network	A generic network notification that doesn't fit into any other category.
network.connected	A network connection notification, such as successful sign-on to a network service. This should not be confused with device.added for new network devices.
network.disconnected	A network disconnected notification. This should not be confused with device.removed for disconnected network devices.
network.error	A network-related or connection-related error.
presence	A generic presence change notification that doesn't fit into any other category, such as going away or idle.
presence.offline	An offline presence change notification.
presence.online	An online presence change notification.
transfer	A generic file transfer or download notification that doesn't fit into any other category.
transfer.complete	A file transfer or download complete notification.
transfer.error	A file transfer or download error.

Click to display more

Emit signals:

property::category When the category value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value category The new value affected to the property.

resident boolean · 1 signal

True if the notification should be kept when an action is pressed.

By default, invoking an action will destroy the notification. Some actions, like the "Snooze" action of alarm clock, will cause the notification to be updated with a date further in the future.

Click to display more

Emit signals:

property::resident When the resident value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value boolean The new value affected to the property.

hover_timeout number · 1 signal

Delay in seconds after which hovered popup disappears.
Click to display more

Emit signals:

property::hover_timeout When the hover_timeout value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value number The new value affected to the property.

screen screen · 1 signal

Target screen for the notification.
Click to display more

Emit signals:

property::screen When the screen value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value screen The new value affected to the property.

position string · 1 signal

Corner of the workarea displaying the popups.

The possible values are:

*top_right*
*top_left*
*bottom_left*
*bottom_right*
*top_middle*
*bottom_middle*
middle

Usage example

for _, pos in ipairs {
    "top_left"   , "top_middle"   , "top_right",
    "bottom_left", "bottom_middle", "bottom_right",
} do
    for i=1, 3 do
        naughty.notification {
            position = pos,
            title    = pos .. " " .. i,
            message  = ever_longer_messages(i)
        }
    end
end

Emit signals:

property::position When the position value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value string The new value affected to the property.

ontop boolean

Boolean forcing popups to display on top.

height number · 1 signal

Popup height.

Usage example

for _, pos in ipairs {
    "top_left"   , "top_middle"   , "top_right",
    "bottom_left", "bottom_middle", "bottom_right",
} do
    for i=1, 2 do
        naughty.notification {
            position = pos,
            title    = pos .. " " .. i,
            width    = 50*i,
            height   = 50*i,
            message  = "This is a very, very, very, "..
                "very, very very long message",
        }
    end
end

Emit signals:

property::height When the height value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value number The new value affected to the property.

width number · 1 signal

Popup width.

Emit signals:

property::width When the width value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value number The new value affected to the property.

font string · 1 signal

Notification font.

Usage example

Usage:

local text = [[An <b>important</b>;<i>notification</i>;]]

require("naughty").notification {
    title        = "Hello world!",
    text         = text,
    icon         = beautiful.icon,
    bg           = "#0000ff",
    fg           = "#ff0000",
    font         = "verdana 14",
    border_width = 1,
    border_color = "#ff0000"
}

Click to display more

Emit signals:

property::font When the font value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value string The new value affected to the property.

icon string or surface · 1 signal

"All in one" way to access the default image or icon.

A notification can provide a combination of an icon, a static image, or if enabled, a looping animation. Add to that the ability to import the icon information from the client or from a .desktop file, there is multiple conflicting sources of "icons".

On the other hand, the vast majority of notifications don't multiple or ambiguous sources of icons. This property will pick the first of the following.

The image.
The app_icon.
The icon from a client with normal type.
The icon of a client with dialog type.

Emit signals:

property::icon When the icon value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value icon The new value affected to the property.

icon_size number · 1 signal

Desired icon size in px.
Click to display more

Emit signals:

property::icon_size When the icon_size value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value number The new value affected to the property.

app_icon string · 1 signal

The icon provided in the app_icon field of the DBus notification.

This should always be either the URI (path) to an icon or a valid XDG icon name to be fetched from the theme.

Click to display more

Emit signals:

property::app_icon When the app_icon value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value string The new value affected to the property.

image string or surface · 1 signal

The notification image.

This is usually provided as a gears.surface object. The image is used instead of the app_icon by notification assets which are auto-generated or stored elsewhere than the filesystem (databases, web, Android phones, etc).

Click to display more

Emit signals:

property::image When the image value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value image The new value affected to the property.

images nil or table · 1 signal

The notification (animated) images.

Note that calling this without first setting naughty.image_animations_enabled to true will throw an exception.

Also note that there is zero support for this anywhere else in naughty and very, very few applications support this.

Click to display more

Emit signals:

property::images When the images value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value images The new value affected to the property.

fg string or color or pattern · 1 signal

Foreground color.

Usage example

-- A notification popup using the default widget_template.
naughty.connect_signal("request::display", function(n)
    naughty.layout.box {notification = n}
end)

-- Notifications as widgets for any <a href="../popups_and_bars/wibox.html#">wibox</a>/<a href="../popups_and_bars/awful.wibar.html#">awful.wibar</a>/<a href="../popups_and_bars/awful.popup.html#">awful.popup</a>
some_wibar.widget = naughty.list.notifications {}

for _, color in ipairs {"#ff0000", "#00ff00", "#0000ff"} do
    naughty.notification {
        title   = "A ".. color .." notification",
        message = "Message",
        fg      = color,
    }
end

require("gears.timer").rundelayedcalls_now()

Emit signals:

property::fg When the fg value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value fg The new value affected to the property.

bg string or color or pattern · 1 signal

Background color.

Usage example

-- A notification popup using the default widget_template.
naughty.connect_signal("request::display", function(n)
    naughty.layout.box {notification = n}
end)

-- Notifications as widgets for any <a href="../popups_and_bars/wibox.html#">wibox</a>/<a href="../popups_and_bars/awful.wibar.html#">awful.wibar</a>/<a href="../popups_and_bars/awful.popup.html#">awful.popup</a>
some_wibar.widget = naughty.list.notifications {}

for _, color in ipairs {"#ff0000", "#00ff00", "#0000ff"} do
    naughty.notification {
        title = "A ".. color .." notification",
        bg    = color,
    }
end

require("gears.timer").rundelayedcalls_now()

Emit signals:

property::bg When the bg value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value bg The new value affected to the property.

border_width number · 1 signal

Border width.
Click to display more

Emit signals:

property::border_width When the border_width value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value number The new value affected to the property.

border_color string · 1 signal

Border color.

Usage example

-- A notification popup using the default widget_template.
naughty.connect_signal("request::display", function(n)
    naughty.layout.box {notification = n}
end)

-- Notifications as widgets for any <a href="../popups_and_bars/wibox.html#">wibox</a>/<a href="../popups_and_bars/awful.wibar.html#">awful.wibar</a>/<a href="../popups_and_bars/awful.popup.html#">awful.popup</a>
some_wibar.widget = naughty.list.notifications {}

for bw, color in ipairs {"#ff0000", "#00ff00", "#0000ff"} do
    naughty.notification {
        title        = "A ".. color .." notification",
        border_color = color,
        border_width = bw*2,
    }
end

require("gears.timer").rundelayedcalls_now()

Emit signals:

property::border_color When the border_color value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value string The new value affected to the property.

shape gears.shape · 1 signal

Widget shape.

Note that when using a custom request::display handler or naughty.rules, choosing between multiple shapes depending on the content can be done using expressions like:

-- The notification object is called <code>n</code>
shape = #n.actions > 0 and
    gears.shape.rounded_rect or gears.shape.rounded_bar,

Usage example

-- A notification popup using the default widget_template.
naughty.connect_signal("request::display", function(n)
    naughty.layout.box {notification = n}
end)

-- Notifications as widgets for any <a href="../popups_and_bars/wibox.html#">wibox</a>/<a href="../popups_and_bars/awful.wibar.html#">awful.wibar</a>/<a href="../popups_and_bars/awful.popup.html#">awful.popup</a>
some_wibar.widget = naughty.list.notifications {}

local shapes = {
    gears.shape.octogon,
    gears.shape.rounded_rect,
    gears.shape.rounded_bar
}

for idx=1, 3 do
    naughty.notification {
        title        = "A notification",
        border_color = "#0000ff",
        border_width = idx*2,
        shape        = shapes[idx],
    }
end

require("gears.timer").rundelayedcalls_now()

Usage example

local text = [[An <b>important</b>;   <i>notification</i>;   ]]

local shapes = {
    gears.shape.rounded_rect,
    gears.shape.hexagon,
    gears.shape.octogon,
    function(cr, w, h)
        return gears.shape.infobubble(cr, w, h, 20, 10, w/2 - 10)
    end
}

for _, s in ipairs(shapes) do
    naughty.notify {
        title        = "Hello world!",
        text         = text,
        icon         = beautiful.icon,
        shape        = s,
        border_width = 3,
        border_color = beautiful.bg_highlight,
        margin       = 15,
    }
end

Click to display more

Emit signals:

property::shape When the shape value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value shape The new value affected to the property.

opacity number · 1 signal

Widget opacity.

Type constraints:

opacity number Between 0 to 1.

Click to display more

Emit signals:

property::opacity When the opacity value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value opacity The new value affected to the property.

margin number or table · 1 signal

Widget margin.

Usage example

-- A notification popup using the default widget_template.
naughty.connect_signal("request::display", function(n)
    naughty.layout.box {notification = n}
end)

-- Notifications as widgets for any <a href="../popups_and_bars/wibox.html#">wibox</a>/<a href="../popups_and_bars/awful.wibar.html#">awful.wibar</a>/<a href="../popups_and_bars/awful.popup.html#">awful.popup</a>
some_wibar.widget = naughty.list.notifications {
    base_layout = wibox.widget {
         spacing = beautiful.notification_spacing,
         layout  = wibox.layout.fixed.horizontal
    },
}

for margin = 10, 20, 5 do
    naughty.notification {
        title        = "A notification",
        margin       = margin,
        border_width = 1,
        border_color = "#ff0000",
    }
end

require("gears.timer").rundelayedcalls_now()

Emit signals:

property::margin When the margin value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value margin The new value affected to the property.

preset table · 1 signal

Table with any of the above parameters. args will override ones defined in the preset.
Click to display more

Emit signals:

property::preset When the preset value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value table The new value affected to the property.

callback function · 1 signal

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.
Click to display more

Emit signals:

property::callback When the callback value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value function The new value affected to the property.

actions table · 1 signal

A table containing strings that represents actions to buttons.

The table key (a number) is used by DBus to set map the action.

Click to display more

Emit signals:

property::actions When the actions value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value table The new value affected to the property.

ignore boolean · 1 signal

Ignore this notification, do not display.

Note that this property has to be set in a preset or in a request::preset handler.

Click to display more

Emit signals:

property::ignore When the ignore value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value boolean The new value affected to the property.

suspended boolean · 1 signal

Tell if the notification is currently suspended (read only).

This is always equal to naughty.suspended

Click to display more

Emit signals:

property::suspended When the suspended value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value boolean The new value affected to the property.

is_expired boolean · 1 signal

If the notification is expired.

Emit signals:

property::is_expired When the is_expired value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value boolean The new value affected to the property.

auto_reset_timeout boolean · 1 signal

If the timeout needs to be reset when a property changes.

By default it fallsback to naughty.auto_reset_timeout, which itself is true by default.

Click to display more

Emit signals:

property::auto_reset_timeout When the auto_reset_timeout value changes.

self naughty.notification 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.

clients table

A list of clients associated with this notification.

When used with DBus notifications, this returns all clients sharing the PID of the notification sender. Note that this is highly unreliable. Applications that use a different process to send the notification or applications (and scripts) calling the notify-send command wont have any client.

max_width number · 1 signal

The maximum popup width.

Some notifications have overlong message, cap them to this width. Note that this is ignored by naughty.list.notifications because it delegate this decision to the layout.

Click to display more

Emit signals:

property::max_width When the max_width value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value number The new value affected to the property.

app_name string · 1 signal

The application name specified by the notification.

This can be anything. It is usually less relevant than the clients property, but can sometime be specified for remote or headless notifications. In these case, it helps to triage and detect the notification from the rules.

Click to display more

Emit signals:

property::app_name When the app_name value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value string The new value affected to the property.

widget_template table · 1 signal

The widget template used to represent the notification.

Some notifications, such as chat messages or music applications are better off with a specialized notification widget.

Click to display more

Emit signals:

property::widget_template When the widget_template value changes.

self naughty.notification The object which changed (useful when connecting many object to the same callback).
new_value table The new value affected to the property.

Deprecated object properties

text string

Text of the notification.

This exists only for the pre-AwesomeWM v4.4 new notification implementation. Please always use title.

Object methods

:destroy (reason[, keep_visible=false]) -> boolean · 1 signal

Destroy notification by notification object.

Parameters:

reason string One of the reasons from notification_closed_reason
keep_visible boolean If true, keep the notification visible (default false)

Returns:

boolean

Emit signals:

destroyed

reason integer The reason.
keep_visible boolean If the notification should be kept.

:reset_timeout (new_timeout)

Set new notification timeout.

Parameters:

new_timeout number Time in seconds after which notification disappears.

:append_actions (new_actions)

Add more actions to the notification.

Parameters:

new_actions table

:grant (permission, context)

Grant a permission for a notification.

Parameters:

permission string The permission name (just the name, no request::).
context string The reason why this permission is requested.

Parameters:

permission string The permission name (just the name, no request::).
context string The reason why this permission is requested.

Parameters:

name string The name of the signal.
... Extra arguments for the callback functions. Each connected function receives the object as first argument and then any extra arguments that are given to emit_signal().

:connect_signal (name, func) · Inherited from gears.object

Connect to a signal.

Parameters:

name string The name of the signal.
func function The callback to call when the signal is emitted.

:weak_connect_signal (name, func) · Inherited from gears.object

Connect to a signal weakly.

This allows the callback function to be garbage collected and automatically disconnects the signal when that happens.

Warning: Only use this function if you really, really, really know what you are doing.

Parameters:

name string The name of the signal.
func function The callback to call when the signal is emitted.

Signals

destroyed

Emitted when the notification is destroyed.

Arguments:

reason number Why it was destroyed
keep_visible boolean If it was kept visible.

Theme variables

beautiful.notification_font string or lgi.Pango.FontDescription

Notifications font.

beautiful.notification_bg color

Notifications background color.

beautiful.notification_fg color

Notifications foreground color.

beautiful.notification_border_width int

Notifications border width.

beautiful.notification_border_color color

Notifications border color.

beautiful.notification_shape gears.shape

Notifications shape.

awesome

Contents

Core components

Input handling

Declarative rules

Widgets

Widget containers

Widget layouts

Popups and bars

Utility libraries

Theme related libraries

Client tiling

Libraries

Sample files

Classes

Documentation

Module: naughty.notification

Info:

Constructors

Object properties

Deprecated object properties

Object methods

Signals

Theme variables

Constructors

Parameters:

Returns:

Usage:

Object properties

Emit signals:

Emit signals:

Emit signals:

Emit signals:

Emit signals:

Emit signals:

Emit signals:

See also:

Emit signals:

See also:

Emit signals:

See also:

Emit signals:

Usage:

Emit signals:

See also:

Emit signals:

Emit signals:

Emit signals:

Emit signals:

Emit signals:

See also:

Emit signals:

See also:

Emit signals:

Emit signals:

See also:

Emit signals:

Emit signals:

Type constraints:

Emit signals:

See also:

Emit signals:

Emit signals:

Emit signals:

Emit signals:

Emit signals:

Emit signals:

See also:

Emit signals:

Emit signals:

Emit signals:

Emit signals:

Emit signals:

Deprecated object properties

See also:

See also:

See also:

Object methods

Parameters:

Returns:

Module: `naughty.notification`