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
idUnique identifier of the notification
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
ignore\_suspend
clientsA list of clients associated with this notification
app\_nameThe application name specified by the notification
widget\_templateThe widget template used to represent the notification

Info:

  • Copyright: 2017-2019 Emmanuel Lepage Vallee
  • Author: Emmanuel Lepage Vallee <[email protected]>

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

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

callbacks table
A list of callback function to call after the properties have been apploed.

See also:

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

See also:

rule_any table
Similar to rule, but each entry is a table with multiple values.

See also:

except table
The negative equivalent of rule.

See also:

except_any table
The negative equivalent of rule_any.

See also:

rule_every table
Matches when one of every \“category\” of components match.

See also:

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

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:

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:

Usage:

    ruled.notification.append_rule {
        rule       = { has_instance = 'amarok' },
        properties = {
            widget_template = my_music_widget_template,
            actions         = get_mpris_actions(),
        }
    }
generated by LDoc 1.4.6 Last updated 2030-01-01 00:00:00