starred/komorebi
1
0
Fork 0
mirror of https://github.com/LGUG2Z/komorebi.git synced 2026-01-11 22:12:53 +01:00
Code Issues 87 Packages Projects Releases 10 Wiki Activity

docs(mkdocs): generate latest cli docs

Browse Source
This commit is contained in:
LGUG2Z
2024-10-16 09:14:00 -07:00
parent c0c3c81d69
commit 1ef7a09163
26 changed files with 153 additions and 334 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/cli/border-colour.md
View File

@@ -18,7 +18,7 @@ Arguments:
Options:
-w, --window-kind <WINDOW_KIND>
[default: single]
[possible values: single, stack, monocle, unfocused]
[possible values: single, stack, monocle, unfocused, floating]
-h, --help
Print help

16
docs/cli/convert-app-specific-configuration.md Normal file
View File

@@ -0,0 +1,16 @@
# convert-app-specific-configuration
```
Convert a v1 ASC YAML file to a v2 ASC JSON file
Usage: komorebic.exe convert-app-specific-configuration <PATH>
Arguments:
<PATH>
YAML file from which the application-specific configurations should be loaded
Options:
-h, --help
Print help
```

3
docs/cli/enable-autostart.md
View File

@@ -9,9 +9,6 @@ Options:
-c, --config <CONFIG>
Path to a static configuration JSON file
-f, --ffm
Enable komorebi's custom focus-follows-mouse implementation
--whkd
Enable autostart of whkd

23
docs/cli/focus-follows-mouse.md
View File

@@ -1,23 +0,0 @@
# focus-follows-mouse
```
Enable or disable focus follows mouse for the operating system
Usage: komorebic.exe focus-follows-mouse [OPTIONS] <BOOLEAN_STATE>
Arguments:
<BOOLEAN_STATE>
[possible values: enable, disable]
Options:
-i, --implementation <IMPLEMENTATION>
[default: windows]
Possible values:
- komorebi: A custom FFM implementation (slightly more CPU-intensive)
- windows: The native (legacy) Windows FFM implementation
-h, --help
Print help (see a summary with '-h')
```

2
docs/cli/format-app-specific-configuration.md
View File

@@ -1,7 +1,7 @@
# format-app-specific-configuration
```
Format a YAML file for use with the 'ahk-app-specific-configuration' command
Format a YAML file for use with the 'app-specific-configuration' command
Usage: komorebic.exe format-app-specific-configuration <PATH>

6
docs/cli/float-rule.md → docs/cli/ignore-rule.md
View File

@@ -1,9 +1,9 @@
# float-rule
# ignore-rule
```
Add a rule to always float the specified application
Add a rule to ignore the specified application
Usage: komorebic.exe float-rule <IDENTIFIER> <ID>
Usage: komorebic.exe ignore-rule <IDENTIFIER> <ID>
Arguments:
<IDENTIFIER>

16
docs/cli/load-custom-layout.md
View File

@@ -1,16 +0,0 @@
# load-custom-layout
```
Load a custom layout from file for the focused workspace
Usage: komorebic.exe load-custom-layout <PATH>
Arguments:
<PATH>
JSON or YAML file from which the custom layout definition should be loaded
Options:
-h, --help
Print help
```

22
docs/cli/named-workspace-custom-layout-rule.md
View File

@@ -1,22 +0,0 @@
# named-workspace-custom-layout-rule
```
Add a dynamic custom layout for the specified workspace
Usage: komorebic.exe named-workspace-custom-layout-rule <WORKSPACE> <AT_CONTAINER_COUNT> <PATH>
Arguments:
<WORKSPACE>
Target workspace name
<AT_CONTAINER_COUNT>
The number of window containers on-screen required to trigger this layout rule
<PATH>
JSON or YAML file from which the custom layout definition should be loaded
Options:
-h, --help
Print help
```

19
docs/cli/named-workspace-custom-layout.md
View File

@@ -1,19 +0,0 @@
# named-workspace-custom-layout
```
Set a custom layout for the specified workspace
Usage: komorebic.exe named-workspace-custom-layout <WORKSPACE> <PATH>
Arguments:
<WORKSPACE>
Target workspace name
<PATH>
JSON or YAML file from which the custom layout definition should be loaded
Options:
-h, --help
Print help
```

3
docs/cli/start.md
View File

@@ -6,9 +6,6 @@ Start komorebi.exe as a background process
Usage: komorebic.exe start [OPTIONS]
Options:
-f, --ffm
Allow the use of komorebi's custom focus-follows-mouse implementation
-c, --config <CONFIG>
Path to a static configuration JSON file

3
docs/cli/stop.md
View File

@@ -9,6 +9,9 @@ Options:
--whkd
Stop whkd if it is running as a background process
--ahk
Stop ahk if it is running as a background process
--bar
Stop komorebi-bar if it is running as a background process

12
docs/cli/toggle-float-override.md Normal file
View File

@@ -0,0 +1,12 @@
# toggle-float-override
```
Enable or disable float override, which makes it so every new window opens in floating mode
Usage: komorebic.exe toggle-float-override
Options:
-h, --help
Print help
```

19
docs/cli/toggle-focus-follows-mouse.md
View File

@@ -1,19 +0,0 @@
# toggle-focus-follows-mouse
```
Toggle focus follows mouse for the operating system
Usage: komorebic.exe toggle-focus-follows-mouse [OPTIONS]
Options:
-i, --implementation <IMPLEMENTATION>
[default: windows]
Possible values:
- komorebi: A custom FFM implementation (slightly more CPU-intensive)
- windows: The native (legacy) Windows FFM implementation
-h, --help
Print help (see a summary with '-h')
```

13
docs/cli/toggle-workspace-float-override.md Normal file
View File

@@ -0,0 +1,13 @@
# toggle-workspace-float-override
```
Enable or disable float override, which makes it so every new window opens in floating mode, for the currently focused workspace. If there was no override value set for the workspace
previously it takes the opposite of the global value
Usage: komorebic.exe toggle-workspace-float-override
Options:
-h, --help
Print help
```

13
docs/cli/toggle-workspace-window-container-behaviour.md Normal file
View File

@@ -0,0 +1,13 @@
# toggle-workspace-window-container-behaviour
```
Toggle the behaviour for new windows (stacking or dynamic tiling) for currently focused workspace. If there was no behaviour set for the workspace previously it takes the opposite of the
global value
Usage: komorebic.exe toggle-workspace-window-container-behaviour
Options:
-h, --help
Print help
```

25
docs/cli/workspace-custom-layout-rule.md
View File

@@ -1,25 +0,0 @@
# workspace-custom-layout-rule
```
Add a dynamic custom layout for the specified workspace
Usage: komorebic.exe workspace-custom-layout-rule <MONITOR> <WORKSPACE> <AT_CONTAINER_COUNT> <PATH>
Arguments:
<MONITOR>
Monitor index (zero-indexed)
<WORKSPACE>
Workspace index on the specified monitor (zero-indexed)
<AT_CONTAINER_COUNT>
The number of window containers on-screen required to trigger this layout rule
<PATH>
JSON or YAML file from which the custom layout definition should be loaded
Options:
-h, --help
Print help
```

22
docs/cli/workspace-custom-layout.md
View File

@@ -1,22 +0,0 @@
# workspace-custom-layout
```
Set a custom layout for the specified workspace
Usage: komorebic.exe workspace-custom-layout <MONITOR> <WORKSPACE> <PATH>
Arguments:
<MONITOR>
Monitor index (zero-indexed)
<WORKSPACE>
Workspace index on the specified monitor (zero-indexed)
<PATH>
JSON or YAML file from which the custom layout definition should be loaded
Options:
-h, --help
Print help
```

29
docs/common-workflows/autostart.md Normal file
View File

@@ -0,0 +1,29 @@
# Autostart
If you would like to autostart `komorebi`, you can use the `komorebic enable-autostart` command to generate a shortcut
in the `shell:startup` folder.
```
Generates the komorebi.lnk shortcut in shell:startup to autostart komorebi
Usage: komorebic.exe enable-autostart [OPTIONS]
Options:
-c, --config <CONFIG>
Path to a static configuration JSON file
-f, --ffm
Enable komorebi's custom focus-follows-mouse implementation
--whkd
Enable autostart of whkd
--ahk
Enable autostart of ahk
--bar
Enable autostart of komorebi-bar
-h, --help
Print help
```

70
docs/common-workflows/custom-layouts.md
View File

@@ -1,70 +0,0 @@
# Custom Layouts
Particularly for users of ultrawide monitors, traditional tiling layouts may
not seem like the most efficient use of screen space. If you feel this is the
case with any of the default layouts, you are also welcome to create your own
custom layouts and save them as JSON or YAML.
If you're not comfortable writing the layouts directly in JSON or YAML, you can
use the [komorebi Custom Layout
Generator](https://lgug2z.github.io/komorebi-custom-layout-generator/) to
interactively define a custom layout, and then copy the generated JSON content.
Custom layouts can be loaded on the current workspace or configured for a
specific workspace in the `komorebi.json` configuration file.
```json
{
"monitors": [
{
"workspaces": [
{
"name": "personal",
"custom_layout": "C:/Users/LGUG2Z/my-custom-layout.json"
},
]
}
]
}
```
The fundamental building block of a custom _komorebi_ layout is the Column.
Columns come in three variants:
- **Primary**: This is where your primary focus will be on the screen most of
the time. There must be exactly one Primary Column in any custom layout.
Optionally, you can specify the percentage of the screen width that you want
the Primary Column to occupy.
- **Secondary**: This is an optional column that can either be full height of
split horizontally into a fixed number of maximum rows. There can be any
number of Secondary Columns in a custom layout.
- **Tertiary**: This is the final column where any remaining windows will be
split horizontally into rows as they get added.
If there is only one window on the screen when a custom layout is selected,
that window will take up the full work area of the screen.
If the number of windows is equal to or less than the total number of columns
defined in a custom layout, the windows will be arranged in an equal-width
columns.
When the number of windows is greater than the number of columns defined in the
custom layout, the windows will begin to be arranged according to the
constraints set on the Primary and Secondary columns of the layout.
Here is an example custom layout that can be used as a starting point for your
own:
```yaml
- column: Secondary
configuration: !Horizontal 2 # max number of rows
- column: Primary
configuration: !WidthPercentage 50 # percentage of screen
- column: Tertiary
configuration: Horizontal
```
<!-- TODO: Record a new video -->
[![Watch the tutorial video](https://img.youtube.com/vi/SgmBHKEOcQ4/hqdefault.jpg)](https://www.youtube.com/watch?v=SgmBHKEOcQ4)

16
docs/common-workflows/floating-applications.md Normal file
View File

@@ -0,0 +1,16 @@
# Floating Windows
Sometimes you will want a specific application to be managed as a floating window.
You can add rules to enforce this behaviour in the `komorebi.json` configuration file.
```json
{
"floating_applications": [
{
"kind": "Title",
"id": "Media Player",
"matching_strategy": "Equals"
}
]
}
```

34
docs/common-workflows/focus-follows-mouse.md
View File

@@ -1,34 +0,0 @@
# Focus Follows Mouse
`komorebi` supports two focus-follows-mouse implementations; the native Windows
Xmouse implementation, which treats the desktop, the task bar, and the system
tray as windows and switches focus to them eagerly, and a custom `komorebi`
implementation, which only considers windows managed by `komorebi` as valid
targets to switch focus to when moving the mouse.
To enable the `komorebi` implementation you must start the process with the
`--ffm` flag to explicitly enable the feature. This is because the mouse
tracking required for this feature significantly increases the CPU usage of the
process (on my machine, it jumps from <1% to ~4~), and this CPU increase
persists regardless of whether focus-follows-mouse is enabled or disabled at
any given time via `komorebic`'s configuration commands.
If the `komorebi` process has been started with the `--ffm` flag, you can
enable focus follows mouse behaviour in the `komorebi.json` configuration file.
```json
{
"focus_follows_mouse": "Komorebi"
}
```
When calling any of the `komorebic` commands related to focus-follows-mouse
functionality, the `windows` implementation will be chosen as the default
implementation. You can optionally specify the `komorebi` implementation by
passing it as an argument to the `--implementation` flag:
```powershell
komorebic.exe toggle-focus-follows-mouse --implementation komorebi
```

4
docs/common-workflows/ignore-windows.md
View File

@@ -5,12 +5,12 @@ applications are [already generated for
you](https://github.com/LGUG2Z/komorebi-application-specific-configuration)
Sometimes you will want a specific application to never be tiled, and instead
float all the time. You can add rules to enforce this behaviour in the
be completely ignored. You can add rules to enforce this behaviour in the
`komorebi.json` configuration file.
```json
{
"float_rules": [
"ignore_rules": [
{
"kind": "Title",
"id": "Media Player",

19
docs/common-workflows/multiple-bar-instances.md Normal file
View File

@@ -0,0 +1,19 @@
# Multiple Bar Instances
If you would like to run multiple instances of `komorebi-bar` to target different monitors, it is possible to do so
by maintaining multiple `komorebi.bar.json` configuration files and specifying their paths in the `bar_configurations`
array in your `komorebi.json` configuration file.
```json
{
"bar_configurations": [
"C:/Users/LGUG2Z/komorebi.bar.monitor1.json",
"C:/Users/LGUG2Z/komorebi.bar.monitor2.json"
]
}
```
You may also use `$Env:USERPROFILE` or `$Env:KOMOREBI_CONFIG_HOME` when specifying the paths.
The main difference between different `komorebi.bar.json` files will be the value of `monitor.index` which is used to
target the monitor for each instance of `komorebi-bar`.

58
docs/release/v0-1-22.md
View File

@@ -1,58 +0,0 @@
# v0.1.22
In addition to the [changelog](https://github.com/LGUG2Z/komorebi/releases/tag/v0.1.22) of new features and fixes,
please note the following changes from `v0.1.21` to adjust your configuration files accordingly.
## tl;dr
The way windows are sized and drawn has been improved to remove the need to manually specify and remove invisible
borders for applications that overflow them. If you use the active window border, the first time you launch `v0.1.22`
you may end up with a _huge_ border due to these changes.
`active_window_border_width` and `active_window_border_offset` have been renamed to `border_width` and `border_offset`
as they now also apply outside the context of the active window border.
```json
{
"active_window_border": true,
"border_width": 8,
"border_offset": -1
}
```
Users of the active window border should start from these settings and read the notes below before making further
adjustments.
## Changes to `active_window_border`, and window sizing:
- The border no longer creates a second drop-shadow around the active window
- Windows are now sized to fill the layout region entirely, ignoring window decorations such as drop shadows
- Border offset now starts exactly at the paint edge of the window on all sides
- Windows are sized such that the border offset and border width are taken into account
## Recommended patterns
### Gapless
- Disable "transparency effects" Personalization > Colors
- Set the following settings in `komorebi.json`:
```json
{
"default_workspace_padding": 0,
"default_container_padding": 0,
"border_offset": -1,
"border_width": 0
}
```
### 1px border
A 1px border is drawn around the window edge. Users may see a gap for a single pixel, if the system theme has a
transparent edge - this is the windows themed edge, and is not present for all applications.
```json
{
"border_offset": 0,
"border_width": 1
}
```

16
komorebic/src/main.rs
View File

@@ -748,6 +748,7 @@ struct AnimationStyle {
#[allow(clippy::struct_excessive_bools)]
struct Start {
/// Allow the use of komorebi's custom focus-follows-mouse implementation
#[clap(hide = true)]
#[clap(short, long = "ffm")]
ffm: bool,
/// Path to a static configuration JSON file
@@ -865,6 +866,7 @@ struct EnableAutostart {
#[clap(action, short, long)]
config: Option<PathBuf>,
/// Enable komorebi's custom focus-follows-mouse implementation
#[clap(hide = true)]
#[clap(short, long = "ffm")]
ffm: bool,
/// Enable autostart of whkd
@@ -1098,6 +1100,7 @@ enum SubCommand {
#[clap(arg_required_else_help = true)]
CycleLayout(CycleLayout),
/// Load a custom layout from file for the focused workspace
#[clap(hide = true)]
#[clap(arg_required_else_help = true)]
LoadCustomLayout(LoadCustomLayout),
/// Flip the layout on the focused workspace (BSP only)
@@ -1142,9 +1145,11 @@ enum SubCommand {
#[clap(arg_required_else_help = true)]
NamedWorkspaceLayout(NamedWorkspaceLayout),
/// Set a custom layout for the specified workspace
#[clap(hide = true)]
#[clap(arg_required_else_help = true)]
WorkspaceCustomLayout(WorkspaceCustomLayout),
/// Set a custom layout for the specified workspace
#[clap(hide = true)]
#[clap(arg_required_else_help = true)]
NamedWorkspaceCustomLayout(NamedWorkspaceCustomLayout),
/// Add a dynamic layout rule for the specified workspace
@@ -1154,9 +1159,11 @@ enum SubCommand {
#[clap(arg_required_else_help = true)]
NamedWorkspaceLayoutRule(NamedWorkspaceLayoutRule),
/// Add a dynamic custom layout for the specified workspace
#[clap(hide = true)]
#[clap(arg_required_else_help = true)]
WorkspaceCustomLayoutRule(WorkspaceCustomLayoutRule),
/// Add a dynamic custom layout for the specified workspace
#[clap(hide = true)]
#[clap(arg_required_else_help = true)]
NamedWorkspaceCustomLayoutRule(NamedWorkspaceCustomLayoutRule),
/// Clear all dynamic layout rules for the specified workspace
@@ -1315,9 +1322,11 @@ enum SubCommand {
#[clap(arg_required_else_help = true)]
AnimationStyle(AnimationStyle),
/// Enable or disable focus follows mouse for the operating system
#[clap(hide = true)]
#[clap(arg_required_else_help = true)]
FocusFollowsMouse(FocusFollowsMouse),
/// Toggle focus follows mouse for the operating system
#[clap(hide = true)]
#[clap(arg_required_else_help = true)]
ToggleFocusFollowsMouse(ToggleFocusFollowsMouse),
/// Enable or disable mouse follows focus on all workspaces
@@ -1402,6 +1411,13 @@ fn main() -> Result<()> {
"docgen",
"alt-focus-hack",
"identify-border-overflow-application",
"load-custom-layout",
"workspace-custom-layout",
"named-workspace-custom-layout",
"workspace-custom-layout-rule",
"named-workspace-custom-layout-rule",
"focus-follows-mouse",
"toggle-focus-follows-mouse",
];
for cmd in subcommands {

22
mkdocs.yml
View File

@@ -57,6 +57,7 @@ nav:
- Troubleshooting: troubleshooting.md
- Common workflows:
- common-workflows/komorebi-config-home.md
- common-workflows/autostart.md
- common-workflows/animations.md
- common-workflows/autohotkey.md
- common-workflows/borders.md
@@ -64,14 +65,12 @@ nav:
- common-workflows/remove-gaps.md
- common-workflows/ignore-windows.md
- common-workflows/force-manage-windows.md
- common-workflows/floating-applications.md
- common-workflows/tray-and-multi-window-applications.md
- common-workflows/focus-follows-mouse.md
- common-workflows/mouse-follows-focus.md
- common-workflows/custom-layouts.md
- common-workflows/dynamic-layout-switching.md
- common-workflows/set-display-index.md
- Release notes:
- release/v0-1-22.md
- common-workflows/multiple-bar-instances.md
- Configuration reference: https://komorebi.lgug2z.com/schema
- Bar reference: https://komorebi-bar.lgug2z.com/schema
- CLI reference:
@@ -146,7 +145,6 @@ nav:
- cli/adjust-workspace-padding.md
- cli/change-layout.md
- cli/cycle-layout.md
- cli/load-custom-layout.md
- cli/flip-layout.md
- cli/promote.md
- cli/promote-focus.md
@@ -162,18 +160,17 @@ nav:
- cli/named-workspace-padding.md
- cli/workspace-layout.md
- cli/named-workspace-layout.md
- cli/workspace-custom-layout.md
- cli/named-workspace-custom-layout.md
- cli/workspace-layout-rule.md
- cli/named-workspace-layout-rule.md
- cli/workspace-custom-layout-rule.md
- cli/named-workspace-custom-layout-rule.md
- cli/clear-workspace-layout-rules.md
- cli/clear-named-workspace-layout-rules.md
- cli/workspace-tiling.md
- cli/named-workspace-tiling.md
- cli/workspace-name.md
- cli/toggle-window-container-behaviour.md
- cli/toggle-float-override.md
- cli/toggle-workspace-window-container-behaviour.md
- cli/toggle-workspace-float-override.md
- cli/toggle-pause.md
- cli/toggle-tiling.md
- cli/toggle-float.md
@@ -190,7 +187,7 @@ nav:
- cli/cross-monitor-move-behaviour.md
- cli/toggle-cross-monitor-move-behaviour.md
- cli/unmanaged-window-operation-behaviour.md
- cli/float-rule.md
- cli/ignore-rule.md
- cli/manage-rule.md
- cli/initial-workspace-rule.md
- cli/initial-named-workspace-rule.md
@@ -217,12 +214,11 @@ nav:
- cli/animation-duration.md
- cli/animation-fps.md
- cli/animation-style.md
- cli/focus-follows-mouse.md
- cli/toggle-focus-follows-mouse.md
- cli/mouse-follows-focus.md
- cli/toggle-mouse-follows-focus.md
- cli/ahk-app-specific-configuration.md
- cli/pwsh-app-specific-configuration.md
- cli/convert-app-specific-configuration.md
- cli/format-app-specific-configuration.md
- cli/fetch-app-specific-configuration.md
- cli/application-specific-configuration-schema.md
@@ -231,4 +227,4 @@ nav:
- cli/static-config-schema.md
- cli/generate-static-config.md
- cli/enable-autostart.md
- cli/disable-autostart.md
- cli/disable-autostart.md