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.
This commit is contained in:
Nikos Tsipinakis 2017-07-01 11:44:36 +03:00
parent 5e2c781cba
commit 264b546155
2 changed files with 276 additions and 252 deletions

View File

@ -72,13 +72,33 @@ Available settings per section:
=over 4 =over 4
=item B<font> (default: "Monospace 8") =item B<monitor> (default: 0)
Defines the font or font set used. Optionally set the size as a decimal number Specifies on which monitor the notifications should be displayed in, count
after the font name and space. starts at 0. See the B<follow> setting.
Multiple font options can be separated with commas.
This options is parsed as a Pango font description. =item B<follow> (values: [none/mouse/keyboard] default: none)
Defines where the notifications should be placed in a multi-monitor setup. All
values except I<none> override the B<monitor> setting.
=over 4
=item B<none>
The notifications will be placed on the monitor specified by the B<monitor>
setting.
=item B<mouse>
The notifications will be placed on the monitor that the mouse is currently in.
=item B<keyboard>
The notifications will be placed on the monitor that contains the window with
keyboard focus.
=back
=item B<geometry> (format: [{width}][x{height}][+/-{x}[+/-{y}]], default: "0x0+0-0") =item B<geometry> (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 =back
=item B<indicate_hidden> (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<geometry>) will be
shown B<in place of the last notification slot>.
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<shrink> (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<transparency> (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<notification_height> (default: 0) =item B<notification_height> (default: 0)
The minimum height of the notification window in pixels. If the text and 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 padding cannot fit in within the height specified by this value, the height
will be increased as needed. will be increased as needed.
=item B<line_height> (default: 0)
The amount of extra spacing between text lines in pixels. Set to 0 to
disable.
=item B<separator_height> (default: 2) =item B<separator_height> (default: 2)
The height in pixels of the separator between notifications, if set to 0 there The height in pixels of the separator between notifications, if set to 0 there
will be no separating line between notifications. will be no separating line between notifications.
=item B<format> (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<markup> 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 '&amp;'
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<follow> (values: [none/mouse/keyboard] default: none)
Defines where the notifications should be placed in a multi-monitor setup. All
values except I<none> override the B<monitor> setting.
=over 4
=item B<none>
The notifications will be placed on the monitor specified by the B<monitor>
setting.
=item B<mouse>
The notifications will be placed on the monitor that the mouse is currently in.
=item B<keyboard>
The notifications will be placed on the monitor that contains the window with
keyboard focus.
=back
=item B<monitor> (default: 0)
Specifies on which monitor the notifications should be displayed in, count
starts at 0. See the B<follow> setting.
=item B<history_length> (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<alignment> (values: [left/center/right], default: left)
Defines how the notification text should be aligned.
=item B<icon_position> (values: [left/right/off], default: off)
Defines the position of the icon in the notification window. Setting it to off
disables icons.
=item B<max_icon_size> (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<icon_position> is set to off, this setting is ignored.
=item B<icon_folders> (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<padding> (default: 0) =item B<padding> (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 separator/border of the window
@ -240,15 +185,17 @@ in the vertical axis
=item B<horizontal_padding> (default: 0) =item B<horizontal_padding> (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 in the horizontal axis
=item B<transparency> (default: 0) =item B<frame_width> (default: 0)
A 0-100 range on how transparent the notification window should be, with 0 Defines width in pixels of frame around the notification window. Set to 0 to
being fully opaque and 100 invisible. disable.
This setting will only work if a compositor is running. =item B<frame_color color> (default: #888888)
Defines color of the frame around the notification window. See COLORS.
=item B<separator_color> (values: [auto/foreground/frame/#RRGGBB] default: auto) =item B<separator_color> (values: [auto/foreground/frame/#RRGGBB] default: auto)
@ -277,14 +224,9 @@ Any other value is interpreted as a color, see COLORS
=back =back
=item B<frame_width> (default: 0) =item B<sort> (values: [true/false], default: true)
Defines width in pixels of frame around the notification window. Set to 0 to If set to true, display notifications with higher urgency above the others.
disable.
=item B<frame_color color> (default: #888888)
Defines color of the frame around the notification window. See COLORS.
=item B<idle_threshold> (default: 0) =item B<idle_threshold> (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. Set to 0 to disable.
=item B<show_age_threshold> (default: -1) =item B<font> (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<line_height> (default: 0)
The amount of extra spacing between text lines in pixels. Set to 0 to
disable.
=item B<markup> (values: [full/strip/no], default: no) =item B<markup> (values: [full/strip/no], default: no)
@ -341,15 +290,50 @@ a global setting.
=back =back
=item B<indicate_hidden> (values: [true/false], default: true) =item B<format> (default: "%s %b")
If this is set to true, a notification indicating how many notifications are Specifies how the various attributes of the notification should be formatted on
not being displayed due to the notification limit (see B<geometry>) will be the notification window.
shown B<in place of the last notification slot>.
Meaning that if this is enabled the number of visible notifications will be 1 Regardless of the status of the B<markup> setting, any markup tags that are
less than what is specified in geometry, the last slot will be taken by the present in the format will be parsed. Note that because of that, if a literal
hidden count. ampersand (&) is needed it needs to be escaped as '&amp;'
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<alignment> (values: [left/center/right], default: left)
Defines how the text should be aligned within the notification.
=item B<show_age_threshold> (default: -1)
Show age of message if message is older than this value (in seconds).
Set to -1 to disable.
=item B<word_wrap> (values: [true/false], default: false) =item B<word_wrap> (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. Hide the count of stacked duplicate notifications.
=item B<sticky_history> (values: [true/false], default: true)
If set to true, notifications that have been recalled from history will not
time out automatically.
=item B<show_indicators> (values: [true/false], default: true) =item B<show_indicators> (values: [true/false], default: true)
Show an indicator if a notification contains actions and/or open-able URLs. See Show an indicator if a notification contains actions and/or open-able URLs. See
ACTIONS below for further details. ACTIONS below for further details.
=item B<sort> (values: [true/false], default: true) =item B<icon_position> (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<shrink> (values: [true/false], default: false) =item B<max_icon_size> (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 If B<icon_position> is set to off, this setting is ignored.
geometry) while also having an upper bound on how long a notification can get
before wrapping. =item B<icon_folders> (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<sticky_history> (values: [true/false], default: true)
If set to true, notifications that have been recalled from history will not
time out automatically.
=item B<history_length> (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<dmenu> (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<browser> (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<always_run_script> (values: [true/false] default: true] =item B<always_run_script> (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 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. WM_CLASS). There should be no need to modify this setting for regular use.
=item B<startup_notification> (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 =back
=head2 Shortcut section =head2 Shortcut section

235
dunstrc
View File

@ -1,6 +1,101 @@
[global] [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 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: # Possible values are:
# full: Allow a small subset of html markup in notifications: # full: Allow a small subset of html markup in notifications:
# <b>bold</b> # <b>bold</b>
@ -35,22 +130,10 @@
# Markup is allowed # Markup is allowed
format = "<b>%s</b>\n%b" format = "<b>%s</b>\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. # Alignment of message text.
# Possible values are "left", "center" and "right". # Possible values are "left", "center" and "right".
alignment = left 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 # Show age of message if message is older than show_age_threshold
# seconds. # seconds.
# Set to -1 to disable. # Set to -1 to disable.
@ -63,111 +146,16 @@
# Ignore newlines '\n' in notifications. # Ignore newlines '\n' in notifications.
ignore_newline = no 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 # Merge multiple notifications with the same content
stack_duplicates = true stack_duplicates = true
# Hide the count of merged notifications with the same content # Hide the count of merged notifications with the same content
hide_duplicate_count = false 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). # Display indicators for URLs (U) and actions (A).
show_indicators = yes show_indicators = yes
# The spacing between lines. If the height is smaller than the ### Icons ###
# 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
# Align icons left/right/off # Align icons left/right/off
icon_position = off icon_position = off
@ -178,15 +166,36 @@
# Paths to default icons. # Paths to default icons.
icon_folders = /usr/share/icons/gnome/16x16/status/:/usr/share/icons/gnome/16x16/devices/ 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 rule-defined scripts, even if the notification is suppressed
always_run_script = true always_run_script = true
# Defines color of the frame around the notification window. # Define the title of the windows spawned by dunst
frame_color = "#aaaaaa" title = Dunst
# Defines width in pixels of frame around the notification window. # Define the class of the windows spawned by dunst
# Set to 0 to disable. class = Dunst
frame_width = 3
# 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 # Experimental features that may or may not work correctly. Do not expect them
# to have a consistent behaviour across releases. # to have a consistent behaviour across releases.