From ec040f68653051055efdcbcb52be66aa7e763777 Mon Sep 17 00:00:00 2001 From: Nikos Tsipinakis Date: Wed, 27 Mar 2019 14:16:33 +0200 Subject: [PATCH] Add more documentation about each rule item --- docs/dunst.pod | 92 ++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 81 insertions(+), 11 deletions(-) diff --git a/docs/dunst.pod b/docs/dunst.pod index 84b253e..25390b3 100644 --- a/docs/dunst.pod +++ b/docs/dunst.pod @@ -616,30 +616,58 @@ Notifications can be matched for any of the following attributes: =item C (discouraged, see desktop_entry) +The name of the application as reported by the client. Be aware that the name +can often differ depending on the locale used. + =item C +The body of the notification + =item C +The category of the notification as defined by the notification spec. See +https://developer.gnome.org/notification-spec/#categories + =item C +GLib based applications export their desktop-entry name. In comparison to the appname, +the desktop-entry won't get localized. + =item C +The icon of the notification in the form of a file path. Can be empty if no icon +is available or a raw icon is used instead. + =item C +Match if the notification has been declared as transient by the client or by +some other rule. + +See C for more details about this attribute. + =item C +Matches the urgency of the notification as set by the client or by some other +rule. + =item C +Matches the stack tag of the notification as set by the client or by some other +rule. + +See set_stack_tag for more information about stack tags. + =item C +Matches the summary, 'title', of the notification. + =back C is the urgency of the notification, it is named so to not conflict with trying to modify the urgency. Instead of the appname filter, it's recommended to use the desktop_entry filter. -GLib based applications export their desktop-entry name. In comparison to the appname, -the desktop-entry won't get localized. + To define a matching rule simply assign the specified value to the value that should be matched, for example: @@ -660,24 +688,75 @@ The following attributes can be overridden: =item C +The background color of the notification. See COLORS for possible values. + =item C +The background color of the notification. See COLORS for possible values. + =item C +Equivalent to the C setting. + =item C +The frame color color of the notification. See COLORS for possible values. + =item C +One of show, delay, or pushback. + +This attribute speicifies how notifications are handled if a fullscreen window +is focused. By default it's set to show so notifications are being shown. + +Other possible values are delay: Already shown notifications are continued to be +displayed until they are dismissed or time out but new notifications will be +held back and displayed when the focus to the fullscreen window is lost. + +Or pushback which is equivalent to delay with the difference that already +existing notifications are paused and hidden until the focus to the fullscreen +window is lost. + =item C +Updates the icon of the notification, it should be a path to a valid image. + =item C +Sets the stack tag for the notification, notifications with the same (non-empty) +stack tag will replace each-other so only the newest one is visible. This can be +useful for example in volume or brightness notifications where only want one of +the same type visible. + +The stack tag can be set by the client with the 'synchronous', +'private-synchronous' 'x-canonical-private-synchronous' or the +'x-dunst-stack-tag' hints. + =item C +Sets whether the notification is considered transient. +Transient notifications will bypass the idle_threshold setting. + +By default notifications are _not_ considered transient but clients can set the +value of this by specifying the 'transient' hint when sending notifications. + =item C +Equivalent to the C setting in the urgency sections. + =item C +This sets the notification urgency. + +B: This currently DOES NOT re-apply the attributes from the +urgency_* sections. The changed urgency will only be visible in rules defined +later. Use C to match it. + +=item C + +Setting this to true will prevent the notification from being displayed +initially but will be saved in history for later viewing. + =back As with the filtering attributes, each one corresponds to @@ -689,15 +768,6 @@ rule definition. If the format is set to an empty string, the notification will not be suppressed. -Notifications with the same non-empty stack_tag value will be stacked -together. The default stack_stag value is set from the string hints -"synchronous", "private-synchronous", "x-canonical-private-synchronous", and -"x-dunst-stack-tag". - -If you want to skip initial display of a notification, but still have -it in history, you can set 'skip_display' to 'true' to get this -behavior. - =back =head2 SCRIPTING