|
|
|
@@ -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.
|
|
|
|
|
|
|
|
|
|
[](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
|
|
|
|
|
|
|
|
|
|
[](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 <COMMAND> --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`.
|
|
|
|
|
|
|
|
|
|
[](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 <MONITOR_INDEX> <WORKSPACE_INDEX> 0
|
|
|
|
|
komorebic.exe workspace-padding <MONITOR_INDEX> <WORKSPACE_INDEX> 0
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
[](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
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
[](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
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
[](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
|
|
|
|
|
LGUG2Z