mirror of
https://github.com/LGUG2Z/komorebi.git
synced 2026-03-18 07:23:57 +01:00
docs(readme): initial readme, license and sample config
This commit is contained in:
LGUG2Z
21
LICENSE
Normal file
21
LICENSE
Normal file
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2021 Jade Iqbal
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
105
README.md
Normal file
105
README.md
Normal file
@@ -0,0 +1,105 @@
|
||||
# komorebi
|
||||
|
||||
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* 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.
|
||||
|
||||
## 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. AutoHotKey) 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
|
||||
ahk --------> komorebic <------> komorebi
|
||||
```
|
||||
|
||||
## Design
|
||||
|
||||
*komorebi* is the successor to [*yatta*](https://github.com/LGUG2Z/yatta) and as such aims to build on the learnings
|
||||
from that project.
|
||||
|
||||
While *yatta* was primary an attempt to learn how to work with and call Windows APIs from Rust, while secondarily
|
||||
implementing a minimal viable tiling window manager for my own needs (largely single monitor, single workspace),
|
||||
*komorebi* has been redesigned from the ground-up to support more complex features that have become standard in tiling
|
||||
window managers on other platforms.
|
||||
|
||||
*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
|
||||
|
||||
This project is still heavily under development and there are no prebuilt binaries available yet.
|
||||
|
||||
If you would like to use *komorebi*, you will need
|
||||
a [working Rust development environment on Windows 10](https://rustup.rs/). If you are using
|
||||
the `x86_64-pc-windows-msvc` toolchain, 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
|
||||
cargo install --path komorebic
|
||||
```
|
||||
|
||||
By running `komorebic start` at a Powershell prompt, you should see the following output:
|
||||
|
||||
```
|
||||
Start-Process komorebi -WindowStyle hidden
|
||||
```
|
||||
|
||||
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`.
|
||||
|
||||
## Configuration
|
||||
|
||||
As previously mentioned, this project does not handle anything related to keybindings and shortcuts directly. I
|
||||
personally use AutoHotKey to manage my window management shortcuts, and have provided a
|
||||
sample [komorebi.ahk](komorebi.sample.ahk) AHK script that you can use as a starting point for your own.
|
||||
|
||||
## Development
|
||||
|
||||
If you would like to contribute code to this repository, there are a few requests that I have to ensure a foundation of
|
||||
code quality, consistency and commit hygiene:
|
||||
|
||||
* Flatten all `use` statements except in `bindings/build.rs`
|
||||
* Run `cargo +nightly clippy` and ensure that all lints and suggestions have been addressed before committing
|
||||
* Run `cargo +nightly fmt --all` to ensure consistent formatting before committing
|
||||
* Use `git cz` with
|
||||
the [Commitizen CLI](https://github.com/commitizen/cz-cli#conventional-commit-messages-as-a-global-utility) to prepare
|
||||
commit messages
|
||||
* Provide at least one short sentence or paragraph in your commit message body to describe your thought process for the
|
||||
changes being committed
|
||||
177
komorebi.sample.ahk
Normal file
177
komorebi.sample.ahk
Normal file
@@ -0,0 +1,177 @@
|
||||
; Ensure there are 3 workspaces created on monitor 0
|
||||
Run, komorebic.exe ensure-workspaces 0 4
|
||||
|
||||
; Give the workspaces some optional names
|
||||
Run, komorebic.exe workspace-name 0 0 bsp
|
||||
Run, komorebic.exe workspace-name 0 1 columns
|
||||
Run, komorebic.exe workspace-name 0 2 thicc
|
||||
Run, komorebic.exe workspace-name 0 3 matrix
|
||||
|
||||
; Set the padding of the different workspaces
|
||||
Run, komorebic.exe workspace-padding 0 1 50
|
||||
Run, komorebic.exe container-padding 0 1 50
|
||||
Run, komorebic.exe workspace-padding 0 2 200
|
||||
Run, komorebic.exe workspace-padding 0 3 0
|
||||
Run, komorebic.exe container-padding 0 3 0
|
||||
|
||||
; Set the layouts of different workspaces
|
||||
Run, komorebic.exe workspace-layout 0 1 columns
|
||||
|
||||
; Always float IntelliJ popups, matching on class
|
||||
Run, komorebic.exe float-class SunAwtDialog, , Hide
|
||||
; Always float Control Panel, matching on title
|
||||
Run, komorebic.exe float-title "Control Panel", , Hide
|
||||
; Always float Task Manager, matching on class
|
||||
Run, komorebic.exe float-class TaskManagerWindow, , Hide
|
||||
; Always float Wally, matching on executable name
|
||||
Run, komorebic.exe float-exe Wally.exe, , Hide
|
||||
; Always float Calculator app, matching on window title
|
||||
Run, komorebic.exe float-title Calculator, , Hide
|
||||
Run, komorebic.exe float-exe 1Password.exe, , Hide
|
||||
|
||||
; Change the focused window, Alt + Vim direction keys
|
||||
!h::
|
||||
Run, komorebic.exe focus left, , Hide
|
||||
return
|
||||
|
||||
!j::
|
||||
Run, komorebic.exe focus down, , Hide
|
||||
return
|
||||
|
||||
!k::
|
||||
Run, komorebic.exe focus up, , Hide
|
||||
return
|
||||
|
||||
!l::
|
||||
Run, komorebic.exe focus right, , Hide
|
||||
return
|
||||
|
||||
; Move the focused window in a given direction, Alt + Shift + Vim direction keys
|
||||
!+h::
|
||||
Run, komorebic.exe move left, Hide
|
||||
return
|
||||
|
||||
!+j::
|
||||
Run, komorebic.exe move down, Hide
|
||||
return
|
||||
|
||||
!+k::
|
||||
Run, komorebic.exe move up, Hide
|
||||
return
|
||||
|
||||
!+l::
|
||||
Run, komorebic.exe move right, Hide
|
||||
return
|
||||
|
||||
; Stack the focused window in a given direction, Alt + direction keys
|
||||
!Left::
|
||||
Run, komorebic.exe stack left, Hide
|
||||
return
|
||||
|
||||
!Down::
|
||||
Run, komorebic.exe stack down, Hide
|
||||
return
|
||||
|
||||
!Up::
|
||||
Run, komorebic.exe stack up, Hide
|
||||
return
|
||||
|
||||
!Right::
|
||||
Run, komorebic.exe stack right, Hide
|
||||
return
|
||||
|
||||
!]::
|
||||
Run, komorebic.exe cycle-stack next, , Hide
|
||||
return
|
||||
|
||||
![::
|
||||
Run, komorebic.exe cycle-stack previous, , Hide
|
||||
return
|
||||
|
||||
; Unstack the focused window
|
||||
!d::
|
||||
Run, komorebic.exe unstack, Hide
|
||||
return
|
||||
|
||||
; Promote the focused window to the top of the tree, Alt + Shift + Enter
|
||||
!+Enter::
|
||||
Run, komorebic.exe promote, Hide
|
||||
return
|
||||
|
||||
; Switch to an equal-width, max-height column layout on the main workspace, Alt + Shift + C
|
||||
!+c::
|
||||
Run, komorebic.exe workspace-layout 0 0 columns, Hide
|
||||
return
|
||||
|
||||
; Switch to the default bsp tiling layout on the main workspace, Alt + Shift + T
|
||||
!+t::
|
||||
Run, komorebic.exe workspace-layout 0 0 bsp, Hide
|
||||
return
|
||||
|
||||
; Toggle the Monocle layout for the focused window, Alt + Shift + F
|
||||
!+f::
|
||||
Run, komorebic.exe toggle-monocle, Hide
|
||||
return
|
||||
|
||||
; Flip horizontally, Alt + X
|
||||
!x::
|
||||
Run, komorebic.exe flip-layout horizontal, Hide
|
||||
return
|
||||
|
||||
; Flip vertically, Alt + Y
|
||||
!y::
|
||||
Run, komorebic.exe flip-layout vertical, Hide
|
||||
return
|
||||
|
||||
; Force a retile if things get janky, Alt + Shift + R
|
||||
!+r::
|
||||
Run, komorebic.exe retile, Hide
|
||||
return
|
||||
|
||||
; Float the focused window, Alt + T
|
||||
!t::
|
||||
Run, komorebic.exe toggle-float, Hide
|
||||
return
|
||||
|
||||
; Pause responding to any window events or komorebic commands, Alt + P
|
||||
!p::
|
||||
Run, komorebic.exe toggle-pause, Hide
|
||||
return
|
||||
|
||||
; Switch to workspace
|
||||
!1::
|
||||
Send !
|
||||
Run, komorebic.exe focus-workspace 0, Hide
|
||||
return
|
||||
|
||||
!2::
|
||||
Send !
|
||||
Run, komorebic.exe focus-workspace 1, Hide
|
||||
return
|
||||
|
||||
!3::
|
||||
Send !
|
||||
Run, komorebic.exe focus-workspace 2, Hide
|
||||
return
|
||||
|
||||
!4::
|
||||
Send !
|
||||
Run, komorebic.exe focus-workspace 3, Hide
|
||||
return
|
||||
|
||||
; Move window to workspace
|
||||
!+1::
|
||||
Run, komorebic.exe move-to-workspace 0, Hide
|
||||
return
|
||||
|
||||
!+2::
|
||||
Run, komorebic.exe move-to-workspace 1, Hide
|
||||
return
|
||||
|
||||
!+3::
|
||||
Run, komorebic.exe move-to-workspace 2, Hide
|
||||
return
|
||||
|
||||
!+4::
|
||||
Run, komorebic.exe move-to-workspace 3, Hide
|
||||
return
|
||||
Reference in New Issue
Block a user