fix #51001

extensions/vscode-api-tests/src/singlefolder-tests/window.test.ts

@@ -156,6 +156,56 @@ suite('window namespace tests', () => {
 		assert.equal(window.activeTextEditor!.viewColumn, ViewColumn.Two);
 	});
 
+	test('showTextDocument ViewColumn.BESIDE', async () => {
+		const [docA, docB, docC] = await Promise.all([
+			workspace.openTextDocument(await createRandomFile()),
+			workspace.openTextDocument(await createRandomFile()),
+			workspace.openTextDocument(await createRandomFile())
+		]);
+
+		await window.showTextDocument(docA, ViewColumn.One);
+		await window.showTextDocument(docB, ViewColumn.Beside);
+
+		assert.ok(window.activeTextEditor);
+		assert.ok(window.activeTextEditor!.document === docB);
+		assert.equal(window.activeTextEditor!.viewColumn, ViewColumn.Two);
+
+		await window.showTextDocument(docC, ViewColumn.Beside);
+
+		assert.ok(window.activeTextEditor!.document === docC);
+		assert.equal(window.activeTextEditor!.viewColumn, ViewColumn.Three);
+	});
+
+	test('showTextDocument ViewColumn is always defined (even when opening > ViewColumn.Nine)', async () => {
+		const [doc1, doc2, doc3, doc4, doc5, doc6, doc7, doc8, doc9, doc10] = await Promise.all([
+			workspace.openTextDocument(await createRandomFile()),
+			workspace.openTextDocument(await createRandomFile()),
+			workspace.openTextDocument(await createRandomFile()),
+			workspace.openTextDocument(await createRandomFile()),
+			workspace.openTextDocument(await createRandomFile()),
+			workspace.openTextDocument(await createRandomFile()),
+			workspace.openTextDocument(await createRandomFile()),
+			workspace.openTextDocument(await createRandomFile()),
+			workspace.openTextDocument(await createRandomFile()),
+			workspace.openTextDocument(await createRandomFile())
+		]);
+
+		await window.showTextDocument(doc1, ViewColumn.One);
+		await window.showTextDocument(doc2, ViewColumn.Two);
+		await window.showTextDocument(doc3, ViewColumn.Three);
+		await window.showTextDocument(doc4, ViewColumn.Four);
+		await window.showTextDocument(doc5, ViewColumn.Five);
+		await window.showTextDocument(doc6, ViewColumn.Six);
+		await window.showTextDocument(doc7, ViewColumn.Seven);
+		await window.showTextDocument(doc8, ViewColumn.Eight);
+		await window.showTextDocument(doc9, ViewColumn.Nine);
+		await window.showTextDocument(doc10, ViewColumn.Beside);
+
+		assert.ok(window.activeTextEditor);
+		assert.ok(window.activeTextEditor!.document === doc10);
+		assert.equal(window.activeTextEditor!.viewColumn, 10);
+	});
+
 	test('issue #27408 - showTextDocument & vscode.diff always default to ViewColumn.One', async () => {
 		const [docA, docB, docC] = await Promise.all([
 			workspace.openTextDocument(await createRandomFile()),

src/vs/vscode.d.ts

@@ -754,7 +754,8 @@ declare module 'vscode' {
 		 * An optional view column in which the [editor](#TextEditor) should be shown.
 		 * The default is the [active](#ViewColumn.Active), other values are adjusted to
 		 * be `Min(column, columnCount + 1)`, the [active](#ViewColumn.Active)-column is
-		 * not adjusted.
+		 * not adjusted. Use [`ViewColumn.Beside`](#ViewColumn.Beside) to open the
+		 * editor to the side of the currently active one.
 		 */
 		viewColumn?: ViewColumn;
 
@@ -4016,17 +4017,23 @@ declare module 'vscode' {
 	}
 
 	/**
-	 * Denotes a column in the editor window. Columns are
-	 * used to show editors side by side.
+	 * Denotes a location of an editor in the window. Editors can be arranged in a grid
+	 * and each column represents one editor location in that grid by counting the editors
+	 * in order of their appearance.
 	 */
 	export enum ViewColumn {
 		/**
-		 * A *symbolic* editor column representing the currently
-		 * active column. This value can be used when opening editors, but the
-		 * *resolved* [viewColumn](#TextEditor.viewColumn)-value of editors will always
-		 * be `One`, `Two`, `Three`, or `undefined` but never `Active`.
+		 * A *symbolic* editor column representing the currently active column. This value
+		 * can be used when opening editors, but the *resolved* [viewColumn](#TextEditor.viewColumn)-value
+		 * of editors will always be `One`, `Two`, `Three`,... or `undefined` but never `Active`.
 		 */
 		Active = -1,
+		/**
+		 * A *symbolic* editor column representing the column to the side of the active one. This value
+		 * can be used when opening editors, but the *resolved* [viewColumn](#TextEditor.viewColumn)-value
+		 * of editors will always be `One`, `Two`, `Three`,... or `undefined` but never `Beside`.
+		 */
+		Beside = -2,
 		/**
 		 * The first editor column.
 		 */
@@ -4038,7 +4045,31 @@ declare module 'vscode' {
 		/**
 		 * The third editor column.
 		 */
-		Three = 3
+		Three = 3,
+		/**
+		 * The fourth editor column.
+		 */
+		Four = 4,
+		/**
+		 * The fifth editor column.
+		 */
+		Five = 5,
+		/**
+		 * The sixth editor column.
+		 */
+		Six = 6,
+		/**
+		 * The seventh editor column.
+		 */
+		Seven = 7,
+		/**
+		 * The eighth editor column.
+		 */
+		Eight = 8,
+		/**
+		 * The ninth editor column.
+		 */
+		Nine = 9
 	}
 
 	/**
@@ -5646,8 +5677,8 @@ declare module 'vscode' {
 		 *
 		 * @param document A text document to be shown.
 		 * @param column A view column in which the [editor](#TextEditor) should be shown. The default is the [active](#ViewColumn.Active), other values
-		 * are adjusted to be `Min(column, columnCount + 1)`, the [active](#ViewColumn.Active)-column is
-		 * not adjusted.
+		 * are adjusted to be `Min(column, columnCount + 1)`, the [active](#ViewColumn.Active)-column is not adjusted. Use [`ViewColumn.Beside`](#ViewColumn.Beside)
+		 * to open the editor to the side of the currently active one.
 		 * @param preserveFocus When `true` the editor will not take focus.
 		 * @return A promise that resolves to an [editor](#TextEditor).
 		 */

src/vs/workbench/api/node/extHostTypeConverters.ts

@@ -23,6 +23,7 @@ import { IRelativePattern } from 'vs/base/common/glob';
 import * as languageSelector from 'vs/editor/common/modes/languageSelector';
 import { WorkspaceEditDto, ResourceTextEditDto } from 'vs/workbench/api/node/extHost.protocol';
 import { MarkerSeverity, IRelatedInformation, IMarkerData, MarkerTag } from 'vs/platform/markers/common/markers';
+import { ACTIVE_GROUP, SIDE_GROUP } from 'vs/workbench/services/editor/common/editorService';
 
 export interface PositionLike {
 	line: number;
@@ -159,29 +160,22 @@ export namespace DiagnosticSeverity {
 
 export namespace ViewColumn {
 	export function from(column?: vscode.ViewColumn): EditorViewColumn {
-		let editorColumn: EditorViewColumn;
-		if (column === <number>types.ViewColumn.One) {
-			editorColumn = 0;
-		} else if (column === <number>types.ViewColumn.Two) {
-			editorColumn = 1;
-		} else if (column === <number>types.ViewColumn.Three) {
-			editorColumn = 2;
-		} else {
-			// in any other case (no column or ViewColumn.Active), leave the
-			// editorColumn as undefined which signals to use the active column
-			editorColumn = undefined;
+		if (typeof column === 'number' && column >= types.ViewColumn.One) {
+			return column - 1; // adjust zero index (ViewColumn.ONE => 0)
+		}
+
+		if (column === types.ViewColumn.Beside) {
+			return SIDE_GROUP;
 		}
-		return editorColumn;
+
+		return ACTIVE_GROUP; // default is always the active group
 	}
 
 	export function to(position?: EditorViewColumn): vscode.ViewColumn {
-		if (position === 0) {
-			return <number>types.ViewColumn.One;
-		} else if (position === 1) {
-			return <number>types.ViewColumn.Two;
-		} else if (position === 2) {
-			return <number>types.ViewColumn.Three;
+		if (typeof position === 'number' && position >= 0) {
+			return position + 1; // adjust to index (ViewColumn.ONE => 1)
 		}
+
 		return undefined;
 	}
 }

src/vs/workbench/api/node/extHostTypes.ts

@@ -1120,9 +1120,16 @@ export class CompletionList {
 
 export enum ViewColumn {
 	Active = -1,
+	Beside = -2,
 	One = 1,
 	Two = 2,
-	Three = 3
+	Three = 3,
+	Four = 4,
+	Five = 5,
+	Six = 6,
+	Seven = 7,
+	Eight = 8,
+	Nine = 9
 }
 
 export enum StatusBarAlignment {

src/vs/workbench/api/shared/editor.ts

@@ -9,18 +9,14 @@ import { IEditorGroupsService, IEditorGroup, GroupsOrder } from 'vs/workbench/se
 import { GroupIdentifier } from 'vs/workbench/common/editor';
 import { ACTIVE_GROUP, SIDE_GROUP } from 'vs/workbench/services/editor/common/editorService';
 
-// TODO@api this was previously a hardcoded list of editor positions (ONE, TWO, THREE)
-// that with the introduction of grid editor feature is now unbounded. This should be
-// revisited when the grid functionality is exposed to extensions,
-
 export type EditorViewColumn = number;
 
 export function viewColumnToEditorGroup(editorGroupService: IEditorGroupsService, position?: EditorViewColumn): GroupIdentifier {
-	if (typeof position !== 'number') {
-		return ACTIVE_GROUP; // prefer active group when position is undefined
+	if (typeof position !== 'number' || position === ACTIVE_GROUP) {
+		return ACTIVE_GROUP; // prefer active group when position is undefined or passed in as such
 	}
 
-	const groups = editorGroupService.getGroups(GroupsOrder.CREATION_TIME);
+	const groups = editorGroupService.getGroups(GroupsOrder.GRID_APPEARANCE);
 
 	let candidate = groups[position];
 	if (candidate) {
@@ -29,14 +25,14 @@ export function viewColumnToEditorGroup(editorGroupService: IEditorGroupsService
 
 	let firstGroup = groups[0];
 	if (groups.length === 1 && firstGroup.count === 0) {
-		return firstGroup.id; // first editor should always open in first group
+		return firstGroup.id; // first editor should always open in first group independent from position provided
 	}
 
-	return SIDE_GROUP; // open to the side if group not found
+	return SIDE_GROUP; // open to the side if group not found or we are instructed to
 }
 
 export function editorGroupToViewColumn(editorGroupService: IEditorGroupsService, editorGroup: IEditorGroup | GroupIdentifier): EditorViewColumn {
-	const group = typeof editorGroup === 'number' ? editorGroupService.getGroup(editorGroup) : editorGroup;
+	const group = (typeof editorGroup === 'number') ? editorGroupService.getGroup(editorGroup) : editorGroup;
 
-	return editorGroupService.getGroups(GroupsOrder.CREATION_TIME).indexOf(group);
+	return editorGroupService.getGroups(GroupsOrder.GRID_APPEARANCE).indexOf(group);
 }