Module: `ruled.notifications`

Rules for notifications.

Usage example

ruled.notification.connect_signal("request::rules", function()
    -- Add a red background for urgent notifications.
    ruled.notification.append_rule {
        rule       = { urgency = "critical" },
        properties = { bg = "#ff0000", fg = "#ffffff", timeout = 0 }
    }

    -- Or green background for normal ones.
    ruled.notification.append_rule {
        rule       = { urgency = "normal" },
        properties = { bg      = "#00ff00", fg = "#000000"}
    }
end)

-- Create a normal notification.
naughty.notification {
    title   = "A notification 1",
    message = "This is very informative",
    icon    = beautiful.awesome_icon,
    urgency = "normal",
}

-- Create a normal notification.
naughty.notification {
    title   = "A notification 2",
    message = "This is very informative",
    icon    = beautiful.awesome_icon,
    urgency = "critical",
}

In this example, we setup a different widget template for some music notifications:

Usage example

ruled.notification.connect_signal("request::rules", function()
    -- Add a red background for urgent notifications.
    ruled.notification.append_rule {
        rule       = { app_name = "mdp" },
        properties = {
            widget_template = {
                {
                    {
                        {
                            {
                                naughty.widget.icon,
                                forced_height = 48,
                                halign        = "center",
                                valign        = "center",
                                widget        = wibox.container.place
                            },
                            {
                                align  = "center",
                                widget = naughty.widget.title,
                            },
                            {
                                align  = "center",
                                widget = naughty.widget.message,
                            },
                            {
                                orientation   = "horizontal",
                                widget        = wibox.widget.separator,
                                forced_height = 1,
                            },
                            {
                                nil,
                                {
                                    wibox.widget.textbox "⏪",
                                    wibox.widget.textbox "⏸",
                                    wibox.widget.textbox "⏩",
                                    spacing = 20,
                                    layout  = wibox.layout.fixed.horizontal,
                                },
                                expand = "outside",
                                nil,
                                layout = wibox.layout.align.horizontal,
                            },
                            spacing = 10,
                            layout  = wibox.layout.fixed.vertical,
                        },
                        margins = beautiful.notification_margin,
                        widget  = wibox.container.margin,
                    },
                    id     = "background_role",
                    widget = naughty.container.background,
                },
                strategy = "max",
                width    = 160,
                widget   = wibox.container.constraint,
            }
        }
    }
end)
naughty.connect_signal("request::display", function(n)
    naughty.layout.box { notification = n }
end)
    icon      = beautiful.awesome_icon,

In this example, we add action to a notification that originally lacked them:

Usage example

ruled.notification.connect_signal("request::rules", function()
    -- Add a red background for urgent notifications.
    ruled.notification.append_rule {
        rule       = { }, -- Match everything.
        properties = {
            append_actions = {
               naughty.action {
                   name = "Snooze (5m)",
               },
               naughty.action {
                   name = "Snooze (15m)",
               },
               naughty.action {
                   name = "Snooze (1h)",
               },
            },
        }
    }
end)

-- Create a normal notification.
naughty.notification {
    title   = "A notification",
    message = "This is very informative",
    icon    = beautiful.awesome_icon,
    actions = {
        naughty.action { name = "Existing 1" },
        naughty.action { name = "Existing 2" },
    }
}

Here is a list of all properties available in the properties section of a rule:

Name	Description
id	Unique identifier of the notification
title	Title of the notification
timeout	Time in seconds after which popup expires
urgency	The notification urgency level
category	The notification category
resident	True if the notification should be kept when an action is pressed
hover\_timeout	Delay in seconds after which hovered popup disappears
screen	Target screen for the notification
position	Corner of the workarea displaying the popups
ontop	Boolean forcing popups to display on top
height	Popup height
width	Popup width
font	Notification font
icon	\"All in one\" way to access the default image or icon
icon\_size	Desired icon size in px
app\_icon	The icon provided in the `app\_icon` field of the DBus notification
image	The notification image
images	The notification (animated) images
fg	Foreground color
bg	Background color
border\_width	Border width
border\_color	Border color
shape	Widget shape
opacity	Widget opacity
margin	Widget margin
preset	Table with any of the above parameters
callback	Function that will be called with all arguments
actions	A table containing strings that represents actions to buttons
ignore	Ignore this notification, do not display
suspended	Tell if the notification is currently suspended (read only)
is\_expired	If the notification is expired
auto\_reset\_timeout	If the timeout needs to be reset when a property changes
ignore\_suspend
clients	A list of clients associated with this notification
app\_name	The application name specified by the notification
widget\_template	The widget template used to represent the notification
id	Unique identifier of the notification
title	Title of the notification
timeout	Time in seconds after which popup expires
urgency	The notification urgency level
category	The notification category
resident	True if the notification should be kept when an action is pressed
hover\_timeout	Delay in seconds after which hovered popup disappears
screen	Target screen for the notification
position	Corner of the workarea displaying the popups
ontop	Boolean forcing popups to display on top
height	Popup height
width	Popup width
font	Notification font
icon	\"All in one\" way to access the default image or icon
icon\_size	Desired icon size in px
app\_icon	The icon provided in the `app\_icon` field of the DBus notification
image	The notification image
images	The notification (animated) images
fg	Foreground color
bg	Background color
border\_width	Border width
border\_color	Border color
shape	Widget shape
opacity	Widget opacity
margin	Widget margin
preset	Table with any of the above parameters
callback	Function that will be called with all arguments
actions	A table containing strings that represents actions to buttons
ignore	Ignore this notification, do not display
suspended	Tell if the notification is currently suspended (read only)
is\_expired	If the notification is expired
auto\_reset\_timeout	If the timeout needs to be reset when a property changes
ignore\_suspend
clients	A list of clients associated with this notification
app\_name	The application name specified by the notification
widget\_template	The widget template used to represent the notification

Info:

Copyright: 2017-2019 Emmanuel Lepage Vallee
Originally authored by: Emmanuel Lepage Vallee <elv1313@gmail.com>
(Full contributors list available on our github project)

Static module functions

ruled.notification.remove_rule_source (name) -> boolean	Remove a source.
ruled.notification.apply (n)	Apply the tag rules to a client.
ruled.notification.append_rule (rule)	Add a new rule to the default set.
ruled.notification.append_rules (rule)	Add a new rules to the default set.
ruled.notification.remove_rule (rule)	Remove a new rule to the default set.
ruled.notifications.add_rule_source (name, callback, depends_on, precede) -> boolean	Add a new rule source.

Rule components

properties	table	A table whose content will be used to set the target object properties.
callbacks	table	A list of callback function to call after the properties have been apploed.
rule	table	A table whose content will be compared to the target object current properties.
rule_any	table	Similar to rule, but each entry is a table with multiple values.
except	table	The negative equivalent of rule.
except_any	table	The negative equivalent of rule_any.
rule_every	table	Matches when one of every \"category\" of components match.
rule_lesser	table	A table whose content will be compared to the target object current properties.
rule_greater	table	A table whose content will be compared to the target object current properties.
id	table or string or number or function	An identifier for this rule.

Extra properties available in the rules

append_actions	table	Append some actions to a notification.
implicit_timeout	number	Set a fallback timeout when the notification doesn't have an explicit timeout.
never_timeout	boolean	Do not let this notification timeout, even if it asks for it.

Extra matching properties used in rules

has_focus	boolean	The notification is attached to the focused client.
has_class	string	The notification is attached to a client with this class.
has_instance	string	The notification is attached to a client with this instance name.

Static module functions

ruled.notification.remove_rule_source (name) -> boolean

Remove a source.

Parameters:

name string The source name.

Returns:

boolean

ruled.notification.apply (n)

Apply the tag rules to a client.

This is useful when it is necessary to apply rules after a tag has been created. Many workflows can make use of "blank" tags which wont match any rules until later.

Parameters:

n naughty.notification The notification.

ruled.notification.append_rule (rule)

Add a new rule to the default set.

Parameters:

rule table A valid rule.

ruled.notification.append_rules (rule)

Add a new rules to the default set.

Parameters:

rule table A table with rules.

ruled.notification.remove_rule (rule)

Remove a new rule to the default set.

Parameters:

rule table A valid rule.

ruled.notifications.add_rule_source (name, callback, depends_on, precede) -> boolean

Add a new rule source.

A rule source is a provider called when a client initially request tags. It allows to configure, select or create a tag (or many) to be attached to the client.

Parameters:

name string The provider name. It must be unique.
callback The callback that is called to produce properties.
- c client The client
- properties table The current properties. The callback should add to and overwrite properties in this table
- callbacks table A table of all callbacks scheduled to be executed after the main properties are applied.
depends_on table A list of names of sources this source depends on (sources that must be executed before name. (default {})
precede table A list of names of sources this source have a priority over. (default {})

Returns:

boolean

Rule components

properties table

A table whose content will be used to set the target object properties.

Extra properties available in the rules

append_actions table

Append some actions to a notification.

Using actions directly is destructive since it will override existing actions.

implicit_timeout number

Set a fallback timeout when the notification doesn't have an explicit timeout.

The value is in seconds. If none is specified, the default is 5 seconds. If the notification specifies its own timeout, this property will be skipped.

never_timeout boolean

Do not let this notification timeout, even if it asks for it.

Extra matching properties used in rules

has_focus boolean

The notification is attached to the focused client.

This is useful, along with other matching properties and the ignore notification property, to prevent focused application from spamming with useless notifications.

Usage:

-- Note that the the message is matched as a pattern.
ruled.notification.append_rule {
    rule       = { message = "I am SPAM", has_focus = true },
    properties = { ignore  = true}
}

has_class string

The notification is attached to a client with this class.

Usage:

ruled.notification.append_rule {
    rule       = { has_class = "amarok" },
    properties = {
        widget_template = my_music_widget_template,
        actions         = get_mpris_actions(),
    }
}

has_instance string

The notification is attached to a client with this instance name.

Usage:

ruled.notification.append_rule {
    rule       = { has_instance = "amarok" },
    properties = {
        widget_template = my_music_widget_template,
        actions         = get_mpris_actions(),
    }
}

awesome

Contents

Declarative rules

Core components

Input handling

Widgets

Widget containers

Widget layouts

Popups and bars

Utility libraries

Theme related libraries

Client tiling

Libraries

Sample files

Classes

Documentation

Module: ruled.notifications

Info:

Static module functions

Rule components

Extra properties available in the rules

Extra matching properties used in rules

Static module functions

Parameters:

Returns:

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Returns:

Rule components

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

Extra properties available in the rules

Extra matching properties used in rules

Usage:

See also:

Usage:

See also:

Usage:

Module: `ruled.notifications`