Tab model API

[lramos15]

There are many cases where the user wants to be able to either get the state of opened editors / tabs or modify it. This has been conveyed in multiple issues such as #15178. This issue will serve to track the proposal and API development for an API which allows the reading and modification of the tabs.

The current proposal is:

vscode/src/vs/vscode.proposed.d.ts

Lines 2224 to 2317 in a0446e9

	//#region https://github.com/Microsoft/vscode/issues/15178
	/**
	* Represents a tab within the window
	*/
	export interface Tab {
	/**
	* The text displayed on the tab
	*/
	readonly label: string;
	/**
	* The index of the tab within the view column
	*/
	readonly index: number;
	/**
	* The column the tab belongs to
	*/
	readonly viewColumn: ViewColumn;
	/**
	* The resource represented by the tab if availble.
	* Note: Not all tabs have a resource associated with them.
	*/
	readonly resource?: Uri;
	/**
	* The identifier of the view contained in the tab
	* This is equivalent to `viewType` for custom editors and `notebookType` for notebooks.
	* The built-in text editor has an id of 'default' for all configurations.
	*/
	readonly viewId?: string;
	/**
	* Whether or not the tab is currently active
	* Dictated by being the selected tab in the active group
	*/
	readonly isActive: boolean;
	/**
	* Closes the tab object
	*/
	close(): void;
	/**
	* Sets the label of the tab
	*/
	setLabel(label: string): void;
	/**
	* Moves the tab to the new index and view column
	* @param index The new index of the tab within the current group
	* @param viewColumn The new view column of the tab.
	*/
	move(index: number, viewColumn: ViewColumn): void;
	}
	export namespace window {
	/**
	* A list of all opened tabs
	* Ordered from left to right
	*/
	export const tabs: readonly Tab[];
	/**
	* The currently active tab
	* Undefined if no tabs are currently opened
	*/
	export const activeTab: Tab | undefined;
	/**
	* An {@link Event} which fires when the array of {@link window.tabs tabs}
	* has changed.
	*/
	export const onDidChangeTabs: Event<readonly Tab[]>;
	/**
	* An {@link Event} which fires when the {@link window.activeTab activeTab}
	* has changed.
	*/
	export const onDidChangeActiveTab: Event<Tab | undefined>;
	/**
	* Opens a tab
	* @param tab The object representing the tab you want to open
	* @returns The opened tab
	*/
	export function openTab(tab: Exclude<Tab, Function>): Thenable<Tab>;
	}
	//#endregion

[JohnnyCrazy]

Sounds very promising and seems like a good fit for #95266, which was stalled for quite some time because of a missing API to detect if all editors for a specific resource URI have been closed. onDidChangeTabs fits this usecase quite well.

I will try to get #95266 running within a week and report my findings :)

[msftwindowslinux]

I mentioned this in #9498, but one thing that seems missing from the window api is a proper "positional" identifier. The currently available ViewColumn isn't enough since there's ambiguity wrt vertical / horizontal splits, let alone editor size (which I could live without since that's likely to be even more difficult).

This request may be out of scope of this exact discussion since the original issue mainly wanted the list of tabs within an editor. But lots of the comments in the thread was about restoring editor states, which I think would require something like what I described, and does seem to fit in the "window" part of this api.

[lramos15]

@msftwindowslinux You are correct there is a gap with regards to the grid layout because we have always used ViewColumn due to it being a way to link the old and new layout world. I'll write this down and bring it up during the next team discussion to see if we would like to prioritize this layout restoring case. For now we have a command vscode.setEditorLayout which you can find more info about here https://code.visualstudio.com/api/references/commands

[msftwindowslinux]

Thanks for the note! Is there a similar getEditorLayout, or would that be a possible addition? I think having an idempotent setEditorLayout(getEditorLayout()) would solve the "workspace saving" problem without being too intrusive.

[lramos15]

Thanks for the note! Is there a similar getEditorLayout, or would that be a possible addition? I think having an idempotent setEditorLayout(getEditorLayout()) would solve the "workspace saving" problem without being too intrusive.

No there is currently not, and no plans to add one at this time

[Kaniee]

Might be a silly question, because I don't know much about the vscode internals but I'll ask anyways:
How is the icon for a tab selected if it's a tab like Settings or the Jupyter Interactive Window? Currently I only see the default icon for those tabs. Would it make sense to provide a icon field in this API?

And what are your thought on a "isPinned" and "isSaved" property for a tab?

[lramos15]

@Kaniee No worries always wiling to answer any questions. No plans to support customizable icons at this point in time. As for isPinned or isSaved / isDirty if you have a viable use case I would be happy to explore those but to avoid bloat we're trying to go with the minimal set of properties

[Kaniee]

@lramos15 I don't have a specific use case in mind for 'isPinned' or 'isSaved'. It just crossed my mind.

I'm sure you have good reasons to not support customizable icons but would you mind sharing those?

[lramos15]

I'm sure you have good reasons to not support customizable icons but would you mind sharing those?

It's just not on the radar at the moment since there's always additional complexity involved with serving user provided content in a secure manner. There are discussions around allowing the coloring of tabs, but that's in the early stages of development. This API is very powerful so we want to make careful decisions to provide a clean interface focused on enabling the most commonly asked for use cases

[martinmeinke]

@Kaniee No worries always wiling to answer any questions. No plans to support customizable icons at this point in time. As for isPinned or isSaved / isDirty if you have a viable use case I would be happy to explore those but to avoid bloat we're trying to go with the minimal set of properties

I'd also be interested in getting the isDirty property of the document that is potentially displayed in the tab.
Regarding a potential use-case: My extension automatically closes tabs that have not been accessed in some time - but I wouldn't want to close unsaved work :)

Generally speaking I am very happy with the proposed Tab api thoug :)

[lramos15]

I'd also be interested in getting the isDirty property of the document that is potentially displayed in the tab.
Regarding a potential use-case: My extension automatically closes tabs that have not been accessed in some time - but I wouldn't want to close unsaved work :)

Interesting use case. Close currently prompts the user if they'd like to save their work so your use case would still work currently, but I understand not wanting to disrupt the user and have a prompt randomly appear

[riccardoferretti]

I am wondering whether this API would actually be enough to support the case from #136162 which feels like a fairly common/userful use case?

In my specific case, I would like to open files in a specific editor (and/or column), based on some properties of the file (whether extension, or metadata I have associated to it). I am not sure this can be achieved with the currently proposed API, am I missing something?

[tamuratak]

The type of input is resolved to unknown, not to a union type, which makes it difficult to get helps from intellisense and others.

vscode/src/vscode-dts/vscode.proposed.tabs.d.ts

Line 57 in 4ae1f28

readonly input: TextTabInput | TextDiffTabInput | CustomEditorTabInput | NotebookEditorTabInput | NotebookDiffEditorTabInput | unknown;

[jrieken]

The type of input is resolved to unknown, not to a union type, which makes it difficult to get helps from intellisense and others.

That's unfortunate but looks like TypeScript issue to me. We need the unknown type here because we want to signal that this list of types isn't finite and can be extended with not yet known future types

[tamuratak]

Thank you for your explanation. I see that, with the type unknown, you can guarantee the backward compatibility when you add a new type to the list.

[lramos15]

\closedWith aa69f3d

[bpasero]

🎸

[lramos15]

To verify:
Please just look over the vscode.d.ts file and ensure starting at window.tabGroups it has the expected types

[jrieken]

👯‍♂️