diff --git a/config-examples/default-config.toml b/config-examples/default-config.toml index efbe9e21..5c59a96e 100644 --- a/config-examples/default-config.toml +++ b/config-examples/default-config.toml @@ -22,8 +22,8 @@ enable-normalization-flatten-containers = true enable-normalization-opposite-orientation-for-nested-containers = true # Accordion is a layout where windows are placed on top of each other. -# - Horizontal accordion puts paddings on left and right to make it clear that containers exist in these directions -# - Vertical accordion puts paddings on above and below to make it clear that containers exist in these directions +# - Horizontal accordion puts paddings on left and right to make it clear that other windows exist in these directions +# - Vertical accordion puts paddings on above and below to make it clear that other windows exist in these directions # The 'accordion-padding' specifies the size of the padding. You can set 0 to disable the padding feature accordion-padding = 30 diff --git a/docs/.assets/h_accordion.png b/docs/.assets/h_accordion.png new file mode 100644 index 00000000..e5faf9e5 Binary files /dev/null and b/docs/.assets/h_accordion.png differ diff --git a/docs/.assets/h_list.png b/docs/.assets/h_list.png new file mode 100644 index 00000000..374574ef Binary files /dev/null and b/docs/.assets/h_list.png differ diff --git a/docs/.assets/tree.png b/docs/.assets/tree.png new file mode 100644 index 00000000..8eb863c7 Binary files /dev/null and b/docs/.assets/tree.png differ diff --git a/docs/.assets/v_accordion.png b/docs/.assets/v_accordion.png new file mode 100644 index 00000000..6593a4e2 Binary files /dev/null and b/docs/.assets/v_accordion.png differ diff --git a/docs/commands.md b/docs/commands.md index d7d31fd7..49389465 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -107,11 +107,97 @@ mode name_of_the_target_mode ## move-through ``` -move-through (left|down|up|right) +move-through (left|down|up|right) [floating_pixel] ``` +Moves the window in the given direction. The optional `floating_pixel` argument specifies how far the window should be moved if +it is floating. The default is 50 pixels + This command is an analog of [i3's move command](https://i3wm.org/docs/userguide.html#move_direction) +**Example 1** + +Given this layout +``` +h_list +├── window 1 (focused) +└── window 2 +``` + +`move-through right` will result in the following layout +``` +h_list +├── window 2 +└── window 1 (focused) +``` + +**Example 2** + +Given this layout +``` +h_list +├── window 1 +├── window 2 (focused) +└── v_list + ├── window 3 + └── window 4 +``` + +`move-through right` will result in the following layout +``` +h_list +├── window 1 +└── v_list + ├── window 3 + ├── window 2 (focused) + └── window 4 +``` + +**Example 3** + +Given this layout +``` +h_list +├── window 1 +└── v_list + ├── window 3 + ├── window 2 (focused) + └── window 4 +``` + +`move-through left` will result in the following layout +``` +h_list +├── window 1 +├── window 2 (focused) +└── v_list + ├── window 3 + └── window 4 +``` + +**Implicit container example** + +In some cases, `move-through` needs to implicitly create a container to fullfill your command. + +Given this layout +``` +h_list +├── window 1 +├── window 2 (focused) +└── window 3 +``` + +`move-through up` will result in the following layout +``` +v_list +├── window 2 (focused) +└── h_list + ├── window 1 + └── window 3 +``` + +`v_list` is an implicitly created container. + ## move-workspace-to-display ## reload-config diff --git a/docs/guide.md b/docs/guide.md index 393999cd..1f030631 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -3,6 +3,7 @@ **Table of contents** - [Tree](#tree) + - [Layouts](#layouts) - [Normalization](#normalization) - [Floating windows](#floating-windows) - [Default keybindings](#default-keybindings) @@ -15,10 +16,64 @@ - [Multiple displays](#multiple-displays) ## Tree -TODO DOCUMENTATION. This section is yet to be written, for now you can refer to https://i3wm.org/docs/userguide.html#tree + +AeroSpace stores all windows and containers in a tree. AeroSpace tree tiling model is [inspired by +i3](https://i3wm.org/docs/userguide.html#tree). + +- Each workspace contains its own single root node +- Each non-leaf node can contain arbitrary number of children nodes +- Windows are the only possible leaf nodes. Windows contain zero children nodes +- Every non-leaf node has two properties: + 1. [Layout](#layouts) (list or accordion) + 2. Orientation (horizontal or vertical) + +When we say "layout of the window", we refer to the layout of the window's parent. + +It's easier to understand tree tiling model by looking at examples + +![](./.assets/h_list.png) +![](./.assets/tree.png) + +You can have as deeply layout as you want to. + +You can navigate in the tree in 4 possible cardinal directions (left, down, up, right). You use [focus +command](./commands.md#focus) to navigate in the tree. + +You can change the tree structure with two commands: +- [move-through](./commands.md#move-through) +- [move-in](./commands.md#move-in) + +### Layouts + +In total, AeroSpace provides 4 possible layouts: +- horizontal list (in i3, it's called "horizontal split") +- vertical list (in i3, it's called "vertical split") +- horizontal accordion (analog of i3's "tabbed layout") +- vertical accordion (analog of i3's "stacked layout") + +From the previous section, you're already familiar with the List layout. + +Accordion is a layout where windows are placed on top of each other. +- Horizontal accordion puts paddings on left and right to make it clear that other windows exist in these directions +- Vertical accordion puts paddings on above and below to make it clear that other windows exist in these directions + +Horizontal accordion looks like this + + + +Vertical accordion looks like this + + + +Just like in a list layout, you can use the [focus](./commands.md#focus) command to navigate an accordion layout. + +You can navigate the windows in an `h_accordion` by using the `focus (left|right)` command, while in a `v_accordion`, you can +navigate the windows using the `focus (up|down)` command. ### Normalization -TODO DOCUMENTATION + +By default, AeroSpace does two types of normalizations to the tree: +- Containers that have only one child are "flattened". ### Floating windows TODO DOCUMENTATION @@ -27,6 +82,7 @@ Normally, floating windows are not part of the tiling tree. But it's not the cas perspective, floating windows are part of the tree. ## Default keybindings + TODO DOCUMENTATION the idea behind default keybindings ## Configuring AeroSpace @@ -35,8 +91,8 @@ AeroSpace will read config file from `~/.aerospace.toml`. Please see the followi - The default config contains all possible keys with comments: [default-config.toml](../config-examples/default-config.toml) - i3 like config: [i3-like-config-example.toml](../config-examples/i3-like-config-example.toml) -AeroSpace uses TOML format for the config. TOML is a popular format with open specification. TOML is easy to read, and it supports -comments. See [TOML site for more info](https://toml.io/en/) +AeroSpace uses TOML format for the config. TOML is easy to read, and it supports comments. See [TOML site for more +info](https://toml.io/en/) ### Binding modes TODO DOCUMENTATION @@ -57,7 +113,18 @@ TODO DOCUMENTATION Enable 'Group windows by application' ### A note on 'Displays have separate Spaces' -TODO DOCUMENTATION + +AeroSpace doesn't care about `System Settings -> Desktop & Dock -> Displays have separate Spaces` setting. It works equally good +whether this option is turned off or on. + +Overview of 'Displays have separate Spaces' + +| | 'Displays have separate Spaces' is enabled | 'Displays have separate Spaces' is disabled | +|-------------------------------------------------------------|--------------------------------------------|---------------------------------------------| +| When the first display is in fullscreen | 😊 Second monitor operates independently | 😔 Second monitor is unusable black screen | +| Is it possible to place a window on the border of monitors? | 😔 No | 😊 Yes | +| macOS status bar ... | ... is displayed on both monitors | ... is displayed only on main monitor | + ## Multiple displays TODO DOCUMENTATION diff --git a/src/command/FocusCommand.swift b/src/command/FocusCommand.swift index 229748b4..902f9346 100644 --- a/src/command/FocusCommand.swift +++ b/src/command/FocusCommand.swift @@ -6,6 +6,7 @@ struct FocusCommand: Command { guard let currentWindow = focusedWindowOrEffectivelyFocused else { return } let workspace = currentWindow.workspace // todo floating windows break mru + // todo floating non AXStandardWindow shouldn't be part of the tree let floatingWindows = makeFloatingWindowsSeenAsTiling(workspace: workspace) defer { restoreFloatingWindows(floatingWindows: floatingWindows, workspace: workspace) diff --git a/src/command/MoveThroughCommand.swift b/src/command/MoveThroughCommand.swift index bfe3c2fa..5ae3bfdf 100644 --- a/src/command/MoveThroughCommand.swift +++ b/src/command/MoveThroughCommand.swift @@ -22,7 +22,7 @@ struct MoveThroughCommand: Command { moveOut(window: currentWindow, direction: direction) } case .workspace: // floating window - break // todo + break // todo support moving floating windows } } }