Module: naughty.notification

Notification manipulation class.

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.

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]} 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 or nil Delay in seconds after which hovered popup disappears.
screen screen Target screen for the notification.
position string or nil Corner of the workarea displaying the popups.
ontop boolean Boolean forcing popups to display on top.
height number or nil Popup height.
width number or nil Popup width.
font font or nil Notification font.
icon image or nil "All in one" way to access the default image or icon.
icon_size integer or nil Desired icon size in px.
app_icon string or nil The icon provided in the app_icon field of the DBus notification.
image image or nil The notification image.
images nil or table The notification (animated) images.
fg color or nil Foreground color.
bg color or nil Background color.
border_width number or nil Border width.
border_color string or nil Border color.
shape shape or nil Widget shape.
opacity number or nil Widget opacity.
margin number or table or nil Widget margin.
preset table or nil Table with any of the above parameters.
callback function or nil 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 or nil The maximum popup width.
app_name string or nil The application name specified by the notification.
widget_template template or nil The widget template used to represent the notification.

Deprecated object properties

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

Object methods

:destroy (reason, keep_visible) -> 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]}
Create a notification.

Parameters:

Note: This constructors 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 naughty.notification{}. This is a Lua shortcut syntax equivalent to naughty.notification({}). args is only a placeholder name for the "lone table argument" used in named parameters calls.
Name Type(s) Description Default value
args Optional table The argument table containing any of the arguments below. {}
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 number Delay in seconds after which hovered popup disappears. Undefined
screen Optional integer or screen Target screen for the notification. 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 or lgi.Pango.FontDescription Notification font. `beautiful.notification_font` or `beautiful.font` or `awesome.font`
icon Optional image 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 gears.color 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
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:

    naughty.notification A new notification object.

Usage:

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

Click to display more

Consumed theme variables:

Theme variable Usage
beautiful.notification_height
beautiful.notification_width
beautiful.notification_font
beautiful.font
beautiful.notification_fg
beautiful.fg_focus
beautiful.bg_focus
beautiful.notification_border_width
beautiful.notification_border_color
beautiful.border_color_active
beautiful.notification_shape
beautiful.notification_opacity
beautiful.notification_margin

Object properties

🔗 title string · 1 signal
Title of the notification.

Constraints:

Default value : ""

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.

Constraints:

Default value : If unspecified, it can come from either the notification itself, the presets or the ruled.notification rules.
Unit : second
Negative allowed : false

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.

Constraints:

Default value : "normal"
Valid values:
"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 urgency 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.

Constraints:

Default value : nil

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.

Constraints:

Default value : false
Valid values : true or false.

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 resident The new value affected to the property.
🔗 hover_timeout number or nil · 1 signal
Delay in seconds after which hovered popup disappears.

Constraints:

Default value : nil
Unit : second
Negative allowed : false

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 hover_timeout The new value affected to the property.
🔗 screen screen · 1 signal
Target screen for the notification.

Constraints:

Default value : awful.screen.preferred()
Type description:
screen : A valid screen object such as retured by awful.screen.focused() or mouse.screen.
integer : A screen global id. Avoid using this since they are unsorted.
string : The "primary" value is also valid.

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 or nil · 1 signal

Corner of the workarea displaying the popups. 

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

Constraints:

Default value : beautiful.notification_position
Valid values:
"top_right"
"top_left"
"bottom_left"
"bottom_right"
"top_middle"
"bottom_middle"
"middle"

See also:

awful.placement.next_to Move a drawable to a relative position next to another one. (awful.placement) static module functions

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 position The new value affected to the property.

Consumed theme variables:

Theme variable Usage
beautiful.notification_position
🔗 ontop boolean
Boolean forcing popups to display on top.

Constraints:

Default value : false
Valid values : true or false.
🔗 height number or nil · 1 signal · 1 theme variable

Popup height. 

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

Constraints:

Default value : beautiful.naughty_notification_height
Type description:
nil : Fallback to the current value of beautiful.notification_height.
Unit : pixel
Negative allowed : false

See also:

width Popup width. object properties

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 height The new value affected to the property.

Consumed theme variables:

Theme variable Usage
beautiful.notification_heightFallback when height isn't set.
🔗 width number or nil · 1 signal · 1 theme variable
Popup width.

Constraints:

Default value : beautiful.naughty_notification_width
Type description:
nil : Fallback to the current value of beautiful.notification_width.
Unit : pixel
Negative allowed : false

See also:

height Popup height. object properties

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 width The new value affected to the property.

Consumed theme variables:

Theme variable Usage
beautiful.notification_widthFallback when width isn't set.
🔗 font font or nil · 1 signal
Notification font.

Constraints:

Default value : beautiful.notification_font
Type description:
string : A Pango font description.
string : An XFT string, such as "--dejavu sans mono-medium-r-normal---80-----iso10646-1".

See also:

wibox.widget.textbox.font Set a textbox font. (wibox.widget.textbox) object properties

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 font The new value affected to the property.

Consumed theme variables:

Theme variable Usage
beautiful.notification_font
🔗 icon image or nil · 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.

Constraints:

Default value : nil
Type description:
string : Interpreted as a path to an image file.
string : A valid SVG content.
cairo : A cairo image surface: Directly used as-is.
librsvg : A librsvg handle object: Directly used as-is.
nil : Unset the image.

See also:

app_icon The icon provided in the app_icon field of the DBus notification. object properties
image The notification image. object properties

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 integer or nil · 1 signal
Desired icon size in px.

Constraints:

Default value : beautiful.notification_icon_size
Unit : pixel
Negative allowed : false

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 icon_size The new value affected to the property.

Consumed theme variables:

Theme variable Usage
beautiful.notification_icon_size
🔗 app_icon string or nil · 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.

Constraints:

Default value : nil

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 app_icon The new value affected to the property.
🔗 image image or nil · 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).

Constraints:

Default value : nil
Type description:
string : Interpreted as a path to an image file.
string : A valid SVG content.
cairo : A cairo image surface: Directly used as-is.
librsvg : A librsvg handle object: Directly used as-is.
nil : Unset the image.

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.

This exists purely to comply with the specification.

Constraints:

Default value : nil
Table content : A list of images.

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 color or nil · 1 signal · 1 theme variable

Foreground color. 

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

Constraints:

Default value : beautiful.naughty_notification_fg
Type description:
string : An hexadecimal color code, such as "#ff0000" for red.
string : A color name, such as "red".
table : A gradient table.
cairo.pattern : Any valid Cairo pattern.
cairo.pattern : A texture build from an image by gears.color.create_png_pattern
nil : Fallback to the current value of beautiful.notification_fg.

See also:

title Title of the notification. object properties
gears.color This module simplifies the creation of cairo pattern objects. module

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.

Consumed theme variables:

Theme variable Usage
beautiful.notification_fgFallback when fg isn't set.
🔗 bg color or nil · 1 signal

Background color. 

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

Constraints:

Default value : beautiful.notification_bg
Type description:
string : An hexadecimal color code, such as "#ff0000" for red.
string : A color name, such as "red".
table : A gradient table.
cairo.pattern : Any valid Cairo pattern.
cairo.pattern : A texture build from an image by gears.color.create_png_pattern

See also:

title Title of the notification. object properties
gears.color This module simplifies the creation of cairo pattern objects. module

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.

Consumed theme variables:

Theme variable Usage
beautiful.notification_bg
🔗 border_width number or nil · 1 signal · 1 theme variable
Border width.

Constraints:

Default value : beautiful.notification_border_width or 0
Type description:
nil : Fallback to the current value of beautiful.notification_border_width.
Unit : pixel
Negative allowed : false

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 border_width The new value affected to the property.

Consumed theme variables:

Theme variable Usage
beautiful.notification_border_width

Consumed theme variables:

Theme variable Usage
beautiful.notification_border_widthFallback when border_width isn't set.
🔗 border_color string or nil · 1 signal
Border color. 

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

Please note that only string (like #ff0000) are supported.

Constraints:

Default value : beautiful.notification_border_color

See also:

gears.color This module simplifies the creation of cairo pattern objects. module

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 border_color The new value affected to the property.

Consumed theme variables:

Theme variable Usage
beautiful.notification_border_color
🔗 shape shape or nil · 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,


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


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

Constraints:

Default value : beautiful.notification_shape
Type description:
gears.shape : Like gears.shape.circle
function: : This can be used for custom shapes or to set parameters of existing shapes.
Function prototype:
Parameters:
cr (cairo.context) : A Cairo context
width (number) : The area width.
height (number) : The area height.
Return : The function returns nothing.

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.

Consumed theme variables:

Theme variable Usage
beautiful.notification_shape
🔗 opacity number or nil · 1 signal
Widget opacity.

Constraints:

Default value : beautiful.notification_opacity
Unit : Gradient beween 0.0 (transparent) and 1.0 (opaque).
Minimum value : 0.0
Maximum value : 1.0

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.

Consumed theme variables:

Theme variable Usage
beautiful.notification_opacity
🔗 margin number or table or nil · 1 signal

Widget margin. 

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

Constraints:

Default value : beautiful.notification_margin
Type description:
number : A single value for all sides.
table: : A different value for all sides.
top (number)
bottom (number)
left (number)
right (number)
Unit : pixel
Negative allowed : false

See also:

shape Widget shape. object properties

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 or nil · 1 signal
Table with any of the above parameters. args will override ones defined in the preset.

Constraints:

Default value : nil

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 preset The new value affected to the property.
🔗 callback function or nil · 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.

Constraints:

Default value : nil
Function prototype:
Parameters:
legacy_data (table)
appname (string)
replaces_id (number)
app_icon (string)
title (string)
message (string)
actions (table)
hints (table)
expire (number)
Return : The function returns nothing.

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

Constraints:

Default value : {}
Table content : A list of naughty.action objects.

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

Constraints:

Default value : false
Valid values : true or false.

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

Constraints:

Default value : false
Valid values : true or false.

See also:

naughty.suspended The global suspension state. (naughty) object properties

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 suspended The new value affected to the property.
🔗 is_expired boolean · 1 signal
If the notification is expired.

Constraints:

Default value : This becomes true either then :destroy() is called or if the timeout expires.
Valid values : true or false.

See also:

naughty.expiration_paused Do not allow notifications to auto-expire. (naughty) object properties

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

Constraints:

Default value : true
Valid values : true or false.

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.

Constraints:

Default value : {}
Table content : A list of client objects.
🔗 max_width number or nil · 1 signal · 1 theme variable
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.

Constraints:

Default value : 500
Type description:
nil : Fallback to the current value of beautiful.notification_max_width.
Unit : pixel
Negative allowed : false

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 max_width The new value affected to the property.

Consumed theme variables:

Theme variable Usage
beautiful.notification_max_widthFallback when max_width isn't set.
🔗 app_name string or nil · 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.

Constraints:

Default value : nil

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 app_name The new value affected to the property.
🔗 widget_template template or nil · 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.

Constraints:

Default value : nil
Type description:
table : A table containing a widget tree definition. WARNING: This is really a table and NOT a widget object. Use the widget = come.class.here to define the topmost class rather than construct an instance.

Click to display more

Emit signals:

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:

title Title of the notification. object properties
🔗 run function
Function to run on left click.

Use the signals rather than this.

See also:

destroyed Emitted when the notification is destroyed. signals
🔗 destroy function
Function to run when notification is destroyed.

Use the signals rather than this.

See also:

destroyed Emitted when the notification is destroyed. signals

Object methods

🔗 :destroy (reason, keep_visible) -> boolean · 1 signal
Destroy notification by notification object.

Parameters:

Name Type(s) Description Default value
reason string One of the reasons from notification_closed_reason Not applicable
keep_visible Optional boolean If true, keep the notification visible false

Returns:

    boolean True if the popup was successfully destroyed, false otherwise.

See also:

naughty.notification_closed_reason The reason why a notification is to be closed. (naughty) tables

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:

Name Type(s) Description
new_timeout number Time in seconds after which notification disappears.
🔗 :append_actions (new_actions)
Add more actions to the notification.

Parameters:

Name Type(s) Description
new_actions table
🔗 :grant (permission, context)
Grant a permission for a notification.

Parameters:

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

See also:

awful.permissions Default implementation of the various requests handers. module
🔗 :deny (permission, context)
Deny a permission for a notification

Parameters:

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

See also:

awful.permissions Default implementation of the various requests handers. module
🔗 :emit_signal (name, ...) · Inherited from gears.object
Emit a signal.

Parameters:

Name Type(s) Description
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 Type(s) Description
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 Type(s) Description
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:

Name Type(s) Description
reason number Why it was destroyed
keep_visible boolean If it was kept visible.

See also:

naughty.notification_closed_reason The reason why a notification is to be closed. (naughty) tables

Theme variables

🔗 beautiful.notification_font string or lgi.Pango.FontDescription
Notifications font.
Click to display more

Used by:
🔗 beautiful.notification_bg color
Notifications background color.
Click to display more

Used by:

  • bg Background color.
  • bg Background color.
🔗 beautiful.notification_fg color
Notifications foreground color.
Click to display more

Used by:
🔗 beautiful.notification_border_width int
Notifications border width.
Click to display more

Used by:
🔗 beautiful.notification_border_color color
Notifications border color.
Click to display more

Used by:
🔗 beautiful.notification_shape gears.shape
Notifications shape.

See also:

gears.shape Module dedicated to gather common shape painters. module

Click to display more

Used by:
🔗 beautiful.notification_opacity int
Notifications opacity.
Click to display more

Used by:
🔗 beautiful.notification_margin int
The margins inside of the notification widget (or popup).
Click to display more

Used by:
🔗 beautiful.notification_width int
Notifications width.
Click to display more

Used by:
🔗 beautiful.notification_height int
Notifications height.
Click to display more

Used by:
🔗 beautiful.notification_spacing number
The spacing between the notifications.

See also:

gears.surface Utilities to integrate and manipulate Cairo drawing surfaces. module

Click to display more

Used by:

  • base_layout A `wibox.layout` to be used to place the entries.
generated by LDoc 1.5.0