layout-machi/README.md

# layout-machi

A manual layout for Awesome with a rapid interactive editor.

## Why?

TL;DR --- I want the control of my layout.

1. Dynamic tiling is an overkill, since tiling is only useful for persistent windows, and people extensively use hibernate/sleep these days.
2. I don't want to have all windows moving around whenever a new window shows up.
3. I want to have a flexible layout such that I can quickly adjust to whatever I need.

## Use the layout

Use `layout = layout_machi.layout.create(name)` to instantiate the layout.
It is advised to instantiate layouts of unique names for each tag (and for each screen), since the editor will restore the last regions of the layout based on the names.

## Editor

Call `editor = layout_machi.editor.create()` to create an editor that can interactively edit the current layout by calling `editor.start_interactive()`.

### The layout editing command

The editing starts with the open area of the entire workarea, takes commands to split the current area into multiple sub-areas, then recursively edits each of them.
The editor is keyboard driven, each command is a key with at most 2 digits as parameters (A, B) before the command.
Undefined parameters are (mostly) treated as 1.

1. `Up`/`Down`: restore to the history command sequence
2. `h`/`v`: split the current region horizontally/vertically into 2 regions. The split will respect the ratio A:B.
3. `w`: Take two parameters (A, B), and split the current region equally into A columns and B rows. If no parameter is defined, behave the same as `Space` without parameters.
4. `s`: shift the current editing region with other open regions. If A is defined, shift for A times.
5. `Space` or `-`: Without parameters, close the current region and move to the next open region. With parameters, set the maximum depth of splitting (default is 2).
6. `Enter`/`.`: close all open regions. When all regions are closed, press `Enter` will save the layout and exit the editor.
7. `Backspace`: undo the last command.
8. `Escape`: exit the editor without saving the layout.

For examples:

`h-v`

```
11 22
11 22
11
11 33
11 33
```


`hvv` (or `22w`)

```
11 33
11 33

22 44
22 44
```


`3-13h2v--2h-12v`

Details:

 - `3-`: set the maximum editing depth to 3
 - `13h`: horizontally split the initial region (entire desktop) to the ratio of 1:3
 - For the left part:
   - `2v`: vertically split the region to the ratio of 2:1
   - `--`: ignore further editing the splitted regions
 - For the right part:
   - `2h`: horizontally split the region to the ratio of 2:1
   - `-`: ignore the left part of the splitted regions
   - `12v`: split the right part vertically to the ratio of 1:2

Tada!

```
11 3333 44
11 3333 44
11 3333
11 3333 55
   3333 55
22 3333 55
22 3333 55
```


### Persistent history

By default, the last 100 command sequences are stored in `~/.machi_history`.
To change that, please refer to `editor.lua`. (XXX more documents)

## Switcher

Calling `layout_machi.switcher.start()` will create a switcher that can (1) move window/focus into other regions by direction keys, and (2) switch windows in the same regions using `Tab` key. 

## Other functions

`layout_machi.editor.fit_region(c, cycle = false)` will fit a floating client into the closest region.
If `cycle` is true, it then moves the window by cycling all regions.

`layout_machi.editor.refresh_layout(layout, screen)` will recalculate the regions of the layout based on the workarea of the `screen` and the last editing command performed on `layout`.

## TODO

 - Tabs on regions?

## License

Apache 2.0 --- See LICENSE