diff --git a/docs/usage/animations.md b/docs/usage/animations.md new file mode 100644 index 00000000..2ac4b4bd --- /dev/null +++ b/docs/usage/animations.md @@ -0,0 +1,82 @@ +# Animations + +Windows can be animated when they move to their place in a layout. Animations are off by default. + +```json +{ + "animation": { + "enabled": true + } +} +``` + +They can also be turned on and off while komorebi is running with the [`komorebic animation`](../cli/animation.md) +command. + +## Duration, style and frame rate + +Every move takes the same amount of time, whatever the distance, and the animation style decides how that time is +spent: whether a window starts quickly and settles gently, or the other way around. + +```json +{ + "animation": { + "enabled": true, + "duration": 250, + "style": "EaseOutCubic", + "fps": 60 + } +} +``` + +The duration is set in milliseconds with [`komorebic animation-duration`](../cli/animation-duration.md), the style with +[`komorebic animation-style`](../cli/animation-style.md), and the number of frames per second with +[`komorebic animation-fps`](../cli/animation-fps.md). + +Styles that start quickly and settle gently, such as `EaseOutCubic`, `EaseOutQuart`, `EaseOutQuint` and `EaseOutExpo`, +tend to feel the most natural for windows, and the ones further down that list settle more gently than the ones above +them. `Linear`, the default, moves windows at a constant speed and stops them abruptly. + +## Different animations for different things + +Every option can be set for a kind of animation instead of for all of them. At the moment `movement` is the only kind. + +```json +{ + "animation": { + "enabled": { + "movement": true + }, + "duration": { + "movement": 300 + }, + "style": { + "movement": "EaseOutQuint" + } + } +} +``` + +## Good to know + +- Windows are moved by asking each app to move them, one frame at a time. The next frame is only started once the last + one has been applied to every window, so that neighbouring windows stay in step. An app that is slow to answer slows + all of the windows down a little, rather than falling out of step with them, unless it takes much longer than a few + frames, in which case it is left to catch up by itself. +- Changing the size of a window is much more work for an app than moving it, because the app has to lay itself out and + draw itself again. For some apps, browsers and editors in particular, that takes longer than a frame. Windows of those + apps are only sent new sizes as often as they can keep up with, and carry on moving smoothly in between, so that they + do not hold the other windows up. They arrive at the right size, but their sizes change in coarser steps on the way. +- Where a window starts from is remembered rather than asked for, so that all of the windows start moving together. It + is forgotten as soon as an app reports that its window has been moved by something else. +- A window is checked once it arrives. If an app ignored a move, or is not able to be as large or as small as the layout + wants, the move is repeated a few times and then left alone. +- Some apps animate every move they are asked to make, which gets in the way of komorebi's animation. While a window is + being animated komorebi turns this off for the app, and puts it back afterwards. +- A window that you grab with the mouse while it is moving is let go of straight away. +- Stacking and unstacking windows, and cycling or focusing a window in a stack, are never animated, and neither is + switching workspaces. +- In the Scrolling layout, windows that scroll out of view slide off the edge of the screen that they left by instead of + disappearing, and windows that scroll back into view slide in from the same edge. +- To see how an animation went, run komorebi with `--log-level debug`. When the windows stop moving, a line starting with + `animated for` reports how many frames were drawn, how many were late, and how long the apps took to answer. diff --git a/mkdocs.yml b/mkdocs.yml index a8107d5a..8049e062 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -62,6 +62,7 @@ nav: - usage/stacking-windows.md - usage/focusing-workspaces.md - usage/moving-windows-across-workspaces.md + - usage/animations.md - Komorebi Configuration: - Schema: https://komorebi.lgug2z.com/schema - CLI reference: