# 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
--- | ---
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
max\_width | The maximum popup width
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) -> 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