Upstream/waveterm
1
0
Fork 0
mirror of https://github.com/wavetermdev/waveterm.git synced 2025-01-02 18:39:05 +01:00
Code Issues Packages Projects Releases Wiki Activity

Add a document detailing the layout system (#1232)

Browse Source
This commit is contained in:
Evan Simkowitz 2024-11-08 11:00:50 -08:00 committed by GitHub
parent 8c17269c88
commit cd0e2949ee
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
8 changed files with 198 additions and 112 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

224
docs/docs/config.mdx
View File

@ -8,143 +8,143 @@ Wave's configuration files are located at `~/.config/waveterm/`.
The main configuration file is `settings.json` (`~/.config/waveterm/settings.json`).
The file is structured as a mostly flat JSON file. Instead of using sub-objects we prefer to
The file is structured as a mostly flat JSON file. Instead of using sub-objects we prefer to
use ":" as level separators.
:::info
If you installed Wave pre-v0.9.0 your configuration file will be located at
`~/.waveterm/config/settings.json`. This includes all of the other configuration
`~/.waveterm/config/settings.json`. This includes all of the other configuration
files as well: `termthemes.json`, `presets.json`, and `widgets.json`.
:::
| Key Name | Type | Function |
|----------|------|----------|
| ai:preset | string | the default AI preset to use |
| ai:baseurl | string | Set the AI Base Url (must be OpenAI compatible) |
| ai:apitoken | string | your AI api token |
| ai:apitype | string | defaults to "open_ai", but can also set to "azure" for special Azure AI handling |
| ai:name | string | string to display in the Wave AI block header |
| ai:model | string | model name to pass to API |
| ai:apiversion | string | for Azure AI only (when apitype is "azure", this will default to "2023-05-15") |
| ai:orgid | string ||
| ai:maxtokens | int | max tokens to pass to API |
| ai:timeoutms | int | timeout (in milliseconds) for AI calls |
| conn:askbeforewshinstall | bool | set to false to disable popup asking if you want to install wsh extensions on new machines |
| term:fontsize | float | the fontsize for the terminal block |
| term:fontfamily | string | font family to use for terminal block |
| term:disablewebgl | bool | set to false to disable WebGL acceleration in terminal |
| term:localshellpath | string | set to override the default shell path for local terminals |
| term:localshellopts | string[] | set to pass additional parameters to the term:localshellpath |
| term:copyonselect | bool | set to false to disable terminal copy-on-select |
| editor:minimapenabled | bool | set to false to disable editor minimap |
| editor:stickscrollenabled | bool | |
| web:openlinksinternally | bool | set to false to open web links in external browser |
| web:defaulturl | string | default web page to open in the web widget when no url is provided (homepage) |
| web:defaultsearch | string | search template for web searches. e.g. `https://www.google.com/search?q={query}`. "\{query}" gets replaced by search term |
| blockheader:showblockids | bool | show first 8 chars of blockid in the header |
| autoupdate:enabled | bool | enable/disable checking for updates (requires app restart) |
| autoupdate:intervalms | float64 | time in milliseconds to wait between update checks (requires app restart) |
| autoupdate:installonquit | bool | whether to automatically install updates on quit (requires app restart) |
| autoupdate:channel | string | the auto update channel "latest" (stable builds), or "beta" (updated more frequently) (requires app restart) |
| widget:showhelp | bool | whether to show help/tips widgets in right sidebar |
| window:transparent | bool | set to true to enable window transparency (cannot be combined with `window:blur`) (macOS and Windows only, requires app restart, see [note on Windows compatibility](https://www.electronjs.org/docs/latest/tutorial/window-customization#limitations)) |
| window:blur | bool | set to enable window background blurring (cannot be combined with `window:transparent`) (macOS and Windows only, requires app restart, see [note on Windows compatibility](https://www.electronjs.org/docs/latest/tutorial/window-customization#limitations)) |
| window:opacity | float64 | 0-1, window opacity when `window:transparent` or `window:blur` are set |
| window:bgcolor | string | set the window background color (should be hex: #xxxxxx) |
| window:reducedmotion | bool | set to true to disable most animations |
| window:tilegapsize | int | set to change override default gap between blocks |
| window:showmenubar | bool | set to use the OS-native menu bar (Windows and Linux only, requires app restart) |
| window:nativetitlebar | bool | set to use the OS-native title bar, rather than the overlay (Windows and Linux only, requires app restart) |
| window:disablehardwareacceleration | bool | set to disable Chromium hardware acceleration to resolve graphical bugs (requires app restart) |
| telemetry:enabled | bool | set to enable/disable telemetry |
| Key Name | Type | Function |
| ---------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ai:preset | string | the default AI preset to use |
| ai:baseurl | string | Set the AI Base Url (must be OpenAI compatible) |
| ai:apitoken | string | your AI api token |
| ai:apitype | string | defaults to "open_ai", but can also set to "azure" for special Azure AI handling |
| ai:name | string | string to display in the Wave AI block header |
| ai:model | string | model name to pass to API |
| ai:apiversion | string | for Azure AI only (when apitype is "azure", this will default to "2023-05-15") |
| ai:orgid | string | |
| ai:maxtokens | int | max tokens to pass to API |
| ai:timeoutms | int | timeout (in milliseconds) for AI calls |
| conn:askbeforewshinstall | bool | set to false to disable popup asking if you want to install wsh extensions on new machines |
| term:fontsize | float | the fontsize for the terminal block |
| term:fontfamily | string | font family to use for terminal block |
| term:disablewebgl | bool | set to false to disable WebGL acceleration in terminal |
| term:localshellpath | string | set to override the default shell path for local terminals |
| term:localshellopts | string[] | set to pass additional parameters to the term:localshellpath |
| term:copyonselect | bool | set to false to disable terminal copy-on-select |
| editor:minimapenabled | bool | set to false to disable editor minimap |
| editor:stickscrollenabled | bool | |
| web:openlinksinternally | bool | set to false to open web links in external browser |
| web:defaulturl | string | default web page to open in the web widget when no url is provided (homepage) |
| web:defaultsearch | string | search template for web searches. e.g. `https://www.google.com/search?q={query}`. "\{query}" gets replaced by search term |
| blockheader:showblockids | bool | show first 8 chars of blockid in the header |
| autoupdate:enabled | bool | enable/disable checking for updates (requires app restart) |
| autoupdate:intervalms | float64 | time in milliseconds to wait between update checks (requires app restart) |
| autoupdate:installonquit | bool | whether to automatically install updates on quit (requires app restart) |
| autoupdate:channel | string | the auto update channel "latest" (stable builds), or "beta" (updated more frequently) (requires app restart) |
| widget:showhelp | bool | whether to show help/tips widgets in right sidebar |
| window:transparent | bool | set to true to enable window transparency (cannot be combined with `window:blur`) (macOS and Windows only, requires app restart, see [note on Windows compatibility](https://www.electronjs.org/docs/latest/tutorial/window-customization#limitations)) |
| window:blur | bool | set to enable window background blurring (cannot be combined with `window:transparent`) (macOS and Windows only, requires app restart, see [note on Windows compatibility](https://www.electronjs.org/docs/latest/tutorial/window-customization#limitations)) |
| window:opacity | float64 | 0-1, window opacity when `window:transparent` or `window:blur` are set |
| window:bgcolor | string | set the window background color (should be hex: #xxxxxx) |
| window:reducedmotion | bool | set to true to disable most animations |
| window:tilegapsize | int | set to change override default gap size (in CSS pixels) between blocks |
| window:showmenubar | bool | set to use the OS-native menu bar (Windows and Linux only, requires app restart) |
| window:nativetitlebar | bool | set to use the OS-native title bar, rather than the overlay (Windows and Linux only, requires app restart) |
| window:disablehardwareacceleration | bool | set to disable Chromium hardware acceleration to resolve graphical bugs (requires app restart) |
| telemetry:enabled | bool | set to enable/disable telemetry |
For reference this is the current default configuration (v0.8.8):
```json
{
"ai:preset": "ai@global",
"ai:model": "gpt-4o-mini",
"ai:maxtokens": 2048,
"ai:timeoutms": 60000,
"autoupdate:enabled": true,
"autoupdate:installonquit": true,
"autoupdate:intervalms": 3600000,
"conn:askbeforewshinstall": true,
"editor:minimapenabled": true,
"web:defaulturl": "https://github.com/wavetermdev/waveterm",
"web:defaultsearch": "https://www.google.com/search?q={query}",
"window:tilegapsize": 3,
"telemetry:enabled": true,
"term:copyonselect": true
"ai:preset": "ai@global",
"ai:model": "gpt-4o-mini",
"ai:maxtokens": 2048,
"ai:timeoutms": 60000,
"autoupdate:enabled": true,
"autoupdate:installonquit": true,
"autoupdate:intervalms": 3600000,
"conn:askbeforewshinstall": true,
"editor:minimapenabled": true,
"web:defaulturl": "https://github.com/wavetermdev/waveterm",
"web:defaultsearch": "https://www.google.com/search?q={query}",
"window:tilegapsize": 3,
"telemetry:enabled": true,
"term:copyonselect": true
}
```
### Terminal Theming
User-defined terminal themes are located in `~/.config/waveterm/termthemes.json`. This JSON file is structured as an object, with each sub-key defining a theme.
Themes are applied by right-clicking on the terminal's header bar and selecting an entry from the "Themes" sub-menu. Alternatively they can be applied to
the block's metadata key `term:theme`. This uses the JSON key value as the identifier. Note, for best consistency all colors should be of the format "#rrggbb" or "#rrggbbaa" (aa = alpha channel for transparency).
User-defined terminal themes are located in `~/.config/waveterm/termthemes.json`. This JSON file is structured as an object, with each sub-key defining a theme.
Themes are applied by right-clicking on the terminal's header bar and selecting an entry from the "Themes" sub-menu. Alternatively they can be applied to
the block's metadata key `term:theme`. This uses the JSON key value as the identifier. Note, for best consistency all colors should be of the format "#rrggbb" or "#rrggbbaa" (aa = alpha channel for transparency).
`wsh setmeta this term:theme="default-dark"`
Here is an example of defining a full terminal theme. All of the built-in themes are defined here: https://github.com/wavetermdev/waveterm/blob/main/pkg/wconfig/defaultconfig/termthemes.json (if you'd like to add a popular terminal theme, please submit a PR!)
Here is an example of defining a full terminal theme. All of the built-in themes are defined here: https://github.com/wavetermdev/waveterm/blob/main/pkg/wconfig/defaultconfig/termthemes.json (if you'd like to add a popular terminal theme, please submit a PR!)
```json
{
"default-dark": {
"display:name": "Default Dark",
"display:order": 1,
"black": "#757575",
"red": "#cc685c",
"green": "#76c266",
"yellow": "#cbca9b",
"blue": "#85aacb",
"magenta": "#cc72ca",
"cyan": "#74a7cb",
"white": "#c1c1c1",
"brightBlack": "#727272",
"brightRed": "#cc9d97",
"brightGreen": "#a3dd97",
"brightYellow": "#cbcaaa",
"brightBlue": "#9ab6cb",
"brightMagenta": "#cc8ecb",
"brightCyan": "#b7b8cb",
"brightWhite": "#f0f0f0",
"gray": "#8b918a",
"cmdtext": "#f0f0f0",
"foreground": "#c1c1c1",
"selectionBackground": "",
"background": "#00000077",
"cursorAccent": ""
}
"default-dark": {
"display:name": "Default Dark",
"display:order": 1,
"black": "#757575",
"red": "#cc685c",
"green": "#76c266",
"yellow": "#cbca9b",
"blue": "#85aacb",
"magenta": "#cc72ca",
"cyan": "#74a7cb",
"white": "#c1c1c1",
"brightBlack": "#727272",
"brightRed": "#cc9d97",
"brightGreen": "#a3dd97",
"brightYellow": "#cbcaaa",
"brightBlue": "#9ab6cb",
"brightMagenta": "#cc8ecb",
"brightCyan": "#b7b8cb",
"brightWhite": "#f0f0f0",
"gray": "#8b918a",
"cmdtext": "#f0f0f0",
"foreground": "#c1c1c1",
"selectionBackground": "",
"background": "#00000077",
"cursorAccent": ""
}
}
```
| Key Name | Type | ANSI FG# | ANSI BG# | Function |
|----------|------|----------|----------|----------|
| display:name | string ||| the name as it will appear in the UI context menu |
| display:order | float ||| entries in the context menu are sorted by display:order |
| black | CSS color | 30 | 40 | color for black |
| red | CSS color | 31 | 41 | color for red |
| green | CSS color | 32 | 42 | color for green |
| yellow | CSS color | 33 | 43 | color for yellow |
| blue | CSS color | 34 | 44 | color for blue |
| magenta | CSS color | 35 | 45 | color for magenta |
| cyan | CSS color | 36 | 46 | color for cyan |
| white | CSS color | 37 | 47 | color for white |
| brightBlack | CSS color | 90 | 100 | color for bright black |
| brightRed | CSS color | 91 | 101 | color for bright red |
| brightGreen | CSS color | 92 | 102 | color for bright green |
| brightYellow | CSS color | 93 | 103 | color for bright yellow |
| brightBlue | CSS color | 94 | 104 | color for bright blue |
| brightMagenta | CSS color | 95 | 105 | color for bright magenta |
| brightCyan | CSS color | 96 | 106 | color for bright cyan |
| brightWhite | CSS color | 97 | 107 | color for bright white |
| gray | CSS color ||| currently unused |
| cmdtext | CSS color ||| currently unused |
| foreground | CSS color ||| foreground color (default when no color code is applied) |
| background | CSS color ||| background color (default when no color code is applied), must have alpha channel (#rrggbbaa) if you want the terminal to be transparent |
| cursorAccent | CSS color ||| color for cursor |
| selectionBackground | CSS color ||| background color for selected text |
| Key Name | Type | ANSI FG# | ANSI BG# | Function |
| ------------------- | --------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| display:name | string | | | the name as it will appear in the UI context menu |
| display:order | float | | | entries in the context menu are sorted by display:order |
| black | CSS color | 30 | 40 | color for black |
| red | CSS color | 31 | 41 | color for red |
| green | CSS color | 32 | 42 | color for green |
| yellow | CSS color | 33 | 43 | color for yellow |
| blue | CSS color | 34 | 44 | color for blue |
| magenta | CSS color | 35 | 45 | color for magenta |
| cyan | CSS color | 36 | 46 | color for cyan |
| white | CSS color | 37 | 47 | color for white |
| brightBlack | CSS color | 90 | 100 | color for bright black |
| brightRed | CSS color | 91 | 101 | color for bright red |
| brightGreen | CSS color | 92 | 102 | color for bright green |
| brightYellow | CSS color | 93 | 103 | color for bright yellow |
| brightBlue | CSS color | 94 | 104 | color for bright blue |
| brightMagenta | CSS color | 95 | 105 | color for bright magenta |
| brightCyan | CSS color | 96 | 106 | color for bright cyan |
| brightWhite | CSS color | 97 | 107 | color for bright white |
| gray | CSS color | | | currently unused |
| cmdtext | CSS color | | | currently unused |
| foreground | CSS color | | | foreground color (default when no color code is applied) |
| background | CSS color | | | background color (default when no color code is applied), must have alpha channel (#rrggbbaa) if you want the terminal to be transparent |
| cursorAccent | CSS color | | | color for cursor |
| selectionBackground | CSS color | | | background color for selected text |

BIN
docs/docs/img/block-drag-example.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 206 KiB

BIN
docs/docs/img/drag-edge.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 717 KiB

BIN
docs/docs/img/drag-swap.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 709 KiB

BIN
docs/docs/img/node-resize.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 299 KiB

1
docs/docs/index.mdx
View File

@ -26,6 +26,7 @@ References:
- [Key Bindings](./keybindings)
- [wsh command](./wsh)
- [Connections](./connections)
- [Tab Layout System](./layout)
- [Custom Widgets](./customwidgets)
- [Telemetry](./telemetry)
- [FAQ](./faq)

81
docs/docs/layout.mdx Normal file
View File

@ -0,0 +1,81 @@
---
sidebar_position: 2
id: "layout"
title: "Tab Layout System"
---
import { PlatformProvider, PlatformToggleButton } from "@site/src/components/platformcontext.tsx";
import { Kbd } from "@site/src/components/kbd.tsx";
<PlatformProvider>
<PlatformToggleButton/>
![screenshot showing a block being dragged over another block, with the placeholder depicting a out-of-line before outer drop](./img/drag-edge.png)
## Layout system under the hood
:::info
**Definitions**
- Layout tree: the in-memory representation of a tab layout, comprised of nodes
- Node: An entry in the layout tree, either a single block (a leaf) or an ordered list of nodes. Defines a tiling direction (row or column) and a unitless size
- Block: The contents of a leaf in the layout tree, defines what contents is displayed at the given layout location
:::
Our layout system emulates the [CSS Flexbox](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_flexible_box_layout/Basic_concepts_of_flexbox) system, comprising of a tree of columns and rows. Under the hood, the layout is represented as an n-tree, where each node in the tree is either a single block, or a list of nodes. Each level in the tree alternates the direction in which it tiles (level 1 tiles as a row, level 2 as a column, level 3 as a row, etc.).
## Layout actions
### Add a new block
You can add new blocks by selecting a widget from the right sidebar.
Starting at the topmost level of the tree, since the first level tiles as a row, new blocks will be added to the right side of existing blocks. Once there are 5 blocks across, new blocks will begin being added below existing blocks, starting from the right side and working to the left. As a new block gets added below an existing one, the node containing the existing block is converted from a single-block node to a list node and the existing block definition is moved one level deeper in the tree as the first element of the node list. New blocks will always be added to the last-available node in the deepest level, where available is defined as having less than five children. We don't set a limit on the number of blocks in a tab, but you may experience degraded performance past around 25 blocks.
While we define a 5-child limit for each node in the tree when automatically placing new blocks, there is no actual limit to the number of children a node can hold. After the block is placed, you are free to move it wherever in the layout
### Delete a block
You can delete blocks by clicking the <i className="fa-sharp fa-xmark-large"/> button in the top-right corner of the block, by right-clicking on the block header and selecting "Close Block" from the context menu, or by running the [`wsh deleteblock` command](./wsh#deleteblock). Alternatively, the currently focused block/widget can be closed by pressing <Kbd k="Cmd:w"/>
When you delete a block, the layout tree will be automatically adjusted to minimize the tree depth.
### Move a block
You can move blocks by clicking on the block header and dragging the block around the tab. You will see placeholders appear to show where the block will land when you drop it.
There are 7 different drop targets for any given block. A block is divided into quadrants along its diagonals. If the block is tiling as a row (left-to-right), dropping a block into the left or right quadrant will place the dropped block in the same level as the targeted block. This can be considered dropping the block inline. If you drop the block out of line (in quadrants corresponding to opposite tiling direction), the block will either be placed one level above or one level below the targeted block. Dropping the block towards the outside will place it in the same level as the target block's parent, while dropping it towards the center of the block will create a new level, where both the target block and the dropped block will be moved. The middle fifth of the block is reserved for the swap action. Dropping a block here will cause the target block and the dropped block to swap positions in the layout.
![screenshot showing a block being dragged over another block, with the placeholder depicting a swap movement](./img/drag-swap.png)
#### Possible block movements
:::note
All block movements except for Swap will cause the rest of the layout to shift to accommodate the block's new displacement.
:::
![annotated example showing the drop targets within a block](./img/block-drag-example.jpg)
1. Inline before: Drops the block under the same node as the target block, placing it before the target in the same tiling direction
2. Inline after: Drops the block under the same node as the target block, placing it after the target in the same tiling direction
3. Out-of-line before outer: Drops the block before the target block's parent node in the opposite tiling direction
4. Out-of-line before inner: Segments the target block, creating a new node in the tree. Places the dropped block before the target block in the opposite tiling direction.
5. Out-of-line after inner: Segments the target block, creating a new node in the tree. Places the dropped block after the target block in the opposite tiling direction.
6. Out-of-line after outer: Drops the block after the target block's parent node in the opposite tiling direction
7. Swap: Swaps the position of the dropped block and the targeted block in the layout, preserving the rest of the layout
### Resize a block
![screenshot showing the line that appears when the cursor hovers over the margin of a block, indicating which blocks will be resized by dragging the margin](./img/node-resize.png)
You do not directly resize a block. Rather, you resize the nodes containing the blocks. If you hover your mouse over the margin of a block, you will see the cursor change to <i className="fa-sharp fa-arrows-left-right"/> or <i className="fa-sharp fa-arrows-up-down"/> to indicate the direction the node can be resized. You will also see a line appear after 500ms to show you how many blocks will be resized by moving that margin. Clicking and dragging on this margin will cause the block(s) to get resized.
Node sizes are unitless values. The ratio of all node sizes at a given tree level determines the displacement of each node. If you move a block and its node is deleted, the other nodes at the given tree level will adjust their sizes to account for the new size ratio.
## Change the gap size between blocks
The gap between blocks defaults to 3px, but this value can be changed by modifying the `window:tilegapsize` configuration value. See [Configuration](./config) for more information on how to change configuration values.
</PlatformProvider>

4
docs/docs/widgets.mdx
View File

@ -35,10 +35,14 @@ Magnifying a widget will pop the widget out in front of everything else. You can
By dragging and dropping their headers, widgets can be moved to different locations in the layout. This effectively allows you to reorganize your screen however you see fit. When dragging, you will see a preview of the widget that is being dragged. When the widget is over a valid drop point, the area where it would be moved to will turn green. Releasing the click will place the widget there and reflow the other widgets around it. If you see a green box cover half of two different widgets, the drop will place the widget between the two. If you see the green box cover half of one widget at the edge of the screen, the widget will be placed between that widget and the edge of the screen. If you see the green box cover one widget entirely, the two widgets will swap locations.
See [Tab Layout System](./layout#move-a-block) for more information.
### How to Resize Widgets
Hovering the mouse between two widgets changes your cursor to <i className="fa-sharp fa-arrows-left-right"/> or <i className="fa-sharp fa-arrows-up-down"/>; and reveals a green line dividing the widgets. By dragging and dropping this green line, you are able to resize the widgets adjacent to it.
See [Tab Layout System](./layout#resize-a-block) for more information.
## Types of Widgets
### Term