Provide GUI for settings

[Tyriar]

Customizing Code would be far less intimidating to new users if there was a GUI for settings customization.

[mrmckeb]

I'd like to jump in and work on this, as I've heard the same thing from others. Are there any design guidelines or references, @Tyriar?

[felixfbecker]

I also think this would make more people adopt VS Code. Here are some ideas:

• Similar to how you can switch between markdown code and preview, allow to switch between the settings.json file and a GUI, with the GUI being the default
• Dynamically generate the GUI from the JSON schema, including those from extensions
  • booleans become checkboxes
  • arrays and hashes become lists were it is possible to add / remove new items
  • numbers become spinners
  • strings become input fields
  • union types?

[Tyriar]

@mrmckeb not yet. But speaking of which, this would probably need to go through UX first. ping @bgashler1

[mrmckeb]

Thanks @Tyriar. Perhaps I could start work on the functionality here and we could polish the UX later? The approach would be something similar to what @felixfbecker described, and I also like how the Atom team manage their settings.

[bgashler1]

Nice idea. I previously had a similar idea, and I agree this could be be less intimidating to new users. It could also beneficial to people who don't know JavaScript and who are using VS Code for another language that doesn't have anything like JSON. Finally, JSON can be unforgiving if you miss a comma or closing brace somewhere.

The worry the team had when I shared this idea previously was that a GUI would not be able to do everything JSON could do as simply and effectively. JSON is leaner (you copy just what you need and change just what you need); it's easy to see what you've changed, because you're only overriding defaults. Intellisense also helps people write what they need. Lastly, JSON results in shareable recipes that can be committed or emailed to others.

Despite the drawbacks, @felixfbecker, you have an interesting idea of generating the GUI based off of JSON—with some careful styling and layout rules, this could work well potentially.

@mrmckeb you mentioned that you've heard this from others. Could you point me to that discussion?

[bgashler1]

Google Chrome settings seems like a good source of inspiration since they filter through a mass of settings based off of keywords.

[bgashler1]

@mrmckeb Before we jump into implementation. Let me first check with the team and also get some mockups to be sure we have the experience right. I would hate to waste any effort before we have the experience where it needs to be.

[egamma]

I like the discussion, but we hear different feedback on this topic:

[mrmckeb]

@bgashler1 I've heard in a literal sense, in my office. I don't have a discussion to point you to sorry. I'd argue that whilst the tweet @egamma has shared is a valid reason to keep the JSON settings in place, it doesn't mean we can't have both - perhaps upon first opening settings, you are given an option as to which way you'd rather proceed?

As the extension/plugin library grows, I'm sure more of the creators of those plugins would also like a settings GUI to tap into (again, Atom has done a great job of this).

I also understand the complexities that are concerning a few people, that maybe the JSON is too complex to auto-generate settings from. The other way to go about this is to specifically create a GUI that's tailored for core settings, and refer users to the JSON for advanced settings - but I really would rather create something smarter and all-encompassing where possible.

If there are concerns about changing the structure of the JSON (which I assume there would be), we could also look at something JSDoc-like for declaring (in comments) what the 'GUI-friendly' name of each setting is, and how it should be displayed in the GUI. Example below.

/**
 * Controls the font family.
 * @name "Font family"
 * @type text
 */
"editor.fontFamily": "",

[felixfbecker]

@mrmckeb You do not need JSDoc, every setting is specified in JSON schema, which allows to specify descriptions, default values and types. An extension can already provide more settings with a schema.

[mrmckeb]

Thanks @felixfbecker, good point - I didn't realise JSON schema was in use here. That's a far better solution.

[ianwesterfield]

@mrmckeb I like the idea of a gui, and think @felixbecker has a good compromise to what @egamma brought up because I find updating the JSON to be faster.

Atom's implementation...it doesn't flow nicely. I find either scrolling forever (especially the beautify package), or jumping into each little extension's page and back again to be a clunky, uninspired design.

Not original, but maybe something akin to the tree in Visual Studio? That would eliminate jumping around to different views for extensions and keep scrolling to a minimum.

[iam3yal]

Personally, I don't like GUIs for options at all, I really wish for the day that Visual Studio will have its options stored in a JSON file too. :)

[mrmckeb]

@ianwesterfield I agree that some of what Atom does could be tuned, and hear both you and @eyalsk. I understand completely that many people prefer to update JSON settings, and can see why.

I'd never propose doing something that alienates part of the community, but I believe that the current approach is alienating some users. It would be great to find a strong compromise here.

There are advantages to both approaches. JSON is fast, explicit, searchable, and easy to manage/share. The GUI allow for intuitive controls, understanding without reading documentation or comments, and the ability for some magic (i.e. automatically disabling setting y as it relies on setting x to be enabled).

The right approach might be that the first time you open the settings JSON, you're prompted and asked if you'd prefer to use the GUI. We could keep data on usage of each, and if the GUI becomes more widely used, we'd default to that instead - but keep the first-time prompt in place.

Again, I'm trying to finds a solution that impacts both parties the least - let me know if you have any better thoughts here, it'd be great to keep this discussion going.

[ianwesterfield]

@mrmckeb I agree, I think some discussion should happen whenever there is a possible user gap.

I vote for @mrmckeb's idea for a prompt when first opening the settings.

I also agree that whatever the gui looks like, it should be generated automatically by the default JSON, and it's settings persist to the user's JSON as they reside today.

@felixbecker had two great points earlier in this thread.

I assume the same would go for keybindings to keep things consistent?

[iam3yal]

@mrmckeb I don't mind to have a GUI as long as it's a separate application and in fact I think it should be, someone can just pick it up and write a GUI application for VSCode and a simple extension to launch it via tasks. :)

If you are really serious about making a GUI that people will actually use then generating it automagically from the JSON file is not only a bad idea but you turn a simple problem to a much larger one that I'm not sure you understand.

P.S. I'm all for discussing it, sorry if I hijacked the post with my objection to it.

[felixfbecker]

@eyalsk the nice thing about JSON generated GUI is that it makes it easy for extensions to add settings that get a GUI aswell.

What do you think about my suggestion where the settings.json just has a button like the Markdown preview button that switches to settings UI?

[ianwesterfield]

@eyalsk I'm afraid I don't really understand how this could become a much larger problem. Perhaps you could elaborate?

I wouldn't expect a user to go find some other application just to manage the settings. That's weird in this context. Can you name other IDE/document editors that manage their settings this way?

[iam3yal]

@felixfbecker The issue with what you are proposing where you exchange text with controls is that I'm not sure how great the experience would be and I'm not sure what you gain by doing it.

So without an actual UI I see no point in it.

@ianwesterfield

I'm afraid I don't really understand how this could become a much larger problem. Perhaps you could elaborate?

Okay, if you refer to the kind of GUI @felixfbecker proposed then I guess it wouldn't be so hard to do but I don't see much value in it but maybe I'm wrong. :)

I wouldn't expect a user to go find some other application just to manage the settings. That's weird in this context. Can you name other IDE/document editors that manage their settings this way?

The person can simply make it available as an extension, when the extension is executed for the first time it grabs the installation and install the application and finally start the application, the second time it just starts the application but the bottom line is that it's not so different than installing any other extension so it certainly not weird.

The VSCode team can make this available by asking the user whether he wants a GUI to manage the settings so the user wouldn't have to find it.

The benefit of making this as a separate application is that it loads as part of a separate process.

[bgashler1]

Here's a proposed look of GUI settings. Special thanks to @felixfbecker for your idea that I incorporated in this design.

• It works similar to markdown preview.
• You can click the "Preview" button on the top of the header for the GUI.
• You can get to a particular setting or category of settings the same way as you do in JSON, by using ⌘ + f or ctrl + f.
• As you update settings in the GUI, they are reflected in the JSON (and vice versa).

[felixfbecker]

@eyalsk

The issue with what you are proposing where you exchange text with controls is that I'm not sure how great the experience would be and I'm not sure what you gain by doing it.

The benefit is easier discovery of settings. Currently, you have a) the default settings where you can discover what settings are available and b) the actual settings.json. You always have to copy+paste the settings or use IntelliSense. In a UI you can see what settings are available, see what values they have and change them at the same place.

So without an actual UI I see no point in it.

I don't get this, there would be an actual UI.

@bgashler1 this is near to how I imagined it, a few complaints though:

• the headlines need to be smaller
• true / false should simply be a checkbox
• I find it a bit weird that the UI opens over the default settings and still shows the actual settings side by side. It would make more sense if you toggled the view of the actual settings.json to get the UI, and then maybe automatically close the default settings json window.
• What should happen when you set a value back to the default value? Should it get removed from the settings file?

[pflannery]

@bgashler1 That is looking good so far. Just keeps it simple.

• The size of the text and radio button look right for people with disabilities. Maybe size could be tailored for preference but default to big so new starters to vs code with disabilities can jump right in.
• I think using radio buttons for true and false is spot on because their best for choosing a single option in a list, where as check boxes are best for opt-in opt-out lists.

Be cool to have a search filter to quickly get to each configuration from inside or outside of the settings file, it could also hide non-relevant settings too. Also categorization for things like theme overrides and extension settings would be wonderful.

I've never liked the way ide's have handled their preference gui's. I've always felt removed from the actual environment I'm working in and to top it off I'd always find a crucial area of configuration stuck in a horrible little single line text box. (:cough: :cough: just like (the old) Microsoft Windows Env Path editor in system properties).

[iam3yal]

@felixfbecker

The benefit is easier discovery of settings. Currently, you have a) the default settings where you can discover what settings are available and b) the actual settings.json. You always have to copy+paste the settings or use IntelliSense. In a UI you can see what settings are available, see what values they have and change them at the same place.

Okay, you make some fair points here.

I don't get this, there would be an actual UI.

Yeah, what I meant by that is that exchanging text with controls might not be as intuitive as a custom made GUI and might be somewhat limited.

Don't mind me though @bgashler1 did a great job so I'm looking forward to see this in action and try it out. :)

@bgashler1 well done! mate.

Paths might be tricky to determine because there's no convention but maybe you can check whether the key ends with .path or Path and replace it with a file input instead of a textbox.

[mrmckeb]

Looking great @bgashler1. When do you expect to get sign off on the design?

I think the technical side of things should be manageable, but as a few people (like @eyalsk) have pointed out - we need to make sure that the JSON translates into a GUI as seamlessly as possible. @felixfbecker's earlier JSON Schema suggestion seems like it would cover this.

My feedback/thoughts:

• There could be a Windows-style settings search/filter, where it effectively filters the settings shown as you type. There's a lot of whitespace, but I think that fits with the design of VSCode..
• There's a lot of whitespace. This isn't necessarily a bad thing, but could make the GUI quite long - especially as people start using more extensions with their own settings.
• Has there been much thought to how extensions would be handled in settings? Would it literally represent the JSON structure? Or would it highlight extension settings vs app settings?

[Tyriar]

@mrmckeb afaik this is just exploratory and we're not committing to anything yet. The main concern of most people seems to be wasted effort in building out this when it's not adding any new real functionality, just an alternate UX. It could also potentially be more confusing have two different editors for the same thing.

Extensions are another beast which would probably need to be handled quite differently. I created an issue for that too https://github.com/Microsoft/vscode/issues/3356

[pflannery]

@mrmckeb I wonder if a prototype of @bgashler1's example could be started now by using a similar technique as @egamma pointed out to @drywolf https://github.com/Microsoft/vscode/issues/3011#issuecomment-195823705

Then later on down the line it could be migrated to a json viewer extension if and when it becomes available (i.e. like the current markdown viewer).

[mrmckeb]

Sure @pflannery, I can take a look at this over the weekend and see what I can get done.

[mrmckeb]

@pflannery, sorry I didn't get a change to look at this over the weekend. I'll try to look one night after work this week, but if not, definitely on the coming weekend.

I'll obviously need to get my head around developing VSCode and it might be slow to start with, but I'm really excited about jumping in.

@Tyriar I'm sure whatever work is done here will be somewhat transferrable to that too (at least in part).

I can see the competing ideas here, and both sides make valid points. I feel that the argument around discoverability does make the GUI option compelling, but understand the need to implement this in such a way that power users could get away with never seeing it.

Personally, I don't want to have to research what each setting does or what options are available. I also see the value in having those settings in JSON so that I can store them with my projects, or synchronise my settings between computers.

If this idea did end up being an extension, I'd hope that it would be something that was an option during the install process. That could be a good compromise, example below:

Would you like to use the GUI for changing settings? Selecting yes will install the extension settings-gui, which can be removed.

[felixfbecker]

I also wanted to point out that this GUI should not only apply to settings. I know people who don't know JSON and are totally confused how to setup a launch.json or tasks.json to make it do what they want. If the GUI is generated from a schema it would be trivial to show the "switch to GUI" button for these files aswell.

[pflannery]

@mrmckeb no need to apologize. Take your time. Don't feel you have to do anything at all.

[mrmckeb]

So, it took me a while, but I've gone with the extension approach for now.

I've made some progress - and can access the current configuration, as well as the contents of both the settings and default settings file. I can also access an object representation of current in-use settings here using workspace.getConfiguration().

I'm hoping someone can advise the best way to access the following (if possible) from the extension:

• Validator / Schema for configuration (to know what format each is expected in).
• Separate objects for default settings, user settings, workspace settings (I can work this out from the files if need be).
• Settings URIs or some other way to know if the JSON file I have open is a settings file (I can assume this based on URI, but wondered if there was a better way).

[mrmckeb]

@felixfbecker I forgot to reply to your comment about the GUI not only applying to settings - I agree, but I think I'll start with settings for now. We can then see if it would make sense to expand capabilities, or to fork to another project for more generalised JSON GUI.

[iam3yal]

@mrmckeb You can tell whether it's the setting file by validating it against its schema, don't you? I mean this seems like the most reliable way to do it.

[felixfbecker]

I would check if the path ends with .vscode/settings.json or wherever user settings are

[mrmckeb]

@eyalsk, that definitely makes sense - but how do I access the schema from within the extension (without anything hacky)? I didn't see a way when I was reading the docs.

@felixfbecker Thanks, that's what I was thinking too. I was hoping there was a way that doesn't mean coupling to a URI. I'll see if any other ideas come back before progressing.

[iam3yal]

@mrmckeb Well, I don't really know but I guess that they actually access the schema when they display the intellisense although I'm not sure whether it's available to extensions.

I guess that the easiest way (and maybe more practical) to go for now is to follow the advice that @felixfbecker gave you, just use the URI.

[egamma]

FYI @aeschli

[bgashler1]

Sorry for my delayed responses.

@felixfbecker

• You bring up excellent points. I chose <h1> size headings at first, because it was top level information. However, <h2> would probably be more appropriate since these settings are actually one level into a a JSON tree (also before the JSON begins, there is a comment, and that one should be an <h1>).
• The checkbox may be simpler, but it could be difficult to make this agnostic to all settings. The idea is I want to make this completely sustainable as settings evolve. We will definitely keep this in mind.
• The reason why I left the editor side-by-side is to help users see what the setting actually looks like. It serves as a learning experience for those who may want to transition to JSON settings, which also affords users the ability to share their settings "recipes" with other users or commit it as part of a repo.
• We would probably remove the setting if they changed back to the default, otherwise it could turn into a junk drawer very fast.

@pflannery Thank you for the feedback! Search is definitely something we would have if we implement this. At a minimum we would have the standard Ctrl + F find used in editors that searches text. Would that be sufficient to you, even if it didn't filter out other settings?

[mrmckeb]

@bgashler1 The way I'm building the prototype/extension is that it will be filterable for now - but otherwise matching your designs. Again, this is all prototypal / proof of concept so anything can be added or removed.

Can you also provide a PSD of the design? You can email it to me if you'd like. That'll help me match the design as close as possible.

[bgashler1]

@mrmckeb what's your email address so I can send it to you? Also, we totally appreciate your enthusiasm on prototyping this, but I do want to make sure we don't hurt any expectations as there's a possibility that we may not choose to officially support this feature. We are seriously considering it, however. Thanks for your help :)

[Tyriar]

The extension UI is being discussed in https://github.com/Microsoft/vscode/issues/637, settings may be impacted by this.

[mrmckeb]

Thanks @Tyriar, I can see how it will.

And no problem @bgashler1 - it's my username @ hotmail.com. I understand that, and I'm purposefully building this as an extension so that even if VSCode doesn't end up with a settings GUI, this work can live on.

I didn't really get the answers I was after here (some great suggestions, but no definite yes/no on what I was trying to achieve). Are either of you able to point me in the direction of the best person to discuss this with? Maybe I missed something really obvious. https://github.com/Microsoft/vscode/issues/3355#issuecomment-202289902

[pflannery]

@mrmckeb

Validator / Schema for configuration (to know what format each is expected in).

I know that it's possible to load the json schema parser and validator used by vscode with the following:

import {extensions} from 'vscode';
const jsonExt = extensions.getExtension('vscode.json');
const jsonSchemaParser = require(jsonExt.extensionPath + '/server/out/jsonParser');

var parsedDocument = jsonSchemaParser.parse(someText);
var validationResult;
jsonSchemaParser.validate(someSchemaObj, validationResult); 
// see https://github.com/Microsoft/vscode/blob/master/extensions/json/server/src/jsonParser.ts#L100

[felixfbecker]

@mrmckeb can you make your repo public? I would like to contribute

[aeschli]

@pflannery Accessing the JSONParser as shown is not supported. These are internal classes of the JSON language service designed to run in a separate process.

[mrmckeb]

@felixfbecker I'll try to do it over the next week or two, I've got a few things on this coming weekend - so it'll likely slip to next week or the next weekend.

[imperez]

I definitely could use this. While the intellisense helps out an actual GUI would make things so much simpler. So I'm very interested to see this come together.

Also I showed the settings to another dev and he balked at the idea any editor would use JSON to manage settings.

[mrmckeb]

I'm still struggling with time, I've just accepted a new role and the interview process along with life and my day job have been a lot, sorry!

At this stage, I still believe that the hardest barrier to making this work as an extension is validating the settings. I have something mocked up (function over form), and will share when I get time to polish the code a little, but there's no way that I can think of where I can actually list all available settings and know their types in the extension - unless I manually manage these, which would mean updating the extension every time VSCode gets a new/changed setting. Am I missing something obvious here?

@imperez I've had similar experiences.

@bgashler1 I've yet to receive your email with the PSD mock-up. I know you're very busy, so just a reminder ;)

[iam3yal]

@mrmckeb can't you infer the types from the values?

[mrmckeb]

@eyalsk I'm not sure how that would work - I may be missing something, so if that's the case, let me know.

The way I see it, if a value is a number, it also need a range - max and min. If a value is a string, it's most likely going to be an option from a list of possibilities. What we'd end up with is the exact same thing presented a little differently, rather than a GUI experience that makes use of select, input[type=range], input[type=number], etc.

Without access to some form of validator/schema, this would need to be manually maintained and then updated each time something changes.

This is the only hurdle I have right now, once solved I can publish something hacky, and then after a little feedback/revising, it'll be publishable.