awm/README.md

# awm – Alacritty Window Manager
A simple WM to manage your Alacritty terminal windows.

## What is AWM?
Alacritty Window Manager (AWM) is a Window Manager (WM) akin to software like DWM 
which is responsible for tiling windows open on the desktop into appropriate
layout configurations. It differs from conventional window tiling acheived by
dragging window tabs into different regions of a desktop environment, simply
because WMs are used in non-DEs whereby this mechanic does not exist. Windows
which also lack decoration frames to allow them to be moved via dragging benefit
from WMs correctly arranging them.

Now, AWM does not take any inspiration from DWM, more than what DWM takes from
general WMs. AWM works with the Win32 API, whereas DWM works with X11, so
everything within the APIs will be completely different. DWM is also a general WM
for tiling all windows on a system, and AWM works only for Alacritty terminals.

## Why Does AWM Exist?
Why do WMs exist in general? They're sleek-looking, organise windows in an easy
fashion, do better jobs than DEs, amongst many more reason. The main reason is
that if a window GUI is created without a frame, there's no easy way to then
move that window, let alone to a specific location on a screen.

AWM achieves all of this. It allows for no decoration on Alacritty windows, whilst
being able to organise up to four windows Alacritty creates for terminal sessions.
And this is all for Windows to make life much easier for users, whilst still
looking like novice ricers.

## How Does AWM Work?
Well, AWM is heavily documented in the code base, which consists of a single C++
file. But the short version is as followed:

- When `awm` is executed, it will go and find all windows associated with
Alacritty (up to 4 at most).
- Once it has found the windows, it organises them based on a set of predefined
configurations depending on the number of windows found.
- This occurs simultaneously to give a smooth organisation transition for any
number of Alacritty terminal windows.

It's that simple. No additional event listeners/hooks, no spawning new processes.

For a more in-depth, and technically explanation where applicable, consult the 
`main.cpp` found in the root directory of the project's workspace.

## How to Install AWM
Currently, the only way to install AWM is by manually compiling the binary and
placing it somewhere in your local user-space and adding that to your path. You 
may wish to keep the compiled binary in the repo and have your path point to that
location.

Compiling can be performed with any compiler. There's no linking of other libraries
or C++ source files, assuming that the appropriate header files are installed to
the system, it should just compile.

However, the only compiler that has been used for AWM is the `g++` compiler by
GNU. If you have this compiler installed, the following command will compile the
binary on your system (CWD set to the awm repo):

```cmd
mkdir bin
g++ -O3 -std=c++11 main.cpp -o bin\awm.exe
```

_Compilation should compile without any errors, and any such which are reported
might be due to missing header files. Please consult the `main.cpp` file for the
relavent header files and/or libraries._

Afterwards, you can add the `bin` directory to your local Path (or system-wide
with appropriate pivilage levels). Something as followed in PowerShell will allow
AWM to be ran anywhere on the system:

```ps
$env:Path += ';\path\to\awm\bin'
```

## How to Use AWM
AWM can simply be called directly as a program, and will attempt to organise any
Alacritty windows it identifies. However, a more useful usage would be via
Alacritty keybindings. This can be simply achieved in the `alacritty.yml`
configuration file using the `command` action.

The following is an example keybinding configuration which can be used in
Alacritty (with respect to potential conflicts with other bindings). Open the
YAML file in an editor (typically located at `%APPDATA%\alacritty\alacritty.yml`)
and add the following line:

```yaml
key_bindings:
  - { key: O, mods: Control|Shift, command: { program: "awm", args: [] } }
```

This will then call AWM wherever its located on the system via Path and organise
Alacritty windows accordingly.

**Note:** AWM does not listen for when Alacritty windows are created or destroyed.
It simply organises windows it's able to collect in a tiled manner when told to.

## AWM Features
AWM comes with a couple different features, notably the WM itself.
- Window Manager – the core functionality of AWM. This goes without say that it's
the biggest and primary feature of AWM (AWM does what it says on the tin). It
supports up to four layouts of Alacritty instances, but does not organise new
Alacritty windows.
- Fullscreen Terminals – AWM supports toggling Alacritty terminals into fullscreen.
This doesn't hide the taskbar, nor consume the entire desktop work area, but it does
take up majority of the desktop. This allows for greater focus and work area within
a selected terminal, hiding other windows behind. Run `awm --fullscreen` to toggle
this behaviour. When exiting fullscreen, the window will be placed back in its
original tiled configuration with other Alacritty instances.

## Known Issues & Limitations
### With AWM Itself
As discussed in the note above, and elsewhere, AWM **does not** add event hooks
to the system, or listen to any event hooks that might trigger when an Alacritty
window is created or destroyed. For this reason, AWM must be manually told when
to organise windows on the desktop. If this feature is to be required, a separate
executable should be created to handle these hook events and compile AWM into its
binary to then call the existing WM source code.

Another known issue is with Task Manager and not compiling with at least `-O3`.
Put simply, if the binary is compiled without this optimisation flag, and Task
Manager is open, AWM will fail to organise the windows due to Task Manager. It's
currently unknown why this bug exists without `-O3`, and doesn't with the flag,
but it can be easily avoided with the `-O3` flag using `g++`. A future patch may
be applied to this in the future.
### Due to Alacritty
It seems that there might be a few issues as a result of Alacritty (or perhaps
within the dependencies it uses). Firstly, after some more in-depth experimentation
of the Win32 API, it seems as though Alacritty does not set the correct flags on a
window defined in the API to indicate that a window is minimised. This makes it
impossible for AWM to correctly filter non-viewable terminals out of organisation.
### Shared & Due to Knowledge
When a new window is created in Alacritty, it simply spawns a new Console Host
program (`conhost.exe`). This is specific to Windows and whose purpose is out of
the scope of this document. However, it means that a single `alacritty.exe` program
exists with multiple conhost applications running PowerShell. From experiments,
you can't simply change the window's context of conhost apps without causing some
mischievious behaviour. A conhost app will refer back to Alacritty in some way,
but it's not possible to refer to Alacritty for changing the context of a window.
Or at least, it's not possible with the current knowledge of the project. Alacritty
might be behaving exactly as intended of Windows' apps, but as it stands, AWM
cannot organise new windows of Alacritty, only new instances.

## Licence
This project is licenced until the GNU GPLv3+ licence agreement, which can be
viewed in the `LICENCE.txt` file in the root directory of the repository.

## Author
Ethan Smith-Coss (ethan.sc@closedless.xyz)

## Bug Tracker
To report a bug, or feature of the program, an Issue can be created with the
relavent information.