docs(wm): border renames and aliases, ahk example

This commit renames a number of border-related code refs, removing the ActiveWindow prefix since these borders are no longer just for the active window. Aliases have been added to preserve backwards compat for existing configs. An example AHK configuration file has been added to the Common Workflows section of the docs site. A link to the docs site has been added to the output of komorebic start. A note has been added recommending that users disable system animations for the best experience in the Getting Started guide.
LGUG2Z · May 15, 2024 · 82aa2ed · 82aa2ed
1 parent 228cb26
commit 82aa2ed
Show file tree

Hide file tree

Showing 25 changed files with 330 additions and 237 deletions.
diff --git a/docs/cli/active-window-border-colour.md b/docs/cli/active-window-border-colour.md
diff --git a/docs/cli/active-window-border-offset.md b/docs/cli/active-window-border-offset.md
diff --git a/docs/cli/active-window-border-width.md b/docs/cli/active-window-border-width.md
diff --git a/docs/cli/border-colour.md b/docs/cli/border-colour.md
@@ -0,0 +1,26 @@
+# border-colour
+
+```
+Set the colour for a window border kind
+
+Usage: komorebic.exe border-colour [OPTIONS] <R> <G> <B>
+
+Arguments:
+  <R>
+          Red
+
+  <G>
+          Green
+
+  <B>
+          Blue
+
+Options:
+  -w, --window-kind <WINDOW_KIND>
+          [default: single]
+          [possible values: single, stack, monocle, unfocused]
+
+  -h, --help
+          Print help
+
+```
diff --git a/docs/cli/border-offset.md b/docs/cli/border-offset.md
@@ -0,0 +1,16 @@
+# border-offset
+
+```
+Set the border offset
+
+Usage: komorebic.exe border-offset <OFFSET>
+
+Arguments:
+  <OFFSET>
+          Desired offset of the window border
+
+Options:
+  -h, --help
+          Print help
+
+```
diff --git a/docs/cli/border-width.md b/docs/cli/border-width.md
@@ -0,0 +1,16 @@
+# border-width
+
+```
+Set the border width
+
+Usage: komorebic.exe border-width <WIDTH>
+
+Arguments:
+  <WIDTH>
+          Desired width of the window border
+
+Options:
+  -h, --help
+          Print help
+
+```
diff --git a/docs/cli/active-window-border.md → docs/cli/border.md b/docs/cli/active-window-border.md → docs/cli/border.md
@@ -1,9 +1,9 @@
-# active-window-border
+# border
 
 ```
-Enable or disable the active window border
+Enable or disable borders
 
-Usage: komorebic.exe active-window-border <BOOLEAN_STATE>
+Usage: komorebic.exe border <BOOLEAN_STATE>
 
 Arguments:
   <BOOLEAN_STATE>

diff --git a/docs/cli/cross-monitor-move-behaviour.md b/docs/cli/cross-monitor-move-behaviour.md
@@ -10,6 +10,7 @@ Arguments:
           Possible values:
           - swap:   Swap the window container with the window container at the edge of the adjacent monitor
           - insert: Insert the window container into the focused workspace on the adjacent monitor
+          - no-op:  Do nothing if trying to move a window container in the direction of an adjacent monitor
 
 Options:
   -h, --help

diff --git a/docs/common-workflows/active-window-border.md b/docs/common-workflows/active-window-border.md
diff --git a/docs/common-workflows/autohotkey.md b/docs/common-workflows/autohotkey.md
@@ -1,27 +1,22 @@
 # AutoHotKey
 
-<!-- TODO: Update this completely -->
-
 If you would like to use Autohotkey, please make sure you have AutoHotKey v2
 installed.
 
 Generally, users who opt for AHK will have specific needs that can only be
 addressed by the advanced functionality of AHK, and so they are assumed to be
 able to craft their own configuration files.
 
-If you would like to try out AHK, a simple sample configuration powered by
-`komorebic.lib.ahk` is provided as a starting point. This sample configuration
-does not take into account the use of a static configuration file; if you
-choose to use a static configuration file alongside AHK, you can remove all the
-configuration options from your `komorebi.ahk` and use it solely to handle
-hotkey bindings.
-
-
-```powershell
-# save the latest generated komorebic library to ~/komorebic.lib.ahk
-iwr https://raw.githubusercontent.com/LGUG2Z/komorebi/v0.1.20/komorebic.lib.ahk -OutFile $Env:USERPROFILE\komorebic.lib.ahk
+If you would like to try out AHK, here is a simple sample configuration which
+largely matches the `whkdrc` sample configuration.
 
-# save the sample komorebi configuration file to ~/komorebi.ahk
-iwr https://raw.githubusercontent.com/LGUG2Z/komorebi/v0.1.20/komorebi.sample.ahk -OutFile $Env:USERPROFILE\komorebi.ahk
 ```
+{% include "../komorebi.ahk" %}
+```
+
+By default, the `komorebi.ahk` file should be located in the `$Env:USERPROFILE`
+directory, however, if `$Env:KOMOREBI_CONFIG_HOME` is set, it should be located
+there.
 
+Once the file is in place, you can stop komorebi and whkd by running `komorebic stop --whkd`,
+and then start komorebi with Autohotkey by running `komorebic start --ahk`.
diff --git a/docs/common-workflows/borders.md b/docs/common-workflows/borders.md
@@ -0,0 +1,28 @@
+# Borders
+
+If you would like to add a visual border around both the currently focused window
+and unfocused windows ensure the following options are defined in the `komorebi.json`
+configuration file.
+
+```json
+{
+  "border": true,
+  "border_width": 8,
+  "border_offset": -1,
+  "border_style": "System",
+  "border_colours": {
+    "single": "#42a5f5",
+    "stack": "#00a542",
+    "monocle": "#ff3399",
+    "unfocused": "#808080"
+  }
+}
+```
+
+It is important to note that borders will only apply to windows managed by `komorebi`.
+
+This feature is not considered stable, and you may encounter visual artifacts
+from time to time.
+
+[![Watch the tutorial
+video](https://img.youtube.com/vi/7_9D22t7KK4/hqdefault.jpg)](https://www.youtube.com/watch?v=7_9D22t7KK4)
diff --git a/docs/installation.md b/docs/installation.md
@@ -30,10 +30,10 @@ to manipulate the window manager, you use
 [WinGet](https://winget.run/pkg/LGUG2Z/komorebi), and you may also built
 it from [source](https://github.com/LGUG2Z/komorebi) if you would prefer.
 
- - [Scoop](#scoop)
- - [WinGet](#winget)
- - [Building from source](#building-from-source)
- - [Offline](#offline)
+- [Scoop](#scoop)
+- [WinGet](#winget)
+- [Building from source](#building-from-source)
+- [Offline](#offline)
 
 ## Long path support
 
@@ -45,6 +45,12 @@ running the following command in an Administrator Terminal before installing
 Set-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' -Name 'LongPathsEnabled' -Value 1
 ```
 
+## Disabling Unnecessary System Animations
+
+It is highly recommended that you enable the "Turn off all unnecessary animations (when possible)" option in
+"Control Panel > Ease of Access > Ease of Access Centre / Make the computer easier to see" for the best performance with
+komorebi.
+
 ## Scoop
 
 Make sure you have installed [`scoop`](https://scoop.sh) and verified that

diff --git a/docs/komorebi.example.json b/docs/komorebi.example.json
@@ -5,17 +5,18 @@
   "cross_monitor_move_behaviour": "Insert",
   "default_workspace_padding": 20,
   "default_container_padding": 20,
+  "border": true,
   "border_width": 8,
   "border_offset": -1,
-  "active_window_border": false,
-  "active_window_border_colours": {
+  "border_colours": {
     "single": "#42a5f5",
     "stack": "#00a542",
-    "monocle": "#ff3399"
+    "monocle": "#ff3399",
+    "unfocused": "#808080"
   },
   "stackbar": {
     "height": 40,
-    "mode": "Never",
+    "mode": "OnStack",
     "tabs": {
       "width": 300,
       "focused_text": "#00a542",

diff --git a/docs/whkdrc.sample b/docs/whkdrc.sample
@@ -10,6 +10,9 @@ alt + shift + o         : komorebic reload-configuration
 # alt + f                 : if ($wshell.AppActivate('Firefox') -eq $False) { start firefox }
 # alt + b                 : if ($wshell.AppActivate('Chrome') -eq $False) { start chrome }
 
+alt + q                 : komorebic close
+alt + m                 : komorebic minimize
+
 # Focus windows
 alt + h                 : komorebic focus left
 alt + j                 : komorebic focus down
@@ -56,8 +59,18 @@ alt + y                 : komorebic flip-layout vertical
 alt + 1                 : komorebic focus-workspace 0
 alt + 2                 : komorebic focus-workspace 1
 alt + 3                 : komorebic focus-workspace 2
+alt + 4                 : komorebic focus-workspace 3
+alt + 5                 : komorebic focus-workspace 4
+alt + 6                 : komorebic focus-workspace 5
+alt + 7                 : komorebic focus-workspace 6
+alt + 8                 : komorebic focus-workspace 7
 
 # Move windows across workspaces
 alt + shift + 1         : komorebic move-to-workspace 0
 alt + shift + 2         : komorebic move-to-workspace 1
 alt + shift + 3         : komorebic move-to-workspace 2
+alt + shift + 4         : komorebic move-to-workspace 3
+alt + shift + 5         : komorebic move-to-workspace 4
+alt + shift + 6         : komorebic move-to-workspace 5
+alt + shift + 7         : komorebic move-to-workspace 6
+alt + shift + 8         : komorebic move-to-workspace 7
diff --git a/justfile b/justfile
@@ -16,12 +16,6 @@ fmt:
 install-target target:
     cargo +stable install --path {{ target }} --locked
 
-prepare:
-    komorebic ahk-asc '~/.config/komorebi/applications.yaml'
-    komorebic pwsh-asc '~/.config/komorebi/applications.yaml'
-    cat '~/.config/komorebi/komorebi.generated.ps1' >komorebi.generated.ps1
-    cat '~/.config/komorebi/komorebi.generated.ahk' >komorebi.generated.ahk
-
 install:
     just install-target komorebic
     just install-target komorebic-no-console

diff --git a/komorebi-client/src/lib.rs b/komorebi-client/src/lib.rs
@@ -9,7 +9,7 @@ pub use komorebi::ring::Ring;
 pub use komorebi::window::Window;
 pub use komorebi::window_manager_event::WindowManagerEvent;
 pub use komorebi::workspace::Workspace;
-pub use komorebi::ActiveWindowBorderColours;
+pub use komorebi::BorderColours;
 pub use komorebi::GlobalState;
 pub use komorebi::Notification;
 pub use komorebi::NotificationEvent;
@@ -18,9 +18,9 @@ pub use komorebi::StackbarConfig;
 pub use komorebi::State;
 pub use komorebi::StaticConfig;
 pub use komorebi::TabsConfig;
-pub use komorebi_core::ActiveWindowBorderStyle;
 pub use komorebi_core::Arrangement;
 pub use komorebi_core::Axis;
+pub use komorebi_core::BorderStyle;
 pub use komorebi_core::CustomLayout;
 pub use komorebi_core::CycleDirection;
 pub use komorebi_core::DefaultLayout;

diff --git a/komorebi-core/src/lib.rs b/komorebi-core/src/lib.rs
@@ -130,9 +130,12 @@ pub enum SocketMessage {
     WatchConfiguration(bool),
     CompleteConfiguration,
     AltFocusHack(bool),
-    ActiveWindowBorder(bool),
-    ActiveWindowBorderColour(WindowKind, u32, u32, u32),
-    ActiveWindowBorderStyle(ActiveWindowBorderStyle),
+    #[serde(alias = "ActiveWindowBorder")]
+    Border(bool),
+    #[serde(alias = "ActiveWindowBorderColour")]
+    BorderColour(WindowKind, u32, u32, u32),
+    #[serde(alias = "ActiveWindowBorderStyle")]
+    BorderStyle(BorderStyle),
     BorderWidth(i32),
     BorderOffset(i32),
     InvisibleBorders(Rect),
@@ -201,7 +204,7 @@ pub enum StackbarMode {
 #[derive(
     Default, Copy, Clone, Debug, Eq, PartialEq, Display, Serialize, Deserialize, JsonSchema,
 )]
-pub enum ActiveWindowBorderStyle {
+pub enum BorderStyle {
     #[default]
     /// Use the system border style
     System,