Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

A BUNCH of docs for 1.19 #712

Merged
merged 5 commits into from
Sep 28, 2023
Merged

A BUNCH of docs for 1.19 #712

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
793bb07
like, a BUNCH of docs
zadjii-msft Sep 26, 2023
21436bd
GIFS. Everybody loves gifs. Do ogres love gifs?
zadjii-msft Sep 26, 2023
45c61b1
this whole court is external
zadjii-msft Sep 26, 2023
18e6ad4
more. More. MORE
zadjii-msft Sep 26, 2023
10dbfd4
hey I just had this laying aroung
zadjii-msft Sep 26, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
166 changes: 130 additions & 36 deletions TerminalDocs/customize-settings/actions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -581,6 +581,70 @@ This command moves the tab "backward" and "forward", which is equivalent to "lef
| ---- | --------- | ------- | ----------- |
| `direction` | Required | `"backward"`, `"forward"` | Direction in which the tab will move. |


### Broadcast input

This command will toggle "broadcast mode" for a pane. When broadcast mode is enabled, all input sent to the pane will be sent to all panes in the same tab. This is useful for sending the same input to multiple panes at once.

**Command name:** `toggleBroadcastInput`

**Default binding:**

```json
{ "command": "toggleBroadcastInput" }
```

> [!IMPORTANT]
> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).

### Open context menu

This command will open the "right-click" context menu for the active pane. This menu has context-relevant actions for managing panes, copying and pasting, and more. This action does not require the `experimental.rightClickContextMenu` setting to be enabled.

**Command name:** `showContextMenu`

**Default binding:**

```json
{ "command": "showContextMenu" }
```

### Open about dialog

This command will open the about dialog for the terminal. This dialog contains information about the terminal, including the version number, the license, and more.

**Command name:** `openAbout`

**Default binding:**

```json
{ "command": "openAbout" }
```

> [!IMPORTANT]
> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).

### Search the web

Attempts to open a browser window with a search for the selected text. This does nothing if there's no text selected. If the `queryUrl` parameter is not provided, the `searchWebDefaultQueryUrl` setting will be used instead. If the `queryUrl` parameter is provided, a `%s` in the string will be replaced by the selected text.

**Command name:** `searchWeb`

**Default binding:**

```json
{ "command": { "action": "searchWeb" } },
```

#### Parameters

| Name | Necessity | Accepts | Description |
| ---- | --------- | ------- | ----------- |
| `queryUrl` | Required | String | URL to use to search with. A `%s` in this string will be replaced by the selected text. If omitted, will default to the `searchWebDefaultQueryUrl` setting. |

> [!IMPORTANT]
> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).

<br />

___
Expand Down Expand Up @@ -882,43 +946,20 @@ You can disable read-only mode on a pane. This works similarly to toggling, howe
> [!IMPORTANT]
> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
zadjii-msft marked this conversation as resolved.
Show resolved Hide resolved

### Split a pane
zadjii-msft marked this conversation as resolved.
Show resolved Hide resolved
### Restart a pane

This halves the size of the active pane and opens another. Without any arguments, this will open the default profile in the new pane. If an action is not specified, the default profile's equivalent setting will be used.
This command will manually restart the `commandline` in the active pane. This is especially useful for scenarios like `ssh`, where you might want to restart a connection without closing the pane.

**Command name:** `splitPane`
Note that this will terminate the process in the pane, if it is currently running.

**Default bindings:**
**Command name:** `restartConnection`

```json
// In settings.json
{ "command": { "action": "splitPane", "split": "auto", "splitMode": "duplicate" }, "keys": "alt+shift+d" },
**Default binding:**

// In defaults.json
{ "command": { "action": "splitPane", "split": "horizontal" }, "keys": "alt+shift+-" },
{ "command": { "action": "splitPane", "split": "vertical" }, "keys": "alt+shift+plus" },
{ "command": { "action": "splitPane", "split": "up" } },
{ "command": { "action": "splitPane", "split": "right" } },
{ "command": { "action": "splitPane", "split": "down" } },
{ "command": { "action": "splitPane", "split": "left" } }
```json
{ "command": "restartConnection" }
```

#### Parameters

| Name | Necessity | Accepts | Description |
| ---- | --------- | ------- | ----------- |
| `split` | Required | `"vertical"`, `"horizontal"`, `"auto"`, `"up"`, `"right"`, `"down"`, `"left"` | How the pane will split. `"auto"` will split in the direction that provides the most surface area. |
| `commandline` | Optional | Executable file name as a string | Executable run within the pane. |
| `startingDirectory` | Optional | Folder location as a string | Directory in which the pane will open. |
| `elevate` | Optional | `true`, `false`, `null` | Overrides the [`elevate`](./profile-general.md#automatically-run-as-administrator) property of the profile. When omitted, this action will behave according to the profile's `elevate` setting. When set to `true` or `false`, this action will behave as though the profile was set with `"elevate": true` or `"elevate": false` (respectively). |
| `tabTitle` | Optional | String | Title of the tab when the new pane is focused. |
| `index` | Optional | Integer | Profile that will open based on its position in the dropdown (starting at 0). |
| `profile` | Optional | Profile's name or GUID as a string | Profile that will open based on its GUID or name. |
| `colorScheme` | Optional | The name of a color scheme as a string | The scheme to use instead of the profile's set `colorScheme` |
| `suppressApplicationTitle` | Optional | `true`, `false` | When set to `false`, applications can change the tab title by sending title change messages. When set to `true`, these messages are suppressed. If not provided, the behavior is inherited from the profile's settings. |
| `splitMode` | Optional | `"duplicate"` | Controls how the pane splits. Only accepts `"duplicate"`, which will duplicate the focused pane's profile into a new pane. |
| `size` | Optional | Float | Specify how large the new pane should be, as a fraction of the current pane's size. `1.0` would be "all of the current pane", and `0.0` is "None of the parent". Defaults to `0.5`. |

<br />

___
Expand Down Expand Up @@ -1003,7 +1044,7 @@ This toggles mark mode. Mark mode is a mode where you can use the keyboard to cr
{ "command": "markMode", "keys": "ctrl+shift+m" },
```

### Switch selection marker
### Switch selection marker

When modifying a selection using the keyboard, you are moving one end of the selection around. You can use this action to switch to the other selection marker.

Expand Down Expand Up @@ -1136,6 +1177,8 @@ This action can be used to manually clear the terminal buffer. This is useful fo
| ---- | --------- | ------- | ----------- |
| `clear` | Optional | `"screen"`, `"scrollback"`, `"all"` | What part of the screen to clear. <ul><li>`"screen"`: Clear the terminal viewport content. Leaves the scrollback untouched. Moves the cursor row to the top of the viewport (unmodified).</li><li>`"scrollback"`: Clear the scrollback. Leaves the viewport untouched.</li><li>`"all"` (_default_): Clear the scrollback and the visible viewport. Moves the cursor row to the top of the viewport. </li></ul> |


<br />
___

## Visual adjustment commands
Expand Down Expand Up @@ -1247,7 +1290,7 @@ Adds a scroll mark to the text buffer. If there's a selection, the mark is place
{ "command": { "action": "addMark", "color": "#ff00ff" } }
```

### Experimental scroll to mark
### Experimental scroll to mark

Scrolls to the scroll mark in the given direction. This is an experimental feature, and its continued existence is not guaranteed.

Expand All @@ -1265,7 +1308,7 @@ Scrolls to the scroll mark in the given direction. This is an experimental featu
{ "command": { "action": "scrollToMark", "direction": "previous" } }
```

### Experimental clear mark
### Experimental clear mark

Clears scroll mark at the current position, either at a selection if there is one or at the cursor position. This is an experimental feature, and its continued existence is not guaranteed.

Expand All @@ -1277,7 +1320,7 @@ Clears scroll mark at the current position, either at a selection if there is on
{ "command": { "action": "clearMark" } }
```

### Experimental clear all marks
### Experimental clear all marks

Clears all scroll marks in the text buffer. This is an experimental feature, and its continued existence is not guaranteed.

Expand All @@ -1288,8 +1331,57 @@ Clears all scroll marks in the text buffer. This is an experimental feature, and
```json
{ "command": { "action": "clearAllMarks" } }
```

<br />
___

## Suggestions

### Open suggestions menu

:::row:::
:::column span="":::

This allows the user to open the suggestions menu. The entries in the suggestions menu are controlled by the `source` property. The suggestions menu behaves much like the command palette. Typing in the text box will filter the results to only show entries that match the text. Pressing `enter` will execute the selected entry. Pressing `esc` will close the menu.

:::column-end:::
:::column span="":::

![Suggestions UI](../images/SuggestionsUI.gif)

:::column-end:::
:::row-end:::

**Command name:** `openSuggestions`

#### Parameters

| Name | Necessity | Accepts | Description |
| ---- | --------- | ------- | ----------- |
| `source` | Required | any number of `"recentCommands"`, `"tasks"`, or `"all"` | Which suggestion sources to use to populate this menu. See below for a description of each. |
| `useCommandline` | Optional | Boolean | If [shell integration](./../tutorials/shell-integration.md) is enabled, and this is `true`, the suggestions menu will be pre-populated with the contents of the current commandline. Defaults to `true` |

#### Suggestion sources

The following suggestion sources are supported:

* `"recentCommands"`: This will populate the suggestions menu with the most recently used commands. These are powered by shell integration, so they will only be available if you have your shell configured to support shell integration. See [Shell Integration](./../tutorials/shell-integration.md) for more information.
* `"tasks"`: This will populate the suggestions menu with all of the `sendInput` actions from your settings.
* `"all"`: Use all suggestion sources.

These values can be used by themselves as a string parameter value, or combined as an array. For example:
```json
{ "command": { "action": "openSuggestions", "source": ["recentCommands", "tasks"] } },
{ "command": { "action": "openSuggestions", "source": "all" } },
{ "command": { "action": "openSuggestions", "source": "recentCommands" } },
```

In the above example, the first two commands will open the suggestions menu with both recent commands and tasks. The third command will open the suggestions menu with only recent commands.

> [!IMPORTANT]
> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).

<br />
___

## Buffer exporting
Expand All @@ -1312,6 +1404,8 @@ This allows the user to export the text of the buffer to a file. If the file doe
| ---- | --------- | ------- | ----------- |
| `path` | Optional | String | If provided, then the Terminal will export the buffer contents to the given file. Otherwise, the terminal will open a file picker to choose the file to export to. |


<br />
___

## Global commands
Expand Down Expand Up @@ -1442,7 +1536,7 @@ ___

## Run multiple actions

This action allows the user to bind multiple sequential actions to one command.
This action allows the user to bind multiple sequential actions to one command.

**Command name:** `multipleActions`

Expand All @@ -1455,7 +1549,7 @@ This action allows the user to bind multiple sequential actions to one command.
#### Example

```jsonc
{ "name": "Create My Layout", "command": {
{ "name": "Create My Layout", "command": {
"action": "multipleActions",
"actions": [
// Create a new tab with 3 panes
Expand Down
50 changes: 49 additions & 1 deletion TerminalDocs/customize-settings/interaction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ This determines the word delimiters used in a double-click selection. Word delim

**Accepts:** Characters as a string

**Default value:**
**Default value:**
<code>&nbsp;&#x2f;&#x5c;&#x5c;&#x28;&#x29;&#x5c;&#x22;&#x27;&#x2d;&#x3a;&#x2c;&#x2e;&#x3b;&#x3c;&#x3e;&#x7e;&#x21;&#x40;&#x23;&#x24;&#x25;&#x5e;&#x26;&#x2a;&#x7c;&#x2b;&#x3d;&#x5b;&#x5d;&#x7b;&#x7d;&#x3f;│</code>
<br>
_(`│` is `U+2502 BOX DRAWINGS LIGHT VERTICAL`)_
Expand Down Expand Up @@ -292,3 +292,51 @@ Force the terminal to use the legacy input encoding. Specific keys in some appli
**Accepts:** `true`, `false`

**Default value:** `false`

<br />

___

## Context Menu

:::row:::
:::column span="":::

The context menu in the Windows Terminal is an easy way to access common actions quickly. When this is set to `true`, a right-click in the Terminal will activate the context menu. When set to `false`, a right-click will paste.

The context menu can also be opened with the `showContextMenu` action, regardless if this setting is enabled or not.

:::column-end:::
:::column span="":::

![A screenshot of the context menu in the Terminal](../images/RightClickMenu.png)

:::column-end:::
:::row-end:::

**Property name:** `experimental.rightClickContextMenu`

**Necessity:** Optional

**Accepts:** `true`, `false`

**Default value:** `false`

<br />

___

## Web searching

This is the default URL used when searching the web from the terminal with the `searchWeb` action (including the right-click context menu). The `%s` in this string is replaced with the selected text. The default value is `https://www.bing.com/search?q=%s`.

**Property name:** `searchWebDefaultQueryUrl`

**Necessity:** Optional

**Accepts:** URL as a string

**Default value:** `https://www.bing.com/search?q=%s`

> [!IMPORTANT]
> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
27 changes: 27 additions & 0 deletions TerminalDocs/customize-settings/profile-advanced.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -218,6 +218,33 @@ This is an experimental feature, and its continued existence is not guaranteed.

___

## Experimental: Move cursor with the mouse

:::row:::
:::column span="":::

This experimentally adds support for moving the text cursor by clicking with the mouse on the current commandline. This is an experimental feature - there are lots of edge cases where this will not work as expected. In ordfer for this setting to work, you will need to enable [shell integration](../tutorials/shell-integration.md) in your shell.

:::column-end:::
:::column span="":::

![A recording of the user moving the cursor with the mouse](../images/moveCursorWithMouse.gif)

:::column-end:::
:::row-end:::

**Property name:** `experimental.repositionCursorWithMouse`

**Necessity:** Optional

**Accepts:** `true`, `false`

**Default value:** `false`

<br />

___

## VT passthrough mode

When set to true, directs the PTY for this connection to use pass-through mode instead of the original Conhost PTY simulation engine. This is an experimental feature, and its continued existence is not guaranteed.
Expand Down
19 changes: 19 additions & 0 deletions TerminalDocs/customize-settings/rendering.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,3 +40,22 @@ When this is set to `true`, the terminal will use the software renderer (a.k.a.
**Accepts:** `true`, `false`

**Default value:** `false`

<br />

___

## Enable unfocused acrylic

When this is set to `true`, the terminal will attempt to use acrylic even when the window is unfocused. This will only work if acrylic is enabled in the OS, and in your profile. When set to `false`, acrylic will only be used when the window is focused (even if `useAcrylic` is set to `true` in a profile's `unfocusedAppearance`).

**Property name:** `compatibility.enableUnfocusedAcrylic`

**Necessity:** Optional

**Accepts:** `true`, `false`

**Default value:** `true`

> [!IMPORTANT]
> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
Loading