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

Add remaining 1.3 release features #119

Merged
merged 29 commits into from
Aug 26, 2020
Merged

Add remaining 1.3 release features #119

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
36a716a
remove preview labels from 1.2 features
cinnamon-msft Aug 23, 2020
43f0e73
Add preview labeling for #7328
cinnamon-msft Aug 23, 2020
73e8b4c
Add preview labeling for #6004
cinnamon-msft Aug 23, 2020
6d20ada
Add command palette page
cinnamon-msft Aug 23, 2020
2d7de19
Document #7117
cinnamon-msft Aug 23, 2020
b6f061a
Add preview labeling for #6732
cinnamon-msft Aug 23, 2020
905ce8f
Document #7235
cinnamon-msft Aug 23, 2020
03e49a7
Add example for #7249
cinnamon-msft Aug 24, 2020
3dc0ada
Document #6989
cinnamon-msft Aug 24, 2020
128030e
Document #7162
cinnamon-msft Aug 24, 2020
0364da3
Document #7176
cinnamon-msft Aug 24, 2020
c474aa4
Add initial contents to command palette page
cinnamon-msft Aug 25, 2020
eafb007
Update TerminalDocs/command-palette.md
cinnamon-msft Aug 25, 2020
022c61b
Update TerminalDocs/command-palette.md
cinnamon-msft Aug 25, 2020
0eea38e
Update TerminalDocs/command-palette.md
cinnamon-msft Aug 25, 2020
eac4314
Update TerminalDocs/command-palette.md
cinnamon-msft Aug 25, 2020
d0da0dc
make closeOtherTabs and closeTabsAfter 'index' optional
carlos-zamora Aug 25, 2020
4c05d98
Add more to command palette page
cinnamon-msft Aug 25, 2020
fda2bc1
Add tip to key bindings page
cinnamon-msft Aug 25, 2020
1d75e22
Tweak command palette page
cinnamon-msft Aug 25, 2020
486abea
Update command palette page
cinnamon-msft Aug 25, 2020
d3c7454
Update command palette page
cinnamon-msft Aug 25, 2020
67d5e0c
Update iterable commands section
cinnamon-msft Aug 25, 2020
d43f817
Update command palette page
cinnamon-msft Aug 25, 2020
7b9e37d
Add examples for #6732
cinnamon-msft Aug 26, 2020
8a69f31
Add example for #6989
cinnamon-msft Aug 26, 2020
cf82dd6
Fix formatting
cinnamon-msft Aug 26, 2020
b21b4cf
Add gifs to command palette page
cinnamon-msft Aug 26, 2020
776b19f
Update TerminalDocs/command-palette.md
zadjii-msft Aug 26, 2020
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
6 changes: 4 additions & 2 deletions TerminalDocs/TOC.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,14 @@
href: customize-settings/key-bindings.md
- name: Command line arguments
href: command-line-arguments.md
- name: Dynamic profiles
href: dynamic-profiles.md
- name: Command palette
href: command-palette.md
- name: Search
href: search.md
- name: Panes
href: panes.md
- name: Dynamic profiles
href: dynamic-profiles.md
- name: Cascadia Code
href: cascadia-code.md
- name: Tips and tricks
Expand Down
5 changes: 1 addition & 4 deletions TerminalDocs/command-line-arguments.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Windows Terminal command-line arguments
description: Learn how to create command-line arguments for Windows Terminal.
author: cinnamon-msft
ms.author: cinnamon
ms.date: 07/21/2020
ms.date: 08/26/2020
ms.topic: how-to
ms.service: terminal
---
Expand Down Expand Up @@ -43,9 +43,6 @@ Below is the full list of supported commands and options for the `wt` command li
| `split-pane`, `sp` | `-H, --horizontal`, `-V, --vertical`, `--profile, -p profile-name`, `--startingDirectory, -d starting-directory`, `commandline`, `--title` | Splits a new pane. |
| `focus-tab`, `ft` | `--target, -t tab-index` | Focuses on a specific tab. |

> [!IMPORTANT]
> `nt`, `sp`, and `ft` are only available in [Windows Terminal Preview](https://aka.ms/terminal-preview/).

> [!NOTE]
> When opening Windows Terminal from cmd (Command Prompt), if you want to use your custom "cmd" profile settings, you will need to use the command `wt -p cmd`. Otherwise, to run your *default* profile settings, just use `wt cmd`.

Expand Down
165 changes: 165 additions & 0 deletions TerminalDocs/command-palette.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,165 @@
---
title: Windows Terminal Command Palette
description: Learn how to use the command palette in the Windows Terminal.
author: cinnamon-msft
ms.author: cinnamon
ms.date: 08/26/2020
ms.topic: how-to
ms.service: terminal
---

# How to use the command palette in Windows Terminal ([Preview](https://aka.ms/terminal-preview/))

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

The command palette lets you see which commands you can run inside Windows Terminal.

## Invoking the command palette

You can invoke the command palette by typing `ctrl+shift+p`. This can be customized by adding the `commandPalette` command to your key bindings.

```json
{ "command": "commandPalette", "keys": "ctrl+shift+p" }
```

## Command line mode

If you'd like to enter a `wt` command into the command palette, you can do so by starting with the `>` character. This will run the `wt` command in the current window. More information on `wt` commands can be found on the [Command line arguments page](./command-line-arguments.md).

![Windows Terminal command line mode](./images/command-palette-command-line-mode.gif)

cinnamon-msft marked this conversation as resolved.
Show resolved Hide resolved
## Defining commands
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Honestly, I recommend rewriting this section from the ground up. How about a structure like this:

  • Explain what is a plain command:
    • simple command: { "command": "newTab" }
    • advanced command { "command": { "action": "newTab", "commandline": "pwsh.exe" } }
    • These are examples of actions you can perform to interact with Windows Terminal. In this case, we're opening a new tab with our default profile with a simple command. The more advanced command opens a new tab with the default profile, but overrides the commandline parameter .
    • These commands appear in your command palette with an autogenerated name, if one exists. More complicated commands do not have an autogenerated name.
  • Adding a key binding shortcut:
    • if you find yourself using a command a lot, you can bind it to a key chord by adding the "keys" key to your json. It will look like this { "command": "newTab", "keys": "ctrl+t" }.
    • Windows Terminal will still try to autogenerate a name for you, so it can be invoked in the command palette. We even display the associated key binding when it appears in the command palette. <include picture/gif>
  • Customizing the command palette entry:
    • You can also add...
      • "name": to override the autogenerated name. Set to null to remove from the command palette.
      • "icon": to make the command stand out more in your command palette
      • <include picture/gif>

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note: don't forget to probably update the key bindings page too. We have "keys" as required. So now it technically isn't?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't disagree with Carlos here.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

At no point do we explain where commands come from in the file.

We probably need to add a paragraph that covers something like:

Commands are automatically generated for each of the actions in your keybindings, when possible. If you'd like to add other commands to the command palette, you can do it like (this).

and make sure we specifically show that the commands are getting added to keybindings


Commands are automatically generated for each of the actions in your `keybindings`, when possible. If you'd like to add other commands to the command palette, you can define them in three different ways.

#### With a value for `keys` without a `name`

This is the behavior that is documented on the [Key bindings page](./customize-settings/key-bindings.md). These commands can be invoked with the defined key binding. The commands will appear in the command palette if Windows Terminal can autogenerate a reasonable name for it.

```json
{ "command": "newTab", "keys": "ctrl+shift+t" }
```

#### Without a value for `keys`, but with a `name`

These commands will only be added to the command palette. They cannot be invoked with a key binding. `name` overrides the autogenerated name.

```json
{ "name": "Open my default tab", "command": "newTab" }
```

#### With a value for `keys` with a `name`

These commands will be added to the command palette and can be invoked with the keyboard. The `name` property will override the autogenerated name.

```json
{ "name": "New tab", "command": "newTab", "keys": "ctrl+shift+t" }
```

### Adding an icon

You can optionally add an icon to a command that appears in the command palette. This can be done by adding the `icon` property to the command. Icons can be a path to an image, a symbol from [Segoe MDL2 Assets](https://docs.microsoft.com/windows/uwp/design/style/segoe-ui-symbol-font), or any character, including emojis.

```json
{ "icon": "C:\\Images\\my-icon.png", "name": "New tab", "command": "newTab", "keys": "ctrl+shift+t" },
{ "icon": "\uE756", "name": "New tab", "command": "newTab", "keys": "ctrl+shift+t" },
{ "icon": "⚡", "name": "New tab", "command": "newTab", "keys": "ctrl+shift+t" }
```

cinnamon-msft marked this conversation as resolved.
Show resolved Hide resolved
### Nested commands

Nested commands let you group multiple commands under one item in the command palette. The example below groups the font resize commands under one command palette item called "Change font size...".

```json
{
"name": "Change font size...",
"commands": [
{ "command": { "action": "adjustFontSize", "delta": 1 } },
{ "command": { "action": "adjustFontSize", "delta": -1 } },
{ "command": "resetFontSize" },
]
}
```

![Windows Terminal nested commands](./images/command-palette-nested-commands.gif)

### Iterable commands

Iterable commands let you create multiple commands at the same time, generated from other objects defined in your settings. Currently, you can create iterable commands for your profiles and color schemes. At runtime, these commands will be expanded to one command for each of the objects of the given type.

You can currently iterate over the following properties:

| `iterateOn` | Property | Property syntax |
| ----------- | -------- | --------------- |
| `profiles` | `name` | `"name": "${profile.name}"` |
| `profiles` | `icon` | `"icon": "${profile.icon}"` |
| `schemes` | `name` | `"name": "${scheme.name}"` |

#### Example

Create a new tab command for each profile.

![Windows Terminal iterable commands](./images/command-palette-iterable-commands.gif)

```json
{
"name": "New tab",
"commands": [
{
"iterateOn": "profiles",
"icon": "${profile.icon}",
"name": "${profile.name}",
"command": { "action": "newTab", "profile": "${profile.name}" }
}
]
}
```

In the above example:

- `"iterateOn": "profiles"` will generate a command for each profile.
- At runtime, the terminal will replace `${profile.icon}` with each profile's icon and `${profile.name}` with each profile's name.

If you had three profiles:

```json
"profiles": [
{ "name": "Command Prompt", "icon": null },
{ "name": "PowerShell", "icon": "C:\\path\\to\\icon.png" },
{ "name": "Ubuntu", "icon": null },
]
```

The above command would behave like the following three commands:

```json
{
"name": "New tab...",
"commands": [
{
"icon": null,
"name": "Command Prompt",
"command": { "action": "newTab", "profile": "Command Prompt" }
},
{
"icon": "C:\\path\\to\\icon",
"name": "PowerShell",
"command": { "action": "newTab", "profile": "PowerShell" }
},
{
"icon": null,
"name": "Ubuntu",
"command": { "action": "newTab", "profile": "Ubuntu" }
}
]
}
```

## Hiding a command

If you would like to keep a command in your key bindings list but not have it appear in the command palette, you can hide it by setting its `name` to `null`. The example below hides the "New tab" action from the command palette.

```json
{ "name": null, "command": "newTab", "keys": "ctrl+shift+t" }
```
48 changes: 34 additions & 14 deletions TerminalDocs/customize-settings/global-settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Windows Terminal Global Settings
description: Learn how to customize the global settings within Windows Terminal.
author: cinnamon-msft
ms.author: cinnamon
ms.date: 07/21/2020
ms.date: 08/26/2020
ms.topic: how-to
ms.service: terminal
ms.localizationpriority: high
Expand Down Expand Up @@ -73,6 +73,32 @@ ___

## Tab settings

### Use tab switcher experience ([Preview](https://aka.ms/terminal-preview))

:::row:::
:::column span="":::
When this is set to `true`, the `nextTab` and `prevTab` commands will use the tab switcher UI. The UI will show all the currently open tabs in a vertical list, navigable with the keyboard or mouse.

The tab switcher will open on the initial press of the keybindings for `nextTab` and `prevTab`, and will stay open as long as a modifier key is held down. When all modifier keys are released, the switcher will close and the highlighted tab will be focused. <kbd>tab</kbd>/<kbd>shift+tab</kbd>, the <kbd>up</kbd> and <kbd>down</kbd> arrow keys, and the `nextTab`/`prevTab` keybindings can be used to cycle through the switcher UI.

**Property name:** `useTabSwitcher`

**Necessity:** Optional

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

**Default value:** `true`

:::column-end:::
:::column span="":::
![Windows Terminal tab switcher](./../images/tab-switcher.gif)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there supposed to be a gif here?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah it's still on the issue checklist. I'll be creating gifs tonight.

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

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

### Always show tabs

:::row:::
Expand Down Expand Up @@ -202,7 +228,7 @@ This is the number of rows displayed in the window upon first load. If `launchMo

**Default value:** `30`

### Always on top mode ([Preview](https://aka.ms/terminal-preview/))
### Always on top mode

When set to true, Windows Terminal windows will launch on top of all other windows on the desktop. This state can also be toggled with the `toggleAlwaysOnTop` key binding.

Expand All @@ -214,9 +240,6 @@ When set to true, Windows Terminal windows will launch on top of all other windo

**Default value:** `false`

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

<br />

___
Expand Down Expand Up @@ -286,6 +309,9 @@ When this is set to `true`, the color and font formatting of the selected text i

**Default value:** `false`

> [!IMPORTANT]
> `"all"`, `"none"`, `"html"`, and `"rtf"` are only available in [Windows Terminal Preview](https://aka.ms/terminal-preview/).

### Word delimiters

This determines the word delimiters used in a double-click selection. Word delimiters are characters that specify where the boundary is between two words. The most common examples are spaces, semicolons, commas, and periods.
Expand All @@ -304,7 +330,7 @@ ___

## Paste warnings

### Warn when the text to paste is very large ([Preview](https://aka.ms/terminal-preview/))
### Warn when the text to paste is very large

When this is set to `true`, trying to paste text with more than 5 KiB of characters will display a dialog asking you whether to continue or not with the paste. When it's set to `false`, the dialog is not shown and instead the text is pasted right away. If you often right-click on the terminal by accident after having selected a lot of text, this might be useful to prevent the terminal from becoming unresponsive while the program connected to the terminal receives the clipboard's content.

Expand All @@ -316,10 +342,7 @@ When this is set to `true`, trying to paste text with more than 5 KiB of charact

**Default value:** `true`

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

### Warn when the text to paste contains multiple lines ([Preview](https://aka.ms/terminal-preview/))
### Warn when the text to paste contains multiple lines

When this is set to `true`, trying to paste text with multiple lines will display a dialog asking you whether to continue or not with the paste. When it's set to `false`, the dialog is not shown and instead the text is pasted right away. In most shells, one line corresponds to one command so if you paste text that contains the "new line" character into a shell, one or more command(s) might be executed automatically upon paste, without you having time to validate the commands. This can be useful if you often copy and paste commands from untrusted websites.

Expand All @@ -331,9 +354,6 @@ When this is set to `true`, trying to paste text with multiple lines will displa

**Default value:** `true`

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

<br />

___
Expand All @@ -351,7 +371,7 @@ This is the number of rows to scroll at a time with the mouse wheel. This will o
**Default value:** `"system"`

> [!CAUTION]
> The `rowsToScroll` setting is no longer available in [Windows Terminal Preview](https://aka.ms/terminal-preview/), version 1.2. This version of Windows Terminal will always use the value configured in the system Mouse settings panel.
> The `rowsToScroll` setting is no longer available versions 1.2 and later. Windows Terminal will use the value configured in the system Mouse settings panel.

<br />

Expand Down
Loading