From feec0c40d414d6821f56a8b9804dbfaac7bdc992 Mon Sep 17 00:00:00 2001 From: Nikita Bobko Date: Tue, 24 Oct 2023 00:47:53 +0200 Subject: [PATCH] guide WIP --- README.md | 87 ++++++++++++++++++++++++++------------------------- docs/guide.md | 56 +++++++++++++++++++++++++++++++++ 2 files changed, 101 insertions(+), 42 deletions(-) create mode 100644 docs/guide.md diff --git a/README.md b/README.md index 18d89d2b..dfefb522 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ AeroSpace is a tiling window manager for macOS. -## Status +## Project status 🚧 **Work in progress.** Not usable yet 🚧 @@ -14,7 +14,8 @@ I will publish first release once I believe it's usable, so subscribe to release - **Manual** tiling window manager - [i3](https://i3wm.org/) inspired -- AeroSpace employs its **own emulation of virtual workspaces** instead of relying on native macOS Spaces due to +- AeroSpace employs its [own emulation of virtual workspaces](./docs/guide.md#emulation-of-virtual-workspaces) instead of relying + on native macOS Spaces due to their considerable limitations - Plain text configuration (dotfiles friendly) - **[PLANNED]** CLI scriptable @@ -22,6 +23,8 @@ I will publish first release once I believe it's usable, so subscribe to release - Proper multi-monitor support (i3-like paradigm) - Status menu icon displays current workspace name +## [AeroSpace Guide](./docs/guide.md) + ## How to build the project You would need a Mac. @@ -37,43 +40,43 @@ Firstly, install [xcodegen](https://github.com/yonaskolb/XcodeGen). Then run in ./run-tests.sh ``` -## Todo - -- is dialog, is resizable, is modal? -- select parent and kill several windows at once -- select parent -> outline several windows? - - OR: outline with "SLSSetWindowOpacity" - - OR: "shake" windows -- CLI interface -- Check all todos in code -- move vs swap -- what is src/Assets.xcassets ? -- license -- unminimize apps automatically -- minimized apps handling -- macOS fullscreen apps handling -- unhide apps automatically - -## Challenges - -- Window overlapping -- "floating" window layout -- windows' min/max sizes - -## Known Special windows to check - -- XCode welcome screen -- Finder preview -- Finder tabs -- Chrome create bookmark window -- Toolbox window -- IntelliJ dialog windows (e.g. "Add to git") -- IntelliJ project structure modal window blocks main window resize -- VLC full screen window (eh, I wish every fullscreen window in macOS worked like that) -- iTerm drop down window -- Chrome cmd+f window - -## Limitations of macOS API - -- It's not possible to find to what monitor window is assigned -- It's not possible to __reliably__ know what monitor is currently active \ No newline at end of file +## Values of the project + +**Values** +- AeroSpace is targeted at advanced users and developers +- Keyboard centric +- Never break configuration files or existing workflows (Guaranteed once AeroSpace reaches 1.0 version) +- AeroSpace doesn't use GUI, unless necessarily + - AeroSpace will never provide a GUI for configuration. For advanced users, it's easier to edit a configuration file in text + editor rather than navigating through checkboxes in GUI. + - Status menu icon is ok, because visual feedback is needed +- Provide _practical_ features. Fancy appearance features are not _practical_ +- If "dark magic" (aka "private APIs", "code injections", etc) can be avoided, it must be avoided + - Right now, AeroSpace uses only a [single private API](./src/Bridged-Header.h). Everything else is [macOS public accessibility + API](https://developer.apple.com/documentation/applicationservices/axuielement_h). + - AeroSpace will never require you to disable SIP (System Integrity Protection). For example, yabai [requires you to disable + SIP](https://github.com/koekeishiya/yabai/issues/1863) to use some of its features. AeroSpace will either find another way + (e.g. [emulation of workspaces](./docs/guide.md#emulation-of-virtual-workspaces)) or will not implement this feature at all + (window transparency and window shadowing are not _practical_ features) + +**Non Values** +- Play nicely with existing macOS features. If limitations are imposed then AeroSpace won't play nicely with existing macOS + features + - E.g. AeroSpace doesn't acknowledge the existence of macOS Spaces, and it uses [emulation of its own + workspaces](./docs/guide.md#emulation-of-virtual-workspaces) + +## Tip of the day + +```bash +defaults write -g NSWindowShouldDragOnGesture YES +``` + +Now, you can move windows by holding `ctrl`+`cmd` and dragging any part of the window (not necessarily the window title) + +Source: [reddit](https://www.reddit.com/r/MacOS/comments/k6hiwk/keyboard_modifier_to_simplify_click_drag_of/) + +## Related projects + +If AeroSpace doesn't work for you, take a look at projects by other authors: +- [Amethyst](https://github.com/ianyh/Amethyst) +- [yabai](https://github.com/koekeishiya/yabai) \ No newline at end of file diff --git a/docs/guide.md b/docs/guide.md new file mode 100644 index 00000000..4d314038 --- /dev/null +++ b/docs/guide.md @@ -0,0 +1,56 @@ +# AeroSpace Guide + +**Table of contents** + +- [Tree](#tree) + - [Normalization](#normalization) + - [Floating windows](#floating-windows) +- [Default keybindings](#default-keybindings) +- [Configuring AeroSpace](#configuring-aerospace) + - [Binding modes](#bindings-modes) + - [Commands](#commands) +- [Emulation of virtual workspaces](#emulation-of-virtual-workspaces) + - [A note on mission control](#a-note-on-mission-control) + - [A note on 'Displays have separate Spaces'](#a-note-on-displays-have-separate-spaces) +- [Multiple displays](#multiple-displays) + +## Tree +TODO + +### Normalization +TODO + +### Floating windows +TODO Normally, floating windows are not part of the tiling tree except for the 'focus' command. From 'focus' command perspective, +floating windows are part of the tree. + +## Default keybindings +TODO the idea behind default keybindings + +## Configuring AeroSpace +TODO + +### Binding modes +TODO + +### Commands +TODO + +## Emulation of virtual workspaces + +The supposed workflow is to only have one macOS Space (or as many as monitors you have) and don't interact with macOS spaces in +any way + +When user quits AeroSpace or before crashing, AeroSpace puts windows back to the center of the screen + +### A note on mission control +TODO +Enable 'Group windows by application' + +### A note on 'Displays have separate Spaces' +TODO + +## Multiple displays +TODO +TODO difference with i3 +