Robert Jordan 89190c6e6c Add support for background image alignment (as one setting) (#1959 )

* Implement base background image alignment settings

TerminalSettings now has two new properties:
* BackgroundImageHorizontalAlignment
* BackgroundImageVerticalAlignment

These properties are used in TermControl::_InitializeBackgroundBrush to specify the alignment for TermControl::_bgImageLayer.

This is a base commit that will split into two possible branches:
* Use one setting in profiles.json: "backgroundImageAlignment"
* Use two settings in profiles.json: "backgroundImageHorizontal/VerticalAlignment"

* Implement background image alignment profile setting

Implement background image alignment as one profile setting.
* This has the benefit of acting as a single setting when the user would likely want to change both horizontal and vertical alignment.
* HorizontalAlignment and VerticalAlignment are still stored as a tuple in Profile because they are an optional field. And thus, it would not make sense for one of the alignments to be left unused while the other is not.
* Cons are that the tuple signature is quite long, but it is only used in a small number of locations. The Serialize method is also a little mishapen with the nested switch statements. Empty lines have been added between base-level cases to improve readability.

* Fix capitalization typo for BackgroundImageStretchModeKey

In Profiles.cpp, the key for the image stretch mode json property had a lowercase 'i' in "Backgroundimage", not following proper UpperCamelCase.
The "i" has been capitalized and the two usages of the constant have been updated as well.

* Document Background Image settings

* Adds entries SettingsSchema.md for the original 3 backgroundImage settings in addition to the new backgroundImageAlignment setting.

* Fix setting capitalization error in UsingJsonSettings.md

* The background image example in UsingJsonSettings.md listing a backgroundImageStretchMode of "Fill" has been corrected to "fill".


Fixes #1949.

2019-07-24 21:47:06 -07:00

4.5 KiB

Raw Blame History

Editing Windows Terminal JSON Settings

One way (currently the only way) to configure Windows Terminal is by editing the profiles.json settings file. At the time of writing you can open the settings file in your default editor by selecting Settings from the WT pull down menu.

The settings are stored in the file $env:LocalAppData\Packages\Microsoft.WindowsTerminal_<randomString>\RoamingState\profiles.json

Details of specific settings can be found here. A general introduction is provided below.

The settings are grouped under four headings:

Global: Settings that apply to the whole application e.g. Default profile, initial size etc.
Key Bindings: Actually a sub field of the global settings, but worth discussing separately
Profiles: A group of settings to be applied to a tab when it is opened using that profile. E.g. shell to use, cursor shape etc.
Schemes: Sets of colors for background, text etc. that can be used by profiles

Global Settings

These settings define startup defaults.

Theme
Title Bar options
Initial size
Default profile used when WT is started

Example settings include

    "defaultProfile" : "{58ad8b0c-3ef8-5f4d-bc6f-13e4c00f2530}",
    "initialCols" : 120,
    "initialRows" : 50,
    "requestedTheme" : "system",
    "keybinding" : []
    ...

Key Bindings

This is an array of key chords and shortcuts to invoke various commands. Each command can have more than one key binding.

NOTE: Key bindings is a subfield of the global settings and key bindings apply to all profiles in the same manner.

Profiles

A profile contains the settings applied when a new WT tab is opened. Each profile is identified by a GUID and contains a number of other fields.

Which command to execute on startup - this can include arguments.
Starting directory
Which color scheme to use (see Schemes below)
Font face and size
Various settings to control appearance. E.g. Opacity, icon, cursor appearance, display name etc.
Other behavioural settings. E.g. Close on exit, snap on input, .....

Example settings include

    "closeOnExit" : true,
    "colorScheme" : "Campbell",
    "commandline" : "wsl.exe -d Debian",
    "cursorColor" : "#FFFFFF",
    "cursorShape" : "bar",
    "fontFace" : "Hack",
    "fontSize" : 9,
    "guid" : "{58ad8b0c-3ef8-5f4d-bc6f-13e4c00f2530}",
    "name" : "Debian",
    "startingDirectory" : "%USERPROFILE%/wslhome"
    ....

The profile GUID is used to reference the default profile in the global settings.

The values for background image stretch mode are documented here

Color Schemes

Each scheme defines the color values to be used for various terminal escape sequences. Each schema is identified by the name field. Examples include

    "name" : "Campbell",
    "background" : "#0C0C0C",
    "black" : "#0C0C0C",
    "blue" : "#0037DA",
    "foreground" : "#F2F2F2",
    "green" : "#13A10E",
    "red" : "#C50F1F",
    "white" : "#CCCCCC",
    "yellow" : "#C19C00"
    ...

The schema name can then be referenced in one or more profiles.

Configuration Examples:

Add a custom background to the WSL Debian terminal profile

Download the Debian SVG logo https://www.debian.org/logos/openlogo.svg
Put the image in the $env:LocalAppData\Packages\Microsoft.WindowsTerminal_<randomString>\RoamingState\ directory (same directory as your profiles.json file).

NOTE: You can put the image anywhere you like, the above suggestion happens to be convenient.
Open your WT json properties file.
Under the Debian Linux profile, add the following fields:

    "backgroundImage": "ms-appdata:///Roaming/openlogo.jpg",
    "backgroundImageOpacity": 0.3,
    "backgroundImageStretchMode":  "fill",

Make sure that useAcrylic is false.
Save the file.
Jump over to WT and verify your changes.

Notes:

You will need to experiment with different color settings and schemes to make your terminal text visible on top of your image
If you store the image in the UWP directory (the same directory as your profiles.json file), then you should use the URI style path name given in the above example. More information about UWP URI schemes here.
Instead of using a UWP URI you can use a:
1. URL such as http://open.esa.int/files/2017/03/Mayer_and_Bond_craters_seen_by_SMART-1-350x346.jpg
2. Local file location such as C:\Users\Public\Pictures\openlogo.jpg

4.5 KiB Raw Blame History