From 79fd309d6cf84163ff1c5c44f222e6a58dfa2872 Mon Sep 17 00:00:00 2001
From: Christian Meissl <meissl.christian@gmail.com>
Date: Fri, 18 Oct 2024 16:00:40 +0200
Subject: support binding actions to switches (#747)

* support spawn action on switch events

this adds a new config section named `switch-events`
that allows to bind `spawn` action to certain switch
toggles.

* Expand docs

---------

Co-authored-by: Ivan Molodetskikh <yalterz@gmail.com>
---
 wiki/Configuration:-Overview.md      |  1 +
 wiki/Configuration:-Switch-Events.md | 45 ++++++++++++++++++++++++++++++++++++
 wiki/_Sidebar.md                     |  1 +
 3 files changed, 47 insertions(+)
 create mode 100644 wiki/Configuration:-Switch-Events.md

(limited to 'wiki')

diff --git a/wiki/Configuration:-Overview.md b/wiki/Configuration:-Overview.md
index 5988ac7c..cf208504 100644
--- a/wiki/Configuration:-Overview.md
+++ b/wiki/Configuration:-Overview.md
@@ -5,6 +5,7 @@ You can find documentation for various sections of the config on these wiki page
 * [`input {}`](./Configuration:-Input.md)
 * [`output "eDP-1" {}`](./Configuration:-Outputs.md)
 * [`binds {}`](./Configuration:-Key-Bindings.md)
+* [`switch-events {}`](./Configuration:-Switch-Events.md)
 * [`layout {}`](./Configuration:-Layout.md)
 * [top-level options](./Configuration:-Miscellaneous.md)
 * [`window-rule {}`](./Configuration:-Window-Rules.md)
diff --git a/wiki/Configuration:-Switch-Events.md b/wiki/Configuration:-Switch-Events.md
new file mode 100644
index 00000000..bb438a20
--- /dev/null
+++ b/wiki/Configuration:-Switch-Events.md
@@ -0,0 +1,45 @@
+### Overview
+
+Switch event bindings are declared in the `switch-events {}` section of the config.
+
+Here are all the events that you can bind at a glance:
+
+```kdl
+switch-events {
+    lid-close { spawn "bash" "-c" "niri msg output \"eDP-1\" off"; }
+    lid-open { spawn "bash" "-c" "niri msg output \"eDP-1\" on"; }
+    tablet-mode-on { spawn "bash" "-c" "gsettings set org.gnome.desktop.a11y.applications screen-keyboard-enabled true"; }
+    tablet-mode-off { spawn "bash" "-c" "gsettings set org.gnome.desktop.a11y.applications screen-keyboard-enabled false"; }
+}
+```
+
+The syntax is similar to key bindings.
+Currently only the `spawn` action are supported.
+
+> [!NOTE]
+> In contrast to key bindings, switch event bindings are *always* executed, even when the session is locked.
+
+### `lid-close`, `lid-open`
+
+These events correspond to closing and opening of the laptop lid.
+
+You could use them to turn the laptop internal monitor off and on (until niri gets this functionality built-in).
+
+```kdl
+switch-events {
+    lid-close { spawn "bash" "-c" "niri msg output \"eDP-1\" off"; }
+    lid-open { spawn "bash" "-c" "niri msg output \"eDP-1\" on"; }
+}
+```
+
+### `tablet-mode-on`, `tablet-mode-off`
+
+These events trigger when a convertible laptop goes into or out of tablet mode.
+In tablet mode, the keyboard and mouse are usually inaccessible, so you can use these events to activate the on-screen keyboard.
+
+```kdl
+switch-events {
+    tablet-mode-on { spawn "bash" "-c" "gsettings set org.gnome.desktop.a11y.applications screen-keyboard-enabled true"; }
+    tablet-mode-off { spawn "bash" "-c" "gsettings set org.gnome.desktop.a11y.applications screen-keyboard-enabled false"; }
+}
+```
diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md
index 0699ef89..6e821b85 100644
--- a/wiki/_Sidebar.md
+++ b/wiki/_Sidebar.md
@@ -14,6 +14,7 @@
 * [Input](./Configuration:-Input.md)
 * [Outputs](./Configuration:-Outputs.md)
 * [Key Bindings](./Configuration:-Key-Bindings.md)
+* [Switch Events](./Configuration:-Switch-Events.md)
 * [Layout](./Configuration:-Layout.md)
 * [Named Workspaces](./Configuration:-Named-Workspaces.md)
 * [Miscellaneous](./Configuration:-Miscellaneous.md)
-- 
cgit