From 0c75ec37d094ef4f5aa14f20e059b7b6d9a2224b Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Sun, 11 Feb 2024 17:45:12 -0800 Subject: [PATCH] docs(mkdocs): add common workflows section --- README.md | 603 +----------------- docs/common-workflows/active-window-border.md | 40 ++ docs/common-workflows/autohotkey.md | 30 + docs/common-workflows/custom-layouts.md | 70 ++ .../dynamic-layout-switching.md | 37 ++ docs/common-workflows/focus-follows-mouse.md | 34 + docs/common-workflows/force-manage-windows.md | 21 + docs/common-workflows/ignore-windows.md | 21 + docs/common-workflows/komorebi-config-home.md | 27 + docs/common-workflows/mouse-follows-focus.md | 15 + docs/common-workflows/remove-gaps.md | 17 + .../tray-and-multi-window-applications.md | 23 + mkdocs.yml | 15 +- 13 files changed, 379 insertions(+), 574 deletions(-) create mode 100644 docs/common-workflows/active-window-border.md create mode 100644 docs/common-workflows/autohotkey.md create mode 100644 docs/common-workflows/custom-layouts.md create mode 100644 docs/common-workflows/dynamic-layout-switching.md create mode 100644 docs/common-workflows/focus-follows-mouse.md create mode 100644 docs/common-workflows/force-manage-windows.md create mode 100644 docs/common-workflows/ignore-windows.md create mode 100644 docs/common-workflows/komorebi-config-home.md create mode 100644 docs/common-workflows/mouse-follows-focus.md create mode 100644 docs/common-workflows/remove-gaps.md create mode 100644 docs/common-workflows/tray-and-multi-window-applications.md diff --git a/README.md b/README.md index f4fcf803..a5759506 100644 --- a/README.md +++ b/README.md @@ -33,15 +33,7 @@ Tiling Window Management for Windows. - [Charitable Donations](#charitable-donations) - [GitHub Sponsors](#github-sponsors) - [Demonstrations](#demonstrations) -- [Description](#description) -- [Design](#design) - [Getting Started](#getting-started) - - [Quickstart](#quickstart) - - [GitHub Releases](#github-releases) - - [Building from Source](#building-from-source) - - [Running](#running) - - [Configuring](#configuring) - - [Common First-Time Tips](#common-first-time-tips) - [Development](#development) - [Logs and Debugging](#logs-and-debugging) - [Restoring Windows](#restoring-windows) @@ -55,46 +47,53 @@ Tiling Window Management for Windows. ## About -_komorebi_ is a tiling window manager that works as an extension to -Microsoft's [Desktop Window Manager](https://docs.microsoft.com/en-us/windows/win32/dwm/dwm-overview) in Windows 10 and -above. +_komorebi_ is a tiling window manager that works as an extension to Microsoft's +[Desktop Window +Manager](https://docs.microsoft.com/en-us/windows/win32/dwm/dwm-overview) in +Windows 10 and above. -_komorebi_ allows you to control application windows, virtual workspaces and display monitors with a CLI which can be -used with third-party software such as [AutoHotKey](https://github.com/Lexikos/AutoHotkey_L) to set user-defined +_komorebi_ allows you to control application windows, virtual workspaces and +display monitors with a CLI which can be used with third-party software such as +[AutoHotKey](https://github.com/Lexikos/AutoHotkey_L) to set user-defined keyboard shortcuts. -_komorebi_ aims to make _as few modifications as possible_ to the operating system and desktop environment by default. -Users are free to make such modifications in their own configuration files for _komorebi_, but these will remain -opt-in and off-by-default for the foreseeable future. +_komorebi_ aims to make _as few modifications as possible_ to the operating +system and desktop environment by default. Users are free to make such +modifications in their own configuration files for _komorebi_, but these will +remain opt-in and off-by-default for the foreseeable future. -Translations of this document can be found in the project wiki: - -- [komorebi 中文用户指南](https://github.com/LGUG2Z/komorebi/wiki/README-zh) (by [@crosstyan](https://github.com/crosstyan)) - -There is a [Discord server](https://discord.gg/mGkn66PHkx) available for _komorebi_-related discussion, help, -troubleshooting etc. If you have any specific feature requests or bugs to report, please create an issue in this +There is a [Discord server](https://discord.gg/mGkn66PHkx) available for +_komorebi_-related discussion, help, troubleshooting etc. If you have any +specific feature requests or bugs to report, please create an issue in this repository. -There is a [YouTube channel](https://www.youtube.com/channel/UCeai3-do-9O4MNy9_xjO6mg) where I livestream development -on _komorebi_. If you would like to be notified of upcoming livestreams please subscribe and turn on -notifications. Videos of previous livestreams are also made available in -a [dedicated playlist](https://www.youtube.com/playlist?list=PLllZnrEJu89Cpu4tMO8LAg1m6gWYWLSGJ). +There is a [YouTube +channel](https://www.youtube.com/channel/UCeai3-do-9O4MNy9_xjO6mg) where I post +_komorebi_ development videos. If you would like to be notified of upcoming +videos please subscribe and turn on notifications. -Articles, blog posts, demos, and videos about _komorebi_ can be added to this list by PR: +Articles, blog posts, demos, and videos about _komorebi_ can be added to this +list by PR: - [Moving to Windows from Linux Pt 1](https://kvwu.io/posts/moving-to-windows/) - [Windows 下的现代化平铺窗口管理器 komorebi](https://zhuanlan.zhihu.com/p/455064481) - [komorebi を導入してみる](https://zenn.dev/omochice/articles/50f42a3df8f426) +## Getting Started + +A [detailed quickstart +guide](https://lgug2z.github.io/komorebi/installation.html) is available on the +documentation website. + ## Charitable Donations -_komorebi_ is a free and open-source project, and one that encourages you to make charitable donations if -you find the software to be useful and have the financial means. +_komorebi_ is a free and open-source project, and one that encourages you to +make charitable donations if you find the software to be useful and have the +financial means. I encourage you to make a charitable donation to the [Palestine Children's -Relief Fund](https://pcrf1.app.neoncrm.com/forms/gaza-recovery) and [Fresh -Start Refugee](https://www.freshstartrefugee.org/donate) before you consider -sponsoring me on GitHub. +Relief Fund](https://pcrf1.app.neoncrm.com/forms/gaza-recovery) before you +consider sponsoring me on GitHub. ## Project Sponsorship @@ -123,546 +122,6 @@ widget enabled. The original video can be viewed https://user-images.githubusercontent.com/13164844/163496414-a9cde3d1-b8a7-4a7a-96fb-a8985380bc70.mp4 -## Description - -_komorebi_ only responds to [WinEvents](https://docs.microsoft.com/en-us/windows/win32/winauto/event-constants) and the -messages it receives on a dedicated socket. - -_komorebic_ is a CLI that writes messages on _komorebi_'s socket. - -_komorebi_ doesn't handle any keyboard or mouse inputs; a third party program (e.g. -[whkd](https://github.com/LGUG2Z/whkd)) is needed in order to translate keyboard and mouse events to _komorebic_ commands. - -This architecture, popularised by [_bspwm_](https://github.com/baskerville/bspwm) on Linux and -[_yabai_](https://github.com/koekeishiya/yabai) on macOS, is outlined as follows: - -``` - PROCESS SOCKET -whkd/ahk --------> komorebic <------> komorebi -``` - -## Design - -_komorebi_ holds a list of physical monitors. - -A monitor is just a rectangle of the available work area which contains one or more virtual workspaces. - -A workspace holds a list of containers. - -A container is just a rectangle where one or more application windows can be displayed. - -This means that: - -- Every monitor has its own collection of virtual workspaces -- Workspaces only know about containers and their dimensions, not about individual application windows -- Every application window must belong to a container, even if that container only contains one application window -- Many application windows can be stacked and cycled through in the same container within a workspace - -## Getting Started - -### Quickstart - -It highly recommended that you enable support for long paths in Windows by running the following command in an -Administrator Terminal before starting with this quickstart guide: - -```powershell -Set-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' -Name 'LongPathsEnabled' -Value 1 -``` - -Make sure that you have either the [Scoop Package Manager](https://scoop.sh) or WinGet installed, then run the following -commands at a PowerShell prompt. If you are using WinGet, make sure that you open a new terminal window or reload your -profile after running the installation steps. Since this is not required when using `scoop`, I personally recommend that -you use `scoop` for this process. - -As of v0.1.17, the quickstart recommends the use of a static configuration file. If you would like to see older versions -of this quickstart which recommend the use of dynamic configuration scripts, please refer to -the [README file of v0.1.16](https://github.com/LGUG2Z/komorebi/tree/v0.1.16). - -```powershell -# if using scoop -scoop bucket add extras -scoop install whkd -scoop install komorebi - -# if using winget -winget install LGUG2Z.whkd -winget install LGUG2Z.komorebi - -# save the example configuration to ~/komorebi.json -iwr https://raw.githubusercontent.com/LGUG2Z/komorebi/v0.1.19/komorebi.example.json -OutFile "$Env:USERPROFILE\komorebi.json" - -# save the latest generated app-specific config tweaks and fixes -komorebic fetch-app-specific-configuration - -# ensure the ~/.config folder exists -mkdir "$Env:USERPROFILE\.config" -ea 0 - -# save the sample whkdrc file with key bindings to ~/.config/whkdrc -iwr https://raw.githubusercontent.com/LGUG2Z/komorebi/v0.1.19/whkdrc.sample -OutFile "$Env:USERPROFILE\.config\whkdrc" - -# start komorebi and whkd -komorebic start -c "$Env:USERPROFILE\komorebi.json" --whkd -``` - -Thanks to [@sitiom](https://github.com/sitiom) for getting _komorebi_ added to both the popular Scoop Extras bucket and -to WinGet. - -You can watch a walkthrough video of this quickstart below on YouTube. - -[![Watch the quickstart walkthrough video](https://img.youtube.com/vi/hDDxtvpjpHs/hqdefault.jpg)](https://www.youtube.com/watch?v=hDDxtvpjpHs) - -#### Using Autohotkey - -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.19/komorebic.lib.ahk -OutFile $Env:USERPROFILE\komorebic.lib.ahk - -# save the latest generated app-specific config tweaks and fixes to ~/komorebi.generated.ahk -iwr https://raw.githubusercontent.com/LGUG2Z/komorebi/v0.1.19/komorebi.generated.ahk -OutFile $Env:USERPROFILE\komorebi.generated.ahk - -# save the sample komorebi configuration file to ~/komorebi.ahk -iwr https://raw.githubusercontent.com/LGUG2Z/komorebi/v0.1.19/komorebi.sample.ahk -OutFile $Env:USERPROFILE\komorebi.ahk -``` - -### GitHub Releases - -Prebuilt binaries are available on the [releases page](https://github.com/LGUG2Z/komorebi/releases) in a `zip` archive. -Once downloaded, you will need to move the `komorebi.exe` and `komorebic.exe` binaries to a directory in your `Path` ( -you can see these directories by running `$Env:Path.split(";")` at a PowerShell prompt). - -### Building from Source - -If you prefer to compile _komorebi_ from source, you will need -a [working Rust development environment on Windows 10/11](https://rustup.rs/). The `x86_64-pc-windows-msvc` toolchain is -required, so make sure you have also installed -the [Build Tools for Visual Studio 2019](https://stackoverflow.com/a/55603112). - -You can then clone this repo and compile the source code to install the binaries for `komorebi` and `komorebic`: - -```powershell -cargo install --path komorebi --locked -cargo install --path komorebic --locked -``` - -### Running - -`komorebi` can be run in two ways, using either a static configuration file or a dynamic configuration script. - -The quickstart covers running with a static configuration file. - -If you would like to use a dynamic configuration script, ensure that you have a `komorebi.ps1` or `komorebi.ahk` file -present, run `komorebic start --await-configuration` at a Powershell prompt, and you will see the following output: - -``` -Start-Process komorebi.exe -ArgumentList '--await-configuration' -WindowStyle hidden -Waiting for komorebi.exe to start...Started! -``` - -This means that `komorebi` is now running in the background, tiling all your windows, and listening for commands sent to -it by `komorebic`. You can similarly stop the process by running `komorebic stop`. - -For further information on running with a dynamic configuration script, please refer to -the quickstart section in the [README file of v0.1.16](https://github.com/LGUG2Z/komorebi/tree/v0.1.16) - -### Configuring - -If you followed the quickstart, `komorebi.json` will be the single place where you declaratively configure the behaviour -of the window manager. There is a [complete JSON Schema for this configuration file](schema.json) available to provide -users with auto-completions in their editors. - -If you are running with a dynamic configuration script as recommended in v0.1.16 and earlier, `komorebi` will find the -sample `komorebi.ps1` file in your `$Env:USERPROFILE` directory and automatically load it. This file also starts `whkd` using the sample `whkdrc` file -in your `$Env:USERPROFILE\.config` directory. - -Alternatively, if you have AutoHotKey installed and a `komorebi.ahk` file in `$Env:UserProfile` directory, `komorebi` -will automatically try to load it when starting. - -#### Migrating to a Static Configuration File - -If you have been using `komorebi` with a dynamic configuration script and wish to migrate to using a static -configuration file, once you have `komorebi` running in the desired configuration state, you can -run `komorebic generate-static-config`. - -This will print a static configuration that mostly represents your current configuration to the terminal. - -There are four configuration options that you may need to set yourself, if you make use of them: - -- Custom layouts paths for workspaces -- Custom layout rules for workspaces -- The applications.yaml path -- Any individual application rules you have that are not in applications.yaml - -[![Watch the tutorial video](https://img.youtube.com/vi/yqCAOJgL3C0/hqdefault.jpg)](https://www.youtube.com/watch?v=yqCAOJgL3C0) - -#### Configuration with `komorebic` - -As previously mentioned, this project does not handle anything related to keybindings and shortcuts directly. I -personally use [`whkd`](https://github.com/LGUG2Z/whkd) to manage my window management shortcuts, and have provided a -sample [whkdrc](whkdrc.sample) configuration that you can use as a starting point for your own. - -You can run `komorebic.exe` to get a full list of the commands that you can use to customise `komorebi` and create -keybindings with. You can run `komorebic.exe --help` to get a full explanation of the arguments required for -each command. - -You can run any configuration command in the `komorebi.ps1` file, and you can bind any action command to your desired -key combinations in the `whkdrc` file. - -#### AutoHotKey Helper Library for `komorebic` - -❗️**NOTE**: This section is only relevant for people who wish to use AutoHotKey instead of [`whkd`](https://github.com/LGUG2Z/whkd). - -❗️**NOTE**: This helper library is only compatible with AutoHotKey v1.1, not with AutoHotKey v2. - -Additionally, you may run `komorebic.exe ahk-library` to generate a helper library for AutoHotKey which wraps -every `komorebic` command in a native AHK function. - -The output of this command is in AHKv1 syntax. It must be manually converted to AHKv2 syntax -using [this tool](https://github.com/mmikeww/AHK-v2-script-converter) or something similar. - -If you include the generated library at the top of your `~/komorebi.ahk` configuration file, you will be able to call -any of the functions that it contains. - -#### Using Different AHK Executables - -❗️**NOTE**: This section is only relevant for people who wish to use AutoHotKey instead of [`whkd`](https://github.com/LGUG2Z/whkd). - -The preferred way to install AutoHotKey for use with `komorebi` is to install it via `scoop`: - -```powershell -scoop bucket add versions -scoop install autohotkey -``` - -If you install AutoHotKey using a different method, the name of the executable file may differ from the name given by -`scoop`, and thus what is expected by default in `komorebi`. - -You may override the executable that `komorebi` looks for to launch and reload `komorebi.ahk` configuration files by -setting the `$Env:KOMOREBI_AHK_EXE` environment variable. - -Please keep in mind that even when setting a custom executable name using these environment variables, the executables -are still required to be in your `Path`. - -### Common First-Time Tips - -#### Setting a Custom KOMOREBI_CONFIG_HOME Directory - -If you do not want to keep _komorebi_-related files in your `$Env:USERPROFILE` directory, you can specify a custom directory -by setting the `$Env:KOMOREBI_CONFIG_HOME` environment variable. - -For example, to use the `~/.config/komorebi` directory: - -```powershell -# Run this command to make sure that the directory has been created -mkdir -p ~/.config/komorebi - -# Run this command to open up your PowerShell profile configuration in Notepad -notepad $PROFILE - -# Add this line (with your login user!) to the bottom of your PowerShell profile configuration -$Env:KOMOREBI_CONFIG_HOME = 'C:\Users\LGUG2Z\.config\komorebi' - -# Save the changes and then reload the PowerShell profile -. $PROFILE -``` - -If you already have configuration files that you wish to keep, move them to the `~/.config/komorebi` directory. - -The next time you run `komorebic start`, any files created by or loaded by _komorebi_ will be placed or expected to -exist in this folder. - -#### Generating Common Application-Specific Configurations - -❗️**NOTE**: This section is only relevant for people who use dynamic configuration scripts. - -A curated selection of application-specific configurations can be generated to -help ease the setup for first-time users. -[`komorebi-application-specific-configuration`](https://github.com/LGUG2Z/komorebi-application-specific-configuration) -contains YAML definitions of settings that are known to make tricky -applications behave as expected. These YAML definitions can be used to generate -a `ps1` or an `ahk` file which you can import at the start of your own `komorebi.ps1` or `komorebi.ahk` files, -leaving you to focus primarily on your desired keybindings and workspace -configurations. - -If you have settings for an application that you think should be part of this -curated selection, please open a PR on the configuration repository. - -In the event that your PR is not accepted, or if you find there are any -settings that you wish to override, this can easily be done using an override -file. - -```powershell -# Clone and enter the repository -git clone https://github.com/LGUG2Z/komorebi-application-specific-configuration.git -cd komorebi-application-specific-configuration - -# Use komorebic to generate a ps1 file -komorebic.exe pwsh-app-specific-configuration applications.yaml - -# Application-specific generated configuration written to C:\Users\LGUG2Z\.config\komorebi\komorebi.generated.ps1 - -# Or use komorebic to generate an ahk file -komorebic.exe ahk-app-specific-configuration applications.yaml - -# Application-specific generated configuration written to C:\Users\LGUG2Z\.config\komorebi\komorebi.generated.ahk -# -# You can include the generated configuration at the top of your komorebi.ahk config with this line: -# -# #Include %A_ScriptDir%\komorebi.generated.ahk - -# Optionally, provide an override file that follows the same schema as the second argument -komorebic.exe pwsh-app-specific-configuration applications.yaml overrides.yaml -``` - -#### Adding an Active Window Border - -If you would like to add a visual border around the currently focused window, two commands are available: - -```powershell -komorebic.exe active-window-border [enable|disable] -komorebic.exe active-window-border-colour [R G B] --window-kind single - -# optionally, if you want a different colour for stacks of windows -komorebic.exe active-window-border-colour [R G B] --window-kind stack - -# optionally, if you want a different colour for windows in monocle mode -komorebic.exe active-window-border-colour [R G B] --window-kind monocle -``` - -It is important to note that the active window border will only apply to windows managed by `komorebi`. - -[![Watch the tutorial video](https://img.youtube.com/vi/ywiAvoMV_gE/hqdefault.jpg)](https://www.youtube.com/watch?v=ywiAvoMV_gE) - -#### Removing Gaps - -If you would like to remove all gaps from a given workspace, both between windows themselves, and between the monitor edges and the windows, you can set the following two configuration options to `0` for the desired monitors and workspaces: - -```powershell -komorebic.exe container-padding 0 -komorebic.exe workspace-padding 0 -``` - -[![Watch the tutorial video](https://img.youtube.com/vi/eGr07mymgWE/hqdefault.jpg)](https://www.youtube.com/watch?v=eGr07mymgWE) - -#### Multiple Layout Changes on Startup - -❗️**NOTE**: This section is only relevant for people who use dynamic configuration scripts. - -Depending on what is in your configuration, when `komorebi` is started, you may experience the layout rapidly being adjusted -with many retile events. - -If you would like to avoid this, you can start `komorebi` with a flag which tells `komorebi` to wait until all configuration -has been loaded before listening to and responding to window manager events: `komorebic start --await-configuration`. - -If you start `komorebi` with the `--await-configuration` flag, you _must_ send the `komorebic complete-configuration` -command at the end of the configuration section of your `komorebi.ps1` (or `komorebi.ahk` config, before you start -defining the key bindings). The layout will not be updated and `komorebi` will not respond to `komorebic` commands until -this command has been received. - -#### Floating Windows - -❗️**NOTE**: A significant number of floating window rules for the most common applications are -[already generated for you](https://github.com/LGUG2Z/komorebi/#generating-common-application-specific-configurations) - -Sometimes you will want a specific application to never be tiled, and instead float all the time. You can add rules to -enforce this behaviour: - -```powershell -komorebic.exe float-rule title "Control Panel" -# komorebic.exe float-rule exe [EXE NAME] -# komorebic.exe float-rule class [CLASS NAME] -``` - -#### Windows Not Getting Managed - -❗️**NOTE**: A significant number of force-manage window rules for the most common applications are -[already generated for you](https://github.com/LGUG2Z/komorebi/#generating-common-application-specific-configurations) - -In some rare cases, a window may not automatically be registered to be managed by `komorebi`. When this happens, you can -manually add a rule to force `komorebi` to manage it: - -```powershell -komorebic.exe manage-rule exe TIM.exe -# komorebic.exe manage-rule class [CLASS NAME] -# komorebic.exe manage-rule title [TITLE] -``` - -#### Tray Applications - -❗️**NOTE**: A significant number of tray application rules for the most common applications are -[already generated for you](https://github.com/LGUG2Z/komorebi/#generating-common-application-specific-configurations) - -If you are experiencing behaviour where -[closing a window leaves a blank tile, but minimizing the same window does not](https://github.com/LGUG2Z/komorebi/issues/6) -, you have probably enabled a 'close/minimize to tray' option for that application. You can tell _komorebi_ to handle -this application appropriately by identifying it via the executable name or the window class: - -```powershell -komorebic.exe identify-tray-application exe Discord.exe -# komorebic.exe identify-tray-application class [CLASS NAME] -# komorebic.exe identify-tray-application title [TITLE] -``` - -#### Microsoft Office Applications - -❗️**NOTE**: Microsoft Office-specific application rules are -[already generated for you](https://github.com/LGUG2Z/komorebi/#generating-common-application-specific-configurations) - -Microsoft Office applications such as Word and Excel require certain configuration options to be set in order to be -managed correctly. Below is an example of configuring Microsoft Word to be managed correctly by _komorebi_. - -```powershell -# This only needs to be added once -komorebic.exe float-rule class _WwB - -# Repeat these for other office applications such as EXCEL.EXE etc -# Note that the capitalised EXE is important here- double check the -# exact case for the name and the file extension in Task Manager or -# the AHK Window Spy - -komorebic.exe identify-layered-application exe WINWORD.EXE -komorebic.exe identify-border-overflow-application exe WINWORD.EXE -``` - -#### Focus Follows Mouse - -`komorebi` supports two focus-follows-mouse implementations; the native Windows Xmouse implementation, which treats the -desktop, the task bar, and the system tray as windows and switches focus to them eagerly, and a custom `komorebi` -implementation, which only considers windows managed by `komorebi` as valid targets to switch focus to when moving the -mouse. - -To enable the `komorebi` implementation you must start the process with the `--ffm` flag to explicitly enable the feature. -This is because the mouse tracking required for this feature significantly increases the CPU usage of the process (on my -machine, it jumps from <1% to ~4~), and this CPU increase persists regardless of whether focus-follows-mouse is enabled -or disabled at any given time via `komorebic`'s configuration commands. - -When calling any of the `komorebic` commands related to focus-follows-mouse functionality, the `windows` -implementation will be chosen as the default implementation. You can optionally specify the `komorebi` implementation by -passing it as an argument to the `--implementation` flag: - -```powershell -komorebic.exe toggle-focus-follows-mouse --implementation komorebi -``` - -#### Mouse Follows Focus - -By default, the mouse will move to the center of the window when the focus is changed in a given direction. This -behaviour is know is 'mouse follows focus'. To disable this behaviour across all workspaces, add the following command -to your configuration file: - -```powershell -komorebic.exe mouse-follows-focus disable -``` - -[![Watch the tutorial video](https://img.youtube.com/vi/LBoyXQiNINc/hqdefault.jpg)](https://www.youtube.com/watch?v=LBoyXQiNINc) - -#### Saving and Loading Resized Layouts - -If you create a BSP layout through various resize adjustments that you want to be able to restore easily in the future, -it is possible to "quicksave" that layout to the system's temporary folder and load it later in the same session, or -alternatively, you may save it to a specific file to be loaded again at any point in the future. - -```powershell -komorebic.exe quick-save # saves the focused workspace to $Env:TEMP\komorebi.quicksave.json -komorebic.exe quick-load # loads $Env:TEMP\komorebi.quicksave.json on the focused workspace - -komorebic.exe save ~/layouts/primary.json # saves the focused workspace to $Env:USERPROFILE\layouts\primary.json -komorebic.exe load ~/layouts/secondary.json # loads $Env:USERPROFILE\layouts\secondary.json on the focused workspace -``` - -These layouts can be applied to arbitrary collections of windows on any workspace, as they only track the layout -dimensions and are not coupled to the applications that were running at the time of saving. - -When layouts that expect more or less windows than the number currently on the focused workspace are loaded, `komorebi` -will automatically reconcile the difference. - -#### Creating and Loading Custom Layouts - -Particularly for users of ultrawide monitors, traditional tiling layouts may not seem like the most efficient use of -screen space. If you feel this is the case with any of the default layouts, you are also welcome to create your own -custom layouts and save them as JSON or YAML. - -If you're not comfortable writing the layouts directly in JSON or YAML, you can use -the [komorebi Custom Layout Generator](https://lgug2z.github.io/komorebi-custom-layout-generator/) to interactively -define a custom layout, and then copy the generated JSON content. - -Custom layouts can be loaded on the current workspace or configured for a specific workspace with the following -commands: - -```powershell -komorebic.exe load-custom-layout ~/custom.yaml -komorebic.exe workspace-custom-layout 0 0 ~/custom.yaml -``` - -The fundamental building block of a custom _komorebi_ layout is the Column. - -Columns come in three variants: - -- **Primary**: This is where your primary focus will be on the screen most of the time. There must be exactly one Primary - Column in any custom layout. Optionally, you can specify the percentage of the screen width that you want the Primary - Column to occupy. -- **Secondary**: This is an optional column that can either be full height of split horizontally into a fixed number of - maximum rows. There can be any number of Secondary Columns in a custom layout. -- **Tertiary**: This is the final column where any remaining windows will be split horizontally into rows as they get added. - -If there is only one window on the screen when a custom layout is selected, that window will take up the full work area -of the screen. - -If the number of windows is equal to or less than the total number of columns defined in a custom layout, the windows -will be arranged in an equal-width columns. - -When the number of windows is greater than the number of columns defined in the custom layout, the windows will begin to -be arranged according to the constraints set on the Primary and Secondary columns of the layout. - -Here is an example custom layout that can be used as a starting point for your own: - -YAML - -```yaml -- column: Secondary - configuration: !Horizontal 2 # max number of rows -- column: Primary - configuration: !WidthPercentage 50 # percentage of screen -- column: Tertiary - configuration: Horizontal -``` - -[![Watch the tutorial video](https://img.youtube.com/vi/SgmBHKEOcQ4/hqdefault.jpg)](https://www.youtube.com/watch?v=SgmBHKEOcQ4) - -#### Dynamically Changing Layouts Based on Number of Visible Window Containers - -With `komorebi` it is possible to define rules to automatically change the layout on a specified workspace when a -threshold of window containers is met. - -```powershell -# On the first workspace of the first monitor (0 0) -# When there are one or more window containers visible on the screen (1) -# Use the bsp layout (bsp) -komorebic workspace-layout-rule 0 0 1 bsp - -# On the first workspace of the first monitor (0 0) -# When there are five or more window containers visible on the screen (five) -# Use the custom layout stored in the home directory (~/custom.yaml) -komorebic workspace-custom-layout-rule 0 0 5 ~/custom.yaml -``` - -However, if you add workspace layout rules, you will not be able to manually change the layout of a workspace until all -layout rules for that workspace have been cleared. - -```powershell -# If you decide that workspace layout rules are not for you, you can remove them from that same workspace like this -komorebic clear-workspace-layout-rules 0 0 -``` - ## Development If you would like to contribute code to this repository, there are a few requests that I have to ensure a foundation of diff --git a/docs/common-workflows/active-window-border.md b/docs/common-workflows/active-window-border.md new file mode 100644 index 00000000..bfd3f391 --- /dev/null +++ b/docs/common-workflows/active-window-border.md @@ -0,0 +1,40 @@ +# Active Window Border + +If you would like to add a visual border around the currently focused window, +ensure the following options are defined in the `komorebi.json` configuration +file. + +```json +{ + "active_window_border": true, + "active_window_border_colours": { + "single": { + "r": 66, + "g": 165, + "b": 245 + }, + "stack": { + "r": 256, + "g": 165, + "b": 66 + }, + "monocle": { + "r": 255, + "g": 51, + "b": 153 + } + } +} + +``` + +It is important to note that the active window border 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/ywiAvoMV_gE/hqdefault.jpg)](https://www.youtube.com/watch?v=ywiAvoMV_gE) diff --git a/docs/common-workflows/autohotkey.md b/docs/common-workflows/autohotkey.md new file mode 100644 index 00000000..c0effc87 --- /dev/null +++ b/docs/common-workflows/autohotkey.md @@ -0,0 +1,30 @@ +# AutoHotKey + + + +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.19/komorebic.lib.ahk -OutFile $Env:USERPROFILE\komorebic.lib.ahk + +# save the latest generated app-specific config tweaks and fixes to ~/komorebi.generated.ahk +iwr https://raw.githubusercontent.com/LGUG2Z/komorebi/v0.1.19/komorebi.generated.ahk -OutFile $Env:USERPROFILE\komorebi.generated.ahk + +# save the sample komorebi configuration file to ~/komorebi.ahk +iwr https://raw.githubusercontent.com/LGUG2Z/komorebi/v0.1.19/komorebi.sample.ahk -OutFile $Env:USERPROFILE\komorebi.ahk +``` + diff --git a/docs/common-workflows/custom-layouts.md b/docs/common-workflows/custom-layouts.md new file mode 100644 index 00000000..9e43f3c0 --- /dev/null +++ b/docs/common-workflows/custom-layouts.md @@ -0,0 +1,70 @@ +# Custom Layouts + +Particularly for users of ultrawide monitors, traditional tiling layouts may +not seem like the most efficient use of screen space. If you feel this is the +case with any of the default layouts, you are also welcome to create your own +custom layouts and save them as JSON or YAML. + +If you're not comfortable writing the layouts directly in JSON or YAML, you can +use the [komorebi Custom Layout +Generator](https://lgug2z.github.io/komorebi-custom-layout-generator/) to +interactively define a custom layout, and then copy the generated JSON content. + +Custom layouts can be loaded on the current workspace or configured for a +specific workspace in the `komorebi.json` configuration file. + +```json +{ + "monitors": [ + { + "workspaces": [ + { + "name": "personal", + "custom_layout": "C:/Users/LGUG2Z/my-custom-layout.json" + }, + ] + } + ] +} +``` + +The fundamental building block of a custom _komorebi_ layout is the Column. + +Columns come in three variants: + +- **Primary**: This is where your primary focus will be on the screen most of + the time. There must be exactly one Primary Column in any custom layout. + Optionally, you can specify the percentage of the screen width that you want + the Primary Column to occupy. +- **Secondary**: This is an optional column that can either be full height of + split horizontally into a fixed number of maximum rows. There can be any + number of Secondary Columns in a custom layout. +- **Tertiary**: This is the final column where any remaining windows will be + split horizontally into rows as they get added. + +If there is only one window on the screen when a custom layout is selected, +that window will take up the full work area of the screen. + +If the number of windows is equal to or less than the total number of columns +defined in a custom layout, the windows will be arranged in an equal-width +columns. + +When the number of windows is greater than the number of columns defined in the +custom layout, the windows will begin to be arranged according to the +constraints set on the Primary and Secondary columns of the layout. + +Here is an example custom layout that can be used as a starting point for your +own: + +```yaml +- column: Secondary + configuration: !Horizontal 2 # max number of rows +- column: Primary + configuration: !WidthPercentage 50 # percentage of screen +- column: Tertiary + configuration: Horizontal +``` + + + +[![Watch the tutorial video](https://img.youtube.com/vi/SgmBHKEOcQ4/hqdefault.jpg)](https://www.youtube.com/watch?v=SgmBHKEOcQ4) diff --git a/docs/common-workflows/dynamic-layout-switching.md b/docs/common-workflows/dynamic-layout-switching.md new file mode 100644 index 00000000..dd901d67 --- /dev/null +++ b/docs/common-workflows/dynamic-layout-switching.md @@ -0,0 +1,37 @@ +# Dynamically Layout Switching + +With `komorebi` it is possible to define rules to automatically change the +layout on a specified workspace when a threshold of window containers is met. + +```json +{ + "monitors": [ + { + "workspaces": [ + { + "name": "personal", + "layout_rules": { + "1": "BSP" + } + "custom_layout_rules": { + "5": "C:/Users/LGUG2Z/my-custom-layout.json" + } + }, + ] + } + ] +} +``` + +In this example, when there are one or more window containers visible on the +screen, the BSP layout is used, and when there are five or more window +containers visible, a custom layout is used. + +However, if you add workspace layout rules, you will not be able to manually +change the layout of a workspace until all layout rules for that workspace have +been cleared. + +```powershell +# for example, to clear rules from monitor 0, workspace 0 +komorebic clear-workspace-layout-rules 0 0 +``` diff --git a/docs/common-workflows/focus-follows-mouse.md b/docs/common-workflows/focus-follows-mouse.md new file mode 100644 index 00000000..1adb06f9 --- /dev/null +++ b/docs/common-workflows/focus-follows-mouse.md @@ -0,0 +1,34 @@ +# Focus Follows Mouse + +`komorebi` supports two focus-follows-mouse implementations; the native Windows +Xmouse implementation, which treats the desktop, the task bar, and the system +tray as windows and switches focus to them eagerly, and a custom `komorebi` +implementation, which only considers windows managed by `komorebi` as valid +targets to switch focus to when moving the mouse. + +To enable the `komorebi` implementation you must start the process with the +`--ffm` flag to explicitly enable the feature. This is because the mouse +tracking required for this feature significantly increases the CPU usage of the +process (on my machine, it jumps from <1% to ~4~), and this CPU increase +persists regardless of whether focus-follows-mouse is enabled or disabled at +any given time via `komorebic`'s configuration commands. + +If the `komorebi` process has been started with the `--ffm` flag, you can +enable focus follows mouse behaviour in the `komorebi.json` configuration file. + +```json +{ + "focus_follows_mouse": "Komorebi" +} +``` + +When calling any of the `komorebic` commands related to focus-follows-mouse +functionality, the `windows` implementation will be chosen as the default +implementation. You can optionally specify the `komorebi` implementation by +passing it as an argument to the `--implementation` flag: + +```powershell +komorebic.exe toggle-focus-follows-mouse --implementation komorebi +``` + + diff --git a/docs/common-workflows/force-manage-windows.md b/docs/common-workflows/force-manage-windows.md new file mode 100644 index 00000000..54807d92 --- /dev/null +++ b/docs/common-workflows/force-manage-windows.md @@ -0,0 +1,21 @@ +# Force Manage Windows + +❗️**NOTE**: A significant number of force-manage window rules for the most +common applications are [already generated for +you](https://github.com/LGUG2Z/komorebi/#generating-common-application-specific-configurations) + +In some rare cases, a window may not automatically be registered to be managed +by `komorebi`. You can add rules to enforce this behaviour in the +`komorebi.json` configuration file. + +```json +{ + "manage_rules": [ + { + "kind": "Title", + "id": "Media Player", + "matching_strategy": "Equals" + } + ] +} +``` diff --git a/docs/common-workflows/ignore-windows.md b/docs/common-workflows/ignore-windows.md new file mode 100644 index 00000000..72cdcb0a --- /dev/null +++ b/docs/common-workflows/ignore-windows.md @@ -0,0 +1,21 @@ +# Ignore Windows + +❗️**NOTE**: A significant number of ignored window rules for the most common +applications are [already generated for +you](https://github.com/LGUG2Z/komorebi/#generating-common-application-specific-configurations) + +Sometimes you will want a specific application to never be tiled, and instead +float all the time. You can add rules to enforce this behaviour in the +`komorebi.json` configuration file. + +```json +{ + "float_rules": [ + { + "kind": "Title", + "id": "Media Player", + "matching_strategy": "Equals" + } + ] +} +``` diff --git a/docs/common-workflows/komorebi-config-home.md b/docs/common-workflows/komorebi-config-home.md new file mode 100644 index 00000000..66a89e88 --- /dev/null +++ b/docs/common-workflows/komorebi-config-home.md @@ -0,0 +1,27 @@ +# `KOMOREBI_CONFIG_HOME` + +If you do not want to keep _komorebi_-related files in your `$Env:USERPROFILE` +directory, you can specify a custom directory by setting the +`$Env:KOMOREBI_CONFIG_HOME` environment variable. + +For example, to use the `~/.config/komorebi` directory: + +```powershell +# Run this command to make sure that the directory has been created +mkdir -p ~/.config/komorebi + +# Run this command to open up your PowerShell profile configuration in Notepad +notepad $PROFILE + +# Add this line (with your login user!) to the bottom of your PowerShell profile configuration +$Env:KOMOREBI_CONFIG_HOME = 'C:\Users\LGUG2Z\.config\komorebi' + +# Save the changes and then reload the PowerShell profile +. $PROFILE +``` + +If you already have configuration files that you wish to keep, move them to the +`~/.config/komorebi` directory. + +The next time you run `komorebic start`, any files created by or loaded by +_komorebi_ will be placed or expected to exist in this folder. diff --git a/docs/common-workflows/mouse-follows-focus.md b/docs/common-workflows/mouse-follows-focus.md new file mode 100644 index 00000000..7c69bf90 --- /dev/null +++ b/docs/common-workflows/mouse-follows-focus.md @@ -0,0 +1,15 @@ +# Mouse Follows Focus + +By default, the mouse will move to the center of the window when the focus is +changed in a given direction. This behaviour is know as 'mouse follows focus'. +This behaviour can be disabled in the `komorebi.json` configuration file. + +```json +{ + "mouse_follows_focus": false, +} +``` + + + +[![Watch the tutorial video](https://img.youtube.com/vi/LBoyXQiNINc/hqdefault.jpg)](https://www.youtube.com/watch?v=LBoyXQiNINc) diff --git a/docs/common-workflows/remove-gaps.md b/docs/common-workflows/remove-gaps.md new file mode 100644 index 00000000..3e060fc6 --- /dev/null +++ b/docs/common-workflows/remove-gaps.md @@ -0,0 +1,17 @@ +# Remove Gaps + +If you would like to remove all gaps by default, both between windows +themselves, and between the monitor edges and the windows, you can set the +following two configuration options to `0` in the `komorebi.json` configuration +file. + +```json +{ + "default_workspace_padding": 0, + "default_container_padding": 0 +} +``` + + + +[![Watch the tutorial video](https://img.youtube.com/vi/eGr07mymgWE/hqdefault.jpg)](https://www.youtube.com/watch?v=eGr07mymgWE) diff --git a/docs/common-workflows/tray-and-multi-window-applications.md b/docs/common-workflows/tray-and-multi-window-applications.md new file mode 100644 index 00000000..e90917be --- /dev/null +++ b/docs/common-workflows/tray-and-multi-window-applications.md @@ -0,0 +1,23 @@ +# Tray and Multi-Window Applications + +❗️**NOTE**: A significant number of tray and multi-window application rules for +the most common applications are [already generated for +you](https://github.com/LGUG2Z/komorebi/#generating-common-application-specific-configurations) + +If you are experiencing behaviour where closing a window leaves a blank tile, +but minimizing the same window does not, you have probably enabled a +'close/minimize to tray' option for that application. You can tell `komorebi` +to handle this application appropriately by identifying it via the executable +name or the window class. + +```json +{ + "tray_and_multi_window_applications": [ + { + "kind": "Class", + "id": "SDL_app", + "matching_strategy": "Equals" + } + ] +} +``` diff --git a/mkdocs.yml b/mkdocs.yml index 4766bcce..43562460 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -50,8 +50,19 @@ nav: - Getting started: - Installation: installation.md - Example configurations: example-configurations.md - - Configuration: - - JSONSchema reference: https://komorebi.lgug2z.com/schema + - Common workflows: + - common-workflows/komorebi-config-home.md + - common-workflows/active-window-border.md + - common-workflows/remove-gaps.md + - common-workflows/ignore-windows.md + - common-workflows/force-manage-windows.md + - common-workflows/tray-and-multi-window-applications.md + - common-workflows/focus-follows-mouse.md + - common-workflows/mouse-follows-focus.md + - common-workflows/custom-layouts.md + - common-workflows/dynamic-layout-switching.md + - common-workflows/autohotkey.md + - Configuration reference: https://komorebi.lgug2z.com/schema - CLI reference: - cli/quickstart.md - cli/start.md