From 3c7a9bf43214c1e544fe3bd851a4f91a7ac579b7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Martynas=20Maciulevi=C4=8Dius?=
 <martynas.maciulevicius@pm.me>
Date: Sat, 22 Feb 2025 09:28:32 +0200
Subject: [PATCH] Documentation for sigusr1 and sigusr2 config

---
 man/waybar.5.scd.in | 39 +++++++++++++++++++++++++++++++++++++--
 src/bar.cpp         |  6 ++++--
 2 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/man/waybar.5.scd.in b/man/waybar.5.scd.in
index 6ca0aa99..002cb50b 100644
--- a/man/waybar.5.scd.in
+++ b/man/waybar.5.scd.in
@@ -151,6 +151,20 @@ The visual display elements for waybar use a CSS stylesheet, see *waybar-styles(
 	default: *false* ++
 	Option to enable reloading the css style if a modification is detected on the style sheet file or any imported css files.
 
+*on_sigusr1* ++
+	typeof: string ++
+	default: *toggle* ++
+	Action that is performed when receiving SIGUSR1 kill signal. ++
+	Possible values: *show*, *hide*, *toggle*, *reload*, *noop*. ++
+	Default value: *toggle*.
+
+*on_sigusr2* ++
+	typeof: string ++
+	default: *reload* ++
+	Action that is performed when receiving SIGUSR2 kill signal. ++
+	Possible values: *show*, *hide*, *toggle*, *reload*, *noop*. ++
+	Default value: *reload*.
+
 # MODULE FORMAT
 
 You can use PangoMarkupFormat (See https://developer.gnome.org/pango/stable/PangoMarkupFormat.html#PangoMarkupFormat).
@@ -206,14 +220,35 @@ A minimal *config* file could look like this:
 Waybar accepts the following signals:
 
 *SIGUSR1*
-	Toggles the bar visibility (hides if shown, shows if hidden)
+	By default toggles the bar visibility (hides if shown, shows if hidden)
 *SIGUSR2*
-	Reloads (resets) the bar
+	By default reloads (resets) the bar
 *SIGINT*
 	Quits the bar
 
 For example, to toggle the bar programmatically, you can invoke `killall -SIGUSR1 waybar`.
 
+## User signal configuration
+
+Config parameters `on_sigusr1` and `on_sigusr2` change what happens when bars receive
+`SIGUSR1` and `SIGUSR2` signals.
+
+This means that commands `killall -SIGUSR1 waybar` and `killall -SIGUSR2 waybar`
+can perform user-configured action.
+
+It also means that if an external script has the PID of the bar then it can
+perform more complex `show`/`hide`/`reload` logic for each instance of Waybar.
+One can find the PID e.g. by doing `pgrep -a waybar` which could then match
+by config name or other parameters.
+
+### Kill parameter meanings
+
+*show*    Switches state to visible (per bar).
+*hide*    Switches state to hidden (per bar).
+*toggle*  Switches state between visible and hidden (per bar).
+*reload*  Reloads whole waybar.
+*noop*    Does nothing when the kill signal is received.
+
 # MULTI OUTPUT CONFIGURATION
 
 ## Limit a configuration to some outputs
diff --git a/src/bar.cpp b/src/bar.cpp
index 5ca2ec04..6e6e76df 100644
--- a/src/bar.cpp
+++ b/src/bar.cpp
@@ -288,7 +288,8 @@ waybar::Bar::Bar(struct waybar_output* w_output, const Json::Value& w_config)
           m_signalActionEnumParser.parseStringToEnum(strSigusr1, util::userKillSignalActions);
     } catch (const std::invalid_argument& e) {
       onSigusr1 = util::SIGNALACTION_DEFAULT_SIGUSR1;
-      spdlog::warn("Invalid string representation for on_sigusr1. Falling back to default mode.");
+      spdlog::warn(
+          "Invalid string representation for on_sigusr1. Falling back to default mode (toggle).");
     }
   }
   const auto& configSigusr2 = config["on_sigusr2"];
@@ -299,7 +300,8 @@ waybar::Bar::Bar(struct waybar_output* w_output, const Json::Value& w_config)
           m_signalActionEnumParser.parseStringToEnum(strSigusr2, util::userKillSignalActions);
     } catch (const std::invalid_argument& e) {
       onSigusr2 = util::SIGNALACTION_DEFAULT_SIGUSR2;
-      spdlog::warn("Invalid string representation for on_sigusr2. Falling back to default mode.");
+      spdlog::warn(
+          "Invalid string representation for on_sigusr2. Falling back to default mode (reload).");
     }
   }