From 1d0264c0e308be628088d4421daf476220913868 Mon Sep 17 00:00:00 2001 From: Isaac Daly Date: Sun, 6 Oct 2024 15:08:25 +1100 Subject: [PATCH] Docs revamp (#1046) - Separated out the YAML and C# docs - Filled out the YAML docs for existing functionality - Added inheritance for common YAML and C# docs - Filled out the layout engines YAML docs - Minor styling improvements --- .github/workflows/docs_commit.yml | 1 + .../customize => _common/core}/styling.md | 4 +- .../plugins/command-palette.md | 39 +- docs/_common/plugins/focus-indicator.md | 8 + docs/_common/plugins/gaps.md | 8 + docs/_common/plugins/layout-preview.md | 3 + .../{docs => _common}/plugins/slice-layout.md | 32 +- docs/{docs => _common}/plugins/tree-layout.md | 34 +- docs/_common/plugins/updater.md | 5 + .../customize => configure/core}/commands.md | 27 +- docs/configure/core/filtering.md | 58 +++ docs/configure/core/keybinds.md | 64 +++ docs/configure/core/layout-engines.md | 175 +++++++++ docs/configure/core/logging.md | 3 + docs/configure/core/monitors.md | 3 + docs/configure/core/routing.md | 72 ++++ docs/configure/core/styling.md | 3 + docs/configure/core/workspaces.md | 3 + docs/configure/plugins/bar.md | 7 + docs/configure/plugins/command-palette.md | 30 ++ docs/configure/plugins/floating-window.md | 3 + .../plugins/focus-indicator.md} | 369 +----------------- docs/configure/plugins/gaps.md | 27 ++ docs/configure/plugins/layout-preview.md | 19 + docs/configure/plugins/overview.md | 17 + docs/configure/plugins/slice-layout.md | 7 + docs/configure/plugins/tree-layout.md | 7 + docs/configure/plugins/updater.md | 21 + docs/configure/toc.yml | 24 ++ docs/configure/yaml-json-configuration.md | 53 +++ docs/{docs => }/contribute/building-whim.md | 2 +- docs/{docs => }/contribute/docs.md | 2 +- .../contribute/environment-setup.md | 0 docs/{docs => }/contribute/guide.md | 2 +- docs/{docs => }/contribute/releases.md | 0 docs/contribute/toc.yml | 6 + docs/docs/getting-started/plugins.md | 23 -- docs/docs/toc.yml | 51 --- docs/index.md | 12 +- .../getting-started => intro}/comparison.md | 4 +- .../getting-started => intro}/customize.md | 4 +- .../getting-started => intro}/inspiration.md | 8 +- docs/intro/plugins.md | 23 ++ docs/intro/toc.yml | 7 + .../troubleshooting.md | 4 +- docs/{docs => script}/architecture/context.md | 0 .../architecture/deprecated.md | 2 +- docs/{docs => script}/architecture/events.md | 0 docs/script/architecture/layout-engines.md | 12 + .../architecture/native-apis.md | 0 docs/{docs => script}/architecture/result.md | 0 docs/{docs => script}/architecture/store.md | 0 docs/script/core/commands.md | 22 ++ .../customize => script/core}/filtering.md | 0 .../customize => script/core}/keybinds.md | 2 +- .../core}/layout-engines.md | 15 +- .../customize => script/core}/logging.md | 0 .../customize => script/core}/monitors.md | 0 .../customize => script/core}/routing.md | 0 .../customize => script/core}/snippets.md | 2 + docs/{docs/customize => script/core}/store.md | 0 docs/script/core/styling.md | 3 + .../customize => script/core}/workspaces.md | 2 +- docs/{docs => script}/plugins/bar.md | 2 +- docs/script/plugins/command-palette.md | 38 ++ .../plugins/floating-window.md | 0 .../plugins/focus-indicator.md | 9 +- docs/{docs => script}/plugins/gaps.md | 9 +- .../plugins/layout-preview.md | 4 +- docs/script/plugins/overview.md | 31 ++ docs/script/plugins/slice-layout.md | 31 ++ .../plugins/tree-layout-bar.md | 4 +- .../plugins/tree-layout-command-palette.md | 0 docs/script/plugins/tree-layout.md | 33 ++ docs/{docs => script}/plugins/updater.md | 6 +- docs/{docs/customize => script}/scripting.md | 4 +- docs/script/toc.yml | 38 ++ docs/template/public/main.css | 29 ++ docs/template/public/main.js | 11 + docs/toc.yml | 14 +- 80 files changed, 973 insertions(+), 624 deletions(-) rename docs/{docs/customize => _common/core}/styling.md (95%) rename docs/{docs => _common}/plugins/command-palette.md (55%) create mode 100644 docs/_common/plugins/focus-indicator.md create mode 100644 docs/_common/plugins/gaps.md create mode 100644 docs/_common/plugins/layout-preview.md rename docs/{docs => _common}/plugins/slice-layout.md (51%) rename docs/{docs => _common}/plugins/tree-layout.md (52%) create mode 100644 docs/_common/plugins/updater.md rename docs/{docs/customize => configure/core}/commands.md (87%) create mode 100644 docs/configure/core/filtering.md create mode 100644 docs/configure/core/keybinds.md create mode 100644 docs/configure/core/layout-engines.md create mode 100644 docs/configure/core/logging.md create mode 100644 docs/configure/core/monitors.md create mode 100644 docs/configure/core/routing.md create mode 100644 docs/configure/core/styling.md create mode 100644 docs/configure/core/workspaces.md create mode 100644 docs/configure/plugins/bar.md create mode 100644 docs/configure/plugins/command-palette.md create mode 100644 docs/configure/plugins/floating-window.md rename docs/{docs/customize/yaml.md => configure/plugins/focus-indicator.md} (64%) create mode 100644 docs/configure/plugins/gaps.md create mode 100644 docs/configure/plugins/layout-preview.md create mode 100644 docs/configure/plugins/overview.md create mode 100644 docs/configure/plugins/slice-layout.md create mode 100644 docs/configure/plugins/tree-layout.md create mode 100644 docs/configure/plugins/updater.md create mode 100644 docs/configure/toc.yml create mode 100644 docs/configure/yaml-json-configuration.md rename docs/{docs => }/contribute/building-whim.md (99%) rename docs/{docs => }/contribute/docs.md (99%) rename docs/{docs => }/contribute/environment-setup.md (100%) rename docs/{docs => }/contribute/guide.md (98%) rename docs/{docs => }/contribute/releases.md (100%) create mode 100644 docs/contribute/toc.yml delete mode 100644 docs/docs/getting-started/plugins.md delete mode 100644 docs/docs/toc.yml rename docs/{docs/getting-started => intro}/comparison.md (95%) rename docs/{docs/getting-started => intro}/customize.md (82%) rename docs/{docs/getting-started => intro}/inspiration.md (82%) create mode 100644 docs/intro/plugins.md create mode 100644 docs/intro/toc.yml rename docs/{docs/getting-started => intro}/troubleshooting.md (83%) rename docs/{docs => script}/architecture/context.md (100%) rename docs/{docs => script}/architecture/deprecated.md (94%) rename docs/{docs => script}/architecture/events.md (100%) create mode 100644 docs/script/architecture/layout-engines.md rename docs/{docs => script}/architecture/native-apis.md (100%) rename docs/{docs => script}/architecture/result.md (100%) rename docs/{docs => script}/architecture/store.md (100%) create mode 100644 docs/script/core/commands.md rename docs/{docs/customize => script/core}/filtering.md (100%) rename docs/{docs/customize => script/core}/keybinds.md (90%) rename docs/{docs/customize => script/core}/layout-engines.md (86%) rename docs/{docs/customize => script/core}/logging.md (100%) rename docs/{docs/customize => script/core}/monitors.md (100%) rename docs/{docs/customize => script/core}/routing.md (100%) rename docs/{docs/customize => script/core}/snippets.md (96%) rename docs/{docs/customize => script/core}/store.md (100%) create mode 100644 docs/script/core/styling.md rename docs/{docs/customize => script/core}/workspaces.md (96%) rename docs/{docs => script}/plugins/bar.md (96%) create mode 100644 docs/script/plugins/command-palette.md rename docs/{docs => script}/plugins/floating-window.md (100%) rename docs/{docs => script}/plugins/focus-indicator.md (59%) rename docs/{docs => script}/plugins/gaps.md (50%) rename docs/{docs => script}/plugins/layout-preview.md (93%) create mode 100644 docs/script/plugins/overview.md create mode 100644 docs/script/plugins/slice-layout.md rename docs/{docs => script}/plugins/tree-layout-bar.md (92%) rename docs/{docs => script}/plugins/tree-layout-command-palette.md (100%) create mode 100644 docs/script/plugins/tree-layout.md rename docs/{docs => script}/plugins/updater.md (83%) rename docs/{docs/customize => script}/scripting.md (94%) create mode 100644 docs/script/toc.yml diff --git a/.github/workflows/docs_commit.yml b/.github/workflows/docs_commit.yml index b7bb0ef43..af2983e63 100644 --- a/.github/workflows/docs_commit.yml +++ b/.github/workflows/docs_commit.yml @@ -6,6 +6,7 @@ on: - .github/workflows/docs_commit.yml - docs/** - toc.yml + - src/** env: # We install the packages to the D:\ drive to avoid the slow IO on the C:\ drive. diff --git a/docs/docs/customize/styling.md b/docs/_common/core/styling.md similarity index 95% rename from docs/docs/customize/styling.md rename to docs/_common/core/styling.md index 13924a06a..5f8b52492 100644 --- a/docs/docs/customize/styling.md +++ b/docs/_common/core/styling.md @@ -1,6 +1,4 @@ -# Styling - -Whim uses XAML resources to style the appearance of certain user interfaces such as the [Bar Plugin](../plugins/bar.md). By default, Whim loads its resources from [Defaults.xaml](https://github.com/dalyIsaac/Whim/blob/main/src/Whim/Resources/Defaults.xaml). +Whim uses XAML resources to style the appearance of certain user interfaces such as the [Bar Plugin](../../configure/plugins/bar.md). By default, Whim loads its resources from [Defaults.xaml](https://github.com/dalyIsaac/Whim/blob/main/src/Whim/Resources/Defaults.xaml). ## Loading custom dictionaries diff --git a/docs/docs/plugins/command-palette.md b/docs/_common/plugins/command-palette.md similarity index 55% rename from docs/docs/plugins/command-palette.md rename to docs/_common/plugins/command-palette.md index 905fd6bec..2dca6cf8d 100644 --- a/docs/docs/plugins/command-palette.md +++ b/docs/_common/plugins/command-palette.md @@ -1,41 +1,4 @@ -# Command Palette Plugin - -The provides a fuzzy command palette, loaded with all the s registered with the . - -The command palette uses a port of Visual Studio Code's fuzzy search algorithm. - -![Command palette demo](../../images/command-palette-demo.gif) - -## Configuration - -The can be used to configure the command palette. The can be used to configure the default commands and matcher to use. - -Custom instances of the command palette can be activated by calling . - -## Example Config - -```csharp -#r "WHIM_PATH\whim.dll" -#r "WHIM_PATH\plugins\Whim.CommandPalette\Whim.CommandPalette.dll" - -using Whim; -using Whim.CommandPalette; - -void DoConfig(IContext context) -{ - // ... - - CommandPaletteConfig commandPaletteConfig = new(context); - CommandPalettePlugin commandPalettePlugin = new(context, commandPaletteConfig); - context.PluginManager.AddPlugin(commandPalettePlugin); - - // ... -} - -return DoConfig; -``` - -## Commands +## Commands | Identifier | Title | Keybind | | --------------------------------------------------------- | ---------------------------------- | ------------------------------------------------ | diff --git a/docs/_common/plugins/focus-indicator.md b/docs/_common/plugins/focus-indicator.md new file mode 100644 index 000000000..41851ae13 --- /dev/null +++ b/docs/_common/plugins/focus-indicator.md @@ -0,0 +1,8 @@ +## Commands + +| Identifier | Title | Keybind | +| ------------------------------------- | --------------------------------------------- | ------------------ | +| `whim.focus_indicator.show` | Show focus indicator | No default keybind | +| `whim.focus_indicator.toggle` | Toggle focus indicator | No default keybind | +| `whim.focus_indicator.toggle_fade` | Toggle whether the focus indicator fades | No default keybind | +| `whim.focus_indicator.toggle_enabled` | Toggle whether the focus indicator is enabled | No default keybind | diff --git a/docs/_common/plugins/gaps.md b/docs/_common/plugins/gaps.md new file mode 100644 index 000000000..cf8154793 --- /dev/null +++ b/docs/_common/plugins/gaps.md @@ -0,0 +1,8 @@ +## Commands + +| Identifier | Title | Keybind | +| -------------------------- | ------------------ | ------------------------------------------------------------------ | +| `whim.gaps.outer.increase` | Increase outer gap | Win + Ctrl + Shift + L | +| `whim.gaps.outer.decrease` | Decrease outer gap | Win + Ctrl + Shift + H | +| `whim.gaps.inner.increase` | Increase inner gap | Win + Ctrl + Shift + K | +| `whim.gaps.inner.decrease` | Decrease inner gap | Win + Ctrl + Shift + J | diff --git a/docs/_common/plugins/layout-preview.md b/docs/_common/plugins/layout-preview.md new file mode 100644 index 000000000..67ae56cca --- /dev/null +++ b/docs/_common/plugins/layout-preview.md @@ -0,0 +1,3 @@ +## Commands + +The `LayoutPreviewPlugin` has no commands. diff --git a/docs/docs/plugins/slice-layout.md b/docs/_common/plugins/slice-layout.md similarity index 51% rename from docs/docs/plugins/slice-layout.md rename to docs/_common/plugins/slice-layout.md index b3c738d29..85163ea46 100644 --- a/docs/docs/plugins/slice-layout.md +++ b/docs/_common/plugins/slice-layout.md @@ -1,34 +1,4 @@ -# Slice Layout Plugin - - provides commands and functionality for the . - - does not load the - that is done when creating a workspace via the . - -For more about the `SliceLayoutEngine`, see the [Layout Engines](../customize//layout-engines.md#slicelayoutengine) page. - -## Example Config - -```csharp -#r "WHIM_PATH\whim.dll" -#r "WHIM_PATH\plugins\Whim.SliceLayout\Whim.SliceLayout.dll" - -using Whim; -using Whim.SliceLayout; - -void DoConfig(IContext context) -{ - // ... - - SliceLayoutPlugin sliceLayoutPlugin = new(context); - context.PluginManager.AddPlugin(sliceLayoutPlugin); - - // ... -} - -return DoConfig; -``` - -## Commands + | Identifier | Title | Keybind | | --------------------------------------------- | ---------------------------------- | ------------------ | diff --git a/docs/docs/plugins/tree-layout.md b/docs/_common/plugins/tree-layout.md similarity index 52% rename from docs/docs/plugins/tree-layout.md rename to docs/_common/plugins/tree-layout.md index aae767007..a9deaeb24 100644 --- a/docs/docs/plugins/tree-layout.md +++ b/docs/_common/plugins/tree-layout.md @@ -1,36 +1,4 @@ -# Tree Layout Plugin - - provides commands and functionality for the . - - does not load the - that is done when creating a workspace via the . - -For more about the `TreeLayoutEngine`, see the [Layout Engines](../customize/layout-engines.md#treelayoutengine) page. - -The [Tree Layout Bar plugin](./tree-layout-bar.md) provides a widget for the bar to set the direction to add the next window. - -## Example Config - -```csharp -#r "WHIM_PATH\whim.dll" -#r "WHIM_PATH\plugins\Whim.TreeLayout\Whim.TreeLayout.dll" - -using Whim; -using Whim.TreeLayout; - -void DoConfig(IContext context) -{ - // ... - - TreeLayoutPlugin treeLayoutPlugin = new(context); - context.PluginManager.AddPlugin(treeLayoutPlugin); - - // ... -} - -return DoConfig; -``` - -## Commands + | Identifier | Title | Keybind | | ------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------- | diff --git a/docs/_common/plugins/updater.md b/docs/_common/plugins/updater.md new file mode 100644 index 000000000..d1e2c4d83 --- /dev/null +++ b/docs/_common/plugins/updater.md @@ -0,0 +1,5 @@ +## Commands + +| Identifier | Title | Keybind | +| -------------------- | ----------------- | ------------------ | +| `whim.updater.check` | Check for updates | No default keybind | diff --git a/docs/docs/customize/commands.md b/docs/configure/core/commands.md similarity index 87% rename from docs/docs/customize/commands.md rename to docs/configure/core/commands.md index c565b3012..e36cad903 100644 --- a/docs/docs/customize/commands.md +++ b/docs/configure/core/commands.md @@ -6,7 +6,7 @@ Whim differentiates three types of commands. 1. [Core commands](#core-commands) expose common functions as ready-to-use commands, many of which come with a default keybinding. 2. [Plugin commands](#plugin-commands) are ready-to-use commands exposed by plugins. -3. [Custom commands](#custom-commands) are user-defined commands, which can compose arbitrary functions. +3. [Custom commands](../../script/core/commands.md) are user-defined commands, which can compose arbitrary functions. ## Core commands @@ -48,27 +48,4 @@ Core commands have identifiers under the `whim.core` namespace. ## Plugin commands -Plugin commands are namespaced by the string defined in the property for plugins - for example, `whim.gaps` for [`GapsPlugin`](../plugins/gaps.md). For a list of available plugin commands, see the "Plugins" section. - -## Custom commands - -Custom commands can be created using the . They are automatically added to the `whim.custom` namespace. For example, the following command closes the current tracked window: - -```csharp -// Create the command. -context.CommandManager.Add( - // Automatically namespaced to `whim.custom`. - identifier: "close_window", - title: "Close focused window", - callback: () => - { - if (context.Store.Pick(Pickers.PickLastFocusedWindow).TryGet(out IWindow window)) - { - window.Close(); - } - } -); - -// Create an associated keybind. -context.KeybindManager.SetKeybind("whim.custom.close_window", new Keybind(IKeybind.WinAlt, VIRTUAL_KEY.VK_D)); -``` +Plugin commands are namespaced by the string defined in the property for plugins - for example, `whim.gaps` for [`GapsPlugin`](../plugins/gaps.md). Commands are listed on the respective plugin documentation pages. diff --git a/docs/configure/core/filtering.md b/docs/configure/core/filtering.md new file mode 100644 index 000000000..faa67d773 --- /dev/null +++ b/docs/configure/core/filtering.md @@ -0,0 +1,58 @@ +# Filters + +By default, Whim ignores a built-in list of windows that are known to cause problems with dynamic tiling window manager. Behind the scenes, Whim automatically updates the built-in list of ignored windows based on a subset of the rules from the community-driven [collection of application rules](https://github.com/LGUG2Z/komorebi-application-specific-configuration) managed by komorebi. + +## Custom Filtering Behavior + +The filters configuration tells Whim to ignore windows that match the specified criteria. + +You can filter windows by: + +- `window_class` +- `process_file_name` +- `title` +- `title_regex` + +## Window Class Filter + +For example, to filter out Chromium windows with the class `Chrome_WidgetWin_1`, add the following to your configuration: + +```yaml +filters: + entries: + - type: window_class + value: Chrome_WidgetWin_1 +``` + +## Process File Name Filter + +For example, to filter out windows with the process file name `explorer.exe`, add the following to your configuration: + +```yaml +filters: + entries: + - type: process_file_name + value: explorer.exe +``` + +## Title Filter + +For example, to filter out windows with the title `Untitled - Notepad`, add the following to your configuration: + +```yaml +filters: + entries: + - type: title + value: Untitled - Notepad +``` + +## Title Match Filter + +For example, to filter out windows with the title that matches the regex `^Untitled - Notepad$`, add the following to your configuration: + +```yaml +filters: + entries: + - type: title_regex + value: ^Untitled - Notepad$ +``` diff --git a/docs/configure/core/keybinds.md b/docs/configure/core/keybinds.md new file mode 100644 index 000000000..f07570ae6 --- /dev/null +++ b/docs/configure/core/keybinds.md @@ -0,0 +1,64 @@ +# Keybinds + +The keybinds configuration has a list of bindings that you can use to bind commands to key combinations. + +## Bindings + +A key modifier is a key that is pressed in combination with another key to perform a specific action. The `bindings` property is a list of keybinds that map a command to a key combination. + +Key modifiers can be any of the following: + +- `Ctrl` +- `Control` +- `LCtrl` +- `LControl` +- `RCtrl` +- `RControl` +- `Shift` +- `LShift` +- `RShift` +- `Alt` +- `LAlt` +- `RAlt` +- `Win` +- `LWin` +- `RWin` + +The associated key for each modifier can be any of the s. + +## Commands + +A command is a string that represents a command that can be executed by Whim. The command can be a built-in command, a plugin command, or a custom command. For more, see the [Commands](commands.md) page. + +## Unify Key Modifiers + +To treat key modifiers like `LWin` and `RWin` the same, set `unify_key_modifiers` to `true`. + +## Keybinds Example + +```yaml +keybinds: + entries: + - command: whim.core.focus_next_monitor + keybind: LCtrl+LShift+LAlt+K + + - command: whim.core.focus_previous_monitor + keybind: LCtrl+LShift+LAlt+J + + - command: whim.custom.next_layout_engine + keybind: LCtrl+LShift+LAlt+L + + - command: whim.core.cycle_layout_engine.next + keybind: LCtrl+LShift+LAlt+L + + - command: whim.core.cycle_layout_engine.previous + keybind: LCtrl+LShift+LAlt+Win+L + + - command: whim.command_palette.find_focus_window + keybind: Win+LCtrl+F + + - command: whim.core.exit_whim + keybind: Win+LCtrl+Q + + unify_key_modifiers: true +``` diff --git a/docs/configure/core/layout-engines.md b/docs/configure/core/layout-engines.md new file mode 100644 index 000000000..927577ac3 --- /dev/null +++ b/docs/configure/core/layout-engines.md @@ -0,0 +1,175 @@ +# Layout Engines + +A "layout engine" or in Whim is responsible for arranging windows in a workspace. Each workspace has a single active layout engine, and can cycle through different layout engines. + +## Available layout engines + +| Engine | TL;DR | +| ----------------------------------------- | ------------------------------------------------------------------------ | +| [`FocusLayoutEngine`](#focuslayoutengine) | One window at a time | +| [`SliceLayoutEngine`](#slicelayoutengine) | `Awesome`/`dwm`-style dynamic tiling (primary/stack, multi-column, etc.) | +| [`TreeLayoutEngine`](#treelayoutengine) | `i3`-style dynamic tiling (arbitrary grids) | + +## Example Usage + +```yaml +layout_engines: + entries: + - type: TreeLayoutEngine + initial_direction: right + + - type: SliceLayoutEngine + variant: + type: row + + - type: SliceLayoutEngine + variant: + type: column + + - type: SliceLayoutEngine + variant: + type: primary_stack + + - type: SliceLayoutEngine + variant: + type: secondary_primary_stack + + - type: SliceLayoutEngine + variant: + type: multi_column_stack + columns: [2, 1, 0] + + - type: SliceLayoutEngine + variant: + type: secondary_primary_stack + primary_capacity: 1 + secondary_capacity: 2 + + - type: FocusLayoutEngine + maximize: false +``` + +## `FocusLayoutEngine` + +The `FocusLayoutEngine` is a layout engine that displays one window at a time. + +```yaml +layout_engines: + entries: + - type: FocusLayoutEngine + maximize: false +``` + +To show the window in the specified direction, call the `whim.core.focus_window_in_direction.(left|right|up|down)` command - see the [Commands](commands.md) page for more information. + +To reorder windows, calling `whim.core.swap_window_in_direction.(left|right|up|down)` will swap the current window with the window in the specified direction. **This will not change the focused window.** + +Windows which are not focused are minimized to the taskbar. + +![FocusLayoutEngine demo](../../images/focus-layout-demo.gif) + +## `SliceLayoutEngine` + +`SliceLayoutEngine` is an `Awesome`/`dwm`-style layout engine, which arranges following a deterministic algorithm filling a grid configured in the config file. + +The YAML/JSON configuration supports built-in layouts, such as primary/stack, multi-column, and secondary primary stack. Arbitrary layouts can be created by nesting areas in the C# configuration - see [Defining different `SliceLayouts`](../../script/core/layout-engines.md#defining-different-slicelayouts) + +Commands for the `SliceLayoutEngine` can be found on the [Slice Layout](../plugins/slice-layout.md#commands) plugin page. + +### Layout Variants + +### Column Layout + +- **Description**: Creates a column layout, where windows are stacked vertically. +- **Example**: + + ```yaml + layout_engines: + entries: + - type: SliceLayoutEngine + variant: column + ``` + +#### Row Layout + +- **Description**: Creates a row layout, where windows are stacked horizontally. +- **Example**: + + ```yaml + layout_engines: + entries: + - type: SliceLayoutEngine + variant: row + ``` + +#### Primary Stack Layout + +- **Description**: Creates a primary stack layout, where the first window takes up half the screen, and the remaining windows are stacked vertically on the other half. +- **Example**: + + ```yaml + layout_engines: + entries: + - type: SliceLayoutEngine + variant: primary_stack + ``` + +#### Multi-Column Stack Layout + +- **Description**: Creates a multi-column layout with the given number of windows in each column. `[2, 1, 0]` will create a layout with 3 columns, where the first column has 2 windows, the second column has 1 window, and the third column has infinite windows. +- **Properties**: + - `columns`: An array of integers specifying the number of windows in each column. +- **Example**: + + ```yaml + layout_engines: + entries: + - type: SliceLayoutEngine + variant: multi_column_stack + columns: [2, 1, 0] + ``` + +#### Secondary Primary Stack Layout + +- **Description**: Creates a three-column layout, where the primary column is in the middle, the secondary column is on the left, and the overflow column is on the right. The middle column takes up 50% of the screen, and the left and right columns take up 25%. +- **Properties**: + - `primary_capacity`: The number of rows in the primary column. This must be a non-negative integer. Default is 1. + - `secondary_capacity`: The number of rows in the secondary column. This must be a non-negative integer. Default is 2. +- **Example**: + + ```yaml + layout_engines: + entries: + - type: SliceLayoutEngine + variant: secondary_primary_stack + primary_capacity: 1 + secondary_capacity: 2 + ``` + +![SliceLayoutEngine demo](../../images/slice-layout-demo.gif) + +## `TreeLayoutEngine` + + is a layout that allows users to create arbitrary grid layouts, similar to `i3`. Unlike [`SliceLayoutEngine`](#slicelayoutengine), windows can can be added in any location at runtime. + +The `TreeLayoutEngine` supports an `initial_direction` property, which specifies the direction of the first split. The available directions are `left`, `right`, `up`, and `down`. + +```yaml +layout_engines: + entries: + - type: TreeLayoutEngine + initial_direction: right +``` + +![TreeLayoutEngine demo](../../images/tree-layout-demo.gif) + +Commands for the `TreeLayoutEngine` can be found on the [Tree Layout](../plugins/tree-layout.md#commands) plugin page. + +## `FloatingLayoutEngine` + +> [!WARNING] +> This is not yet supported by the YAML/JSON configuration. + + is a layout that has all windows being free-floating. To have specific windows float within a different layout, see the [Floating Window Plugin](../plugins/floating-window.md). + +![FloatingLayoutEngine demo](../../images/floating-layout-demo.gif) diff --git a/docs/configure/core/logging.md b/docs/configure/core/logging.md new file mode 100644 index 000000000..399020bc3 --- /dev/null +++ b/docs/configure/core/logging.md @@ -0,0 +1,3 @@ +# Logging + +👷🏗️🚧 diff --git a/docs/configure/core/monitors.md b/docs/configure/core/monitors.md new file mode 100644 index 000000000..dcd53bd8e --- /dev/null +++ b/docs/configure/core/monitors.md @@ -0,0 +1,3 @@ +# Monitors + +👷🏗️🚧 diff --git a/docs/configure/core/routing.md b/docs/configure/core/routing.md new file mode 100644 index 000000000..7e3f56a2b --- /dev/null +++ b/docs/configure/core/routing.md @@ -0,0 +1,72 @@ +# Routers + +The routers configuration tells Whim to route windows that match the specified criteria to the first workspace with name `workspace_name`. + +## Default Routing Behavior + +To customize the default window routing behavior, you can use the `routing_behavior` property. The default routing behavior is `route_to_launched_workspace`. + +The available routing behaviors are: + +- `route_to_launched_workspace` +- `route_to_active_workspace` +- `route_to_last_tracked_active_workspace` + +## Custom Routing Behavior + +You can also define custom routing behavior by specifying a list of routing entries. Each routing entry has a `type`, `value`, and `workspace_name`. + +The available router types are: + +- `window_class` +- `process_file_name` +- `title` +- `title_regex` + +## Window Class Router + +For example, to route Chromium windows with the class `Chrome_WidgetWin_1` to the workspace `web`, add the following to your configuration: + +```yaml +routers: + entries: + - type: window_class + value: Chrome_WidgetWin_1 + workspace_name: web +``` + +## Process File Name Router + +For example, to route windows with the process file name `explorer.exe` to the workspace `file_explorer`, add the following to your configuration: + +```yaml +routers: + entries: + - type: process_file_name + value: explorer.exe + workspace_name: file_explorer +``` + +## Title Router + +For example, to route windows with the title `Untitled - Notepad` to the workspace `notepad`, add the following to your configuration: + +```yaml +routers: + entries: + - type: title + value: Untitled - Notepad + workspace_name: notepad +``` + +## Title Match Router + +For example, to route windows with the title that matches the regex `^Untitled - Notepad$` to the workspace `notepad`, add the following to your configuration: + +```yaml +routers: + entries: + - type: title_regex + value: ^Untitled - Notepad$ + workspace_name: notepad +``` diff --git a/docs/configure/core/styling.md b/docs/configure/core/styling.md new file mode 100644 index 000000000..143f60da4 --- /dev/null +++ b/docs/configure/core/styling.md @@ -0,0 +1,3 @@ +# Styling + +[!INCLUDE [Styling](../../_common/core/styling.md)] diff --git a/docs/configure/core/workspaces.md b/docs/configure/core/workspaces.md new file mode 100644 index 000000000..5ee4532e9 --- /dev/null +++ b/docs/configure/core/workspaces.md @@ -0,0 +1,3 @@ +# Workspaces + +👷🏗️🚧 diff --git a/docs/configure/plugins/bar.md b/docs/configure/plugins/bar.md new file mode 100644 index 000000000..52c0cf826 --- /dev/null +++ b/docs/configure/plugins/bar.md @@ -0,0 +1,7 @@ +# Bar Plugin + +👷🏗️🚧 + +## Tree Layout + +👷🏗️🚧 diff --git a/docs/configure/plugins/command-palette.md b/docs/configure/plugins/command-palette.md new file mode 100644 index 000000000..a9a21cc57 --- /dev/null +++ b/docs/configure/plugins/command-palette.md @@ -0,0 +1,30 @@ +# Command Palette Plugin + +The `CommandPalettePlugin` adds the command palette to Whim. + +![Command palette demo](../../images/command-palette-demo.gif) + +```yaml +plugins: + command_palette: + is_enabled: true + + max_height_percent: 40 + max_width_pixels: 800 + y_position_percent: 20 +``` + +## Configuration + +| Property | Description | +| -------------------- | -------------------------------------------------------------------------------- | +| `is_enabled` | Whether the plugin is enabled. Defaults to `true`. | +| `max_height_percent` | The maximum height of the command palette as a percentage of the monitor height. | +| `max_width_pixels` | The maximum width of the command palette in pixels. | +| `y_position_percent` | The y position of the command palette as a percentage of the monitor height. | + +[!INCLUDE [Commands](../../_common/plugins/command-palette.md)] + +## Tree Layout + +👷🏗️🚧 diff --git a/docs/configure/plugins/floating-window.md b/docs/configure/plugins/floating-window.md new file mode 100644 index 000000000..cfbf5c54d --- /dev/null +++ b/docs/configure/plugins/floating-window.md @@ -0,0 +1,3 @@ +# Floating Window + +👷🏗️🚧 diff --git a/docs/docs/customize/yaml.md b/docs/configure/plugins/focus-indicator.md similarity index 64% rename from docs/docs/customize/yaml.md rename to docs/configure/plugins/focus-indicator.md index 90d640288..500fffe72 100644 --- a/docs/docs/customize/yaml.md +++ b/docs/configure/plugins/focus-indicator.md @@ -1,335 +1,4 @@ -# YAML Configuration (WIP) - -Whim is in the process of adding YAML configuration support - this is being tracked in [#1009](https://github.com/dalyIsaac/Whim/issues/1009). This has been implemented in the `Whim.Yaml` plugin, and may have breaking changes in the future. - -## Setup - -Whim looks for a `whim.config.yaml` or `whim.config.json` file in the root of your `.whim` directory. If it finds one, it will use that file to configure Whim. - -Add to your `whim.config.csx`: - -```csharp -// ...previous references - -// NOTE: Replace WHIM_PATH with the path to your Whim installation -#r "WHIM_PATH\plugins\Whim.Yaml\Whim.Yaml.dll" - -using System; -// ...usings... -using Whim.Yaml; - -// ... - -void DoConfig(IContext context) -{ - // Make sure to place this at the top of your config - YamlLoader.Load(context); -} -``` - -## Schema - -The schema for the YAML and JSON configuration is available [here](https://raw.githubusercontent.com/dalyIsaac/Whim/main/src/Whim.Yaml/schema.json). - -To use the schema in your YAML file, add the following line at the top of your file: - -```yaml -# yaml-language-server: $schema=https://raw.githubusercontent.com/dalyIsaac/Whim/main/src/Whim.Yaml/schema.json -``` - -To use the schema in your JSON file, add the following line at the top of your file: - -```json -{ - "$schema": "https://raw.githubusercontent.com/dalyIsaac/Whim/main/src/Whim.Yaml/schema.json", - ... -} -``` - -## Layout Engines - -The layout engines configuration has a list of layout engines that you can use to customize the layout of your windows. These apply to all workspaces, unless overridden by workspace-specific configuration. - -### Layout Engines Example - -```yaml -layout_engines: - entries: - - type: TreeLayoutEngine - initial_direction: right - - - type: SliceLayoutEngine - variant: - type: row - - - type: SliceLayoutEngine - variant: - type: column - - - type: SliceLayoutEngine - variant: - type: primary_stack - - - type: SliceLayoutEngine - variant: - type: secondary_primary_stack - - - type: SliceLayoutEngine - variant: - type: multi_column_stack - columns: [2, 1, 0] - - - type: SliceLayoutEngine - variant: - type: secondary_primary_stack - primary_capacity: 1 - secondary_capacity: 2 - - - type: FocusLayoutEngine - maximize: false -``` - -TODO: Add layout engine descriptions - -## Keybinds - -The keybinds configuration has a list of bindings that you can use to bind commands to key combinations. - -### Bindings - -A key modifier is a key that is pressed in combination with another key to perform a specific action. The `bindings` property is a list of keybinds that map a command to a key combination. - -Key modifiers can be any of the following: - -- `Ctrl` -- `Control` -- `LCtrl` -- `LControl` -- `RCtrl` -- `RControl` -- `Shift` -- `LShift` -- `RShift` -- `Alt` -- `LAlt` -- `RAlt` -- `Win` -- `LWin` -- `RWin` - -The associated key for each modifier can be any of the s. - -### Unify Key Modifiers - -To treat key modifiers like `LWin` and `RWin` the same, set `unify_key_modifiers` to `true`. - -### Keybinds Example - -```yaml -keybinds: - entries: - - command: whim.core.focus_next_monitor - keybind: LCtrl+LShift+LAlt+K - - - command: whim.core.focus_previous_monitor - keybind: LCtrl+LShift+LAlt+J - - - command: whim.custom.next_layout_engine - keybind: LCtrl+LShift+LAlt+L - - - command: whim.core.cycle_layout_engine.next - keybind: LCtrl+LShift+LAlt+L - - - command: whim.core.cycle_layout_engine.previous - keybind: LCtrl+LShift+LAlt+Win+L - - - command: whim.command_palette.find_focus_window - keybind: Win+LCtrl+F - - - command: whim.core.exit_whim - keybind: Win+LCtrl+Q - - unify_key_modifiers: true -``` - -## Filters - -By default, Whim ignores a built-in list of windows that are known to cause problems with dynamic tiling window manager. Behind the scenes, Whim automatically updates the built-in list of ignored windows based on a subset of the rules from the community-driven [collection of application rules](https://github.com/LGUG2Z/komorebi-application-specific-configuration) managed by komorebi. - -### Custom Filtering Behavior - -The filters configuration tells Whim to ignore windows that match the specified criteria. - -You can filter windows by: - -- `window_class` -- `process_file_name` -- `title` -- `title_regex` - -### Window Class Filter - -For example, to filter out Chromium windows with the class `Chrome_WidgetWin_1`, add the following to your configuration: - -```yaml -filters: - entries: - - type: window_class - value: Chrome_WidgetWin_1 -``` - -### Process File Name Filter - -For example, to filter out windows with the process file name `explorer.exe`, add the following to your configuration: - -```yaml -filters: - entries: - - type: process_file_name - value: explorer.exe -``` - -### Title Filter - -For example, to filter out windows with the title `Untitled - Notepad`, add the following to your configuration: - -```yaml -filters: - entries: - - type: title - value: Untitled - Notepad -``` - -### Title Match Filter - -For example, to filter out windows with the title that matches the regex `^Untitled - Notepad$`, add the following to your configuration: - -```yaml -filters: - entries: - - type: title_regex - value: ^Untitled - Notepad$ -``` - -## Routers - -The routers configuration tells Whim to route windows that match the specified criteria to the first workspace with name `workspace_name`. - -### Default Routing Behavior - -To customize the default window routing behavior, you can use the `routing_behavior` property. The default routing behavior is `route_to_launched_workspace`. - -The available routing behaviors are: - -- `route_to_launched_workspace` -- `route_to_active_workspace` -- `route_to_last_tracked_active_workspace` - -### Custom Routing Behavior - -You can also define custom routing behavior by specifying a list of routing entries. Each routing entry has a `type`, `value`, and `workspace_name`. - -The available router types are: - -- `window_class` -- `process_file_name` -- `title` -- `title_regex` - -#### Window Class Router - -For example, to route Chromium windows with the class `Chrome_WidgetWin_1` to the workspace `web`, add the following to your configuration: - -```yaml -routers: - entries: - - type: window_class - value: Chrome_WidgetWin_1 - workspace_name: web -``` - -#### Process File Name Router - -For example, to route windows with the process file name `explorer.exe` to the workspace `file_explorer`, add the following to your configuration: - -```yaml -routers: - entries: - - type: process_file_name - value: explorer.exe - workspace_name: file_explorer -``` - -#### Title Router - -For example, to route windows with the title `Untitled - Notepad` to the workspace `notepad`, add the following to your configuration: - -```yaml -routers: - entries: - - type: title - value: Untitled - Notepad - workspace_name: notepad -``` - -#### Title Match Router - -For example, to route windows with the title that matches the regex `^Untitled - Notepad$` to the workspace `notepad`, add the following to your configuration: - -```yaml -routers: - entries: - - type: title_regex - value: ^Untitled - Notepad$ - workspace_name: notepad -``` - -## Plugins - -The plugins configuration tells Whim to load the specified plugins. Each plugin has is a key under the `plugins` top-Level key. - -### Gaps Plugin - -The `GapsPlugin` adds the config and commands to add gaps between each of the windows in the layout. - -![Gaps plugin demo](../../images/gaps-demo.png) - -```yaml -plugins: - gaps: - is_enabled: true - outer_gap: 10 - inner_gap: 10 - default_outer_delta: 2 - default_inner_delta: 2 -``` - -Commands for the `GapsPlugin` can be found at the [Gaps Plugin](../plugins/gaps.md#commands) page. - -### Command Palette Plugin - -The `CommandPalettePlugin` adds the command palette to Whim. - -![Command palette demo](../../images/command-palette-demo.gif) - -```yaml -plugins: - command_palette: - is_enabled: true - - # max_height_pixels is the maximum height of the command palette as a percentage of the monitor height - max_height_percent: 40 - - # max_width_pixels is the maximum width of the command palette in pixels - max_width_pixels: 800 - - # max_width_percent is the y position of the command palette as a percentage of the monitor height - y_position_percent: 20 -``` - -Commands for the `CommandPalettePlugin` can be found at the [Command Palette Plugin](../plugins/command-palette.md#commands) page. - -### Focus Indicator Plugin +# Focus Indicator Plugin The `FocusIndicatorPlugin` adds a focus indicator to the focused window. @@ -345,6 +14,18 @@ plugins: color: green ``` +## Configuration + +| Property | Description | +| ----------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| `is_enabled` | Whether the plugin is enabled. Defaults to `true`. | +| `color` | The color of the focus indicator. Default is `red`. | +| `border_size` | The size of the border of the focus indicator, in pixels. Default is `4`. | +| `is_fade_enabled` | When `true`, the focus indicator will be visible for `fade_timeout` seconds after the window is focused. Default is `false`. | +| `fade_timeout` | The time in seconds before the focus indicator fades out. Default is `10`. | + +## Colors + The color can be any valid RGB or RGBA hex color. The following named colors are also supported: | Color Name | RGBA Value | Preview | @@ -491,26 +172,4 @@ The color can be any valid RGB or RGBA hex color. The following named colors are | `yellow` | `#FFFFFF00` | | | `yellow_green` | `#FF9ACD32` | | -### Layout Preview Plugin - -The `LayoutPreviewPlugin` adds a layout preview to Whim. - -![Layout preview demo](../../images/layout-preview-demo.gif) - -```yaml -plugins: - layout_preview: - is_enabled: true -``` - -### Updater Plugin - -The `UpdaterPlugin` adds the ability to notify the user when a new version of Whim is available. - -```yaml -plugins: - updater: - is_enabled: true - release_channel: alpha - update_frequency: weekly -``` +[!INCLUDE [Commands](../../_common/plugins/focus-indicator.md)] diff --git a/docs/configure/plugins/gaps.md b/docs/configure/plugins/gaps.md new file mode 100644 index 000000000..00c999b45 --- /dev/null +++ b/docs/configure/plugins/gaps.md @@ -0,0 +1,27 @@ +# Gaps Plugin + +The `GapsPlugin` adds the config and commands to add gaps between each of the windows in the layout. + +![Gaps plugin demo](../../images/gaps-demo.png) + +```yaml +plugins: + gaps: + is_enabled: true + outer_gap: 10 + inner_gap: 10 + default_outer_delta: 2 + default_inner_delta: 2 +``` + +## Configuration + +| Property | Description | +| --------------------- | -------------------------------------------------------------------------------------- | +| `is_enabled` | Whether the plugin is enabled | +| `outer_gap` | The gap between the parent layout engine and the area where windows are placed | +| `inner_gap` | The gap between windows | +| `default_outer_delta` | The default outer gap used by commands `gaps.outer.increase` and `gaps.outer.decrease` | +| `default_inner_delta` | The default inner gap used by commands `gaps.inner.increase` and `gaps.inner.decrease` | + +[!INCLUDE [Commands](../../_common/plugins/gaps.md)] diff --git a/docs/configure/plugins/layout-preview.md b/docs/configure/plugins/layout-preview.md new file mode 100644 index 000000000..cea9de805 --- /dev/null +++ b/docs/configure/plugins/layout-preview.md @@ -0,0 +1,19 @@ +# Layout Preview Plugin + +The `LayoutPreviewPlugin` adds a layout preview to Whim. + +![Layout preview demo](../../images/layout-preview-demo.gif) + +```yaml +plugins: + layout_preview: + is_enabled: true +``` + +## Configuration + +| Property | Description | +| ------------ | -------------------------------------------------- | +| `is_enabled` | Whether the plugin is enabled. Defaults to `true`. | + +[!INCLUDE [Commands](../../_common/plugins/layout-preview.md)] diff --git a/docs/configure/plugins/overview.md b/docs/configure/plugins/overview.md new file mode 100644 index 000000000..bdeb6e61d --- /dev/null +++ b/docs/configure/plugins/overview.md @@ -0,0 +1,17 @@ +# Plugins Overview + +Whim is build around plugins. Plugins are loaded as required by Whim based on the configuration. + +| Plugin | TL;DR | Docs | +| --------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------- | +| Bar | Adds a configurable bar to the top of each screen | [`plugins.bar`](bar.md) | +| Command Palette | Fuzzy command palette filled with [commands](../core/commands.md) | [`plugins.command_palette`](command-palette.md) | +| Floating Window | Lets windows float outside other layout engines | [`plugins.floating_window`](floating-window.md) | +| Focus | Adds a border around the current window | [`plugins.focus_indicator`](focus-indicator.md) | +| Gaps | Adds gaps between windows | [`plugins.gaps`](gaps.md) | +| Layout Preview | Shows a preview when dragging windows | [`plugins.layout_preview`](layout-preview.md) | +| Slice Layout | Plugin for the [`SliceLayoutEngine`](../core/layout-engines.md#slicelayoutengine) | [`plugins.slice_layout`](slice-layout.md) | +| Tree Layout | Plugin for the [`TreeLayoutEngine`](../core/layout-engines.md#treelayoutengine) | [`plugins.tree_layout`](tree-layout.md) | +| Tree Layout Bar | Provides a widget for the [Bar](bar.md), for the `TreeLayoutEngine` | [`plugins.bar`](bar.md#tree-layout) | +| Tree Layout Command Palette | Adds `TreeLayoutEngine`-specific commands to the [Command Palette](command-palette.md) | [`plugins.command_palette`](command-palette.md#tree-layout) | +| Updater | Plugin to automatically update Whim | [`plugins.updater`](updater.md) | diff --git a/docs/configure/plugins/slice-layout.md b/docs/configure/plugins/slice-layout.md new file mode 100644 index 000000000..dc07356f6 --- /dev/null +++ b/docs/configure/plugins/slice-layout.md @@ -0,0 +1,7 @@ +# Slice Layout Plugin + +The `SliceLayoutPlugin` is automatically loaded when the `SliceLayoutEngine` is used in the configuration - see [Layout Engines](../core/layout-engines.md) and [Workspaces](../core/workspaces.md). + +## Commands + +[!INCLUDE [Commands](../../_common/plugins/slice-layout.md)] diff --git a/docs/configure/plugins/tree-layout.md b/docs/configure/plugins/tree-layout.md new file mode 100644 index 000000000..6bbf73a85 --- /dev/null +++ b/docs/configure/plugins/tree-layout.md @@ -0,0 +1,7 @@ +# Tree Layout Plugin + +The `TreeLayoutPlugin` is automatically loaded when the `TreeLayoutEngine` is used in the configuration - see [Layout Engines](../core/layout-engines.md) and [Workspaces](../core/workspaces.md). + +## Commands + +[!INCLUDE [Commands](../../_common/plugins/tree-layout.md)] diff --git a/docs/configure/plugins/updater.md b/docs/configure/plugins/updater.md new file mode 100644 index 000000000..e7f935777 --- /dev/null +++ b/docs/configure/plugins/updater.md @@ -0,0 +1,21 @@ +# Updater Plugin + +The `UpdaterPlugin` adds the ability to notify the user when a new version of Whim is available. + +```yaml +plugins: + updater: + is_enabled: true + release_channel: alpha + update_frequency: weekly +``` + +## Configuration + +| Property | Description | +| ------------------ | ----------------------------------------------------------------------------------------------------------- | +| `is_enabled` | Whether the plugin is enabled. Default is `true`. | +| `release_channel` | The release channel to use. Options are `alpha`, `beta`, and `stable`. Default is `alpha`. | +| `update_frequency` | How often to check for updates. Options are `never`, `daily`, `weekly`, and `monthly`. Default is `weekly`. | + +[!INCLUDE [Commands](../../_common/plugins/updater.md)] diff --git a/docs/configure/toc.yml b/docs/configure/toc.yml new file mode 100644 index 000000000..ae23d0c6d --- /dev/null +++ b/docs/configure/toc.yml @@ -0,0 +1,24 @@ +items: + - href: yaml-json-configuration.md + + - name: Core + - href: core/workspaces.md + - href: core/layout-engines.md + - href: core/monitors.md + - href: core/keybinds.md + - href: core/commands.md + - href: core/routing.md + - href: core/filtering.md + - href: core/styling.md + - href: core/logging.md + + - name: Plugins + - href: plugins/overview.md + - href: plugins/bar.md + - href: plugins/command-palette.md + - href: plugins/focus-indicator.md + - href: plugins/gaps.md + - href: plugins/layout-preview.md + - href: plugins/slice-layout.md + - href: plugins/tree-layout.md + - href: plugins/updater.md diff --git a/docs/configure/yaml-json-configuration.md b/docs/configure/yaml-json-configuration.md new file mode 100644 index 000000000..73a9a7148 --- /dev/null +++ b/docs/configure/yaml-json-configuration.md @@ -0,0 +1,53 @@ +# YAML/JSON Configuration (WIP) + +Whim is in the process of adding YAML configuration support - this is being tracked in [#1009](https://github.com/dalyIsaac/Whim/issues/1009). + +This has been implemented in the `Whim.Yaml` plugin, and may have breaking changes for the lifetime of the GitHub issue. + +In the meantime, Whim can be configured fully in C# - see [Scripting](../script/scripting.md) for more information. + +## Setup + +The YAML/JSON configuration is not yet included in the default Whim configuration. + +Add to your `whim.config.csx`: + +```csharp +// ...previous references + +// NOTE: Replace WHIM_PATH with the path to your Whim installation +#r "WHIM_PATH\plugins\Whim.Yaml\Whim.Yaml.dll" + +using System; +// ...usings... +using Whim.Yaml; + +// ... + +void DoConfig(IContext context) +{ + // Make sure to place this at the top of your config + YamlLoader.Load(context); +} +``` + +Whim will then look for a `whim.config.yaml` or `whim.config.json` file in the root of your `.whim` directory. If it finds one, it will use that file to configure Whim. + +## Schema + +The schema for the YAML and JSON configuration is available [here](https://raw.githubusercontent.com/dalyIsaac/Whim/main/src/Whim.Yaml/schema.json). This schema will eventually be bundled with the Whim installation. + +To use the schema in your YAML file, add the following line at the top of your file: + +```yaml +# yaml-language-server: $schema=https://raw.githubusercontent.com/dalyIsaac/Whim/main/src/Whim.Yaml/schema.json +``` + +To use the schema in your JSON file, add the following line at the top of your file: + +```json +{ + "$schema": "https://raw.githubusercontent.com/dalyIsaac/Whim/main/src/Whim.Yaml/schema.json", + ... +} +``` diff --git a/docs/docs/contribute/building-whim.md b/docs/contribute/building-whim.md similarity index 99% rename from docs/docs/contribute/building-whim.md rename to docs/contribute/building-whim.md index 8c1bf4c3f..f5a165d8a 100644 --- a/docs/docs/contribute/building-whim.md +++ b/docs/contribute/building-whim.md @@ -13,7 +13,7 @@ Visual Studio 2022 is the easiest way to get started with working on Whim. Check - The **Configuration Manager** is set to `Debug` and your target architecture is correct (e.g. `x64`). - The **green Start arrow** is labeled `Whim.Runner (Unpackaged)`. -![Visual Studio setup](../../images/visual-studio-setup.gif) +![Visual Studio setup](../images/visual-studio-setup.gif) **Recommended Extensions:** diff --git a/docs/docs/contribute/docs.md b/docs/contribute/docs.md similarity index 99% rename from docs/docs/contribute/docs.md rename to docs/contribute/docs.md index e8e8a86c7..a4f366654 100644 --- a/docs/docs/contribute/docs.md +++ b/docs/contribute/docs.md @@ -31,7 +31,7 @@ Before making a pull request, please run the `markdownlint` formatter, available ```shell # In the repo root, run the CLI formatter -markdownlint-cli2 --fix --config ".markdownlint-cli2.jsonc" "docs/**/*.md" +markdownlint-cli2 --fix --config ".markdownlint-cli2.jsonc" "docs/**/*.md" ``` ## Things to keep in mind diff --git a/docs/docs/contribute/environment-setup.md b/docs/contribute/environment-setup.md similarity index 100% rename from docs/docs/contribute/environment-setup.md rename to docs/contribute/environment-setup.md diff --git a/docs/docs/contribute/guide.md b/docs/contribute/guide.md similarity index 98% rename from docs/docs/contribute/guide.md rename to docs/contribute/guide.md index 9b861a118..ffe6ad619 100644 --- a/docs/docs/contribute/guide.md +++ b/docs/contribute/guide.md @@ -1,4 +1,4 @@ -# Contributing Guide +# Guide Whim is an open-source project and contributions are welcome! This guide will help you get started with contributing to Whim. diff --git a/docs/docs/contribute/releases.md b/docs/contribute/releases.md similarity index 100% rename from docs/docs/contribute/releases.md rename to docs/contribute/releases.md diff --git a/docs/contribute/toc.yml b/docs/contribute/toc.yml new file mode 100644 index 000000000..6fd470e41 --- /dev/null +++ b/docs/contribute/toc.yml @@ -0,0 +1,6 @@ +items: + - href: guide.md + - href: environment-setup.md + - href: building-whim.md + - href: docs.md + - href: releases.md diff --git a/docs/docs/getting-started/plugins.md b/docs/docs/getting-started/plugins.md deleted file mode 100644 index 28e710ed6..000000000 --- a/docs/docs/getting-started/plugins.md +++ /dev/null @@ -1,23 +0,0 @@ -# Plugins - -Whim is build around plugins. Plugins are referenced using `#r` and `using` statements at the top of the config file. Each plugin generally has a `Config` class, and a `Plugin` class, and needs to be added to the . For example: - -```csharp -BarConfig barConfig = new(leftComponents, centerComponents, rightComponents); -BarPlugin barPlugin = new(context, barConfig); -context.PluginManager.AddPlugin(barPlugin); -``` - -| Plugin | TL;DR | -|--------------------------------------------------------------------------| ------------------------------------------------------------------------------------------------- | -| [Bar](../plugins/bar.md) | Adds a configurable bar to the top of each screen | -| [Command Palette](../plugins/command-palette.md) | Fuzzy command palette filled with [commands](../customize/commands.md) | -| [Floating Window](../plugins/floating-window.md) | Lets windows float outside other layout engines | -| [Focus](../plugins/focus-indicator.md) | Adds a border around the current window | -| [Gaps](../plugins/gaps.md) | Adds gaps between windows | -| [Layout Preview](../plugins/layout-preview.md) | Shows a preview when dragging windows | -| [Slice Layout](../plugins/slice-layout.md) | Plugin for the [`SliceLayoutEngine`](../customize/layout-engines.md#slicelayoutengine) | -| [Tree Layout](../plugins/tree-layout.md) | Plugin for the [`TreeLayoutEngine`](../customize//layout-engines.md#treelayoutengine) | -| [Tree Layout Bar](../plugins/tree-layout-bar.md) | Provides a widget for the [Bar](../plugins/bar.md), for the `TreeLayoutEngine` | -| [Tree Layout Command Palette](../plugins/tree-layout-command-palette.md) | Adds `TreeLayoutEngine`-specific commands to the [Command Palette](../plugins/command-palette.md) | -| [Updater](../plugins/updater.md) | Plugin to automatically update Whim | diff --git a/docs/docs/toc.yml b/docs/docs/toc.yml deleted file mode 100644 index 96bfd7b8b..000000000 --- a/docs/docs/toc.yml +++ /dev/null @@ -1,51 +0,0 @@ -items: - - name: Getting Started - - href: ../index.md - - href: getting-started/comparison.md - - href: getting-started/customize.md - - href: getting-started/plugins.md - - href: getting-started/inspiration.md - - href: getting-started/troubleshooting.md - - - name: Customize - - href: customize/scripting.md - - href: customize/commands.md - - href: customize/keybinds.md - - href: customize/workspaces.md - - href: customize/layout-engines.md - - href: customize/monitors.md - - href: customize/store.md - - href: customize/routing.md - - href: customize/filtering.md - - href: customize/logging.md - - href: customize/styling.md - - href: customize/snippets.md - - href: customize/yaml.md - - - name: Plugins - - href: plugins/bar.md - - href: plugins/command-palette.md - - href: plugins/floating-window.md - - href: plugins/focus-indicator.md - - href: plugins/gaps.md - - href: plugins/layout-preview.md - - href: plugins/slice-layout.md - - href: plugins/tree-layout.md - - href: plugins/tree-layout-bar.md - - href: plugins/tree-layout-command-palette.md - - href: plugins/updater.md - - - name: Architecture - - href: architecture/context.md - - href: architecture/store.md - - href: architecture/result.md - - href: architecture/events.md - - href: architecture/native-apis.md - - href: architecture/deprecated.md - - - name: Contributing - - href: contribute/guide.md - - href: contribute/environment-setup.md - - href: contribute/building-whim.md - - href: contribute/docs.md - - href: contribute/releases.md diff --git a/docs/index.md b/docs/index.md index 183e45474..0a398bb7b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,13 +4,15 @@ > All the power to the user! -Whim is a hackable, pluggable and scriptable dynamic window manager for Windows 10 and 11, built using WinUI 3, .NET, and C# scripting. +Whim is a hackable, pluggable and scriptable dynamic window manager for Windows 10 and 11, built using WinUI 3, .NET, and C# scripting. Whim supports multiple layout engines, workspaces, and plugins. Whim is designed to be highly customizable and extensible, allowing users to create their own layouts, workspaces, and plugins. + +Whim can be configured using YAML, JSON, or C# scripting. ![Whim demo](images/demo.gif) ## Installation -Alpha builds are available on the [releases page](https://github.com/dalyIsaac/Whim/releases) on GitHub. Whim has an [updater plugin](docs/plugins/updater.md) to notify you of new releases. +Alpha builds are available on the [releases page](https://github.com/dalyIsaac/Whim/releases) on GitHub. Whim has an [updater plugin](configure/plugins/updater.md) to notify you of new releases. Installation via package managers is coming in [dalyIsaac/Whim#792](https://github.com/dalyIsaac/Whim/issues/792). @@ -18,10 +20,10 @@ Installation via package managers is coming in [dalyIsaac/Whim#792](https://gith A window manager is responsible for controlling the layout of windows in your desktop environment. Whim is a [dynamic window manager](https://en.wikipedia.org/wiki/Dynamic_window_manager), where windows are arranged according to different layouts. -Whim supports multiple layout engines. Each [workspace](docs/customize/workspaces.md) can switch between different layout engines. For example, the `TreeLayoutEngine` allows users to create arbitrary grids of windows during runtime (similar to `i3`), while the `SliceLayoutEngine` fully automates windows placement using a predefined, customizable logic (similar to `Awesome` or `dwm`) . For more, see [Layout Engines](docs/customize/layout-engines.md). +Whim supports multiple layout engines. Each [workspace](configure/core/workspaces.md) can switch between different layout engines. For example, the [`TreeLayoutEngine`](configure/core/layout-engines.md#treelayoutengine) allows users to create arbitrary grids of windows during runtime (similar to `i3`), while the [`SliceLayoutEngine`](configure/core/layout-engines.md#slicelayoutengine) fully automates windows placement using a predefined, customizable logic (similar to `Awesome` or `dwm`) . For more, see [Layout Engines](configure/core/layout-engines.md). Whim is configured using C# scripting - no YAML to be found here. This means you can use the full power of C# to configure Whim. Whim also exposes its API for plugins to use. Accordingly, much of the more custom functionality has been implemented as plugins which users can choose to use or not. -Whim works by sitting on top of Windows' own window manager. It listens to window events and moves windows accordingly. Whim does not use Windows' native "virtual" desktops, as they lack the ability to activate "desktops" independently of monitors. Instead, Whim has [workspaces](docs/customize/workspaces.md). +Whim works by sitting on top of Windows' own window manager. It listens to window events and moves windows accordingly. Whim does not use Windows' native "virtual" desktops, as they lack the ability to activate "desktops" independently of monitors. Instead, Whim has [workspaces](configure/core/workspaces.md). -To see how Whim compares to other Windows window managers, see [Whim vs. Other Window Managers](docs/getting-started/comparison.md). +To see how Whim compares to other Windows window managers, see [Whim vs. Other Window Managers](intro/comparison.md). diff --git a/docs/docs/getting-started/comparison.md b/docs/intro/comparison.md similarity index 95% rename from docs/docs/getting-started/comparison.md rename to docs/intro/comparison.md index 4796d18be..74dfbb9a2 100644 --- a/docs/docs/getting-started/comparison.md +++ b/docs/intro/comparison.md @@ -19,13 +19,13 @@ | Feature\Window Manager | Whim | bug.n | FancyWM | GlazeWM | Komorebi | PowerToys' FancyZones | Workspacer | | ---------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | | Written in | C# | AutoHotkey | C# | Rust | Rust | C++ | C# | -| Configured with | C# | AutoHotkey | GUI/JSON | YAML | YAML or shell script | GUI | C# | +| Configured with | C#/YAML/JSON | AutoHotkey | GUI/JSON | YAML | YAML or shell script | GUI | C# | | Dynamic management | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | ✅ | | Manual management | ✅ | ❌ | ❌ | ✅ | ❌ | ☑️ but not tiling | ❌ | | Customizable layouts | ✅ | ❌ | ☑️ with [limited manual panels](https://github.com/FancyWM/fancywm/wiki/Panels) | ❌ | ☑️ with [custom dynamic layouts](https://github.com/LGUG2Z/komorebi?tab=readme-ov-file#creating-and-loading-custom-layouts) | ☑️ with [custom manual layouts](https://learn.microsoft.com/en-us/windows/powertoys/fancyzones#creating-a-custom-layout) | ✅ | | Plugin architecture | ✅ via C# | ❌ | ❌ | ☑️ via external control | ☑️ via external control | ❌ | ✅ via C# | | System tray support | 💡 in [backlog](https://github.com/dalyIsaac/Whim/issues/78) | ❌ | ❌ | ✅ | ❌ | ❌ | ✅ | -| On the fly reload | ❌ | ❌ | ❌ - see [settings.json](https://github.com/FancyWM/fancywm/wiki/settings.json) | ✅ | ✅ | ✅ | ❌ | +| On the fly reload | 💡 | ❌ | ❌ - see [settings.json](https://github.com/FancyWM/fancywm/wiki/settings.json) | ✅ | ✅ | ✅ | ❌ | | Information bars | ✅ | ✅ | ✅ | ✅ | ✅, via [Yasb](https://github.com/da-rth/yasb) | ❌ | ✅ | | External control | 💡 in [backlog](https://github.com/dalyIsaac/Whim/issues/670) | ❌ | ✅ via [shell scripting](https://github.com/FancyWM/fancywm/wiki/Scripting) | ❌ | ✅, via [komorebic](https://github.com/LGUG2Z/komorebi?tab=readme-ov-file#configuration-with-komorebic), [named pipes and TCP](https://github.com/LGUG2Z/komorebi?tab=readme-ov-file#configuration-with-komorebic) | ❌ | ❌ | | Maintenance | Active | [Not active](https://github.com/fuhsjr00/bug.n?tab=readme-ov-file#development) | Active | Active | Active | Active | [Not active](https://github.com/workspacer/workspacer/discussions/485) | diff --git a/docs/docs/getting-started/customize.md b/docs/intro/customize.md similarity index 82% rename from docs/docs/getting-started/customize.md rename to docs/intro/customize.md index 68060031e..e4c7242c4 100644 --- a/docs/docs/getting-started/customize.md +++ b/docs/intro/customize.md @@ -7,9 +7,9 @@ When you run Whim for the first time, it will create the `C:\Users\{username}\.w `whim.config.csx` is a C# script file, and is reloaded every time Whim starts. On first run, it is populated with a pre-filled example which you can use as a starting point - see the config [here](https://github.com/dalyIsaac/Whim/blob/main/src/Whim/Template/whim.config.csx). The core of the configuration is nested inside a function, which is written in typical C# code. The function takes an parameter. `DoConfig` is the entry point for your config. Prior to calling `DoConfig`, Whim will set up the `IContext` and its constituent parts, which exposes Whim's [API](/api) to be used in the configuration. -**For more, see the [Scripting](../customize/scripting.md) page**. +**For more, see the [Scripting](../script/scripting.md) page**. -The pages under the **Customize** section (in the left sidebar) document popular configuration options. Unless explicitly stated otherwise, all code snippets found in the **Customize** section are expected to be located inside the body of `DoConfig`. +YAML and JSON configuration is in the works - see [#1009](https://github.com/dalyIsaac/Whim/issues/1009) for more information. ## Recommended tooling diff --git a/docs/docs/getting-started/inspiration.md b/docs/intro/inspiration.md similarity index 82% rename from docs/docs/getting-started/inspiration.md rename to docs/intro/inspiration.md index 75a8d8f6d..adc657c43 100644 --- a/docs/docs/getting-started/inspiration.md +++ b/docs/intro/inspiration.md @@ -11,7 +11,7 @@ There are several key differences between Whim and workspacer: workspacer stores all windows in an [`IEnumerable`](https://github.com/workspacer/workspacer/blob/17750d1f84b8bb9015638ee7a733a2976ce08d25/src/workspacer.Shared/Workspace/Workspace.cs#L10) stack which is passed to each [`ILayout` implementation](https://github.com/workspacer/workspacer/blob/17750d1f84b8bb9015638ee7a733a2976ce08d25/src/workspacer.Shared/Layout/ILayoutEngine.cs#L23). This has a number of downsides: - All layout engines must work with the same list of windows. -- workspacer cannot support more complex window layouts. In comparison, each in Whim stores windows in their own manner. For example, Whim's [tree layout](../plugins/tree-layout.md) uses a n-ary tree structure to store windows in arbitrary grid layouts. For more, see [Layout Engines](../customize/layout-engines.md). +- workspacer cannot support more complex window layouts. In comparison, each in Whim stores windows in their own manner. For example, Whim's [tree layout](../configure/plugins/tree-layout.md) uses a n-ary tree structure to store windows in arbitrary grid layouts. For more, see [Layout Engines](../configure/core/layout-engines.md). Whim's s also have methods for directional operations, like: @@ -21,14 +21,14 @@ Whim's s also have methods for directional operations, Whim's does not have the concept of a "primary area". However, this can be provided by `ILayoutEngine` implementations - for example, the . -Implementations of Whim's `ILayoutEngine` should be immutable. This was done to support functionality like previewing changes to layouts before committing them, with the [Layout Preview](../plugins/layout-preview.md) plugin. In comparison, workspacer's `ILayoutEngine` implementations are mutable. +Implementations of Whim's `ILayoutEngine` should be immutable. This was done to support functionality like previewing changes to layouts before committing them, with the [Layout Preview](../configure/plugins/layout-preview.md) plugin. In comparison, workspacer's `ILayoutEngine` implementations are mutable. ## Commands -Whim has a command system with common functionality, which makes it easier to interact with at a higher level. The command system is used by different components, like the and [Command Palette](../plugins/command-palette.md). +Whim has a command system with common functionality, which makes it easier to interact with at a higher level. The command system is used by different components, like the and [Command Palette](../configure/plugins/command-palette.md). The command palette in Whim is also more powerful than the one in workspacer, using a port of the Visual Studio Code command palette fuzzy search algorithm. ## Appearance -Whim is built on top of WinUI 3 instead of Windows Forms. This makes it easier to have a more modern-looking UI, and means it's possible for users to specify styling using XAML - see [Styling](../customize/styling.md). +Whim is built on top of WinUI 3 instead of Windows Forms. This makes it easier to have a more modern-looking UI, and means it's possible for users to specify styling using XAML - see [Styling](../configure/core/styling.md). diff --git a/docs/intro/plugins.md b/docs/intro/plugins.md new file mode 100644 index 000000000..ad2958409 --- /dev/null +++ b/docs/intro/plugins.md @@ -0,0 +1,23 @@ +# Plugins + +Whim is build around plugins. Plugins are referenced using `#r` and `using` statements at the top of the config file. Each plugin generally has a `Config` class, and a `Plugin` class, and needs to be added to the . For example: + +```csharp +BarConfig barConfig = new(leftComponents, centerComponents, rightComponents); +BarPlugin barPlugin = new(context, barConfig); +context.PluginManager.AddPlugin(barPlugin); +``` + +| Plugin | TL;DR | YAML JSON Docs | Docs | +| --------------------------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | +| Bar | Adds a configurable bar to the top of each screen | [`plugins.bar`](../configure/plugins/bar.md) | [`Whim.Bar`](../script/plugins/bar.md) | +| Command Palette | Fuzzy command palette filled with [commands](../configure/core/commands.md) | [`plugins.command_palette`](../configure/plugins/command-palette.md) | [`Whim.CommandPalette`](../script/plugins/command-palette.md) | +| Floating Window | Lets windows float outside other layout engines | [`plugins.floating_window`](../configure/plugins/floating-window.md) | [`Whim.FloatingWindow`](../script/plugins/floating-window.md) | +| Focus | Adds a border around the current window | [`plugins.focus_indicator`](../configure/plugins/focus-indicator.md) | [`Whim.FocusIndicator`](../script/plugins/focus-indicator.md) | +| Gaps | Adds gaps between windows | [`plugins.gaps`](../configure/plugins/gaps.md) | [`Whim.Gaps`](../script/plugins/gaps.md) | +| Layout Preview | Shows a preview when dragging windows | [`plugins.layout_preview`](../configure/plugins/layout-preview.md) | [`Whim.LayoutPreview`](../script/plugins/layout-preview.md) | +| Slice Layout | Plugin for the [`SliceLayoutEngine`](../configure/core/layout-engines.md#slicelayoutengine) | [`plugins.slice_layout`](../configure/plugins/slice-layout.md) | [`Whim.SliceLayout`](../script/plugins/slice-layout.md) | +| Tree Layout | Plugin for the [`TreeLayoutEngine`](../configure/core/layout-engines.md#treelayoutengine) | [`plugins.tree_layout`](../configure/plugins/tree-layout.md) | [`Whim.TreeLayout`](../script/plugins/tree-layout.md) | +| Tree Layout Bar | Provides a widget for the [Bar](../configure/plugins/bar.md), for the `TreeLayoutEngine` | [`plugins.bar`](../configure/plugins/bar.md#tree-layout) | [`Whim.TreeLayoutBar`](../script/plugins/tree-layout-bar.md) | +| Tree Layout Command Palette | Adds `TreeLayoutEngine`-specific commands to the [Command Palette](../configure/plugins/command-palette.md) | [`plugins.command_palette`](../configure/plugins/command-palette.md#tree-layout) | [`Whim.TreeLayoutCommandPalette`](../script/plugins/tree-layout-command-palette.md) | +| Updater | Plugin to automatically update Whim | [`plugins.updater`](../configure/plugins/updater.md) | [`Whim.Updater`](../script/plugins/updater.md) | diff --git a/docs/intro/toc.yml b/docs/intro/toc.yml new file mode 100644 index 000000000..98a3571fc --- /dev/null +++ b/docs/intro/toc.yml @@ -0,0 +1,7 @@ +items: + - href: ../index.md + - href: comparison.md + - href: customize.md + - href: plugins.md + - href: inspiration.md + - href: troubleshooting.md diff --git a/docs/docs/getting-started/troubleshooting.md b/docs/intro/troubleshooting.md similarity index 83% rename from docs/docs/getting-started/troubleshooting.md rename to docs/intro/troubleshooting.md index ce0d1654b..8d4b0a1c2 100644 --- a/docs/docs/getting-started/troubleshooting.md +++ b/docs/intro/troubleshooting.md @@ -14,8 +14,8 @@ To counteract this, the has a in Whim was responsible for using the stored the assignment of windows to workspaces, and the assignment of workspaces to monitors. -When [scripting](../customize/scripting.md), use `IButler` methods to move windows between workspaces and monitors. +When scripting, use `IButler` methods to move windows between workspaces and monitors. ## Window Manager diff --git a/docs/docs/architecture/events.md b/docs/script/architecture/events.md similarity index 100% rename from docs/docs/architecture/events.md rename to docs/script/architecture/events.md diff --git a/docs/script/architecture/layout-engines.md b/docs/script/architecture/layout-engines.md new file mode 100644 index 000000000..cd276600f --- /dev/null +++ b/docs/script/architecture/layout-engines.md @@ -0,0 +1,12 @@ +# Layout Engines + +A "layout engine" or in Whim is responsible for arranging windows in a workspace. Each workspace has a single active layout engine, and can cycle through different layout engines. + +There are two different types of layout engines: + +- proxy layout engines +- leaf layout engines + +**Proxy layout engines** wrap other engines, and can be used to modify the behavior of other engines. For example, the [`Gaps` plugin](../plugins/gaps.md) will add gaps between windows - normally layout engines won't leave gaps between windows. + +**Leaf layout engines** are the lowest level layout engines, and are responsible for actually arranging windows. diff --git a/docs/docs/architecture/native-apis.md b/docs/script/architecture/native-apis.md similarity index 100% rename from docs/docs/architecture/native-apis.md rename to docs/script/architecture/native-apis.md diff --git a/docs/docs/architecture/result.md b/docs/script/architecture/result.md similarity index 100% rename from docs/docs/architecture/result.md rename to docs/script/architecture/result.md diff --git a/docs/docs/architecture/store.md b/docs/script/architecture/store.md similarity index 100% rename from docs/docs/architecture/store.md rename to docs/script/architecture/store.md diff --git a/docs/script/core/commands.md b/docs/script/core/commands.md new file mode 100644 index 000000000..1f633b604 --- /dev/null +++ b/docs/script/core/commands.md @@ -0,0 +1,22 @@ +# Commands + +Custom commands can be created using the . They are automatically added to the `whim.custom` namespace. For example, the following command closes the current tracked window: + +```csharp +// Create the command. +context.CommandManager.Add( + // Automatically namespaced to `whim.custom`. + identifier: "close_window", + title: "Close focused window", + callback: () => + { + if (context.Store.Pick(Pickers.PickLastFocusedWindow).TryGet(out IWindow window)) + { + window.Close(); + } + } +); + +// Create an associated keybind. +context.KeybindManager.SetKeybind("whim.custom.close_window", new Keybind(IKeybind.WinAlt, VIRTUAL_KEY.VK_D)); +``` diff --git a/docs/docs/customize/filtering.md b/docs/script/core/filtering.md similarity index 100% rename from docs/docs/customize/filtering.md rename to docs/script/core/filtering.md diff --git a/docs/docs/customize/keybinds.md b/docs/script/core/keybinds.md similarity index 90% rename from docs/docs/customize/keybinds.md rename to docs/script/core/keybinds.md index a35ac3f1a..8f490a675 100644 --- a/docs/docs/customize/keybinds.md +++ b/docs/script/core/keybinds.md @@ -4,7 +4,7 @@ Keybinds are managed using the , which can be used to ## Default Keybinds -See the listing of [core commands](commands.md#core-commands) for a summary of default keybinds. Some plugins also come with additional default keybinds, which are documented on the individual plugin pages. +See the listing of [core commands](../../configure/core/commands.md#core-commands) for a summary of default keybinds. Some plugins also come with additional default keybinds, which are documented on the individual plugin pages. ## Creating Keybinds diff --git a/docs/docs/customize/layout-engines.md b/docs/script/core/layout-engines.md similarity index 86% rename from docs/docs/customize/layout-engines.md rename to docs/script/core/layout-engines.md index 6af6ae484..f626e0b9b 100644 --- a/docs/docs/customize/layout-engines.md +++ b/docs/script/core/layout-engines.md @@ -1,16 +1,5 @@ # Layout Engines -A "layout engine" or in Whim is responsible for arranging windows in a workspace. Each workspace has a single active layout engine, and can cycle through different layout engines. - -There are two different types of layout engines: - -- proxy layout engines -- leaf layout engines - -**Proxy layout engines** wrap other engines, and can be used to modify the behavior of other engines. For example, the [`Gaps` plugin](../plugins/gaps.md) will add gaps between windows - normally layout engines won't leave gaps between windows. - -**Leaf layout engines** are the lowest level layout engines, and are responsible for actually arranging windows. - ## Available layout engines | Engine | TL;DR | @@ -21,7 +10,7 @@ There are two different types of layout engines: ### `FocusLayoutEngine` - is a layout engine that displays one window at a time: + is a layout engine that displays one window at a time. To focus the window in the specified direction, call . @@ -111,6 +100,6 @@ context.PluginManager.AddPlugin(treeLayoutPlugin); ### `FloatingLayoutEngine` - is a layout that has all windows being free-floating. To have specific windows float within a different layout, see the [Floating Window Plugin](../plugins/floating-window.md). + is a layout that has all windows being free-floating. To have specific windows float within a different layout, see the [Floating Window Plugin](../plugins/floating-window.md). ![FloatingLayoutEngine demo](../../images/floating-layout-demo.gif) diff --git a/docs/docs/customize/logging.md b/docs/script/core/logging.md similarity index 100% rename from docs/docs/customize/logging.md rename to docs/script/core/logging.md diff --git a/docs/docs/customize/monitors.md b/docs/script/core/monitors.md similarity index 100% rename from docs/docs/customize/monitors.md rename to docs/script/core/monitors.md diff --git a/docs/docs/customize/routing.md b/docs/script/core/routing.md similarity index 100% rename from docs/docs/customize/routing.md rename to docs/script/core/routing.md diff --git a/docs/docs/customize/snippets.md b/docs/script/core/snippets.md similarity index 96% rename from docs/docs/customize/snippets.md rename to docs/script/core/snippets.md index 1806e3654..9c1bc2e7a 100644 --- a/docs/docs/customize/snippets.md +++ b/docs/script/core/snippets.md @@ -2,6 +2,8 @@ Potentially useful code snippets. +Each of these snippets (apart from the `using` statements) should be added inside the `DoConfig` function in your `whim.config.csx` file. + ## Minimize a specific window ```csharp diff --git a/docs/docs/customize/store.md b/docs/script/core/store.md similarity index 100% rename from docs/docs/customize/store.md rename to docs/script/core/store.md diff --git a/docs/script/core/styling.md b/docs/script/core/styling.md new file mode 100644 index 000000000..a317edfb5 --- /dev/null +++ b/docs/script/core/styling.md @@ -0,0 +1,3 @@ +# Styling + +[!INCLUDE [Styling](../../_common/core/styling.md)] diff --git a/docs/docs/customize/workspaces.md b/docs/script/core/workspaces.md similarity index 96% rename from docs/docs/customize/workspaces.md rename to docs/script/core/workspaces.md index 1ac29fb7f..9694eae8f 100644 --- a/docs/docs/customize/workspaces.md +++ b/docs/script/core/workspaces.md @@ -58,4 +58,4 @@ context.CommandManager.Add( ); ``` -For more, see the [Store](./store.md) and [Commands](./commands.md) pages. +For more, see the [Store](./store.md) and [Commands](../../configure/core/commands.md) pages. diff --git a/docs/docs/plugins/bar.md b/docs/script/plugins/bar.md similarity index 96% rename from docs/docs/plugins/bar.md rename to docs/script/plugins/bar.md index b68b36efd..3d13cfb19 100644 --- a/docs/docs/plugins/bar.md +++ b/docs/script/plugins/bar.md @@ -8,7 +8,7 @@ The adds a configurable bar at the top of a screen. The takes in three lists of s in its constructor. These correspond to the left, center, and right components on the bar. -The bar can be styled using XAML - see [Styling](../customize/styling.md). +The bar can be styled using XAML - see [Styling](../core/styling.md). > [!NOTE] > The height of the bar can be configured the XAML styling. However, [BarConfig.Height](xref:Whim.Bar.BarConfig.Height) takes precedence over the height specified in the XAML. diff --git a/docs/script/plugins/command-palette.md b/docs/script/plugins/command-palette.md new file mode 100644 index 000000000..c2dd01358 --- /dev/null +++ b/docs/script/plugins/command-palette.md @@ -0,0 +1,38 @@ +# Command Palette Plugin + +The provides a fuzzy command palette, loaded with all the s registered with the . + +The command palette uses a port of Visual Studio Code's fuzzy search algorithm. + +![Command palette demo](../../images/command-palette-demo.gif) + +## Configuration + +The can be used to configure the command palette. The can be used to configure the default commands and matcher to use. + +Custom instances of the command palette can be activated by calling . + +## Example Config + +```csharp +#r "WHIM_PATH\whim.dll" +#r "WHIM_PATH\plugins\Whim.CommandPalette\Whim.CommandPalette.dll" + +using Whim; +using Whim.CommandPalette; + +void DoConfig(IContext context) +{ + // ... + + CommandPaletteConfig commandPaletteConfig = new(context); + CommandPalettePlugin commandPalettePlugin = new(context, commandPaletteConfig); + context.PluginManager.AddPlugin(commandPalettePlugin); + + // ... +} + +return DoConfig; +``` + +[!INCLUDE [Commands](../../_common/plugins/command-palette.md)] diff --git a/docs/docs/plugins/floating-window.md b/docs/script/plugins/floating-window.md similarity index 100% rename from docs/docs/plugins/floating-window.md rename to docs/script/plugins/floating-window.md diff --git a/docs/docs/plugins/focus-indicator.md b/docs/script/plugins/focus-indicator.md similarity index 59% rename from docs/docs/plugins/focus-indicator.md rename to docs/script/plugins/focus-indicator.md index 92fe08ec8..77f124f0e 100644 --- a/docs/docs/plugins/focus-indicator.md +++ b/docs/script/plugins/focus-indicator.md @@ -30,11 +30,4 @@ void DoConfig(IContext context) return DoConfig; ``` -## Commands - -| Identifier | Title | Keybind | -| ------------------------------------- | --------------------------------------------- | ------------------ | -| `whim.focus_indicator.show` | Show focus indicator | No default keybind | -| `whim.focus_indicator.toggle` | Toggle focus indicator | No default keybind | -| `whim.focus_indicator.toggle_fade` | Toggle whether the focus indicator fades | No default keybind | -| `whim.focus_indicator.toggle_enabled` | Toggle whether the focus indicator is enabled | No default keybind | +[!INCLUDE [Commands](../../_common/plugins/focus-indicator.md)] diff --git a/docs/docs/plugins/gaps.md b/docs/script/plugins/gaps.md similarity index 50% rename from docs/docs/plugins/gaps.md rename to docs/script/plugins/gaps.md index 3fd1ddfbb..abda2b0df 100644 --- a/docs/docs/plugins/gaps.md +++ b/docs/script/plugins/gaps.md @@ -29,11 +29,4 @@ void DoConfig(IContext context) return DoConfig; ``` -## Commands - -| Identifier | Title | Keybind | -| -------------------------- | ------------------ | ------------------------------------------------------------------ | -| `whim.gaps.outer.increase` | Increase outer gap | Win + Ctrl + Shift + L | -| `whim.gaps.outer.decrease` | Decrease outer gap | Win + Ctrl + Shift + H | -| `whim.gaps.inner.increase` | Increase inner gap | Win + Ctrl + Shift + K | -| `whim.gaps.inner.decrease` | Decrease inner gap | Win + Ctrl + Shift + J | +[!INCLUDE [Commands](../../_common/plugins/gaps.md)] diff --git a/docs/docs/plugins/layout-preview.md b/docs/script/plugins/layout-preview.md similarity index 93% rename from docs/docs/plugins/layout-preview.md rename to docs/script/plugins/layout-preview.md index b0717f362..e5b27f7fb 100644 --- a/docs/docs/plugins/layout-preview.md +++ b/docs/script/plugins/layout-preview.md @@ -33,6 +33,4 @@ return DoConfig; ``` -## Commands - -N/A +[!INCLUDE [Commands](../../_common/plugins/layout-preview.md)] diff --git a/docs/script/plugins/overview.md b/docs/script/plugins/overview.md new file mode 100644 index 000000000..74bfd5bdc --- /dev/null +++ b/docs/script/plugins/overview.md @@ -0,0 +1,31 @@ +# Plugins Overview + +Whim is build around plugins. Plugins are referenced using `#r` and `using` statements at the top of the config file. Each plugin generally has a `Config` class, and a `Plugin` class, and needs to be added to the . For example: + +```csharp +BarConfig barConfig = new(leftComponents, centerComponents, rightComponents); +BarPlugin barPlugin = new(context, barConfig); +context.PluginManager.AddPlugin(barPlugin); +``` + +If a plugin was loaded by the YAML/JSON configuration, it will be loaded automatically and does not need to be added to the `PluginManager`. Such plugins can be access via: + +```csharp +BarPlugin barPlugin = (BarPlugin)context.PluginManager.LoadedPlugins.First(p => p.Name == "whim.bar"); +``` + +## Plugins + +| Plugin | TL;DR | C# Scripting Docs | +| --------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | +| Bar | Adds a configurable bar to the top of each screen | [`Whim.Bar`](bar.md) | +| Command Palette | Fuzzy command palette filled with [commands](../../configure/core/commands.md) and [custom commands](../core/commands.md) | [`Whim.CommandPalette`](command-palette.md) | +| Floating Window | Lets windows float outside other layout engines | [`Whim.FloatingWindow`](floating-window.md) | +| Focus | Adds a border around the current window | [`Whim.FocusIndicator`](focus-indicator.md) | +| Gaps | Adds gaps between windows | [`Whim.Gaps`](gaps.md) | +| Layout Preview | Shows a preview when dragging windows | [`Whim.LayoutPreview`](layout-preview.md) | +| Slice Layout | Plugin for the [`SliceLayoutEngine`](../core/layout-engines.md#slicelayoutengine) | [`Whim.SliceLayout`](slice-layout.md) | +| Tree Layout | Plugin for the [`TreeLayoutEngine`](../core/layout-engines.md#treelayoutengine) | [`Whim.TreeLayout`](tree-layout.md) | +| Tree Layout Bar | Provides a widget for the [Bar](bar.md), for the `TreeLayoutEngine` | [`Whim.TreeLayoutBar`](tree-layout-bar.md) | +| Tree Layout Command Palette | Adds `TreeLayoutEngine`-specific commands to the [Command Palette](command-palette.md) | [`Whim.TreeLayoutCommandPalette`](tree-layout-command-palette.md) | +| Updater | Plugin to automatically update Whim | [`Whim.Updater`](updater.md) | diff --git a/docs/script/plugins/slice-layout.md b/docs/script/plugins/slice-layout.md new file mode 100644 index 000000000..49308c76f --- /dev/null +++ b/docs/script/plugins/slice-layout.md @@ -0,0 +1,31 @@ +# Slice Layout Plugin + + provides commands and functionality for the . + + does not load the - that is done when creating a workspace via the . + +For more about the `SliceLayoutEngine`, see the [Layout Engines](../core/layout-engines.md#slicelayoutengine) page. + +## Example Config + +```csharp +#r "WHIM_PATH\whim.dll" +#r "WHIM_PATH\plugins\Whim.SliceLayout\Whim.SliceLayout.dll" + +using Whim; +using Whim.SliceLayout; + +void DoConfig(IContext context) +{ + // ... + + SliceLayoutPlugin sliceLayoutPlugin = new(context); + context.PluginManager.AddPlugin(sliceLayoutPlugin); + + // ... +} + +return DoConfig; +``` + +[!INCLUDE [Commands](../../_common/plugins/slice-layout.md)] diff --git a/docs/docs/plugins/tree-layout-bar.md b/docs/script/plugins/tree-layout-bar.md similarity index 92% rename from docs/docs/plugins/tree-layout-bar.md rename to docs/script/plugins/tree-layout-bar.md index f054a03a3..56ba1a379 100644 --- a/docs/docs/plugins/tree-layout-bar.md +++ b/docs/script/plugins/tree-layout-bar.md @@ -23,13 +23,13 @@ void DoConfig(IContext context) TreeLayoutPlugin treeLayoutPlugin = new(context); context.PluginManager.AddPlugin(treeLayoutPlugin); - // Tree layout bar + // Tree layout bar TreeLayoutBarPlugin treeLayoutBarPlugin = new(treeLayoutPlugin); context.PluginManager.AddPlugin(treeLayoutBarPlugin); rightComponents.Add(treeLayoutBarPlugin.CreateComponent()); // Bar plugin - List leftComponents = new() { WorkspaceWidget.CreateComponent() }; + List leftComponents = new() { WorkspaceWidget.CreateComponent() }; List centerComponents = new() { FocusedWindowWidget.CreateComponent() }; List rightComponents = new() { diff --git a/docs/docs/plugins/tree-layout-command-palette.md b/docs/script/plugins/tree-layout-command-palette.md similarity index 100% rename from docs/docs/plugins/tree-layout-command-palette.md rename to docs/script/plugins/tree-layout-command-palette.md diff --git a/docs/script/plugins/tree-layout.md b/docs/script/plugins/tree-layout.md new file mode 100644 index 000000000..97e2bfed5 --- /dev/null +++ b/docs/script/plugins/tree-layout.md @@ -0,0 +1,33 @@ +# Tree Layout Plugin + + provides commands and functionality for the . + + does not load the - that is done when creating a workspace via the . + +For more about the `TreeLayoutEngine`, see the [Layout Engines](../../configure/core/layout-engines.md#treelayoutengine) page. + +The [Tree Layout Bar plugin](./tree-layout-bar.md) provides a widget for the bar to set the direction to add the next window. + +## Example Config + +```csharp +#r "WHIM_PATH\whim.dll" +#r "WHIM_PATH\plugins\Whim.TreeLayout\Whim.TreeLayout.dll" + +using Whim; +using Whim.TreeLayout; + +void DoConfig(IContext context) +{ + // ... + + TreeLayoutPlugin treeLayoutPlugin = new(context); + context.PluginManager.AddPlugin(treeLayoutPlugin); + + // ... +} + +return DoConfig; +``` + +[!INCLUDE [Commands](../../_common/plugins/tree-layout.md)] diff --git a/docs/docs/plugins/updater.md b/docs/script/plugins/updater.md similarity index 83% rename from docs/docs/plugins/updater.md rename to docs/script/plugins/updater.md index 2f7583cd2..d3b02f73b 100644 --- a/docs/docs/plugins/updater.md +++ b/docs/script/plugins/updater.md @@ -32,8 +32,4 @@ void DoConfig(IContext context) return DoConfig; ``` -## Commands - -| Identifier | Title | Keybind | -| -------------------- | ----------------- | ------------------ | -| `whim.updater.check` | Check for updates | No default keybind | +[!INCLUDE [Commands](../../_common/plugins/updater.md)] diff --git a/docs/docs/customize/scripting.md b/docs/script/scripting.md similarity index 94% rename from docs/docs/customize/scripting.md rename to docs/script/scripting.md index 453e4ae36..e20a38095 100644 --- a/docs/docs/customize/scripting.md +++ b/docs/script/scripting.md @@ -2,7 +2,7 @@ Whim uses the [Microsoft.CodeAnalysis.CSharp](https://learn.microsoft.com/en-us/dotnet/api/microsoft.codeanalysis.csharp) scripting engine to run your `.whim/whim.config.csx` file. -An example config file is created in your `.whim` directory when Whim is first run. +Various snippets can be found on the [Snippets](core/snippets.md) page. ## Directives @@ -44,4 +44,4 @@ The `DoConfig` function is returned at the end of the script so Whim can call it ### Examples -The rest of this _Customize_ section documents popular configuration options. A few more elaborate examples can be found in [Snippets](./snippets.md). +The rest of this _Customize_ section documents popular configuration options. A few more elaborate examples can be found in [Snippets](core/snippets.md). diff --git a/docs/script/toc.yml b/docs/script/toc.yml new file mode 100644 index 000000000..25aab8579 --- /dev/null +++ b/docs/script/toc.yml @@ -0,0 +1,38 @@ +items: + - href: scripting.md + + - name: Core + - href: core/store.md + - href: core/workspaces.md + - href: core/layout-engines.md + - href: core/monitors.md + - href: core/keybinds.md + - href: core/commands.md + - href: core/routing.md + - href: core/filtering.md + - href: core/styling.md + - href: core/logging.md + - href: core/snippets.md + + - name: Plugins + - href: plugins/overview.md + - href: plugins/bar.md + - href: plugins/command-palette.md + - href: plugins/floating-window.md + - href: plugins/focus-indicator.md + - href: plugins/gaps.md + - href: plugins/layout-preview.md + - href: plugins/slice-layout.md + - href: plugins/tree-layout.md + - href: plugins/tree-layout-bar.md + - href: plugins/tree-layout-command-palette.md + - href: plugins/updater.md + + - name: Architecture + - href: architecture/context.md + - href: architecture/result.md + - href: architecture/store.md + - href: architecture/layout-engines.md + - href: architecture/events.md + - href: architecture/native-apis.md + - href: architecture/deprecated.md diff --git a/docs/template/public/main.css b/docs/template/public/main.css index c99a05b82..e0eddcdca 100644 --- a/docs/template/public/main.css +++ b/docs/template/public/main.css @@ -13,8 +13,37 @@ color: var(--bs-secondary-color) !important; } +.nav-link:hover { + text-decoration: underline; +} + +.active { + color: rgba(var(--bs-link-color-rgb), var(--bs-link-opacity, 1)) !important; + text-decoration: underline; +} + .color-block { width: 1rem; height: 1rem; display: inline-block; } + +code { + background-color: var(--bs-border-color); + padding: 0.1rem 0.2rem; + border-radius: 0.25rem; +} + +pre code { + background-color: unset; + padding: unset; + border-radius: var(--bs-border-radius-lg); +} + +/* Make the table have rounded corners */ +table { + border-collapse: collapse; + border-spacing: 0; + width: 100%; + border-radius: var(--bs-border-radius-xl); +} diff --git a/docs/template/public/main.js b/docs/template/public/main.js index 24d63367d..b8eb5bbf9 100644 --- a/docs/template/public/main.js +++ b/docs/template/public/main.js @@ -61,6 +61,17 @@ export default { element.focus(); } + function changeSearchPlaceholder() { + const searchElement = document.getElementById("search-query"); + + if (searchElement === null) { + return; + } + + searchElement.placeholder = "Search /"; + } + document.addEventListener("keydown", listener); + changeSearchPlaceholder(); }, }; diff --git a/docs/toc.yml b/docs/toc.yml index 31411e0ff..ae224a1fc 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -1,4 +1,14 @@ -- name: Documentation - href: docs/ +- name: Introduction + href: intro/ + +- name: Configure + href: configure/ + +- name: Script + href: script/ + - name: API href: api/ + +- name: Contribute + href: contribute/