From 264b546155fc2c325644c8bcacd293f7f0829b35 Mon Sep 17 00:00:00 2001 From: Nikos Tsipinakis Date: Sat, 1 Jul 2017 11:44:36 +0300 Subject: [PATCH] Rearrange the settings into groups Rearrange the settings in the example dunstrc and the manpage into broad categories according to the part of the program they affect: Display, text, icons, history and misc. --- docs/dunst.pod | 293 ++++++++++++++++++++++++++----------------------- dunstrc | 235 ++++++++++++++++++++------------------- 2 files changed, 276 insertions(+), 252 deletions(-) diff --git a/docs/dunst.pod b/docs/dunst.pod index 9e864bd..45afd0c 100644 --- a/docs/dunst.pod +++ b/docs/dunst.pod @@ -72,13 +72,33 @@ Available settings per section: =over 4 -=item B (default: "Monospace 8") +=item B (default: 0) -Defines the font or font set used. Optionally set the size as a decimal number -after the font name and space. -Multiple font options can be separated with commas. +Specifies on which monitor the notifications should be displayed in, count +starts at 0. See the B setting. -This options is parsed as a Pango font description. +=item B (values: [none/mouse/keyboard] default: none) + +Defines where the notifications should be placed in a multi-monitor setup. All +values except I override the B setting. + +=over 4 + +=item B + +The notifications will be placed on the monitor specified by the B +setting. + +=item B + +The notifications will be placed on the monitor that the mouse is currently in. + +=item B + +The notifications will be placed on the monitor that contains the window with +keyboard focus. + +=back =item B (format: [{width}][x{height}][+/-{x}[+/-{y}]], default: "0x0+0-0") @@ -122,117 +142,42 @@ the notification on the left border of the screen while a horizontal offset of =back +=item B (values: [true/false], default: true) + +If this is set to true, a notification indicating how many notifications are +not being displayed due to the notification limit (see B) will be +shown B. + +Meaning that if this is enabled the number of visible notifications will be 1 +less than what is specified in geometry, the last slot will be taken by the +hidden count. + +=item B (values: [true/false], default: false) + +Shrink window if it's smaller than the width. Will be ignored if width is 0. + +This is used mainly in order to have the shrinking benefit of dynamic width (see +geometry) while also having an upper bound on how long a notification can get +before wrapping. + +=item B (default: 0) + +A 0-100 range on how transparent the notification window should be, with 0 +being fully opaque and 100 invisible. + +This setting will only work if a compositor is running. + =item B (default: 0) The minimum height of the notification window in pixels. If the text and padding cannot fit in within the height specified by this value, the height will be increased as needed. -=item B (default: 0) - -The amount of extra spacing between text lines in pixels. Set to 0 to -disable. - =item B (default: 2) The height in pixels of the separator between notifications, if set to 0 there will be no separating line between notifications. -=item B (default: "%s %b") - -Specifies how the various attributes of the notification should be formatted on -the notification window. - -Regardless of the status of the B setting, any markup tags that are -present in the format will be parsed. Note that because of that, if a literal -ampersand (&) is needed it needs to be escaped as '&' - -If '\n' is present anywhere in the format, it will be replaced with -a literal newline. - -If any of the following strings are present, they will be replaced with the -equivalent notification attribute. - -=over 4 - -=item B<%a> appname - -=item B<%s> summary - -=item B<%b> body - -=item B<%i> iconname (including its path) - -=item B<%I> iconname (without its path) - -=item B<%p> progress value ([ 0%] to [100%]) - -=back - -If any of these exists in the format but hasn't been specified in the -notification (e.g. no icon has been set), the placeholders will simply be -removed from the format. - -=item B (values: [none/mouse/keyboard] default: none) - -Defines where the notifications should be placed in a multi-monitor setup. All -values except I override the B setting. - -=over 4 - -=item B - -The notifications will be placed on the monitor specified by the B -setting. - -=item B - -The notifications will be placed on the monitor that the mouse is currently in. - -=item B - -The notifications will be placed on the monitor that contains the window with -keyboard focus. - -=back - -=item B (default: 0) - -Specifies on which monitor the notifications should be displayed in, count -starts at 0. See the B setting. - -=item B (default: 20) - -Maximum number of notifications that will be kept in history. After that limit -is reached, older notifications will be deleted once a new one arrives. See -HISTORY. - -=item B (values: [left/center/right], default: left) - -Defines how the notification text should be aligned. - -=item B (values: [left/right/off], default: off) - -Defines the position of the icon in the notification window. Setting it to off -disables icons. - -=item B (default: 32) - -Defines the maximum size in pixels for the icons. -If the icon is smaller than the specified value it won't be affected. -If it's larger then it will be scaled down so that the larger axis is equivalent -to the specified size. - -If B is set to off, this setting is ignored. - -=item B (default: "/usr/share/icons/gnome/16x16/status/:/usr/share/icons/gnome/16x16/devices/") - -Can be set to a colon-separated list of paths to search for icons to use with -notifications. - -Dunst doesn't currently do any type of icon lookup outside of these -directories. - =item B (default: 0) The distance in pixels from the content to the separator/border of the window @@ -240,15 +185,17 @@ in the vertical axis =item B (default: 0) -The distance in pixels from the content to the separator/border of the window +The distance in pixels from the content to the border of the window in the horizontal axis -=item B (default: 0) +=item B (default: 0) -A 0-100 range on how transparent the notification window should be, with 0 -being fully opaque and 100 invisible. +Defines width in pixels of frame around the notification window. Set to 0 to +disable. -This setting will only work if a compositor is running. +=item B (default: #888888) + +Defines color of the frame around the notification window. See COLORS. =item B (values: [auto/foreground/frame/#RRGGBB] default: auto) @@ -277,14 +224,9 @@ Any other value is interpreted as a color, see COLORS =back -=item B (default: 0) +=item B (values: [true/false], default: true) -Defines width in pixels of frame around the notification window. Set to 0 to -disable. - -=item B (default: #888888) - -Defines color of the frame around the notification window. See COLORS. +If set to true, display notifications with higher urgency above the others. =item B (default: 0) @@ -292,11 +234,18 @@ Don't timeout notifications if user is idle longer than this value (in seconds). Set to 0 to disable. -=item B (default: -1) +=item B (default: "Monospace 8") -Show age of message if message is older than this value (in seconds). +Defines the font or font set used. Optionally set the size as a decimal number +after the font name and space. +Multiple font options can be separated with commas. -Set to -1 to disable. +This options is parsed as a Pango font description. + +=item B (default: 0) + +The amount of extra spacing between text lines in pixels. Set to 0 to +disable. =item B (values: [full/strip/no], default: no) @@ -341,15 +290,50 @@ a global setting. =back -=item B (values: [true/false], default: true) +=item B (default: "%s %b") -If this is set to true, a notification indicating how many notifications are -not being displayed due to the notification limit (see B) will be -shown B. +Specifies how the various attributes of the notification should be formatted on +the notification window. -Meaning that if this is enabled the number of visible notifications will be 1 -less than what is specified in geometry, the last slot will be taken by the -hidden count. +Regardless of the status of the B setting, any markup tags that are +present in the format will be parsed. Note that because of that, if a literal +ampersand (&) is needed it needs to be escaped as '&' + +If '\n' is present anywhere in the format, it will be replaced with +a literal newline. + +If any of the following strings are present, they will be replaced with the +equivalent notification attribute. + +=over 4 + +=item B<%a> appname + +=item B<%s> summary + +=item B<%b> body + +=item B<%i> iconname (including its path) + +=item B<%I> iconname (without its path) + +=item B<%p> progress value ([ 0%] to [100%]) + +=back + +If any of these exists in the format but hasn't been specified in the +notification (e.g. no icon has been set), the placeholders will simply be +removed from the format. + +=item B (values: [left/center/right], default: left) + +Defines how the text should be aligned within the notification. + +=item B (default: -1) + +Show age of message if message is older than this value (in seconds). + +Set to -1 to disable. =item B (values: [true/false], default: false) @@ -376,27 +360,53 @@ it, summary, body, icon and urgency are all identical. Hide the count of stacked duplicate notifications. -=item B (values: [true/false], default: true) - -If set to true, notifications that have been recalled from history will not -time out automatically. - =item B (values: [true/false], default: true) Show an indicator if a notification contains actions and/or open-able URLs. See ACTIONS below for further details. -=item B (values: [true/false], default: true) +=item B (values: [left/right/off], default: off) -If set to true, display notifications with higher urgency above the others. +Defines the position of the icon in the notification window. Setting it to off +disables icons. -=item B (values: [true/false], default: false) +=item B (default: 32) -Shrink window if it's smaller than the width. Will be ignored if width is 0. +Defines the maximum size in pixels for the icons. +If the icon is smaller than the specified value it won't be affected. +If it's larger then it will be scaled down so that the larger axis is equivalent +to the specified size. -This is used mainly in order to have the shrinking benefit of dynamic width (see -geometry) while also having an upper bound on how long a notification can get -before wrapping. +If B is set to off, this setting is ignored. + +=item B (default: "/usr/share/icons/gnome/16x16/status/:/usr/share/icons/gnome/16x16/devices/") + +Can be set to a colon-separated list of paths to search for icons to use with +notifications. + +Dunst doesn't currently do any type of icon lookup outside of these +directories. + +=item B (values: [true/false], default: true) + +If set to true, notifications that have been recalled from history will not +time out automatically. + +=item B (default: 20) + +Maximum number of notifications that will be kept in history. After that limit +is reached, older notifications will be deleted once a new one arrives. See +HISTORY. + +=item B (default: "/usr/bin/dmenu") + +The command that will be run when opening the context menu. Should be either +a dmenu command or a dmenu-compatible menu. + +=item B (default: "/usr/bin/firefox") + +The command that will be run when opening a URL. The URL to be opened will be +appended to the end of the value of this setting. =item B (values: [true/false] default: true] @@ -413,6 +423,11 @@ property). There should be no need to modify this setting for regular use. Defines the class of notification windows spawned by dunst. (First part of WM_CLASS). There should be no need to modify this setting for regular use. +=item B (values: [true/false], default: false) + +Display a notification on startup. This is usually used for debugging and there +shouldn't be any need to use this option. + =back =head2 Shortcut section diff --git a/dunstrc b/dunstrc index cffc220..81fcb1b 100644 --- a/dunstrc +++ b/dunstrc @@ -1,6 +1,101 @@ [global] + ### Display ### + + # Which monitor should the notifications be displayed on. + monitor = 0 + + # Display notification on focused monitor. Possible modes are: + # mouse: follow mouse pointer + # keyboard: follow window with keyboard focus + # none: don't follow anything + # + # "keyboard" needs a window manager that exports the + # _NET_ACTIVE_WINDOW property. + # This should be the case for almost all modern window managers. + # + # If this option is set to mouse or keyboard, the monitor option + # will be ignored. + follow = mouse + + # The geometry of the window: + # [{width}]x{height}[+/-{x}+/-{y}] + # The geometry of the message window. + # The height is measured in number of notifications everything else + # in pixels. If the width is omitted but the height is given + # ("-geometry x2"), the message window expands over the whole screen + # (dmenu-like). If width is 0, the window expands to the longest + # message displayed. A positive x is measured from the left, a + # negative from the right side of the screen. Y is measured from + # the top and down respectively. + # The width can be negative. In this case the actual width is the + # screen width minus the width defined in within the geometry option. + geometry = "300x5-30+20" + + # Show how many messages are currently hidden (because of geometry). + indicate_hidden = yes + + # Shrink window if it's smaller than the width. Will be ignored if + # width is 0. + shrink = no + + # The transparency of the window. Range: [0; 100]. + # This option will only work if a compositing window manager is + # present (e.g. xcompmgr, compiz, etc.). + transparency = 0 + + # The height of the entire notification. If the height is smaller + # than the font height and padding combined, it will be raised + # to the font height and padding. + notification_height = 0 + + # Draw a line of "separator_height" pixel height between two + # notifications. + # Set to 0 to disable. + separator_height = 2 + + # Padding between text and separator. + padding = 8 + + # Horizontal padding. + horizontal_padding = 8 + + # Defines width in pixels of frame around the notification window. + # Set to 0 to disable. + frame_width = 3 + + # Defines color of the frame around the notification window. + frame_color = "#aaaaaa" + + # Define a color for the separator. + # possible values are: + # * auto: dunst tries to find a color fitting to the background; + # * foreground: use the same color as the foreground; + # * frame: use the same color as the frame; + # * anything else will be interpreted as a X color. + separator_color = frame + + # Sort messages by urgency. + sort = yes + + # Don't remove messages, if the user is idle (no mouse or keyboard input) + # for longer than idle_threshold seconds. + # Set to 0 to disable. + idle_threshold = 120 + + # The frequency with which text that is longer than the notification + # window allows bounces back and forth. + # This option conflicts with "word_wrap". + # Set to 0 to disable. + bounce_freq = 0 + + ### Text ### + font = Monospace 8 + # The spacing between lines. If the height is smaller than the + # font height, it will get raised to the font height. + line_height = 0 + # Possible values are: # full: Allow a small subset of html markup in notifications: # bold @@ -35,22 +130,10 @@ # Markup is allowed format = "%s\n%b" - # Sort messages by urgency. - sort = yes - - # Show how many messages are currently hidden (because of geometry). - indicate_hidden = yes - # Alignment of message text. # Possible values are "left", "center" and "right". alignment = left - # The frequency with which text that is longer than the notification - # window allows bounces back and forth. - # This option conflicts with "word_wrap". - # Set to 0 to disable. - bounce_freq = 0 - # Show age of message if message is older than show_age_threshold # seconds. # Set to -1 to disable. @@ -63,111 +146,16 @@ # Ignore newlines '\n' in notifications. ignore_newline = no - - # The geometry of the window: - # [{width}]x{height}[+/-{x}+/-{y}] - # The geometry of the message window. - # The height is measured in number of notifications everything else - # in pixels. If the width is omitted but the height is given - # ("-geometry x2"), the message window expands over the whole screen - # (dmenu-like). If width is 0, the window expands to the longest - # message displayed. A positive x is measured from the left, a - # negative from the right side of the screen. Y is measured from - # the top and down respectively. - # The width can be negative. In this case the actual width is the - # screen width minus the width defined in within the geometry option. - geometry = "300x5-30+20" - - # Define the title of the windows spawned by dunst - title = Dunst - - # Define the class of the windows spawned by dunst - class = Dunst - - # Shrink window if it's smaller than the width. Will be ignored if - # width is 0. - shrink = no - - # The transparency of the window. Range: [0; 100]. - # This option will only work if a compositing window manager is - # present (e.g. xcompmgr, compiz, etc.). - transparency = 0 - - # Don't remove messages, if the user is idle (no mouse or keyboard input) - # for longer than idle_threshold seconds. - # Set to 0 to disable. - idle_threshold = 120 - - # Which monitor should the notifications be displayed on. - monitor = 0 - - # Display notification on focused monitor. Possible modes are: - # mouse: follow mouse pointer - # keyboard: follow window with keyboard focus - # none: don't follow anything - # - # "keyboard" needs a window manager that exports the - # _NET_ACTIVE_WINDOW property. - # This should be the case for almost all modern window managers. - # - # If this option is set to mouse or keyboard, the monitor option - # will be ignored. - follow = mouse - # Merge multiple notifications with the same content stack_duplicates = true # Hide the count of merged notifications with the same content hide_duplicate_count = false - # Should a notification popped up from history be sticky or timeout - # as if it would normally do. - sticky_history = yes - - # Maximum amount of notifications kept in history - history_length = 20 - # Display indicators for URLs (U) and actions (A). show_indicators = yes - # The spacing between lines. If the height is smaller than the - # font height, it will get raised to the font height. - line_height = 0 - - # The height of the entire notification. If the height is smaller - # than the font height and padding combined, it will be raised - # to the font height and padding. - notification_height = 0 - - # Draw a line of "separator_height" pixel height between two - # notifications. - # Set to 0 to disable. - separator_height = 2 - - # Padding between text and separator. - padding = 8 - - # Horizontal padding. - horizontal_padding = 8 - - # Define a color for the separator. - # possible values are: - # * auto: dunst tries to find a color fitting to the background; - # * foreground: use the same color as the foreground; - # * frame: use the same color as the frame; - # * anything else will be interpreted as a X color. - separator_color = frame - - # Print a notification on startup. - # This is mainly for error detection, since dbus (re-)starts dunst - # automatically after a crash. - startup_notification = false - - # dmenu path. - dmenu = /usr/bin/dmenu -p dunst: - - # Browser for opening urls in context menu. - browser = /usr/bin/firefox -new-tab + ### Icons ### # Align icons left/right/off icon_position = off @@ -178,15 +166,36 @@ # Paths to default icons. icon_folders = /usr/share/icons/gnome/16x16/status/:/usr/share/icons/gnome/16x16/devices/ + ### History ### + + # Should a notification popped up from history be sticky or timeout + # as if it would normally do. + sticky_history = yes + + # Maximum amount of notifications kept in history + history_length = 20 + + ### Misc/Advanced ### + + # dmenu path. + dmenu = /usr/bin/dmenu -p dunst: + + # Browser for opening urls in context menu. + browser = /usr/bin/firefox -new-tab + # Always run rule-defined scripts, even if the notification is suppressed always_run_script = true - # Defines color of the frame around the notification window. - frame_color = "#aaaaaa" + # Define the title of the windows spawned by dunst + title = Dunst - # Defines width in pixels of frame around the notification window. - # Set to 0 to disable. - frame_width = 3 + # Define the class of the windows spawned by dunst + class = Dunst + + # Print a notification on startup. + # This is mainly for error detection, since dbus (re-)starts dunst + # automatically after a crash. + startup_notification = false # Experimental features that may or may not work correctly. Do not expect them # to have a consistent behaviour across releases.