Skip to content

Commit

Permalink
Add Cascading User + Default Settings (#2515)
Browse files Browse the repository at this point in the history 
This PR represents the start of the work on Cascading User + default settings, #754.

Cascading settings will be done in two parts: 
* [ ] Layered Default+User settings (this PR)
* [ ] Dynamic Profile Generation (#2603).

Until _both_ are done, _neither are going in. The dynamic profiles PR will target this PR when it's ready, but will go in as a separate commit into master.

This PR covers adding one primary feature: the settings are now in two separate files:
* a static `defaults.json` that ships with the package (the "default settings")
* a `profiles.json` with the user's customizations (the "user settings)

User settings are _layered_ upon the settings in the defaults settings.

## References

Other things that might be related here:
* #1378 - This seems like it's definitely fixed. The default keybindings are _much_ cleaner, and without the save-on-load behavior, the user's keybindings will be left in a good state 
* #1398 - This might have honestly been solved by #2475 

## PR Checklist
* [x] Closes #754
* [x] Closes #1378 
* [x] Closes #2566
* [x] I work here
* [x] Tests added/passed
* [x] Requires documentation to be updated - it **ABSOLUTELY DOES**


## Detailed Description of the Pull Request / Additional comments

1. We start by taking all of the `FromJson` functions in Profile, ColorScheme, Globals, etc, and converting them to `LayerJson` methods. These are effectively the same, with the change that instead of building a new object, they are simply layering the values on top of `this` object. 
2. Next, we add tests for layering properties like that.
3. Now, we add a `defaults.json` to the package. This is the file the users can refer to as our default settings.
4. We then take that `defaults.json` and stamp it into an auto generated `.h` file, so we can use it's data without having to worry about reading it from disk.
5. We then change the `LoadAll` function in `CascadiaSettings`. Now, the function does two loads - one from the defaults, and then a second load from the `profiles.json` file, layering the settings from each source upon the previous values.
6. If the `profiles.json` file doesn't exist, we'll create it from a hardcoded `userDefaults.json`, which is stamped in similar to how `defaults.json` is.
7. We also add support for _unbinding_ keybindings that might exist in the `defaults.json`, but the user doesn't want to be bound to anything.
8. We add support for _hiding_ a profile, which is useful if a user doesn't want one of the default profiles to appear in the list of profiles.

## TODO:
* [x] Still need to make Alt+Click work on the settings button
* [x] Need to write some user documentation on how the new settings model works
* [x] Fix the pair of tests I broke (re: Duplicate profiles)


<hr>

* Create profiles by layering them

* Update test to layer multiple times on the same profile

* Add support for layering an array of profiles, but break a couple tests

* Add a defaults.json to the package

* Layer colorschemes

  * Moves tests into individual classes
  * adds support for layering a colorscheme on top of another

* Layer an array of color schemes

* oh no, this was missed with #2481

  must have committed without staging this change, uh oh. Not like those tests actually work so nbd

* Layer keybindings

* Read settings from defaults.json + profiles.json, layer appropriately

  This is like 80% of #754. Needs tests.

* Add tests for keybindings

  * add support to unbind a key with `null` or `"unbound"` or `"garbage"`

* Layer or clear optional properties

* Add a helper to get an optional variable for a bunch of different types

  In the end, I think we need to ask _was this worth it_

* Do this with the stretch mode too

* Add back in the GUID check for profiles

* Add some tests for global settings layering

* M A D  W I T H  P O W E R

  Add a MsBuild target to auto-generate a header with the defaults.json as a
  string in the file. That way, we can _always_ load the defaults. Literally impossible to not.

* When the user's profile.json doesn't exist, create it from a template

* Re-order profiles to match the order set in the user's profiles.json

* Add tests for re-ordering profiles to match user ordering

* Add support for hiding profiles using `"hidden": true`

* Use the hardcoded defaults.json for the exception->"use defaults" case

* Somehow I messed up the git submodules?

* woo documentation

* Fix a Terminal.App.Unit.Tests failure

* signed/unsigned is hard

* Use Alt+Settings button to open the default settings

* Missed a signed/unsigned

* Some very preliminary PR feedback

* More PR feedback

  Use the wil helper for the exe path
  Move jsonutils into their own file
  kill some dead code

* Add templates to these bois

* remove some code for generating defaults, reorder defaults.json a tad

* Make guid a std::optional

* Large block of PR feedback

  * Remove some dead code
  * add some comments
  * tag some todos

* stl is love, stl is life

* add `-noprofile`

* Fix the crash that dustin found

* -Encoding ASCII

* Set a profile's default scheme to Campbell

* Fix the tests I regressed

* Update UsingJsonSetting.md to reflect that changes from these PRs

* Change how GenerateGuidForProfile works

* Make AppKeyBindings do its own serialization

* Remove leftover dead code from the previous commit

* Fix up an enormous number of PR nits

* Fix a typo; Update the defaults to match #2378

* Tiny nits

* Some typos, PR nits

* Fix this broken defaults case
  • Loading branch information
@zadjii-msft
zadjii-msft authored Sep 16, 2019
1 parent ed87689 commit 8ba8f35
Show file tree
Hide file tree
Showing 36 changed files with 2,783 additions and 699 deletions.
138 changes: 120 additions & 18 deletions doc/user-docs/UsingJsonSettings.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,22 @@
# 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.
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`
The settings are stored in the file `$env:LocalAppData\Packages\Microsoft.WindowsTerminal_<randomString>\RoamingState\profiles.json`.

Details of specific settings can be found [here](../cascadia/SettingsSchema.md). A general introduction is provided below.
As of [#2515](https://github.com/microsoft/terminal/pull/2515), the settings are
split into _two_ files: a hardcoded `defaults.json`, and `profiles.json`, which
contains the user settings. Users should only be concerned with the contents of
the `profiles.json`, which contains their customizations. The `defaults.json`
file is only provided as a reference of what the default settings are. For more
details on how these two files work, see [Settings
Layering](#settings-layering). To view the default settings file, click on the
"Settings" button while holding the <kbd>Alt</kbd> key.

Details of specific settings can be found [here](../cascadia/SettingsSchema.md).
A general introduction is provided below.

The settings are grouped under four headings:

Expand All @@ -17,12 +27,13 @@ The settings are grouped under four headings:

## Global Settings

These settings define startup defaults.
These settings define startup defaults, and application-wide settings that might
not affect a particular terminal instance.

* Theme
* Title Bar options
* Initial size
* Default profile used when WT is started
* Default profile used when the Windows Terminal is started

Example settings include

Expand All @@ -31,10 +42,13 @@ Example settings include
"initialCols" : 120,
"initialRows" : 50,
"requestedTheme" : "system",
"keybinding" : []
"keybindings" : []
...
```

These global properties can exist either in the root json object, or in and
object under a root property `"globals"`.

## Key Bindings

This is an array of key chords and shortcuts to invoke various commands.
Expand All @@ -43,10 +57,29 @@ 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.

For example, here's a sample of the default keybindings:

```json
{
"keybindings":
[
{ "command": "closePane", "keys": ["ctrl+shift+w"] },
{ "command": "copy", "keys": ["ctrl+shift+c"] },
{ "command": "newTab", "keys": ["ctrl+shift+t"] },
// etc.
]
}

```

## 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.
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.

> 👉 **Note**: The `guid` property is the unique identifier for a profile. If
> multiple profiles all have the same `guid` value, you may see unexpected
> behavior.
* Which command to execute on startup - this can include arguments.
* Starting directory
Expand Down Expand Up @@ -77,6 +110,14 @@ The profile GUID is used to reference the default profile in the global settings

The values for background image stretch mode are documented [here](https://docs.microsoft.com/en-us/uwp/api/windows.ui.xaml.media.stretch)

### Hiding a profile

If you want to remove a profile from the list of profiles in the new tab
dropdown, but keep the profile around in your `profiles.json` file, you can add
the property `"hidden": true` to the profile's json. This can also be used to
remove the default `cmd` and PowerShell profiles, if the user does not wish to
see them.

## Color Schemes

Each scheme defines the color values to be used for various terminal escape sequences.
Expand All @@ -97,6 +138,62 @@ Each schema is identified by the name field. Examples include

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

## Settings layering

The runtime settings are actually constructed from _three_ sources:
* The default settings, which are hardcoded into the application, and available
in `defaults.json`. This includes the default keybindings, color schemes, and
profiles for both Windows PowerShell and Command Prompt (`cmd.exe`).
* Dynamic Profiles, which are generated at runtime. These include Powershell
Core, the Azure Cloud Shell connector, and profiles for and WSL distros.
* The user settings from `profiles.json`.

Settings from each of these sources are "layered" upon the settings from
previous sources. In this manner, the user settings in `profiles.json` can
contain _only the changes from the default settings_. For example, if a user
would like to only change the color scheme of the default `cmd` profile to
"Solarized Dark", you could change your cmd profile to the following:

```js
{
// Make changes here to the cmd.exe profile
"guid": "{0caa0dad-35be-5f56-a8ff-afceeeaa6101}",
"colorScheme": "Solarized Dark"
}
```

Here, we're know we're changing the `cmd` profile, because the `guid`
`"{0caa0dad-35be-5f56-a8ff-afceeeaa6101}"` is `cmd`'s unique GUID. Any profiles
with that GUID will all be treated as the same object. Any changes in that
profile will overwrite those from the defaults.

Similarly, you can overwrite settings from a color scheme by defining a color
scheme in `profiles.json` with the same name as a default color scheme.

If you'd like to unbind a keystroke that's bound to an action in the default
keybindings, you can set the `"command"` to `"unbound"` or `null`. This will
allow the keystroke to fallthough to the commandline application instead of
performing the default action.

### Dynamic Profiles

When dynamic profiles are created at runtime, they'll be added to the
`profiles.json` file. You can identify these profiles by the presence of a
`"source"` property. These profiles are tied to their source - if you uninstall
a linux distro, then the profile will remain in your `profiles.json` file, but
the profile will be hidden.

If you'd like to disable a particular dynamic profile source, you can add that
`source` to the global `"disabledProfileSources"` array. For example, if you'd
like to hide all the WSL profiles, you could add the following setting:

```json

"disabledProfileSources": ["Microsoft.Terminal.WSL"],
...

```

## Configuration Examples:

### Add a custom background to the WSL Debian terminal profile
Expand Down Expand Up @@ -127,15 +224,17 @@ then you should use the URI style path name given in the above example.
More information about UWP URI schemes [here](https://docs.microsoft.com/en-us/windows/uwp/app-resources/uri-schemes).
3. 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`
`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`

### Adding Copy and Paste Keybindings
### Adding Copy and Paste Keybindings

As of [#1093](https://github.com/microsoft/terminal/pull/1093) (first available in Windows Terminal v0.3), the Windows Terminal now
supports copy and paste keyboard shortcuts. However, if you installed and ran
the terminal before that, you won't automatically get the new keybindings added
to your settings. If you'd like to add shortcuts for copy and paste, you can do so by inserting the following objects into your `globals.keybindings` array:
As of [#1093](https://github.com/microsoft/terminal/pull/1093) (first available
in Windows Terminal v0.3), the Windows Terminal now supports copy and paste
keyboard shortcuts. However, if you installed and ran the terminal before that,
you won't automatically get the new keybindings added to your settings. If you'd
like to add shortcuts for copy and paste, you can do so by inserting the
following objects into your `globals.keybindings` array:

```json
{ "command": "copy", "keys": ["ctrl+shift+c"] },
Expand Down Expand Up @@ -171,5 +270,8 @@ You can even set multiple keybindings for a single action if you'd like. For exa
will bind both <kbd>ctrl+shift+v</kbd> and
<kbd>shift+Insert</kbd> to `paste`.

Note: If you set your copy keybinding to `"ctrl+c"`, you'll only be able to send an interrupt to the commandline application using <kbd>Ctrl+C</kbd> when there's no text selection.
Additionally, if you set `paste` to `"ctrl+v"`, commandline applications won't be able to read a ctrl+v from the input. For these reasons, we suggest `"ctrl+shift+c"` and `"ctrl+shift+v"`
Note: If you set your copy keybinding to `"ctrl+c"`, you'll only be able to send
an interrupt to the commandline application using <kbd>Ctrl+C</kbd> when there's
no text selection. Additionally, if you set `paste` to `"ctrl+v"`, commandline
applications won't be able to read a ctrl+v from the input. For these reasons,
we suggest `"ctrl+shift+c"` and `"ctrl+shift+v"`
8 changes: 8 additions & 0 deletions src/cascadia/CascadiaPackage/CascadiaPackage.wapproj
View file
Original file line number Diff line number Diff line change
Expand Up @@ -249,6 +249,7 @@
<Content Include="$(OpenConsoleDir)res\terminal\Wide310x150Logo.scale-400.png">
<Link>Images\Wide310x150Logo.scale-400.png</Link>
</Content>
<!-- Profile Icons -->
<Content Include="ProfileIcons\{0caa0dad-35be-5f56-a8ff-afceeeaa6101}.scale-100.png" />
<Content Include="ProfileIcons\{0caa0dad-35be-5f56-a8ff-afceeeaa6101}.scale-200.png" />
<Content Include="ProfileIcons\{574e775e-4f2a-5b96-ac1e-a2962a402336}.scale-100.png" />
Expand All @@ -259,9 +260,16 @@
<Content Include="ProfileIcons\{9acb9455-ca41-5af7-950f-6bca1bc9722f}.scale-200.png" />
<Content Include="ProfileIcons\{b453ae62-4e3d-5e58-b989-0a998ec441b8}.scale-100.png" />
<Content Include="ProfileIcons\{b453ae62-4e3d-5e58-b989-0a998ec441b8}.scale-200.png" />
<!-- Default Settings -->
<Content Include="$(OpenConsoleDir)src\cascadia\TerminalApp\defaults.json">
<Link>defaults.json</Link>
</Content>
<!-- Resources -->
<PRIResource Include="Resources\en-US\Resources.resw" />
</ItemGroup>

<Import Project="$(OpenConsoleDir)src\wap-common.build.post.props" />

<ItemGroup>
<ProjectReference Include="..\WindowsTerminal\WindowsTerminal.vcxproj" />
<ProjectReference Include="..\..\host\exe\Host.EXE.vcxproj" />
Expand Down
Loading

0 comments on commit 8ba8f35

Please sign in to comment.