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

Add initial settings UI spec #6720

Merged
merged 16 commits into from
Sep 9, 2020
Merged

Add initial settings UI spec #6720

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
53242c7
upload first draft of settings UI spec
cinnamon-msft Jun 29, 2020
b414852
Merge branch 'master' into cinnamon/spec-settings-ui
cinnamon-msft Jul 6, 2020
edfd673
update mockup and remove json setting
cinnamon-msft Jul 7, 2020
f289008
add another nav option
cinnamon-msft Jul 8, 2020
70d76b2
Merge branch 'master' into cinnamon/spec-settings-ui
cinnamon-msft Jul 13, 2020
de97933
update from discussion on Friday
cinnamon-msft Jul 13, 2020
47698e6
update navigation image
cinnamon-msft Jul 13, 2020
ae30dc9
add design doc
cinnamon-msft Jul 13, 2020
3b6701f
make the spelling bot stop yelling at me
cinnamon-msft Jul 13, 2020
2f31826
spell bot pls
cinnamon-msft Jul 13, 2020
2eecb22
add keyboard mockups
cinnamon-msft Jul 24, 2020
79e2b25
Update doc/specs/#1564 - Settings UI/spec.md
cinnamon-msft Jul 24, 2020
44d0c84
Merge branch 'master' into cinnamon/spec-settings-ui
cinnamon-msft Aug 10, 2020
c67e8f5
address feedback
cinnamon-msft Aug 10, 2020
fe4b76d
fix spelling
cinnamon-msft Aug 10, 2020
53e305c
address feedback
cinnamon-msft Aug 11, 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
Binary file added doc/specs/#1564 - Settings UI/appearance.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
112 changes: 112 additions & 0 deletions doc/specs/#1564 - Settings UI/design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
---
author: Kayla Cinnamon @cinnamon-msft
created on: 2020-07-13
last updated: 2020-08-11
issue id: #1564
---

# Settings UI Design

## Abstract

This design document describes how each page of the settings UI will be laid out along with design mockups to display how the UI will appear. The mock ups are for appearance purposes and some layouts and naming may be different in this doc. This doc should be considered the final say.

## UI Design

### Overall navigation with Startup page

This is the list of the top-level navigation items that will appear on the left nav bar:

- General
- Startup
- Interaction
- Rendering
- Appearance
- Global
- Color schemes
- Themes*
- Profiles
- Defaults
- Enumerate profiles
- Add new
- Keyboard
- Mouse*
- Command Palette*
- Marketplace*

\* Themes, mouse, command palette, and marketplace will be added once they're implemented.

![Overall navigation](./navigation-2.png)

### Profile appearance page

This page requires special design because it includes the TerminalControl window to preview appearance changes. This preview window will appear on the following pages:

- Appearance - Color Schemes
- Profiles - Appearance

![Appearance page](./appearance.png)

### Keyboard page
cinnamon-msft marked this conversation as resolved.
Show resolved Hide resolved

The keyboard page will list the enabled key bindings and provide a way for users to add and remove them.

![Keyboard page](./keyboard.png)

When someone hovers over one of the items in the table, the Edit and Delete buttons will appear. Below is what the modal looks like if they were to click Edit on a command that does not have any arguments/actions. In the future, we would want this text box to be able to listen for key combinations. This would add a "listen" button to the UI.

![Keyboard page modal](./keyboard-modal.png)

If the command they select has additional arguments/actions, the modal will dynamically size as arguments/actions are added.

![Keyboard page modal add new arguments](./keyboard-modal-add.png)

![Keyboard page modal arguments](./keyboard-modal-args.png)

## Settings layout

Below is the list of all settings on their respective pages in the settings UI. The title row aligns with the navigation view on the left of the UI. Bolded headers in those columns align with top nav on the page.

| General - Startup | General - Interaction | General - Rendering | Appearance - Global | Appearance - Color Schemes | Profiles - Global | Profiles - Enumerate profiles | Profiles - Add new |
| ---------------- | --------------------- | ------------------- | ------------------- | -------------------------- | ----------------- | ----------------------------- | ------------------ |
| Default profile (dropdown) | Copy after selection is made (checkbox) | Software rendering (checkbox) | Theme (radio) | Name (text box) | **General** | **General** | **General** | **General** |
| Launch on startup (checkbox) | Copy formatting (checkbox) | Screen redrawing (checkbox) | Show/Hide the title bar (checkbox) | Cursor color (color picker) | Command line (text box) | Scrollbar visibility (radio) | Scrollbar visibility (radio) |
| Launch size (radio) | Word delimiters (text box) | | Show terminal title in title bar (checkbox) | Selection background (color picker) | Starting directory (browse button) | Command line (browse button) | Command line (browse button) |
| Launch position (text box) | Window resize behavior (checkbox) | | Always show tabs (checkbox) | Background (color picker) | Icon (browse button) | Starting directory (browse button) | Starting directory (browse button) |
| Columns on first launch (number picker) | | | Tab width mode (radio) | Foreground (color picker) | Tab title (text box) | Name (text box) | Name (text box) |
| Rows on first launch (number picker) | | | Hide close all tabs popup (checkbox) | Black (color picker) | Scrollbar visibility (radio) | Icon (browse button) | Icon (browse button) |
| Automatically create new profiles when new shells are installed (checkbox) | | | | Blue (color picker) | **Appearance** | Tab title (text box) | Tab title (text box) |
| | | | | Cyan (color picker) | Font face (text box) | **Appearance** | **Appearance** |
| | | | | Green (color picker) | Font size (number picker) | Retro terminal effects (checkbox) | Retro terminal effects (checkbox) |
| | | | | Purple (color picker) | Font weight (dropdown) | Font face (text box) | Font face (text box) |
| | | | | Red (color picker) | Padding (text box) | Font size (number picker) | Font size (number picker) |
| | | | | White (color picker) | Cursor shape (radio) | Font weight (dropdown) | Font weight (dropdown) |
| | | | | Yellow (color picker) | Cursor color (color picker) | Padding (text box) | Padding (text box) |
| | | | | Bright black (color picker) | Cursor height (number picker) | Cursor shape (radio) | Cursor shape (radio) |
| | | | | Bright blue (color picker) | Color scheme (dropdown) | Cursor color (color picker) | Cursor color (color picker) |
| | | | | Bright cyan (color picker) | Foreground color (color picker) | Cursor height (number picker) | Cursor height (number picker) |
| | | | | Bright green (color picker) | Background color (color picker) | Color scheme (dropdown) | Color scheme (dropdown) |
| | | | | Bright purple (color picker) | Selection background color (color picker) | Foreground color (color picker) | Foreground color (color picker) |
| | | | | Bright red (color picker) | Enable acrylic (checkbox) | Background color (color picker) | Background color (color picker) |
| | | | | Bright white (color picker) | Acrylic opacity (number picker) | Selection background color (color picker) | Selection background color (color picker) |
| | | | | Bright yellow (color picker) | Background image (browse button) | Enable acrylic (checkbox) | Enable acrylic (checkbox) |
| | | | | | Background image stretch mode (radio) | Acrylic opacity (number picker) | Acrylic opacity (number picker) |
| | | | | | Background image alignment (dropdown) | Background image (browse button) | Background image (browse button) |
| | | | | | Background image opacity (number picker) | Background image stretch mode (radio) | Background image stretch mode (radio) |
| | | | | | Retro terminal effects (checkbox) | Background image alignment (dropdown) | Background image alignment (dropdown) |
| | | | | | **Advanced** | Background image opacity (number picker) | Background image opacity (number picker) |
| | | | | | Hide profile from dropdown (checkbox) | **Advanced** | **Advanced** |
| | | | | | Suppress title changes (checkbox) | GUID (text box) | GUID (text box) |
| | | | | | Antialiasing text (radio) | Hide profile from dropdown (checkbox) | Hide profile from dropdown (checkbox) |
| | | | | | AltGr aliasing (checkbox) | Suppress title changes (checkbox) | Suppress title changes (checkbox) |
| | | | | | Scroll to input when typing (checkbox) | Antialiasing text (radio) | Antialiasing text (radio) |
| | | | | | History size (number picker) | AltGr aliasing (checkbox) | AltGr aliasing (checkbox) |
| | | | | | How the profile closes (radio) | Scroll to input when typing (checkbox) | Scroll to input when typing (checkbox) |
| | | | | | | History size (number picker) | History size (number picker) |
| | | | | | | How the profile closes (radio) | How the profile closes (radio) |

## Potential Issues

## Future considerations

## Resources
Binary file added doc/specs/#1564 - Settings UI/keyboard-modal-add.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added doc/specs/#1564 - Settings UI/keyboard-modal-args.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added doc/specs/#1564 - Settings UI/keyboard-modal.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added doc/specs/#1564 - Settings UI/keyboard.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added doc/specs/#1564 - Settings UI/navigation-2.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added doc/specs/#1564 - Settings UI/navigation.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
122 changes: 122 additions & 0 deletions doc/specs/#1564 - Settings UI/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
---
author: Kayla Cinnamon @cinnamon-msft
created on: 2020-06-29
last updated: 2020-08-10
issue id: #1564
---

# Settings UI Implementation

## Abstract

This spec describes the basic functionality of the settings UI, including disabling it, the navigation items, launch methods, and editing of settings. The specific layout of each page will defined in later design reviews.

## Inspiration

We have been wanting a settings UI since the dawn of Terminal time, so we need to define how it will interact with the application and how users should expect to interact with it.

## Solution Design

The settings UI will be the default experience. We will provide users an option to skip the settings UI and edit the raw JSON file.

### Ability to disable displaying the settings UI

Some users don't want a UI for the settings. We can update the `openSettings` key binding with a `settingsUI` option.

If people still like the UI but want to access the JSON file, we can provide an "Open the JSON file" button at the bottom of the navigation menu.
Copy link
Member

Choose a reason for hiding this comment

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

Minor thing but it should be mentioned/discussed. How do you open defaults.json from the Settings UI instead of settings.json?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Is this something we want? I'm imagining a "reset to defaults" button, which I can add to this spec.

Copy link
Member

@carlos-zamora carlos-zamora Jul 10, 2020 •
edited
Loading

Choose a reason for hiding this comment

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

Not reset to defaults. Open the defaults.json. Right now, people alt-click "Settings" in the dropdown to open defaults.json. We've seen a ton of cases where people don't actually know that's a thing. Would it be possible to put 2 buttons in the Nav menu?...

  • Open the JSON file
  • Open the Defaults JSON file

(name could use some massaging but you get the idea)


### Launch method: launch in a new tab

Clicking the settings button in the dropdown menu will open the settings UI in a new tab. This helps us take steps toward supporting non-terminal content in a tab. Users will be able to see their visual changes by using the preview window inside the settings UI on relevant pages.

#### We also considered: launch in a new window

Clicking the settings button in the dropdown menu will open the settings UI in a new window. This allows the user to edit their settings and see the Terminal live update with their changes.

In the Windows taskbar, the icon will appear as if Terminal has multiple windows open.

### Editing and saving settings: implement a save button

Users will only see their settings changes take place once they click "Save". Clicking "Save" will write to the settings.json file. This aligns with the functionality that exists today by editing the settings.json file in a text editor and saving it.

Copy link
Member

Choose a reason for hiding this comment

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

opinion - I think I prefer 1 to 2 as far as launching goes. In my head, there was a third "switch the TerminalPage for a SettingsPage" option, where the entire contents of the window were changed into the settings UI until the user dismissed the settings. That certainly doesn't let the user preview the settings as well, and might be technically very challenging (esp with the titlebar shennanigans we currently have.)

We will also be adding a TerminalControl inside the settings UI to preview what the changes will look like before actually saving them to the settings.json file.

#### We also considered: automatically save settings

As users edit fields in the settings UI, they are automatically saved and written to the JSON file. This allows the user to see their settings changes taking place in real time.
Copy link
Member

Choose a reason for hiding this comment

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

I'm not sure how I feel about this. I typically prefer a conscious "save" button. Think of something like the Settings app on Windows - it doesn't really provide any feedback when you change a setting, even though it auto-saves changes. As a user, I often worry that the settings app didn't actually change the values, because there's no feedback that the value I changed was persisted.

That being said, auto-saving is convenient. I think there just needs to be some sort of _subtle_visual cue that the settings were saved when the user makes changes.

Copy link

Choose a reason for hiding this comment

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

I'm just going to aside that it's generally bad to get too far away from the OS default behaviors, so if Windows 10 is auto-saving settings, apps designed for Windows 10 should follow suit or convince MS to go back to the Apply/OK paradigm.

Copy link
Contributor

Choose a reason for hiding this comment

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

My opinion: I liked the Apply/Cancel/Okay button since you can easily revert back if you don't like something.

Copy link
Contributor

Choose a reason for hiding this comment

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

I think there should be an auto-save option. However, there should also be manual option such as Chips has mentioned. So basically how you save the settings should be an option in settings. That can go under a General or Maintenance Page at the very bottom that's used for directly configuring how you want the Settings UI to look and feel as well how it does things like saving.


## UI/UX Design

Layout of all of the settings per page can be found in the [design doc](./design.md).

### Top-level navigation: more descriptive navigation

The navigation menu is broken up into more digestible sections. This aligns more closely to other terminals. The following are the proposed navigation items:

- General
- Startup
- Interaction
- Rendering
- Appearance
- Global
- Color schemes
- Themes*
- Profiles
- Defaults
- Enumerate profiles
Copy link
Member

Choose a reason for hiding this comment

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

When we enumerate the profiles, how are "hidden" profiles handled? Do they still appear in the dropdown, but when you open it, there's a "hidden" switch? Or is there a way we can denote it as hidden in the dropdown (I think that would be the most ideal)?

Copy link
Member

Choose a reason for hiding this comment

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

bug: #4139

Copy link
Member

Choose a reason for hiding this comment

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

So, because of how we serialize "hidden", if a user hides a profile, the only way to un-hide it is to go to the json?

- Add new
- Keyboard
- Mouse*
- Command Palette*
- Marketplace*

\* Themes, mouse, command palette, and marketplace will be added once they're implemented.

![Settings UI navigation 2](./navigation-2.png)

#### We also considered: align with JSON

The settings UI could have top-level navigation that aligns with the overall structure of the settings.json file. The following are the proposed navigation items:

- Globals
- Profiles
- Color schemes
- Bindings

For Bindings, it would have key bindings, mouse bindings, and command palette inside it.

![Settings UI navigation 1](./navigation.png)

## Capabilities

### Accessibility

This will have to undergo full accessibility testing because it is a new UI element. All items inside the settings UI should be accessible by a screen reader and the keyboard. Additionally, all of the settings UI will have to be localized.

### Security

This does not impact security.

### Reliability

This will not improve reliability.

### Compatibility

This will change the default experience to open the UI, rather than the JSON file in a text editor. This behavior can be reverted with the setting listed [above](#ability-to-disable-displaying-the-settings-ui).

### Performance, Power, and Efficiency

This does not affect performance, power, nor efficiency.

## Potential Issues
Copy link
Member

Choose a reason for hiding this comment

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

Do we have any concerns about the way any of the current settings we have will be exposed to the user? Like, are there any where we're worried about what control we use to let the user change the setting?

Copy link
Member

Choose a reason for hiding this comment

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

Keybindings and commands (CmdPlt) are gonna be the weird ones, but Kayla and I have been thinking about them for a while now so you'll get those mockups in the upcoming commits 😉

I think Enum flags might be a bit weird to represent. But we don't really have any settings out right now that use enum flags, so we'll probably just deal with them when the Settings UI XAML is actually being implemented.


## Future considerations

- We will have to have design reviews for all of the content pages.
- The `hidden` property will need special consideration. Ideally, all profiles will appear in the settings regardless if `hidden` is set to `true`.
- We should have undo functionality. In a text editor, you can type `Ctrl+Z` however the settings UI is a bit more complex.
carlos-zamora marked this conversation as resolved.
Show resolved Hide resolved
- Once we have a marketplace for themes and extensions, this should be added to the top-level navigation.
- As we add more features, the top-level navigation is subject to change in favor of improved usability.

## Resources