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
  • Author: Emmanuel Lepage Vallee

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]) Destroy notification by notification object.
:reset_timeout (new_timeout) Set new notification timeout.
:append_actions (new_actions) Add more actions to the notification.
:emit_signal (name, ...) Emit a signal.
:connect_signal (name, func) Connect to a signal.
:weak_connect_signal (name, func) Connect to a signal weakly.

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_focus or '#535d6c'] args.border_color Border color.

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

Object properties

title (string)
Title of the notification.

Usage example

timeout (number)
Time in seconds after which popup expires. Set 0 for no timeout.
urgency (string)

The notification urgency level.

The default urgency levels are:

  • low
  • normal
  • critical
category (string or nil)
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
deviceA generic device-related notification that doesn’t fit into any other category.
device.addedA device, such as a USB device, was added to the system.
device.errorA device had some kind of error.
device.removedA device, such as a USB device, was removed from the system.
emailA generic e-mail-related notification that doesn’t fit into any other category.
email.arrivedA new e-mail notification.
email.bouncedA notification stating that an e-mail has bounced.
imA generic instant message-related notification that doesn’t fit into any other category.
im.errorAn instant message error notification.
im.receivedA received instant message notification.
networkA generic network notification that doesn’t fit into any other category.
network.connectedA 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.disconnectedA network disconnected notification. This should not be confused with
device.removed for disconnected network devices.
network.errorA network-related or connection-related error.
presenceA generic presence change notification that doesn’t fit into any other category,
such as going away or idle.
presence.offlineAn offline presence change notification.
presence.onlineAn online presence change notification.
transferA generic file transfer or download notification that doesn’t fit into any other category.
transfer.completeA file transfer or download complete notification.
transfer.errorA file transfer or download error.
resident (boolean)
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.

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.

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

See also:

ontop (boolean)
Boolean forcing popups to display on top.
height (number)

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

See also:

width (number)
Popup width.

See also:

font (string)
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'
    }
icon (string or surface)

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

See also:

icon_size (number)
Desired icon size in px.
app_icon (string)
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.

image (string or surface)
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).

images (nil or table)
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.

fg (string or color or pattern)
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’).run_delayed_calls_now()

See also:

bg (string or color or pattern)
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’).run_delayed_calls_now()

See also:

border_width (number)
Border width.

See also:

border_color (string)
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’).run_delayed_calls_now()

See also:

shape (gears.shape)

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’).run_delayed_calls_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
opacity (number)
Widget opacity.

Type constraints:

  • opacity number Between 0 to 1.
margin (number or table)
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’).run_delayed_calls_now()

See also:

preset (table)
Table with any of the above parameters. args will override ones defined in the preset.
callback (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.
actions (table)
A table containing strings that represents actions to buttons.

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

ignore (boolean)
Ignore this notification, do not display.

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

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

This is always equal to naughty.suspended

is_expired (boolean)
If the notification is expired.

See also:

auto_reset_timeout (boolean)
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.

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

app_name (string)
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.

widget_template (table)
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.

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.

See also:

run (function)
Function to run on left click.

Use the signals rather than this.

See also:

destroy (function)
Function to run when notification is destroyed.

Use the signals rather than this.

See also:

Object methods

:destroy (reason[, keep_visible=false])
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:

    True if the popup was successfully destroyed, false otherwise
: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:

:emit_signal (name, ...)
Emit a signal.

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

See also:

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.

See also:

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.

See also:

generated by LDoc 1.4.6 Last updated 2030-01-01 00:00:00