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

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

See also:


Click to display more

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

See also:


Click to display more

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.

See also:


Click to display more

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.

See also:


Click to display more

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

See also:


Click to display more

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

See also:


Click to display more

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

See also:


Click to display more

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

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

See also:


Click to display more

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.

See also:


Click to display more

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:

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.

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

See also:


Click to display more

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:

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

See also:

:deny (permission, context)
Deny 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.

See also:

:emit_signal (name, ...) · Inherited from gears.object
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) · 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.

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