diff --git a/doc/cascadia/SettingsSchema.md b/doc/cascadia/SettingsSchema.md index bef3d885b5f..aa9a0f62323 100644 --- a/doc/cascadia/SettingsSchema.md +++ b/doc/cascadia/SettingsSchema.md @@ -1,196 +1,197 @@ -# Profiles.json Documentation - -## Globals -Properties listed below affect the entire window, regardless of the profile settings. - -| Property | Necessity | Type | Default | Description | -| -------- | --------- | ---- | ------- | ----------- | -| `alwaysShowTabs` | _Required_ | Boolean | `true` | When set to `true`, tabs are always displayed. When set to `false` and `showTabsInTitlebar` is set to `false`, tabs only appear after typing Ctrl + T. | -| `copyOnSelect` | Optional | Boolean | `false` | When set to `true`, a selection is immediately copied to your clipboard upon creation. When set to `false`, the selection persists and awaits further action. | -| `defaultProfile` | _Required_ | String | PowerShell guid | Sets the default profile. Opens by typing Ctrl + T or by clicking the '+' icon. The guid of the desired default profile is used as the value. | -| `initialCols` | _Required_ | Integer | `120` | The number of columns displayed in the window upon first load. | -| `initialRows` | _Required_ | Integer | `30` | The number of rows displayed in the window upon first load. | -| `rowsToScroll` | Optional | Integer | `system` | The number of rows to scroll at a time with the mouse wheel. This will override the system setting if the value is not zero or "system". | -| `requestedTheme` | _Required_ | String | `system` | Sets the theme of the application. Possible values: `"light"`, `"dark"`, `"system"` | -| `showTerminalTitleInTitlebar` | _Required_ | Boolean | `true` | When set to `true`, titlebar displays the title of the selected tab. When set to `false`, titlebar displays "Windows Terminal". | -| `showTabsInTitlebar` | Optional | Boolean | `true` | When set to `true`, the tabs are moved into the titlebar and the titlebar disappears. When set to `false`, the titlebar sits above the tabs. | -| `snapToGridOnResize` | Optional | Boolean | `false` | When set to `true`, the window will snap to the nearest character boundary on resize. When `false`, the window will resize "smoothly" | -| `wordDelimiters` | Optional | String |  /\()"'-:,.;<>~!@#$%^&*|+=[]{}~?│
_(`│` is `U+2502 BOX DRAWINGS LIGHT VERTICAL`)_ | Determines the delimiters used in a double click selection. | - -## Profiles -Properties listed below are specific to each unique profile. - -| Property | Necessity | Type | Default | Description | -| -------- | --------- | ---- | ------- | ----------- | -| `guid` | _Required_ | String | | Unique identifier of the profile. Written in registry format: `"{00000000-0000-0000-0000-000000000000}"`. | -| `name` | _Required_ | String | | Name of the profile. Displays in the dropdown menu.
Additionally, this value will be used as the "title" to pass to the shell on startup. Some shells (like `bash`) may choose to ignore this initial value, while others (`cmd`, `powershell`) may use this value over the lifetime of the application. This "title" behavior can be overriden by using `tabTitle`. | -| `acrylicOpacity` | Optional | Number | `0.5` | When `useAcrylic` is set to `true`, it sets the transparency of the window for the profile. Accepts floating point values from 0-1. | -| `background` | Optional | String | | Sets the background color of the profile. Overrides `background` set in color scheme if `colorscheme` is set. Uses hex color format: `"#rrggbb"`. | -| `backgroundImage` | Optional | String | | Sets the file location of the Image to draw over the window background. | -| `backgroundImageAlignment` | Optional | String | `center` | Sets how the background image aligns to the boundaries of the window. Possible values: `"center"`, `"left"`, `"top"`, `"right"`, `"bottom"`, `"topLeft"`, `"topRight"`, `"bottomLeft"`, `"bottomRight"` | -| `backgroundImageOpacity` | Optional | Number | `1.0` | Sets the transparency of the background image. Accepts floating point values from 0-1. | -| `backgroundImageStretchMode` | Optional | String | `uniformToFill` | Sets how the background image is resized to fill the window. Possible values: `"none"`, `"fill"`, `"uniform"`, `"uniformToFill"` | -| `closeOnExit` | Optional | String | `graceful` | Sets how the profile reacts to termination or failure to launch. Possible values: `"graceful"` (close when `exit` is typed or the process exits normally), `"always"` (always close) and `"never"` (never close). `true` and `false` are accepted as synonyms for `"graceful"` and `"never"` respectively. | -| `colorScheme` | Optional | String | `Campbell` | Name of the terminal color scheme to use. Color schemes are defined under `schemes`. | -| `colorTable` | Optional | Array[String] | | Array of colors used in the profile if `colorscheme` is not set. Array follows the format defined in `schemes`. | -| `commandline` | Optional | String | | Executable used in the profile. | -| `cursorColor` | Optional | String | `#FFFFFF` | Sets the cursor color for the profile. Uses hex color format: `"#rrggbb"`. | -| `cursorHeight` | Optional | Integer | | Sets the percentage height of the cursor starting from the bottom. Only works when `cursorShape` is set to `"vintage"`. Accepts values from 25-100. | -| `cursorShape` | Optional | String | `bar` | Sets the cursor shape for the profile. Possible values: `"vintage"` ( ▃ ), `"bar"` ( ┃ ), `"underscore"` ( ▁ ), `"filledBox"` ( █ ), `"emptyBox"` ( ▯ ) | -| `fontFace` | Optional | String | `Consolas` | Name of the font face used in the profile. We will try to fallback to Consolas if this can't be found or is invalid. | -| `fontSize` | Optional | Integer | `12` | Sets the font size. | -| `foreground` | Optional | String | | Sets the foreground color of the profile. Overrides `foreground` set in color scheme if `colorscheme` is set. Uses hex color format: `#rgb` or `"#rrggbb"`. | -| `hidden` | Optional | Boolean | `false` | If set to true, the profile will not appear in the list of profiles. This can be used to hide default profiles and dynamicially generated profiles, while leaving them in your settings file. | -| `historySize` | Optional | Integer | `9001` | The number of lines above the ones displayed in the window you can scroll back to. | -| `icon` | Optional | String | | Image file location of the icon used in the profile. Displays within the tab and the dropdown menu. | -| `padding` | Optional | String | `8, 8, 8, 8` | Sets the padding around the text within the window. Can have three different formats: `"#"` sets the same padding for all sides, `"#, #"` sets the same padding for left-right and top-bottom, and `"#, #, #, #"` sets the padding individually for left, top, right, and bottom. | -| `scrollbarState` | Optional | String | | Defines the visibility of the scrollbar. Possible values: `"visible"`, `"hidden"` | -| `selectionBackground` | Optional | String | | Sets the selection background color of the profile. Overrides `selectionBackground` set in color scheme if `colorscheme` is set. Uses hex color format: `"#rrggbb"`. | -| `snapOnInput` | Optional | Boolean | `true` | When set to `true`, the window will scroll to the command input line when typing. When set to `false`, the window will not scroll when you start typing. | -| `source` | Optional | String | | Stores the name of the profile generator that originated this profile. _There are no discoverable values for this field._ | -| `startingDirectory` | Optional | String | `%USERPROFILE%` | The directory the shell starts in when it is loaded. | -| `suppressApplicationTitle` | Optional | Boolean | | When set to `true`, `tabTitle` overrides the default title of the tab and any title change messages from the application will be suppressed. When set to `false`, `tabTitle` behaves as normal. | -| `tabTitle` | Optional | String | | If set, will replace the `name` as the title to pass to the shell on startup. Some shells (like `bash`) may choose to ignore this initial value, while others (`cmd`, `powershell`) may use this value over the lifetime of the application. | -| `useAcrylic` | Optional | Boolean | `false` | When set to `true`, the window will have an acrylic background. When set to `false`, the window will have a plain, untextured background. | -| `experimental.retroTerminalEffect` | Optional | Boolean | `false` | When set to `true`, enable retro terminal effects. This is an experimental feature, and its continued existence is not guaranteed. | - -## Schemes -Properties listed below are specific to each color scheme. [ColorTool](https://github.com/microsoft/terminal/tree/master/src/tools/ColorTool) is a great tool you can use to create and explore new color schemes. All colors use hex color format. - -| Property | Necessity | Type | Description | -| -------- | ---- | ----------- | ----------- | -| `name` | _Required_ | String | Name of the color scheme. | -| `foreground` | _Required_ | String | Sets the foreground color of the color scheme. | -| `background` | _Required_ | String | Sets the background color of the color scheme. | -| `selectionBackground` | Optional | String | Sets the selection background color of the color scheme. | -| `black` | _Required_ | String | Sets the color used as ANSI black. | -| `blue` | _Required_ | String | Sets the color used as ANSI blue. | -| `brightBlack` | _Required_ | String | Sets the color used as ANSI bright black. | -| `brightBlue` | _Required_ | String | Sets the color used as ANSI bright blue. | -| `brightCyan` | _Required_ | String | Sets the color used as ANSI bright cyan. | -| `brightGreen` | _Required_ | String | Sets the color used as ANSI bright green. | -| `brightPurple` | _Required_ | String | Sets the color used as ANSI bright purple. | -| `brightRed` | _Required_ | String | Sets the color used as ANSI bright red. | -| `brightWhite` | _Required_ | String | Sets the color used as ANSI bright white. | -| `brightYellow` | _Required_ | String | Sets the color used as ANSI bright yellow. | -| `cyan` | _Required_ | String | Sets the color used as ANSI cyan. | -| `green` | _Required_ | String | Sets the color used as ANSI green. | -| `purple` | _Required_ | String | Sets the color used as ANSI purple. | -| `red` | _Required_ | String | Sets the color used as ANSI red. | -| `white` | _Required_ | String | Sets the color used as ANSI white. | -| `yellow` | _Required_ | String | Sets the color used as ANSI yellow. | - -## Keybindings -Properties listed below are specific to each custom key binding. - -| Property | Necessity | Type | Description | -| -------- | ---- | ----------- | ----------- | -| `command` | _Required_ | String | The command executed when the associated key bindings are pressed. | -| `keys` | _Required_ | Array[String] | Defines the key combinations used to call the command. | - -### Implemented Commands - -Commands listed below are per the implementation in [`src/cascadia/TerminalApp/AppKeyBindingsSerialization.cpp`](https://github.com/microsoft/terminal/blob/master/src/cascadia/TerminalApp/AppKeyBindingsSerialization.cpp) - -- copy -- copyTextWithoutNewlines -- paste -- newTab -- openNewTabDropdown -- duplicateTab -- newTabProfile0 -- newTabProfile1 -- newTabProfile2 -- newTabProfile3 -- newTabProfile4 -- newTabProfile5 -- newTabProfile6 -- newTabProfile7 -- newTabProfile8 -- closeWindow -- closeTab -- closePane -- switchToTab -- nextTab -- prevTab -- increaseFontSize -- decreaseFontSize -- resetFontSize -- scrollUp -- scrollDown -- scrollUpPage -- scrollDownPage -- switchToTab0 -- switchToTab1 -- switchToTab2 -- switchToTab3 -- switchToTab4 -- switchToTab5 -- switchToTab6 -- switchToTab7 -- switchToTab8 -- openSettings -- splitPane -- resizePaneLeft -- resizePaneRight -- resizePaneUp -- resizePaneDown -- moveFocusLeft -- moveFocusRight -- moveFocusUp -- moveFocusDown -- toggleFullscreen -- find - -## Example Keys -- ctrl+1 -- ctrl+plus -- alt+- -- shift+numpad_1 -- ctrL+shift+numpad_plus -- ctrl+pgdn -- ctrl+alt+shift+pgup - -## Background Images and Icons -Some Terminal settings allow you to specify custom background images and icons. It is recommended that custom images and icons are stored in system-provided folders and are referred to using the correct [URI Schemes](https://docs.microsoft.com/en-us/windows/uwp/app-resources/uri-schemes). URI Schemes provide a way to reference files independent of their physical paths (which may change in the future). - -The most useful URI schemes to remember when customizing background images and icons are: - -| URI Scheme | Corresponding Physical Path | Use / description | -| --- | --- | ---| -| `ms-appdata:///Local/` | `%localappdata%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\` | Per-machine files | -| `ms-appdata:///Roaming/` | `%localappdata%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\RoamingState\` | Common files | - -> ⚠ Note: 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. - -### Icons -Terminal displays icons for each of your profiles which Terminal generates for any built-in shells - PowerShell Core, PowerShell, and any installed Linux/WSL distros. Each profile refers to a stock icon via the `ms-appx` URI Scheme. - -> ⚠ Note: Do not rely on the files referenced by the `ms-appx` URI Scheme - they are considered an internal implementation detail and may change name/location or may be omitted in the future. - -You can refer to you own icons if you wish, e.g.: - -```json - "icon" : "C:\\Users\\richturn\\OneDrive\\WindowsTerminal\\icon-ubuntu-32.png", -``` - -> 👉 Tip: Icons should be sized to 32x32px in an appropriate raster image format (e.g. .PNG, .GIF, or .ICO) to avoid having to scale your icons during runtime (causing a noticeable delay and loss of quality.) - -### Custom Background Images -You can apply a background image to each of your profiles, allowing you to configure/brand/style each of your profiles independently from one another if you wish. - -To do so, specify your preferred `backgroundImage`, position it using `backgroundImageAlignment`, set its opacity with `backgroundImageOpacity`, and/or specify how your image fill the available space using `backgroundImageStretchMode`. - -For example: -```json - "backgroundImage": "C:\\Users\\richturn\\OneDrive\\WindowsTerminal\\bg-ubuntu-256.png", - "backgroundImageAlignment": "bottomRight", - "backgroundImageOpacity": 0.1, - "backgroundImageStretchMode": "none" -``` - -> 👉 Tip: You can easily roam your collection of images and icons across all your machines by storing your icons and images in OneDrive (as shown above). - -With these settings, your Terminal's Ubuntu profile would look similar to this: - -![Custom icon and background image](../images/custom-icon-and-background-image.jpg) +# Profiles.json Documentation + +## Globals +Properties listed below affect the entire window, regardless of the profile settings. + +| Property | Necessity | Type | Default | Description | +| -------- | --------- | ---- | ------- | ----------- | +| `alwaysShowTabs` | _Required_ | Boolean | `true` | When set to `true`, tabs are always displayed. When set to `false` and `showTabsInTitlebar` is set to `false`, tabs only appear after typing Ctrl + T. | +| `copyOnSelect` | Optional | Boolean | `false` | When set to `true`, a selection is immediately copied to your clipboard upon creation. When set to `false`, the selection persists and awaits further action. | +| `defaultProfile` | _Required_ | String | PowerShell guid | Sets the default profile. Opens by typing Ctrl + T or by clicking the '+' icon. The guid of the desired default profile is used as the value. | +| `initialCols` | _Required_ | Integer | `120` | The number of columns displayed in the window upon first load. | +| `initialRows` | _Required_ | Integer | `30` | The number of rows displayed in the window upon first load. | +| `rowsToScroll` | Optional | Integer | `system` | The number of rows to scroll at a time with the mouse wheel. This will override the system setting if the value is not zero or "system". | +| `requestedTheme` | _Required_ | String | `system` | Sets the theme of the application. Possible values: `"light"`, `"dark"`, `"system"` | +| `showTerminalTitleInTitlebar` | _Required_ | Boolean | `true` | When set to `true`, titlebar displays the title of the selected tab. When set to `false`, titlebar displays "Windows Terminal". | +| `showTabsInTitlebar` | Optional | Boolean | `true` | When set to `true`, the tabs are moved into the titlebar and the titlebar disappears. When set to `false`, the titlebar sits above the tabs. | +| `snapToGridOnResize` | Optional | Boolean | `false` | When set to `true`, the window will snap to the nearest character boundary on resize. When `false`, the window will resize "smoothly" | +| `tabWidthMode` | Optional | String | `equal` | Sets the width of the tabs. Possible values: `"equal"`, `"titleLength"` | +| `wordDelimiters` | Optional | String |  /\()"'-:,.;<>~!@#$%^&*|+=[]{}~?│
_(`│` is `U+2502 BOX DRAWINGS LIGHT VERTICAL`)_ | Determines the delimiters used in a double click selection. | + +## Profiles +Properties listed below are specific to each unique profile. + +| Property | Necessity | Type | Default | Description | +| -------- | --------- | ---- | ------- | ----------- | +| `guid` | _Required_ | String | | Unique identifier of the profile. Written in registry format: `"{00000000-0000-0000-0000-000000000000}"`. | +| `name` | _Required_ | String | | Name of the profile. Displays in the dropdown menu.
Additionally, this value will be used as the "title" to pass to the shell on startup. Some shells (like `bash`) may choose to ignore this initial value, while others (`cmd`, `powershell`) may use this value over the lifetime of the application. This "title" behavior can be overriden by using `tabTitle`. | +| `acrylicOpacity` | Optional | Number | `0.5` | When `useAcrylic` is set to `true`, it sets the transparency of the window for the profile. Accepts floating point values from 0-1. | +| `background` | Optional | String | | Sets the background color of the profile. Overrides `background` set in color scheme if `colorscheme` is set. Uses hex color format: `"#rrggbb"`. | +| `backgroundImage` | Optional | String | | Sets the file location of the Image to draw over the window background. | +| `backgroundImageAlignment` | Optional | String | `center` | Sets how the background image aligns to the boundaries of the window. Possible values: `"center"`, `"left"`, `"top"`, `"right"`, `"bottom"`, `"topLeft"`, `"topRight"`, `"bottomLeft"`, `"bottomRight"` | +| `backgroundImageOpacity` | Optional | Number | `1.0` | Sets the transparency of the background image. Accepts floating point values from 0-1. | +| `backgroundImageStretchMode` | Optional | String | `uniformToFill` | Sets how the background image is resized to fill the window. Possible values: `"none"`, `"fill"`, `"uniform"`, `"uniformToFill"` | +| `closeOnExit` | Optional | String | `graceful` | Sets how the profile reacts to termination or failure to launch. Possible values: `"graceful"` (close when `exit` is typed or the process exits normally), `"always"` (always close) and `"never"` (never close). `true` and `false` are accepted as synonyms for `"graceful"` and `"never"` respectively. | +| `colorScheme` | Optional | String | `Campbell` | Name of the terminal color scheme to use. Color schemes are defined under `schemes`. | +| `colorTable` | Optional | Array[String] | | Array of colors used in the profile if `colorscheme` is not set. Array follows the format defined in `schemes`. | +| `commandline` | Optional | String | | Executable used in the profile. | +| `cursorColor` | Optional | String | `#FFFFFF` | Sets the cursor color for the profile. Uses hex color format: `"#rrggbb"`. | +| `cursorHeight` | Optional | Integer | | Sets the percentage height of the cursor starting from the bottom. Only works when `cursorShape` is set to `"vintage"`. Accepts values from 25-100. | +| `cursorShape` | Optional | String | `bar` | Sets the cursor shape for the profile. Possible values: `"vintage"` ( ▃ ), `"bar"` ( ┃ ), `"underscore"` ( ▁ ), `"filledBox"` ( █ ), `"emptyBox"` ( ▯ ) | +| `fontFace` | Optional | String | `Consolas` | Name of the font face used in the profile. We will try to fallback to Consolas if this can't be found or is invalid. | +| `fontSize` | Optional | Integer | `12` | Sets the font size. | +| `foreground` | Optional | String | | Sets the foreground color of the profile. Overrides `foreground` set in color scheme if `colorscheme` is set. Uses hex color format: `#rgb` or `"#rrggbb"`. | +| `hidden` | Optional | Boolean | `false` | If set to true, the profile will not appear in the list of profiles. This can be used to hide default profiles and dynamicially generated profiles, while leaving them in your settings file. | +| `historySize` | Optional | Integer | `9001` | The number of lines above the ones displayed in the window you can scroll back to. | +| `icon` | Optional | String | | Image file location of the icon used in the profile. Displays within the tab and the dropdown menu. | +| `padding` | Optional | String | `8, 8, 8, 8` | Sets the padding around the text within the window. Can have three different formats: `"#"` sets the same padding for all sides, `"#, #"` sets the same padding for left-right and top-bottom, and `"#, #, #, #"` sets the padding individually for left, top, right, and bottom. | +| `scrollbarState` | Optional | String | | Defines the visibility of the scrollbar. Possible values: `"visible"`, `"hidden"` | +| `selectionBackground` | Optional | String | | Sets the selection background color of the profile. Overrides `selectionBackground` set in color scheme if `colorscheme` is set. Uses hex color format: `"#rrggbb"`. | +| `snapOnInput` | Optional | Boolean | `true` | When set to `true`, the window will scroll to the command input line when typing. When set to `false`, the window will not scroll when you start typing. | +| `source` | Optional | String | | Stores the name of the profile generator that originated this profile. _There are no discoverable values for this field._ | +| `startingDirectory` | Optional | String | `%USERPROFILE%` | The directory the shell starts in when it is loaded. | +| `suppressApplicationTitle` | Optional | Boolean | | When set to `true`, `tabTitle` overrides the default title of the tab and any title change messages from the application will be suppressed. When set to `false`, `tabTitle` behaves as normal. | +| `tabTitle` | Optional | String | | If set, will replace the `name` as the title to pass to the shell on startup. Some shells (like `bash`) may choose to ignore this initial value, while others (`cmd`, `powershell`) may use this value over the lifetime of the application. | +| `useAcrylic` | Optional | Boolean | `false` | When set to `true`, the window will have an acrylic background. When set to `false`, the window will have a plain, untextured background. | +| `experimental.retroTerminalEffect` | Optional | Boolean | `false` | When set to `true`, enable retro terminal effects. This is an experimental feature, and its continued existence is not guaranteed. | + +## Schemes +Properties listed below are specific to each color scheme. [ColorTool](https://github.com/microsoft/terminal/tree/master/src/tools/ColorTool) is a great tool you can use to create and explore new color schemes. All colors use hex color format. + +| Property | Necessity | Type | Description | +| -------- | ---- | ----------- | ----------- | +| `name` | _Required_ | String | Name of the color scheme. | +| `foreground` | _Required_ | String | Sets the foreground color of the color scheme. | +| `background` | _Required_ | String | Sets the background color of the color scheme. | +| `selectionBackground` | Optional | String | Sets the selection background color of the color scheme. | +| `black` | _Required_ | String | Sets the color used as ANSI black. | +| `blue` | _Required_ | String | Sets the color used as ANSI blue. | +| `brightBlack` | _Required_ | String | Sets the color used as ANSI bright black. | +| `brightBlue` | _Required_ | String | Sets the color used as ANSI bright blue. | +| `brightCyan` | _Required_ | String | Sets the color used as ANSI bright cyan. | +| `brightGreen` | _Required_ | String | Sets the color used as ANSI bright green. | +| `brightPurple` | _Required_ | String | Sets the color used as ANSI bright purple. | +| `brightRed` | _Required_ | String | Sets the color used as ANSI bright red. | +| `brightWhite` | _Required_ | String | Sets the color used as ANSI bright white. | +| `brightYellow` | _Required_ | String | Sets the color used as ANSI bright yellow. | +| `cyan` | _Required_ | String | Sets the color used as ANSI cyan. | +| `green` | _Required_ | String | Sets the color used as ANSI green. | +| `purple` | _Required_ | String | Sets the color used as ANSI purple. | +| `red` | _Required_ | String | Sets the color used as ANSI red. | +| `white` | _Required_ | String | Sets the color used as ANSI white. | +| `yellow` | _Required_ | String | Sets the color used as ANSI yellow. | + +## Keybindings +Properties listed below are specific to each custom key binding. + +| Property | Necessity | Type | Description | +| -------- | ---- | ----------- | ----------- | +| `command` | _Required_ | String | The command executed when the associated key bindings are pressed. | +| `keys` | _Required_ | Array[String] | Defines the key combinations used to call the command. | + +### Implemented Commands + +Commands listed below are per the implementation in [`src/cascadia/TerminalApp/AppKeyBindingsSerialization.cpp`](https://github.com/microsoft/terminal/blob/master/src/cascadia/TerminalApp/AppKeyBindingsSerialization.cpp) + +- copy +- copyTextWithoutNewlines +- paste +- newTab +- openNewTabDropdown +- duplicateTab +- newTabProfile0 +- newTabProfile1 +- newTabProfile2 +- newTabProfile3 +- newTabProfile4 +- newTabProfile5 +- newTabProfile6 +- newTabProfile7 +- newTabProfile8 +- closeWindow +- closeTab +- closePane +- switchToTab +- nextTab +- prevTab +- increaseFontSize +- decreaseFontSize +- resetFontSize +- scrollUp +- scrollDown +- scrollUpPage +- scrollDownPage +- switchToTab0 +- switchToTab1 +- switchToTab2 +- switchToTab3 +- switchToTab4 +- switchToTab5 +- switchToTab6 +- switchToTab7 +- switchToTab8 +- openSettings +- splitPane +- resizePaneLeft +- resizePaneRight +- resizePaneUp +- resizePaneDown +- moveFocusLeft +- moveFocusRight +- moveFocusUp +- moveFocusDown +- toggleFullscreen +- find + +## Example Keys +- ctrl+1 +- ctrl+plus +- alt+- +- shift+numpad_1 +- ctrL+shift+numpad_plus +- ctrl+pgdn +- ctrl+alt+shift+pgup + +## Background Images and Icons +Some Terminal settings allow you to specify custom background images and icons. It is recommended that custom images and icons are stored in system-provided folders and are referred to using the correct [URI Schemes](https://docs.microsoft.com/en-us/windows/uwp/app-resources/uri-schemes). URI Schemes provide a way to reference files independent of their physical paths (which may change in the future). + +The most useful URI schemes to remember when customizing background images and icons are: + +| URI Scheme | Corresponding Physical Path | Use / description | +| --- | --- | ---| +| `ms-appdata:///Local/` | `%localappdata%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\` | Per-machine files | +| `ms-appdata:///Roaming/` | `%localappdata%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\RoamingState\` | Common files | + +> ⚠ Note: 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. + +### Icons +Terminal displays icons for each of your profiles which Terminal generates for any built-in shells - PowerShell Core, PowerShell, and any installed Linux/WSL distros. Each profile refers to a stock icon via the `ms-appx` URI Scheme. + +> ⚠ Note: Do not rely on the files referenced by the `ms-appx` URI Scheme - they are considered an internal implementation detail and may change name/location or may be omitted in the future. + +You can refer to you own icons if you wish, e.g.: + +```json + "icon" : "C:\\Users\\richturn\\OneDrive\\WindowsTerminal\\icon-ubuntu-32.png", +``` + +> 👉 Tip: Icons should be sized to 32x32px in an appropriate raster image format (e.g. .PNG, .GIF, or .ICO) to avoid having to scale your icons during runtime (causing a noticeable delay and loss of quality.) + +### Custom Background Images +You can apply a background image to each of your profiles, allowing you to configure/brand/style each of your profiles independently from one another if you wish. + +To do so, specify your preferred `backgroundImage`, position it using `backgroundImageAlignment`, set its opacity with `backgroundImageOpacity`, and/or specify how your image fill the available space using `backgroundImageStretchMode`. + +For example: +```json + "backgroundImage": "C:\\Users\\richturn\\OneDrive\\WindowsTerminal\\bg-ubuntu-256.png", + "backgroundImageAlignment": "bottomRight", + "backgroundImageOpacity": 0.1, + "backgroundImageStretchMode": "none" +``` + +> 👉 Tip: You can easily roam your collection of images and icons across all your machines by storing your icons and images in OneDrive (as shown above). + +With these settings, your Terminal's Ubuntu profile would look similar to this: + +![Custom icon and background image](../images/custom-icon-and-background-image.jpg) diff --git a/doc/cascadia/profiles.schema.json b/doc/cascadia/profiles.schema.json index f3238665e4a..6d42723b64a 100644 --- a/doc/cascadia/profiles.schema.json +++ b/doc/cascadia/profiles.schema.json @@ -323,6 +323,15 @@ "description": "When set to `true`, the window will snap to the nearest character boundary on resize. When `false`, the window will resize 'smoothly'", "type": "boolean" }, + "tabWidthMode": { + "default": "equal", + "description": "Sets the width of the tabs.", + "enum": [ + "equal", + "titleLength" + ], + "type": "string" + }, "wordDelimiters": { "default": " ./\\()\"'-:,.;<>~!@#$%^&*|+=[]{}~?│", "description": "Determines the delimiters used in a double click selection.", diff --git a/src/cascadia/TerminalApp/GlobalAppSettings.cpp b/src/cascadia/TerminalApp/GlobalAppSettings.cpp index b1f856c2c2f..7c41ba6ea36 100644 --- a/src/cascadia/TerminalApp/GlobalAppSettings.cpp +++ b/src/cascadia/TerminalApp/GlobalAppSettings.cpp @@ -15,6 +15,7 @@ using namespace winrt::TerminalApp; using namespace winrt::Windows::Data::Json; using namespace winrt::Windows::UI::Xaml; using namespace ::Microsoft::Console; +using namespace winrt::Microsoft::UI::Xaml::Controls; static constexpr std::string_view KeybindingsKey{ "keybindings" }; static constexpr std::string_view DefaultProfileKey{ "defaultProfile" }; @@ -25,6 +26,9 @@ static constexpr std::string_view RowsToScrollKey{ "rowsToScroll" }; static constexpr std::string_view InitialPositionKey{ "initialPosition" }; static constexpr std::string_view ShowTitleInTitlebarKey{ "showTerminalTitleInTitlebar" }; static constexpr std::string_view RequestedThemeKey{ "requestedTheme" }; +static constexpr std::string_view TabWidthModeKey{ "tabWidthMode" }; +static constexpr std::wstring_view EqualTabWidthModeValue{ L"equal" }; +static constexpr std::wstring_view TitleLengthTabWidthModeValue{ L"titleLength" }; static constexpr std::string_view ShowTabsInTitlebarKey{ "showTabsInTitlebar" }; static constexpr std::string_view WordDelimitersKey{ "wordDelimiters" }; static constexpr std::string_view CopyOnSelectKey{ "copyOnSelect" }; @@ -49,6 +53,7 @@ GlobalAppSettings::GlobalAppSettings() : _showTitleInTitlebar{ true }, _showTabsInTitlebar{ true }, _requestedTheme{ ElementTheme::Default }, + _tabWidthMode{ TabViewWidthMode::Equal }, _wordDelimiters{ DEFAULT_WORD_DELIMITERS }, _copyOnSelect{ false }, _launchMode{ LaunchMode::DefaultMode } @@ -114,6 +119,16 @@ void GlobalAppSettings::SetRequestedTheme(const ElementTheme requestedTheme) noe _requestedTheme = requestedTheme; } +TabViewWidthMode GlobalAppSettings::GetTabWidthMode() const noexcept +{ + return _tabWidthMode; +} + +void GlobalAppSettings::SetTabWidthMode(const TabViewWidthMode tabWidthMode) +{ + _tabWidthMode = tabWidthMode; +} + std::wstring GlobalAppSettings::GetWordDelimiters() const noexcept { return _wordDelimiters; @@ -206,6 +221,7 @@ Json::Value GlobalAppSettings::ToJson() const jsonObject[JsonKey(CopyOnSelectKey)] = _copyOnSelect; jsonObject[JsonKey(LaunchModeKey)] = winrt::to_string(_SerializeLaunchMode(_launchMode)); jsonObject[JsonKey(RequestedThemeKey)] = winrt::to_string(_SerializeTheme(_requestedTheme)); + jsonObject[JsonKey(TabWidthModeKey)] = winrt::to_string(_SerializeTabWidthMode(_tabWidthMode)); jsonObject[JsonKey(KeybindingsKey)] = _keybindings->ToJson(); jsonObject[JsonKey(SnapToGridOnResizeKey)] = _SnapToGridOnResize; @@ -291,6 +307,11 @@ void GlobalAppSettings::LayerJson(const Json::Value& json) _requestedTheme = _ParseTheme(GetWstringFromJson(requestedTheme)); } + if (auto tabWidthMode{ json[JsonKey(TabWidthModeKey)] }) + { + _tabWidthMode = _ParseTabWidthMode(GetWstringFromJson(tabWidthMode)); + } + if (auto keybindings{ json[JsonKey(KeybindingsKey)] }) { _keybindings->LayerJson(keybindings); @@ -454,6 +475,41 @@ std::wstring_view GlobalAppSettings::_SerializeLaunchMode(const LaunchMode launc } } +// Method Description: +// - Helper function for converting the user-specified tab width +// to a TabViewWidthMode enum value +// Arguments: +// - tabWidthModeString: The string value from the settings file to parse +// Return Value: +// - The corresponding enum value which maps to the string provided by the user +TabViewWidthMode GlobalAppSettings::_ParseTabWidthMode(const std::wstring& tabWidthModeString) noexcept +{ + if (tabWidthModeString == TitleLengthTabWidthModeValue) + { + return TabViewWidthMode::SizeToContent; + } + // default behavior for invalid data or EqualTabWidthValue + return TabViewWidthMode::Equal; +} + +// Method Description: +// - Helper function for converting a TabViewWidthMode to its corresponding string +// value. +// Arguments: +// - tabWidthMode: The enum value to convert to a string. +// Return Value: +// - The string value for the given TabWidthMode +std::wstring_view GlobalAppSettings::_SerializeTabWidthMode(const TabViewWidthMode tabWidthMode) noexcept +{ + switch (tabWidthMode) + { + case TabViewWidthMode::SizeToContent: + return TitleLengthTabWidthModeValue; + default: + return EqualTabWidthModeValue; + } +} + // Method Description: // - Adds the given colorscheme to our map of schemes, using its name as the key. // Arguments: diff --git a/src/cascadia/TerminalApp/GlobalAppSettings.h b/src/cascadia/TerminalApp/GlobalAppSettings.h index 952fbfc5c4c..4831a62c537 100644 --- a/src/cascadia/TerminalApp/GlobalAppSettings.h +++ b/src/cascadia/TerminalApp/GlobalAppSettings.h @@ -52,6 +52,8 @@ class TerminalApp::GlobalAppSettings final void SetRequestedTheme(const winrt::Windows::UI::Xaml::ElementTheme requestedTheme) noexcept; + void SetTabWidthMode(const winrt::Microsoft::UI::Xaml::Controls::TabViewWidthMode tabWidthMode); + bool GetShowTabsInTitlebar() const noexcept; void SetShowTabsInTitlebar(const bool showTabsInTitlebar) noexcept; @@ -70,6 +72,8 @@ class TerminalApp::GlobalAppSettings final winrt::Windows::UI::Xaml::ElementTheme GetRequestedTheme() const noexcept; + winrt::Microsoft::UI::Xaml::Controls::TabViewWidthMode GetTabWidthMode() const noexcept; + Json::Value ToJson() const; static GlobalAppSettings FromJson(const Json::Value& json); void LayerJson(const Json::Value& json); @@ -100,12 +104,16 @@ class TerminalApp::GlobalAppSettings final std::wstring _wordDelimiters; bool _copyOnSelect; winrt::Windows::UI::Xaml::ElementTheme _requestedTheme; + winrt::Microsoft::UI::Xaml::Controls::TabViewWidthMode _tabWidthMode; winrt::TerminalApp::LaunchMode _launchMode; static winrt::Windows::UI::Xaml::ElementTheme _ParseTheme(const std::wstring& themeString) noexcept; static std::wstring_view _SerializeTheme(const winrt::Windows::UI::Xaml::ElementTheme theme) noexcept; + static std::wstring_view _SerializeTabWidthMode(const winrt::Microsoft::UI::Xaml::Controls::TabViewWidthMode tabWidthMode) noexcept; + static winrt::Microsoft::UI::Xaml::Controls::TabViewWidthMode _ParseTabWidthMode(const std::wstring& tabWidthModeString) noexcept; + static void _ParseInitialPosition(const std::wstring& initialPosition, std::optional& initialX, std::optional& initialY) noexcept; diff --git a/src/cascadia/TerminalApp/TabRowControl.xaml b/src/cascadia/TerminalApp/TabRowControl.xaml index 1f1794802f7..26cd9dc0ccd 100644 --- a/src/cascadia/TerminalApp/TabRowControl.xaml +++ b/src/cascadia/TerminalApp/TabRowControl.xaml @@ -14,7 +14,7 @@ the MIT License. See LICENSE in the project root for license information. --> VerticalAlignment="Bottom" HorizontalContentAlignment="Stretch" IsAddTabButtonVisible="false" - TabWidthMode="SizeToContent" + TabWidthMode="Equal" CanReorderTabs="True" CanDragTabs="True" AllowDropTabs="True"> diff --git a/src/cascadia/TerminalApp/TerminalPage.cpp b/src/cascadia/TerminalApp/TerminalPage.cpp index 7e22e319c71..0f789142365 100644 --- a/src/cascadia/TerminalApp/TerminalPage.cpp +++ b/src/cascadia/TerminalApp/TerminalPage.cpp @@ -127,6 +127,7 @@ namespace winrt::TerminalApp::implementation _tabView.TabItemsChanged({ this, &TerminalPage::_OnTabItemsChanged }); _CreateNewTabFlyout(); + _UpdateTabWidthMode(); _OpenNewTab(nullptr); _tabContent.SizeChanged({ this, &TerminalPage::_OnContentSizeChanged }); @@ -695,6 +696,13 @@ namespace winrt::TerminalApp::implementation } } + // Method Description: + // - Handle changes to the tab width set by the user + void TerminalPage::_UpdateTabWidthMode() + { + _tabView.TabWidthMode(_settings->GlobalSettings().GetTabWidthMode()); + } + // Method Description: // - Handle changes in tab layout. void TerminalPage::_UpdateTabView() @@ -1416,6 +1424,7 @@ namespace winrt::TerminalApp::implementation // profile, which might have changed if (auto page{ weakThis.get() }) { + page->_UpdateTabWidthMode(); page->_CreateNewTabFlyout(); } }); diff --git a/src/cascadia/TerminalApp/TerminalPage.h b/src/cascadia/TerminalApp/TerminalPage.h index 0be45149fef..4e059e35271 100644 --- a/src/cascadia/TerminalApp/TerminalPage.h +++ b/src/cascadia/TerminalApp/TerminalPage.h @@ -84,6 +84,7 @@ namespace winrt::TerminalApp::implementation void _UpdateTitle(std::shared_ptr tab); void _UpdateTabIcon(std::shared_ptr tab); void _UpdateTabView(); + void _UpdateTabWidthMode(); void _DuplicateTabViewItem(); void _RemoveTabViewItem(const Microsoft::UI::Xaml::Controls::TabViewItem& tabViewItem); void _RemoveTabViewItemByIndex(uint32_t tabIndex); diff --git a/src/cascadia/TerminalApp/defaults.json b/src/cascadia/TerminalApp/defaults.json index 4f62cd9dfbc..14a84fb1d61 100644 --- a/src/cascadia/TerminalApp/defaults.json +++ b/src/cascadia/TerminalApp/defaults.json @@ -7,6 +7,7 @@ "requestedTheme": "system", "showTabsInTitlebar": true, "showTerminalTitleInTitlebar": true, + "tabWidthMode": "equal", "snapToGridOnResize": false, "wordDelimiters": " /\\()\"'-.,:;<>~!@#$%^&*|+=[]{}~?\u2502",