Test: Integrated terminal API

[Tyriar]

Test for #9957

• Windows @octref
• Linux @rebornix
• Mac @ramya-rao-a

---

An API for the integrated terminal was added. See window.createTerminal and vscode.Terminal. To test this please make sure the API does what it claims and that it fits your expectations and is useful.

Instructions for testing against latest API here: #11111 (comment)

Sample API implementation here: https://github.com/Tyriar/vscode-terminal-api-example

[dbaeumer]

Sorry for the late assignment but the test plan item wasn't assigned to the August milestone

[octref]

Tested in Windows 10, all methods in the API example work as expected. Made a few small changes for your example in Tyriar/vscode-terminal-api-example#3

I'd suggest adding API for getting active terminal and a list of all terminals, though.
Extensions authors might be only interested in using the available terminals and don't want to create new ones.

[rebornix]

Not sure if it's a problem but Terminal.hide doesn't seem consistent with other methods. When you run Terminal.dispose, corresponding terminal will be disposed and the next terminal in stack will be active. But if you run Terminal.hide, the whole terminal pane hides. This is somewhat confusing as hide should just work on the specific terminal instance, not the whole terminal pane.

Another thing is I don't find the difference between Terminal.show(true); and Terminal.show(false), do you mind describing more about what's the expected behavior of this parameter? @Tyriar

Others are all good.

[octref]

@rebornix @Tyriar
My first guess was also Terminal.show(true) would preserve the focus on the editor while showing the terminal. It's a bit confusing.
And if you have 2 Terminals, with the second active. Calling hide() on first one would NOT hide the panel.

I think a better design is to expose

• showTerminalPanel
• hideTerminalPanel
• toggleTerminalPanel

Also expose

• createTerminal
• getActiveTerminal
• getAllTerminals

Then for each terminal, allow it to set itself as active terminal.

[Tyriar]

@rebornix Terminal.hide is meant to hide the panel, only if that specific terminal is active, otherwise it does nothing. It wouldn't be useful to move to the next terminal as there could be an arbitrary number of terminals.

I believe Terminal.dispose currently shows the terminal. I think there is a TODO in the code but no associated GH issue (created #11275).

Terminal.show's arg is meant to indicate whether to focus the panel.

@octref it was an intentional design decision to not allow extensions access to terminal that were created by the user via the regular commands. Operations on the terminal panel as a whole may be good, but the API is being kept very slim currently, I want some compelling use cases from extension authors before adding more as it's difficult to change the API once it's in place.

I created #11276 to try clarify the functions some more 👍

[ramya-rao-a]

I agree with @Tyriar on not allowing extensions access to terminals created by users and on starting with slim design with additional features based on community feedback.

Regarding points made by @rebornix, extension authors are bound to have similar confusions, better documentation should help in that regard.

[rebornix]

I agree that we leave this out of extension api. But we still have two issues (questions) left:

1. @octref and I don't see the argument of Terminal.show(args) takes effect, the pane gets focused whether it's true or false.
2. [Question] Current commands for managing terminals are somewhat limited. People who leverage these commands can only manage terminal created by themselves, which means if there are other terminal instances created by others, manually or through API, we have no control on them. Is this by purpose?

About improving the documentation, I think we may want to make sure people are clear about that two dimensions of status of terminal: active/inactive and show/hide.

For community feedback, @Tyriar you reached out to the author of https://marketplace.visualstudio.com/items?itemName=formulahendry.code-runner, I think it might be a good extension that can adopt your new command.