diff --git a/TerminalDocs/command-palette.md b/TerminalDocs/command-palette.md index 8a175148..2cb78477 100644 --- a/TerminalDocs/command-palette.md +++ b/TerminalDocs/command-palette.md @@ -41,6 +41,9 @@ You can optionally add an icon to a command defined in your [settings.json](./in { "icon": "⚡", "name": "New tab", "command": "newTab", "keys": "ctrl+shift+t" } ``` +> [!NOTE] +> As of Windows Terminal 1.24, `icon` may refer to content adjacent to the `settings.json` file. + ## 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...". diff --git a/TerminalDocs/customize-settings/actions.md b/TerminalDocs/customize-settings/actions.md index 94d2d45b..5f4212fe 100644 --- a/TerminalDocs/customize-settings/actions.md +++ b/TerminalDocs/customize-settings/actions.md @@ -102,6 +102,9 @@ This sets the icon that displays within the command palette. **Accepts:** File location as a string, or an emoji +> [!NOTE] +> As of Windows Terminal 1.24, `icon` may refer to content adjacent to the `settings.json` file. + ### ID This sets the id of this action. If one isn't provided, the terminal will generate an ID for this action. The ID is used to refer to this action when creating keybindings. diff --git a/TerminalDocs/customize-settings/appearance.md b/TerminalDocs/customize-settings/appearance.md index f151c9f7..74fe64ff 100644 --- a/TerminalDocs/customize-settings/appearance.md +++ b/TerminalDocs/customize-settings/appearance.md @@ -326,6 +326,9 @@ This entry type represents a profile from your list of profiles. The profile can | `profile` | Required | Profile's name or GUID as a string | Profile that will open based on its GUID or name. | | `icon` | Optional | Path to an icon as a string | Path to an icon that will be displayed next to the profile name. The profile's default icon will be used if not specified. | +> [!NOTE] +> As of Windows Terminal 1.24, `icon` may refer to content adjacent to the `settings.json` file. + #### Folder This entry type represents a nested folder in the new tab dropdown menu. Folders can be nested inside of other folders. @@ -353,6 +356,9 @@ This entry type represents a nested folder in the new tab dropdown menu. Folders | `allowEmpty` | Optional | Boolean (defaults to `true`) | If set to `true`, the folder will be displayed even if it has no entries. If set to `false`, the folder will not be displayed if it has no entries. This can be useful with `matchProfiles` entries. | | `inline` | Optional | Boolean (defaults to `false`) | If set to `true`, and there's only a single entry in the folder, this folder won't create a nested menu. Instead, the entry in the menu will just be the single entry in the folder. This can be useful with `matchProfiles` entries. | +> [!NOTE] +> As of Windows Terminal 1.24, `icon` may refer to content adjacent to the `settings.json` file. + #### Separator This entry type represents a separator in the new tab dropdown menu. @@ -409,4 +415,8 @@ For more information, see the [custom actions and keybindings](actions.md) docum | ---- | --------- | ------- | ----------- | | `id` | Required | Action ID as a string | Action that will be executed | | `icon` | Optional | Path to an icon as a string | Path to an icon that will be displayed next to the action name. If not specified, the action's own icon will be used (if configured). | + +> [!NOTE] +> As of Windows Terminal 1.24, `icon` may refer to content adjacent to the `settings.json` file. + ___ diff --git a/TerminalDocs/customize-settings/interaction.md b/TerminalDocs/customize-settings/interaction.md index 00752278..a2093807 100644 --- a/TerminalDocs/customize-settings/interaction.md +++ b/TerminalDocs/customize-settings/interaction.md @@ -244,6 +244,7 @@ When enabled, this allows the Terminal window to automatically be hidden as soon **Default value:** `false`
+ ___ ## Automatically focus pane on mouse hover @@ -262,6 +263,31 @@ When this is set to `true`, the terminal will move focus to the pane on mouse ho ___ +## Adjust terminal font size by scrolling while holding the Ctrl key + +When this is set to `true`, holding the Ctrl key while scrolling will increase or decrease the terminal font size. This is an experimental feature and its continued existence is not guaranteed. + +**Property name:** `experimental.scrollToZoom` + +
+___ + +## Adjust terminal opacity by scrolling while holding the Ctrl and Shift keys + +When this is set to `true`, holding the Ctrl and Shift keys while scrolling will change the window opacity. This is an experimental feature and its continued existence is not guaranteed. + +**Property name:** `experimental.scrollToChangeOpacity` + +**Necessity:** Optional + +**Accepts:** `true`, `false` + +**Default value:** `true` + +
+ +___ + ## Automatically detect URLs and make them clickable When this is set to `true`, URLs will be detected by the terminal. This will cause URLs to underline on hover and be clickable by pressing Ctrl. This is an experimental feature and its continued existence is not guaranteed. diff --git a/TerminalDocs/customize-settings/profile-appearance.md b/TerminalDocs/customize-settings/profile-appearance.md index fa4ccac9..093a002e 100644 --- a/TerminalDocs/customize-settings/profile-appearance.md +++ b/TerminalDocs/customize-settings/profile-appearance.md @@ -261,6 +261,9 @@ It is recommended that custom images and icons are stored in system-provided fol > [!WARNING] > Do not rely on file references using the ms-appx URI scheme (i.e. icons). These files are considered an internal implementation detail and may change name/location or may be omitted in the future. +> [!NOTE] +> As of Windows Terminal 1.24, `backgroundImage` may refer to content adjacent to the `settings.json` file. + ### Icons Windows Terminal displays icons for each profile which the terminal generates for any built-in shells, for example: PowerShell Core, PowerShell, and any installed Linux/WSL distributions. Each profile refers to a stock icon via the ms-appx URI scheme. You can refer to you own custom icons by entering a path in your [settings.json file](../install.md#settings-json-file): @@ -540,3 +543,14 @@ If set, this will override the `experimental.retroTerminalEffect` setting. **Necessity:** Optional **Accepts:** A path to an `.hlsl` shader file, as a string + +An additional setting, `experimental.pixelShaderImagePath`, allows you to specify an image file to be loaded alongsize the shader. It will be made available in texture register `t1`. + +**Property name:** `experimental.pixelShaderImagePath` + +**Necessity:** Optional + +**Accepts:** A path to an image file, as a string + +> [!NOTE] +> As of Windows Terminal 1.24, `experimental.pixelShaderPath` and `experimental.pixelShaderImagePath` may refer to content adjacent to the `settings.json` file. diff --git a/TerminalDocs/customize-settings/profile-general.md b/TerminalDocs/customize-settings/profile-general.md index 2d52ad95..749a3cfa 100644 --- a/TerminalDocs/customize-settings/profile-general.md +++ b/TerminalDocs/customize-settings/profile-general.md @@ -98,6 +98,11 @@ This sets the icon that displays within the tab, dropdown menu, jumplist, and ta **Example:** By placing the icon image `ubuntu.ico` in the folder located at `%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\RoamingState`, you can display the icon by adding this line to the profile in your [settings.json](../install.md#settings-json-file): `"icon": "ms-appdata:///roaming/ubuntu.ico"`. +> [!NOTE] +> As of Windows Terminal 1.24, `icon` paths may refer to content adjacent to the `settings.json` file. +> +> In the example above, you can place `ubuntu.ico` in the `LocalState` directory alongside `settings.json`, and refer to it with `"icon": "ubuntu.ico"`. +
___ diff --git a/TerminalDocs/docfx.json b/TerminalDocs/docfx.json index 7c59213f..1645a7dd 100644 --- a/TerminalDocs/docfx.json +++ b/TerminalDocs/docfx.json @@ -42,7 +42,7 @@ "externalReference": [], "globalMetadata": { "breadcrumb_path": "/windows/terminal/breadcrumb/toc.json", - "uhfHeaderId": "MSDocsHeader-Windows", + "uhfHeaderId": "MSDocsHeader-Windows-DevTools", "keywords": "Windows Terminal, terminal, windows shell, terminal docs", "feedback_product_url": "https://github.com/Microsoft/terminal/issues", "feedback_system": "OpenSource", diff --git a/TerminalDocs/json-fragment-extensions.md b/TerminalDocs/json-fragment-extensions.md index 67d655d6..6651fc4c 100644 --- a/TerminalDocs/json-fragment-extensions.md +++ b/TerminalDocs/json-fragment-extensions.md @@ -189,3 +189,32 @@ In the second case, the installation is only for the current user. In this case, `C:\Users\\AppData\Local\Microsoft\Windows Terminal\Fragments\{app-name}\{file-name}.json` Note that both the `ProgramData` and `LocalAppData` folders are known folders that the installer should be able to access. If in either case, if the `Windows Terminal\Fragments` directory does not exist, the installer should create it. The `{app-name}` should be unique to your application and the `{file-name}.json` can be anything - the terminal will read all .json files in that directory. + +## Distributing media resources with your fragment extension + +As of Windows Terminal 1.24, fragment extensions can distribute media resources such as images and pixel shaders to be used with the `icon`, `backgroundImage`, `experimental.pixelShaderPath` and `experimental.pixelShaderImagePath` properties on profiles and actions. + +Earlier versions of Terminal supported Web URLs for `icon` and `backgroundImage`. Those versions will continue to load Web URL resources in perpetuity. +Newer versions will no longer access web URLs, but will instead look in the directory containing your fragment file. + +If you wish to maintain compatibility with all available versions of Terminal, you may place any web resources in the same directory as your `.json` files. + +``` +Fragments\ + `- AppName\ <- FRAGMENT_ROOT + |- file1.json + |- file2.json + `- app_icon.png +``` + +You can rely on the following compatibility behaviors: + +| Resource Path | < 1.24 | ≥ 1.24 | +| ------------------------------------------------ | --------------------- | ------------------------------------------- | +| `https://example.com/app/app_icon.png` | ✅ loaded from the web | ✅ loaded from `$FRAGMENT_ROOT\app_icon.png` | +| `app_icon.png` | ❌ ignored | ✅ loaded from `$FRAGMENT_ROOT\app_icon.png` | +| `ms-appx://MyApplication/Fragments/app_icon.png` | ❌ ignored | ✅ loaded from `$FRAGMENT_ROOT\app_icon.png` | + +> [!NOTE] +> Versions of Windows Terminal prior to 1.24 only supported Web URLs for `icon` and `backgroundImage` on a profile. +> There is no way to specify a compatible fallback for either `experimental.pixelShaderPath` or action `icon`s. diff --git a/TerminalDocs/tutorials/custom-prompt-setup.md b/TerminalDocs/tutorials/custom-prompt-setup.md index 51897ee3..6674e86a 100644 --- a/TerminalDocs/tutorials/custom-prompt-setup.md +++ b/TerminalDocs/tutorials/custom-prompt-setup.md @@ -31,7 +31,6 @@ In this tutorial, you learn how to: Customized command prompts often use glyphs (a graphic symbol) to style the prompt. If your font does not include the appropriate glyphs, you may see several Unicode replacement characters '▯' in your prompt. Customized command prompts often use glyphs (a graphic symbol) to style the prompt. If your font does not include the appropriate glyphs, you may see several Unicode replacement characters '▯' in your prompt. -To see all of the glyphs in your terminal, we recommend installing a [Nerd Font](https://www.nerdfonts.com/font-downloads) like Cascadia Code NF, which can be downloaded from the [Cascadia Code release page](https://github.com/microsoft/cascadia-code/releases). To see all of the glyphs in your terminal, we recommend installing a [Nerd Font](https://www.nerdfonts.com/font-downloads) like Cascadia Code NF, which can be downloaded from the [Cascadia Code release page](https://github.com/microsoft/cascadia-code/releases). After downloading, you will need to unzip and install the font on your system. ([How to add a new font to Windows](https://support.microsoft.com/en-us/office/add-a-font-b7c5f17c-4426-4b53-967f-455339c564c1)). diff --git a/TerminalDocs/tutorials/new-tab-same-directory.md b/TerminalDocs/tutorials/new-tab-same-directory.md index 3c5148ff..ac2b942a 100644 --- a/TerminalDocs/tutorials/new-tab-same-directory.md +++ b/TerminalDocs/tutorials/new-tab-same-directory.md @@ -14,7 +14,6 @@ Typically, the "new tab" and "split pane" actions will always open a new tab/pan Unfortunately, on Windows, it's tricky to determine what the current working directory ("CWD") for a process is. Even if we were able to look it up, not all applications actually set their CWD as they navigate. Notably, Windows PowerShell doesn't change its CWD as you `cd` around the file system! Duplicating the CWD of PowerShell automatically would almost always be wrong. -Fortunately, there's a workaround. Applications can emit a special escape sequence (specifically the "OSC 9;9" format) to manually tell the Terminal what the CWD should be. Fortunately, there's a workaround. Applications can emit a special escape sequence (specifically the "OSC 9;9" format) to manually tell the Terminal what the CWD should be. In this tutorial, you learn how to: