wiki: Clarify animations

1 files changed, 58 insertions, 41 deletions

diff --git a/wiki/Configuration:-Animations.md b/wiki/Configuration:-Animations.md
index 73bac452..4a73a208 100644
--- a/wiki/Configuration:-Animations.md
+++ b/wiki/Configuration:-Animations.md
@@ -20,14 +20,6 @@ animations {
         spring damping-ratio=1.0 stiffness=1000 epsilon=0.0001
     }
 
-    horizontal-view-movement {
-        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
-    }
-
-    window-movement {
-        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
-    }
-
     window-open {
         duration-ms 150
         curve "ease-out-expo"
@@ -38,6 +30,14 @@ animations {
         curve "ease-out-quad"
     }
 
+    horizontal-view-movement {
+        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
+    }
+
+    window-movement {
+        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
+    }
+
     window-resize {
         spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
     }
@@ -132,75 +132,73 @@ animations {
 }
 ```
 
-#### `horizontal-view-movement`
+#### `window-open`
 
-All horizontal camera view movement animations, such as:
+Window opening animation.
 
-- When a window off-screen is focused and the camera scrolls to it.
-- When a new window appears off-screen and the camera scrolls to it.
-- When a window resizes bigger and the camera scrolls to show it in full.
-    - Since 0.1.5, animated window resizes will use the `window-resize` animation parameters for the view animation to make them synchronized.
-- After a horizontal touchpad gesture (a spring is recommended).
+This one uses an easing type by default.
 
 ```
 animations {
-    horizontal-view-movement {
-        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
+    window-open {
+        duration-ms 150
+        curve "ease-out-expo"
     }
 }
 ```
 
-#### `window-movement`
+#### `window-close`
 
 <sup>Since: 0.1.5</sup>
 
-Movement of individual windows within a workspace.
-
-Includes:
-
-- Moving window columns with `move-column-left` and `move-column-right`.
-- Moving windows inside a column with `move-window-up` and `move-window-down`.
-- Since 0.1.5, moving windows out of the way upon window opening and closing.
-- Since 0.1.5, window movement between columns when consuming/expelling.
+Window closing animation.
 
-This animation *does not* include the camera view movement, such as scrolling the workspace left and right.
+This one uses an easing type by default.
 
 ```
 animations {
-    window-movement {
-        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
+    window-open {
+        duration-ms 150
+        curve "ease-out-quad"
     }
 }
 ```
 
-#### `window-open`
+#### `horizontal-view-movement`
 
-Window opening animation.
+All horizontal camera view movement animations, such as:
 
-This one uses an easing type by default.
+- When a window off-screen is focused and the camera scrolls to it.
+- When a new window appears off-screen and the camera scrolls to it.
+- After a horizontal touchpad gesture (a spring is recommended).
 
 ```
 animations {
-    window-open {
-        duration-ms 150
-        curve "ease-out-expo"
+    horizontal-view-movement {
+        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
     }
 }
 ```
 
-#### `window-close`
+#### `window-movement`
 
 <sup>Since: 0.1.5</sup>
 
-Window closing animation.
+Movement of individual windows within a workspace.
 
-This one uses an easing type by default.
+Includes:
+
+- Moving window columns with `move-column-left` and `move-column-right`.
+- Moving windows inside a column with `move-window-up` and `move-window-down`.
+- Moving windows out of the way upon window opening and closing.
+- Window movement between columns when consuming/expelling.
+
+This animation *does not* include the camera view movement, such as scrolling the workspace left and right.
 
 ```
 animations {
-    window-open {
-        duration-ms 150
-        curve "ease-out-quad"
+    window-movement {
+        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
     }
 }
 ```
@@ -235,3 +233,22 @@ animations {
     }
 }
 ```
+
+### Synchronized Animations
+
+<sup>Since: 0.1.5</sup>
+
+Sometimes, when two animations are meant to play together synchronized, niri will drive them both with the same configuration.
+
+For example, if a window resize causes the view to move, then that view movement animation will also use the `window-resize` configuration (rather than the `horizontal-view-movement` configuration).
+This is especially important for animated resizes to look good when using `center-focused-column "always"`.
+
+As another example, resizing a window in a column vertically causes other windows to move up or down into their new position.
+This movement will use the `window-resize` configuration, rather than the `window-movement` configuration, to keep the animations synchronized.
+
+A few actions are still missing this synchronization logic, since in some cases it is difficult to implement properly.
+Therefore, for the best results, consider using the same parameters for related animations (they are all the same by default):
+
+- `horizontal-view-movement`
+- `window-movement`
+- `window-resize`