Change the "Run and Debug" View's "Play" icon to a "Connect" icon when an Attach Mode Configuration is Selected

[ericdrobinson]

Feature Request

Please add a distinct "Connect" button icon for starting "request": "attach"-type debug sessions in the debug view.

Details

"Launch" mode debug sessions run ("play") some script or program when the start. By default, ending such a debug session will also "stop" said script or program. This is very clean and mirrored by the UI:

• Launch Mode Debug Session Start (Play):
  
• Launch Mode Debug Session Stop:
  

However, an "Attach" mode debug session "connects" to some engine/program/script when it is started. By default, ending such a debug session will "disconnect" from the engine/program/script and allow it to continue. This is very clean but not mirrored by the UI:

• Attach Mode Debug Session Start (Connect):
  
• Attach Mode Debug Session Disconnect:
  

In the "Attach" mode case, there is no paired "Connect" icon to signal to the user that starting this debug session will connect to a host (engine/program/script) and not run something.

The asymmetry can be summed up with this single screenshot:

"Play" and "Stop" work well together for a "Launch" mode debug session. A "Connect" icon would better communicate what starting an "Attach" mode debugger actually does.

The current icon list does not have a "connect" icon, but I imagine that it would be pretty straightforward to create one based on the current "disconnect" icon design language.

Important Note

Please note that I am requesting this on behalf of our debugger extension's users. See below for more.

Background

I am working on a major update to the ExtendScript Debugger extension. ExtendScript is a custom JavaScript-like language developed by Adobe and implemented in several "host applications" (e.g. Photoshop, Illustrator, InDesign, Premiere Pro, etc.). Scripts are run in engines within the host applications in a variety of ways, including:

• Automatically at startup
• Specified directly via application menus
• Via callbacks from custom UIs (e.g. button clicks)
• Via a properly configured debugger

The new version will support starting debug sessions using both attach and launch configurations to support the myriad operating scenarios. It will also support running a script directly within a target host application+engine from VS Code. This latter feature is implemented via commands and with a status bar button for convenience. This status bar button is accompanied by the $(play) icon.

Many of our pre-release users have expressed confusion about the "Attach" mode debug configurations. When they click the "Play" button to connect to the host they have an expectation that the focused script will actually be run. We consistently have to explain that this is not how "Attach" mode configurations work and suggest that they either try the "Launch" mode configuration or keep their current configuration and use the script evaluation commands/button (which, again, has a "play" icon).

We did not connect the consistent user confusion about the configuration modes until we received the following feedback from an especially insightful user (emphasis mine):

I also figured out what makes the new debugger hard to 'grok' for me... I now think that the root cause is the UI. The thing is that the 'play' symbol in VSCode... does not mean 'Run' or 'Play' - it means 'Connect'. If that symbol were instead something else - like a power plug or so, that would help me remember that [it means] 'Connect'. And then the 'Eval in...' [button] at the bottom - that is where the little triangle should appear.

That way I am connecting to a particular engine in a particular app, and when I click that 'Eval in...' [button] I am running a script.

Now that I know how to adjust my thinking, things work a lot better for me, but I reckon that for new users, it would be helpful to change the play symbol into a 'connect' symbol and add a 'play' symbol to the 'Eval in....' bar.

When this user provided this feedback it was as though a light had been turned on - suddenly the constant confusion of users made sense. They see the "Play" button and they think "this will run something". That is a reasonable assumption. In the case of "Attach" mode configurations, however, that assumption does not hold.

[vscodenpa]

This feature request is now a candidate for our backlog. The community has 60 days to upvote the issue. If it receives 20 upvotes we will move it to our backlog. If not, we will close it. To learn more about how we handle feature requests, please see our documentation.

Happy Coding!

[weinand]

I'm not sure that we want to change the "Play" icon drastically because users know it since the beginning of time and there have been no other complaints that "Play" does not work for "attach".

I suggest that we continue to use the "Play" icon but may be add some "attach" adornment to the icon.

Another issue: what icon should we show for composite launch configs that combine "launch" and "attach" configs?
Counting the "attach" and "launch" configs and using the maximum doesn't make a lot of sense.
Should we use an icon that represents a "composite"?

[ericdrobinson]

there have been no other complaints that "Play" does not work for "attach".

Yeah, but this may be a case of "users don't understand it and simply accept the status quo once they figure it out". I know that's how it worked for me, but it's been so long that I don't recall my specific process of understanding. Regardless, this is why I said it was like someone turned a lightbulb on when the user provided the insight.

I suggest that we continue to use the "Play" icon but may be add some "attach" adornment to the icon.

👍 Perhaps that could be one end of a power plug like that used in the "disconnect" icon?

Another issue: what icon should we show for composite launch configs that combine "launch" and "attach" configs? Counting the "attach" and "launch" configs and using the maximum doesn't make a lot of sense.

Ooh, good question. I would simply pick the icon for whichever is first in the list and document this in the compound configurations documentation. My understanding is that the order isn't especially important, so users could reorder if they wanted a different icon.

Alternatively, a few ideas:

1. Is there an icon that could indicate "more than one"/"multiple"?
2. Is there a way to add a plus symbol to the Play button or Connect button, indicating "more than one" and that they've got a compound debug session situation?

[zwettemaan]

I'm not sure that we want to change the "Play" icon drastically because users know it since the beginning of time and there have been no other complaints that "Play" does not work for "attach".

Users since beginning of time only covers 'existing users' that have figured it out. However, VSCode is meant to gain more and more users over time, no? Each one of those new users will have to 'figure it out'. All those new users 'yet to come' don't know the secret handshake...

[stibinator]

The status quo is confusing. Confused the crap outta me, for one. Can I suggest something like the unicode U+1F91D handshake character?

[vscodenpa]

🙂 This feature request received a sufficient number of community upvotes and we moved it to our backlog. To learn more about how we handle feature requests, please see our documentation.

Happy Coding!

[weinand]

From past experience I don't think that we can easily attract new users to debugging by confusing them
with these icons:


instead of the green play icon:

[stibinator]

What's confusing is a symbol being overloaded to mean something that it doesn't normally represent. Attaching the debugger is different to running the script in the host, which is what the play symbol represents.

[stibinator]

In hindsight, the handshake may not be the best choice, it may be specific to Western business culture.

[zwettemaan]

In those contexts where the green play button is correct, it would have to remain a green play button.

But in this particular context, showing a play button, and have the user click it, and then nothing happens - that is extremely confusing.

It has lead to endless confusion amongst many users of Adobe's ExtendScript debugger, which often heavily relies on attaching rather than launching.

The problem is that a user clicks the green play icon and apparently nothing useful happens.

That's because the green play icon has attached to the debug engine, but nothing has launched. You need to click another thing to make it actually run/launch.

I think Eric's initial request explained it very well and in great detail. If you have not read it, please do!

The issue is that VSCode has overloaded a single button with a single icon and makes it serve two totally different purposes, all depending on the context. To the user it is unclear: are we attaching or launching?

The first proposed icon of connecting plugs would make most sense to me.

The counterpart (un-attach) of that icon is already used on VSCode's little stop/start/pause... button panel once the session has started.

VSCode already knows how to show 'un-attach' and has an icon for it, but it has no icon for 'attach'.

The second proposal, the handshake icon, feels incongruous and has no consistency with anything else, IMO.

[weinand]

If users have the following problem:

The problem is that a user clicks the green play icon and apparently nothing useful happens. That's because the green play icon has attached to the debug engine, but nothing has launched. You need to click another thing to make it actually run/launch.

then I don't think that just a different icon will make this problem go away.
If the "attach" launch config is missing something, the debug extension could show a notification or alert to make the user aware of it.
Or even better: the debug extension could ask the user what to launch via a picker dialog.

[ericdrobinson]

@weinand Let me try to explain this... again.

If the "attach" launch config is missing something, the debug extension could show a notification or alert to make the user aware of it.
Or even better: the debug extension could ask the user what to launch via a picker dialog.

The "attach" configurations (I'm not going to say "attach launch config" here because that silliness is preceisly part of what is causing the confusion - we do not say "launch launch config" even though that is actually more correct) do actually do something: they connect to the host. When the user presses the "Play" button and start a fully specified attach config, the status bar turns orange and the debugger UI appears. If the attach config is not fully specified, then it does show one-or-more pickers to complete the configuration and start the session.

That is NOT the problem we're discussing here.

The problem is that users create these attach configurations and either:

1. See the "play" button and believe that this will somehow magically send their currently active script to the connected host for processing.
2. Let a few weeks pass, come back to do more debugging and forget that the "Debug Photoshop" configuration they created and have selected is actually an attach config. They see the "play" button and believe that starting the debug session will somehow magically send their currently active script tot he connected host for processing.

What do you expect us-as-extension-developers to do in this case to help communicate the situation to users? Are we to pop up a notification every time a user uses an attach config to remind them that "Hey! I notice you're using an attach configuration! A friendly reminder for you: this won't actually run your script!"

So what @zwettemaan was attempting to communicate to you in his post was that "nothing happens" means "I expected that the 'play' button would result in the script actually playing but it didn't because there is nothing to communicate to me that the configuration I selected was an attach configuration and not a launch one".

As the developer of the debugger extension, here is how I had to work around this confusion myself:

But I'm also about as expert a user of this debugger extension as you can get.

As much as we debugger extension developers can suggest that users name their debug configurations with "Attach to..." or "Launch in..." prefixes, we cannot require it or somehow adjust that after-the-fact. So you end up with users who have write "Debug Photoshop" and then simply forget that this configuration is "attach" instead of "launch". This causes confusion.

[weinand]

My suggestion was to show the notification/alert only if the attach configuration is running against a debug target where no script is running. If the script is running, then "attach" would not post a notification/alert.

Other debuggers will run into a timeout when an "attach" config is used against a nonexistent target. Why is this not possible in your case?

---

Just changing the icon in the debug dropdown does not work in these two cases:

• user has selected "attach" config and switches to the explorer (so that the debug drop down menu is no longer visible). User uses "F5" and nothing happens.
• user presses "F1" and types "Select and start debugging....". User will see debug configuration names but no icons. User selects one and nothing happens.

[ericdrobinson]

From past experience I don't think that we can easily attract new users to debugging by confusing them
with these icons:
...
instead of the green play icon:
...

I agree that the proposed handshake icon is not appropriate in this case. It is an interesting idea, but does not have symmetry with the disconnect symbol.

I don't understand why you bundled the disconnect icon into that. I agree that adding the disconnect icon is not necessarily the correct approach (though it honestly might be fine).

But I do think that specifying a green connect icon would be an improvement. There is now a vscode-codicons issue to add a connect icon. The issue links to another Microsoft icon set that has a solution for this. See:

Using that new icon in a matching green color would do a much better job of communicating what the selected configuration does:

The Fluent UI icon set also contains a plug with an inset plus symbol which is exactly one of the suggestions I made for compound configurations. Applying that to the example might look like:

Alternatively, you could use something like Fluent UI's "Power" icon for all configuration types:

That said, the "connect" icon is far more expressive and clears up the ambiguity.

[ericdrobinson]

My suggestion was to show the notification/alert only if the attach configuration is running against a debug target where no script is running. If the script is running, then "attach" would not post a notification/alert.

This does not work for the Adobe host scenario. There is no running script when the debug session is attached. The script is loaded and run in the connected engine when the user clicks a button or via some other interaction within the host application. You will need to expand your understanding of what attached debug targets can do/how they operate.

Other debuggers will run into a timeout when an "attach" config is used against a nonexistent target. Why is this not possible in your case?

Because the engine exists but it is very likely to be idling. Attaching to the host application does two very important things:

1. Identifies the extension process as the debugger.
2. Loads all breakpoint information into the engine.

When any script is later processed/evaluated/run while the debugger extension is attached to the target engine within the host application, the host application will then have information about when it may need to break. These engines work very hard to not be constantly running scripts. When a button is clicked, for instance, they load and execute the script. Unless the debugger is already attached, there is no way for us to "catch" that brief instance.

user presses "F1" and types "Select and start debugging....". User will see debug configuration names but no icons. User selects one and nothing happens.

You could add the icons to this picker to resolve this issue.

user has selected "attach" config and switches to the explorer (so that the debug drop down menu is no longer visible). User uses "F5" and nothing happens.

This one is a bit more challenging, but a user who configures multiple configurations and just hits F5 while the Debug View isn't open likely either has a single debug configuration configured or uses the debugger frequently enough that they know what's going on. I think most of the users who are confused by the play button are those that click the play button (which means they are using the UI and not hitting F5).

Additionally, you do provide UI (a button, actually) that shows what the selected debug configuration is in the status bar. The icon for that should also be updated to match the "attach-vs-launch" icon status based on the selected (and therefore reported) configuration:

[weinand]

@ericdrobinson since I have now "expanded my understanding of how attached debug targets operate" I would like to understand how a "launched" debug target operates.

[ericdrobinson]

I would like to understand how a "launched" debug target operates.

When the user starts a "launch" config debug session, the following happens:

1. The extension collects all configured VS Code breakpoint information.
2. The extension connects to the configured host engine (whether fully specified in the configuration or selected via pickers).
3. The extension immediately sends the configured script to the host engine for evaluation - it "runs" / "plays" the script in the host engine.
4. When the script evaluation completes, the debug session automatically ends.

The basic differences between "attach" and "launch" configurations with the ExtendScript Debugger Extension are as follows:

• attach configurations do not tie the existence of the debug session to the run of a script. These debug sessions inform the host engine that they are ready to perform debugger operations, should any be needed. These sessions then simply wait for the host application to communicate that a breakpoint/exception/print event has occurred in the targeted engine.
• launch configurations directly tie the existence of the debug session to the run of a script. Starting a launch debug session will cause a script to be evaluated in the host engine. Stopping the script (whether by allowing the script to run its course or by issuing a "Halt Script" command via the command palette or status bar button) will also end the debug session.

To be clear, the "disconnect" and "stop" debugger control semantics are also intentionally different:

• disconnect (which is the default "end debug session" button for "attach" configs) will inform the host engine that the debugger is disconnecting. This is accompanied by a "Continue" command behind the scenes in the event that the debugger is paused when the user clicks "disconnect".
• stop (which is the default "end debug session" button for "launch" configs) will both inform the host engine that the debugger is disconnecting and issue a "halt script" command, stopping evaluation.

Importantly, "end debug session" semantics are respected regardless of which configuration request type was used when starting the command (as users can select an option from the dropdown in the debugger UI or by holding Alt/Option to flip the meaning of the "end debug session" button).

You can see how this flexibility opens up workflow options for users.

I should also mention that the debugger extension provides the user with the ability (via command and status bar button) to run a script in a host application regardless of debug session state. A user can run a script with no debug session to simply trigger some process they desire to run in a host engine/application. Alternatively, a user can run a script while an "attach" config debug session is active and this may cause the break UI to appear (in the event that a breakpoint or exception are triggered). Attempts to run a script while a "launch" config debug session is active in the target engine result in an error explaining that a script evaluation is already active in the target engine.

This architecture makes VS Code an extremely powerful tool for Adobe's extension developers. Several users have now expressed confusion with the "play" button being used for all debug configuration request types. Insightful users figured out that this is due to the fact that "attach" config debug sessions inherit the "play" button even though they do not actually cause a "script"/"program" to "play"/"run".

Having worked with this stuff for quite a while now, I personally understand that the concept of the "play" button is intended to mean "start a debug session". But I am not in a position to demand that users see the world as I intended. As a developer doing their best to improve the accessibility and usability of the software I develop, I am doing my best to understand how users interpret the UI they interface with and reduce areas of confusion to the best of my ability. As the source of confusion in this case lies in an area to which I do not have any control as an extension developer, I am bringing the confusion to you for your understanding and consideration.

[Harbs]

To clarify a bit more why attach makes sense without a script actively running:

Scripting engines in Adobe apps can be persistent. So variables set in one script session can be accessible in another one.

Scripts can also be fired on events and write to the console.

[weinand]

@ericdrobinson thanks for explaining the difference between "attach" and "launch" for the ExtendScript debugger.

It confirms that the ExtendScript debugger uses the same "attach" and "launch" semantics as all other debugger extensions that support "attach" and "launch". Thus, the ExtendScript debugger does not introduce any new semantics and does not impose any new requirements on VS code.

---

Above you said:

I personally understand that the concept of the "play" button is intended to mean "start a debug session"

Yes, that's correct.
And I agree that the "Play" button can be (mis-)interpreted as "start debuggee" instead of "start debug session".
However, the "Play" button is in use since 7 years, and nobody has ever complained about that.
Changing icons is always asking for trouble. That's the reason why we are not yet convinced that changing the "Play" icon is worth the trouble...

---

If case we want to change the "Play" icon, I like your proposal to go with a single icon for all config types. But instead of the "Power" icon I suggest to use a "Bug" icon:

@roblourens @connor4312 @isidorn @misolori what do you think?

[isidorn]

@weinand that's brave :)
Then we would need to change the icon if it is debug or if it is run.

I suggest to not change the icon, and wait for more user feedback before we do any action.

The current icon is well suited for beginners that are also learning how to just run their code. And that might got used to the play icon that is used by other IDEs. And I would always lean towards the beginners in this case...

[Harbs]

Changing icons is always asking for trouble. That's the reason why we are not yet convinced that changing the "Play" icon is worth the trouble...

If case we want to change the "Play" icon, I like your proposal to go with a single icon for all config types. But instead of the "Power" icon I suggest to use a "Bug" icon:

I don't think the primary suggestion here is to replace the icon for a normal debug session. For a normal debug session where the script is run, the current play icon (AKA run) makes a lot of sense and fits norms.

It's only when it's an attach session where the script is not run where the play button is confusing and there the plug icon conveys the intent much better.

I'm confused by the apparent resistance to this suggestion. It really seems like a "no brainer" to me.

[connor4312]

I'm not a huge fan of the bug icon being used instead. The nice thing about the play button, and even the proposed 'connect' icon, is that they symbolize action, while a bug alone doesn't do that. The power icon also signals an action, but imo not the right one...

My suggestion talking to Andre yesterday was allow codicon usage in the name of launch configs. If a launch config name begins with a codicon, then replace the play button with that icon.

I don't think the primary suggestion here is to replace the icon for a normal debug session... It's only when it's an attach session

Fwiw, in JS land attach configs are pretty common and not especially advanced or abnormal.

[weinand]

The "Play" icon is part of a button which has a stable UI for a long time.
It means "start one or more debug sessions".

Changing the icon based on the debug configuration's "request" type makes the button appearance dynamic (and unstable). This is what I don't like and try to avoid.

In order to address the misleading "Play" semantics, I tried to propose an icon that is "neutral" and does not convey the "launch" vs. "attach" semantics.

[miguelsolorio]

My suggestion talking to Andre yesterday was allow codicon usage in the name of launch configs. If a launch config name begins with a codicon, then replace the play button with that icon.

I like this idea and we already support this for tasks (though it's in the quick pick, so different component):

For the configurations, this would only appear in the view and not in the dropdown (since icons aren't supported in menus):

Would get a little tricky in implementation given our config dropdown uses the native dropdown syntax, but I'm sure we can work around that with an overlapping container for the icon.

[connor4312]

Changing the icon based on the debug configuration's "request" type makes the button appearance dynamic (and unstable). This is what I don't like and try to avoid.

I agree, but the benefit of doing it this way is that the behavior becomes "user configurable", even if it's something VS Code itself doesn't automatically do/endorse.

Would get a little tricky in implementation given our config dropdown uses the native dropdown syntax, but I'm sure we can work around that with an overlapping container.

Within the dropdown we would need to strip the icons.

[roblourens]

Does making it user-configurable help given that this is supposed to be an issue for beginners? It doesn't seem much better than just naming your configs "Attach to..."

[ericdrobinson]

However, the "Play" button is in use since 7 years, and nobody has ever complained about that.
Changing icons is always asking for trouble. That's the reason why we are not yet convinced that changing the "Play" icon is worth the trouble...

Changing the icon based on the debug configuration's "request" type makes the button appearance dynamic (and unstable). This is what I don't like and try to avoid.

Normally I would agree with this assessment. In this case, however, the change under consideration is only suggested to disambiguate what is currently ambiguous.

The fact that no one has previously complained about this may simply be that each and every developer has had to work through whatever confusion they had, realize that they had misinterpreted the "play" button, and then adjusted their views. In working on a debugger extension myself I have had to explain to users multiple times that they shouldn't view the "play" button as equating to "running the script" but rather as "starting/running the debug session". That a particularly insightful user (themselves a developer, of course, familiar with UX issues) realized and communicated the source of their confusion (which I have relayed here) is, as I see it, a stroke of luck for the community.

But let's get back to the proposed solution.

I personally have a hard time understanding how the following presents a potential increase in confusion for users (new and old alike):

Icons like this serve to disambiguate what will happen when a user clicks the button. In the bottom version, it is now clear that this will "Connect to the debuggee in order to 'Debug Node.js'". Without the icon to differentiate the debug session type, it is entirely ambiguous.

In addition, by using this type of icon language the Debug UI overall improves in terms of symmetry. See:

The lack of this type of communication in the UI puts the onus on the user to disambiguate. It relies upon users to assiduously name all configurations with the terms "Launch" or "Attach" (as I did here). This appears to be a decently common practice as the Python debugger documentation uses examples with names like "Python: Attach" or even, somewhat comically, just "Attach". Unfortunately, even the main debugging documentation has examples with names like "node" which clearly does not disambiguate...

Another nicety of using the suggested icon language is that it expresses the actions that clicking the button will undertake as described in the documentation (adjusted emphasis mine):

The best way to explain the difference between launch and attach is to think of a launch configuration as a recipe for how to start your app in debug mode before VS Code attaches to it, while an attach configuration is a recipe for how to connect VS Code's debugger to an app or process that's already running.

This feature request is only requesting that the button messaging reflect the verbs used to describe the actions undertaken when the buttons are clicked.

---

Does making it user-configurable help given that this is supposed to be an issue for beginners? It doesn't seem much better than just naming your configs "Attach to..."

I agree. While there may be ways to "seed" a configuration to a beginner, the encoding in the configuration would be non-obvious. We already attempt to "seed" users with best practices by using the following names when someone uses the VS Code UI to start a new launch configuration:

Regardless, we have found that this does not stop users from encountering the ambiguity and getting confused.

---

Fwiw, in JS land attach configs are pretty common and not especially advanced or abnormal.

This holds true for the ExtendScript ecosystem as well. And yet here we are.

[zwettemaan]

Visual Studio 2019 does 'the right thing'. 'Running' has a play-button icon, 'attaching' is represented by two interlocking gears...