Module: ruled.notifications

Apply properties to a new naughty.notification based on pre-determined rules.

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

ruled.notification.connect_signal("request::rules", function()
    -- Add a red background for urgent notifications.
    ruled.notification.append_rule {
        rule       = { app_name = "mpd" },
        properties = {
            widget_template = {
                {
                    {
                        {
                            {
                                naughty.widget.icon,
                                forced_height = 48,
                                halign        = "center",
                                valign        = "center",
                                widget        = wibox.container.place
                            },
                            {
                                halign = "center",
                                widget = naughty.widget.title,
                            },
                            {
                                halign = "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)

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

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
titleTitle of the notification
timeoutTime in seconds after which popup expires
urgencyThe notification urgency level
categoryThe notification category
residentTrue if the notification should be kept when an action is pressed
hover_timeoutDelay in seconds after which hovered popup disappears
screenTarget screen for the notification
positionCorner of the workarea displaying the popups
ontopBoolean forcing popups to display on top
heightPopup height
widthPopup width
fontNotification font
icon\"All in one\" way to access the default image or icon
icon_sizeDesired icon size in px
app_iconThe icon provided in the app\_icon field of the DBus notification
imageThe notification image
imagesThe notification (animated) images
fgForeground color
bgBackground color
border_widthBorder width
border_colorBorder color
shapeWidget shape
opacityWidget opacity
marginWidget margin
presetTable with any of the above parameters
callbackFunction that will be called with all arguments
actionsA table containing strings that represents actions to buttons
ignoreIgnore this notification, do not display
suspendedTell if the notification is currently suspended (read only)
is_expiredIf the notification is expired
auto_reset_timeoutIf the timeout needs to be reset when a property changes
clientsA list of clients associated with this notification
max_widthThe maximum popup width
app_nameThe application name specified by the notification
widget_templateThe widget template used to represent the notification

Info:

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) -> boolean 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.
callback function A callback function to call before the properties have been applied.
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 Type(s) Description
name string The source name.

Returns:

    boolean If the source was removed.
🔗 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:

Name Type(s) Description
n naughty.notification The notification.
🔗 ruled.notification.append_rule (rule)
Add a new rule to the default set.

Parameters:

Name Type(s) Description
rule table A valid rule.
🔗 ruled.notification.append_rules (rule)
Add a new rules to the default set.

Parameters:

Name Type(s) Description
rule table A table with rules.
🔗 ruled.notification.remove_rule (rule) -> boolean
Remove a new rule to the default set.

Parameters:

Name Type(s) Description
rule table A valid rule.

Returns:

    boolean true if the rule was removed.
🔗 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 Type(s) Description Default value
name string The provider name. It must be unique. Not applicable
callback table The callback that is called to produce properties. Not applicable
c client The client Not applicable
properties table The current properties. The callback should add to and overwrite properties in this table Not applicable
callbacks table A table of all callbacks scheduled to be executed after the main properties are applied. Not applicable
depends_on Optional table A list of names of sources this source depends on (sources that must be executed before name. {}
precede Optional table A list of names of sources this source have a priority over. {}

Returns:

    boolean Returns false if a dependency conflict was found.

Rule components

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

See also:

callback A callback function to call before the properties have been applied. rule components
🔗 callback function
A callback function to call before the properties have been applied.

The callback is called with the current client as first argument.

🔗 rule table
A table whose content will be compared to the target object current properties.

See also:

rule_any Similar to rule, but each entry is a table with multiple values. rule components
except The negative equivalent of rule. rule components
🔗 rule_any table
Similar to rule, but each entry is a table with multiple values.

See also:

rule A table whose content will be compared to the target object current properties. rule components
except_any The negative equivalent of rule_any. rule components
🔗 except table
The negative equivalent of rule.

See also:

rule A table whose content will be compared to the target object current properties. rule components
except_any The negative equivalent of rule_any. rule components
🔗 except_any table
The negative equivalent of rule_any.

See also:

rule A table whose content will be compared to the target object current properties. rule components
except The negative equivalent of rule. rule components
🔗 rule_every table
Matches when one of every \"category\" of components match.

See also:

rule A table whose content will be compared to the target object current properties. rule components
except The negative equivalent of rule. rule components
🔗 rule_lesser table
A table whose content will be compared to the target object current properties.

The comparison will be made using the lesser (<) operator.

See also:

rule A table whose content will be compared to the target object current properties. rule components
except The negative equivalent of rule. rule components
🔗 rule_greater table
A table whose content will be compared to the target object current properties.

The comparison will be made using the greater (>) operator.

See also:

rule A table whose content will be compared to the target object current properties. rule components
except The negative equivalent of rule. rule components
🔗 id table or string or number or function
An identifier for this rule.

It can be anything. It will be compared with the == operator. Strings are highly recommended.

Setting an id is useful to be able to remove the rule by using its id instead of a table reference. Modules can also listen to rule::appended and modify or disable a rule.

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.

See also:

has_instance The notification is attached to a client with this instance name. extra matching properties used in rules

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.

See also:

has_class The notification is attached to a client with this class. extra matching properties used in rules

Usage:

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