From 23ef7f5846ca48e58b2851c6fc9ca141f40f603b Mon Sep 17 00:00:00 2001 From: Andre Weinand Date: Wed, 16 Sep 2020 17:32:11 +0200 Subject: [PATCH] update for latest notebook API --- .vscode/launch.json | 16 +- package.json | 1 + src/nodeKernel.ts | 6 +- src/nodebookProvider.ts | 43 +- src/types/vscode.d.ts | 466 ++++++++++++++++--- src/types/vscode.proposed.d.ts | 798 +++++++++++++++++++++------------ 6 files changed, 961 insertions(+), 369 deletions(-) diff --git a/.vscode/launch.json b/.vscode/launch.json index 2ae4bfc..cb7b872 100644 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -9,29 +9,15 @@ "name": "Run Extension", "type": "extensionHost", "request": "launch", - "runtimeExecutable": "${execPath}", "args": [ "--extensionDevelopmentPath=${workspaceFolder}", + "--enable-proposed-api", "undefined_publisher.vscode-nodebook", "${workspaceFolder}/samplenotebooks" ], "outFiles": [ "${workspaceFolder}/out/**/*.js" ], "preLaunchTask": "${defaultBuildTask}" - }, - { - "name": "Extension Tests", - "type": "extensionHost", - "request": "launch", - "runtimeExecutable": "${execPath}", - "args": [ - "--extensionDevelopmentPath=${workspaceFolder}", - "--extensionTestsPath=${workspaceFolder}/out/test/suite/index" - ], - "outFiles": [ - "${workspaceFolder}/out/test/**/*.js" - ], - "preLaunchTask": "${defaultBuildTask}" } ] } diff --git a/package.json b/package.json index 0715ec1..7e55b0c 100644 --- a/package.json +++ b/package.json @@ -12,6 +12,7 @@ ], "activationEvents": [ "onNotebookEditor:nodebook", + "onNotebook:nodebook", "onDebugDynamicConfigurations:node" ], "main": "./out/extension.js", diff --git a/src/nodeKernel.ts b/src/nodeKernel.ts index f2282ea..3642d40 100644 --- a/src/nodeKernel.ts +++ b/src/nodeKernel.ts @@ -22,7 +22,6 @@ export class NodeKernel { private debugPort?: number; constructor(private document: vscode.NotebookDocument) { - this.tmpDirectory = fs.mkdtempSync(PATH.join(os.tmpdir(), 'vscode-nodebook-')); } public async start() { @@ -51,7 +50,7 @@ export class NodeKernel { __notebookID: this.document.uri.toString(), name: 'nodebook', request: 'attach', - type: 'node', + type: 'node2', // doesn't work with 'pwa-node' port: this.debugPort, timeout: 100000, outputCapture: 'std', @@ -143,6 +142,9 @@ export class NodeKernel { // find cell in document by matching its URI const cell = this.document.cells.find(c => c.uri.toString() === uri); if (cell) { + if (!this.tmpDirectory) { + this.tmpDirectory = fs.mkdtempSync(PATH.join(os.tmpdir(), 'vscode-nodebook-')); + } const cellPath = `${this.tmpDirectory}/nodebook_cell_${cellUri.fragment}.js`; this.pathToCell.set(cellPath, cell); diff --git a/src/nodebookProvider.ts b/src/nodebookProvider.ts index 0ea7903..59c4985 100644 --- a/src/nodebookProvider.ts +++ b/src/nodebookProvider.ts @@ -22,11 +22,12 @@ const debugTypes = ['node', 'node2', 'pwa-node', 'pwa-chrome']; export class NodebookContentProvider implements vscode.NotebookContentProvider, vscode.NotebookKernel { + readonly id = 'nodebookKernel'; + public label = 'Node.js Kernel'; + private _localDisposables: vscode.Disposable[] = []; private readonly _associations = new Map(); - public label = 'Node.js Kernel'; - public kernel = this; onDidChangeNotebook: vscode.Event = new vscode.EventEmitter().event; @@ -84,6 +85,14 @@ export class NodebookContentProvider implements vscode.NotebookContentProvider, } })) ); + + vscode.notebook.registerNotebookKernelProvider({ + viewType: 'nodebook', + }, { + provideKernels: () => { + return [this]; + } + }); } public lookupNodebook(keyOrUri: string | vscode.Uri | undefined): Nodebook | undefined { @@ -157,23 +166,9 @@ export class NodebookContentProvider implements vscode.NotebookContentProvider, }; } - public async executeCell(document: vscode.NotebookDocument, cell: vscode.NotebookCell, token: vscode.CancellationToken): Promise { - - if (!cell) { - const project = this.lookupNodebook(document.uri); - if (project) { - project.restartKernel(); - } - // run them all - for (let cell of document.cells) { - if (cell.cellKind === vscode.CellKind.Code && cell.metadata.runnable) { - await this.executeCell(document, cell, token); - } - } - return; - } + public async executeCell(_document: vscode.NotebookDocument, cell: vscode.NotebookCell): Promise { let output = ''; let error: Error | undefined; @@ -200,16 +195,20 @@ export class NodebookContentProvider implements vscode.NotebookContentProvider, } } - public async executeAllCells(document: vscode.NotebookDocument, token: vscode.CancellationToken): Promise { + public cancelCellExecution(_document: vscode.NotebookDocument, _cell: vscode.NotebookCell): void { + // not yet supported + } + public async executeAllCells(document: vscode.NotebookDocument): Promise { for (const cell of document.cells) { - if (token.isCancellationRequested) { - break; - } - await this.executeCell(document, cell, token); + await this.executeCell(document, cell); } } + cancelAllCellsExecution(_document: vscode.NotebookDocument): void { + // not yet supported + } + public dispose() { this._localDisposables.forEach(d => d.dispose()); } diff --git a/src/types/vscode.d.ts b/src/types/vscode.d.ts index d4a0d5d..fe8860c 100644 --- a/src/types/vscode.d.ts +++ b/src/types/vscode.d.ts @@ -1112,7 +1112,7 @@ declare module 'vscode' { * isn't one of the main editors, e.g. an embedded editor, or when the editor * column is larger than three. */ - viewColumn?: ViewColumn; + readonly viewColumn?: ViewColumn; /** * Perform an edit on the document associated with this text editor. @@ -1160,7 +1160,7 @@ declare module 'vscode' { revealRange(range: Range, revealType?: TextEditorRevealType): void; /** - * ~~Show the text editor.~~ + * Show the text editor. * * @deprecated Use [window.showTextDocument](#window.showTextDocument) instead. * @@ -1170,7 +1170,7 @@ declare module 'vscode' { show(column?: ViewColumn): void; /** - * ~~Hide the text editor.~~ + * Hide the text editor. * * @deprecated Use the command `workbench.action.closeActiveEditor` instead. * This method shows unexpected behavior and will be removed in the next major update. @@ -1475,7 +1475,8 @@ declare module 'vscode' { * A function that represents an event to which you subscribe by calling it with * a listener function as argument. * - * @sample `item.onDidChange(function(event) { console.log("Event happened: " + event); });` + * @example + * item.onDidChange(function(event) { console.log("Event happened: " + event); }); */ export interface Event { @@ -1734,8 +1735,8 @@ declare module 'vscode' { /** * Dialog title. * - * Depending on the underlying operating system this parameter might be ignored, since some - * systems do not present title on open dialogs. + * This parameter might be ignored, as not all operating systems display a title on open dialogs + * (for example, macOS). */ title?: string; } @@ -1769,8 +1770,8 @@ declare module 'vscode' { /** * Dialog title. * - * Depending on the underlying operating system this parameter might be ignored, since some - * systems do not present title on save dialogs. + * This parameter might be ignored, as not all operating systems display a title on save dialogs + * (for example, macOS). */ title?: string; } @@ -1920,8 +1921,11 @@ declare module 'vscode' { * the [language](#TextDocument.languageId), the [scheme](#Uri.scheme) of * its resource, or a glob-pattern that is applied to the [path](#TextDocument.fileName). * - * @sample A language filter that applies to typescript files on disk: `{ language: 'typescript', scheme: 'file' }` - * @sample A language filter that applies to all package.json paths: `{ language: 'json', scheme: 'untitled', pattern: '**​/package.json' }` + * @example A language filter that applies to typescript files on disk + * { language: 'typescript', scheme: 'file' } + * + * @example A language filter that applies to all package.json paths + * { language: 'json', scheme: 'untitled', pattern: '**​/package.json' } */ export interface DocumentFilter { @@ -1951,7 +1955,8 @@ declare module 'vscode' { * a feature works without further context, e.g. without the need to resolve related * 'files'. * - * @sample `let sel:DocumentSelector = { scheme: 'file', language: 'typescript' }`; + * @example + * let sel:DocumentSelector = { scheme: 'file', language: 'typescript' }; */ export type DocumentSelector = DocumentFilter | string | Array; @@ -2498,9 +2503,9 @@ declare module 'vscode' { } /** - * ~~MarkedString can be used to render human-readable text. It is either a markdown string + * MarkedString can be used to render human-readable text. It is either a markdown string * or a code-block that provides a language and a code snippet. Note that - * markdown strings will be sanitized - that means html will be escaped.~~ + * markdown strings will be sanitized - that means html will be escaped. * * @deprecated This type is deprecated, please use [`MarkdownString`](#MarkdownString) instead. */ @@ -2753,7 +2758,7 @@ declare module 'vscode' { constructor(name: string, kind: SymbolKind, containerName: string, location: Location); /** - * ~~Creates a new symbol information object.~~ + * Creates a new symbol information object. * * @deprecated Please use the constructor taking a [location](#Location) object. * @@ -3086,6 +3091,8 @@ declare module 'vscode' { * @param uri Uri of the new file.. * @param options Defines if an existing file should be overwritten or be * ignored. When overwrite and ignoreIfExists are both set overwrite wins. + * When both are unset and when the file already exists then the edit cannot + * be applied successfully. * @param metadata Optional metadata for the entry. */ createFile(uri: Uri, options?: { overwrite?: boolean, ignoreIfExists?: boolean }, metadata?: WorkspaceEditEntryMetadata): void; @@ -3818,6 +3825,13 @@ declare module 'vscode' { * A string that should be used when comparing this item * with other items. When `falsy` the [label](#CompletionItem.label) * is used. + * + * Note that `sortText` is only used for the initial ordering of completion + * items. When having a leading word (prefix) ordering is based on how + * well completion match that prefix and the initial ordering is only used + * when completions match equal. The prefix is defined by the + * [`range`](#CompletionItem.range)-property and can therefore be different + * for each completion. */ sortText?: string; @@ -3825,6 +3839,10 @@ declare module 'vscode' { * A string that should be used when filtering a set of * completion items. When `falsy` the [label](#CompletionItem.label) * is used. + * + * Note that the filter text is matched against the leading word (prefix) which is defined + * by the [`range`](#CompletionItem.range)-property. + * prefix. */ filterText?: string; @@ -3872,12 +3890,12 @@ declare module 'vscode' { /** * @deprecated Use `CompletionItem.insertText` and `CompletionItem.range` instead. * - * ~~An [edit](#TextEdit) which is applied to a document when selecting + * An [edit](#TextEdit) which is applied to a document when selecting * this completion. When an edit is provided the value of - * [insertText](#CompletionItem.insertText) is ignored.~~ + * [insertText](#CompletionItem.insertText) is ignored. * - * ~~The [range](#Range) of the edit must be single-line and on the same - * line completions were [requested](#CompletionItemProvider.provideCompletionItems) at.~~ + * The [range](#Range) of the edit must be single-line and on the same + * line completions were [requested](#CompletionItemProvider.provideCompletionItems) at. */ textEdit?: TextEdit; @@ -4682,7 +4700,7 @@ declare module 'vscode' { * The *effective* value (returned by [`get`](#WorkspaceConfiguration.get)) is computed by overriding or merging the values in the following order. * * ``` - * `defaultValue` + * `defaultValue` (if defined in `package.json` otherwise derived from the value's type) * `globalValue` (if defined) * `workspaceValue` (if defined) * `workspaceFolderValue` (if defined) @@ -5218,7 +5236,7 @@ declare module 'vscode' { show(preserveFocus?: boolean): void; /** - * ~~Reveal this channel in the UI.~~ + * Reveal this channel in the UI. * * @deprecated Use the overload with just one parameter (`show(preserveFocus?: boolean): void`). * @@ -5420,6 +5438,66 @@ declare module 'vscode' { dispose(): void; } + /** + * Provides information on a line in a terminal in order to provide links for it. + */ + export interface TerminalLinkContext { + /** + * This is the text from the unwrapped line in the terminal. + */ + line: string; + + /** + * The terminal the link belongs to. + */ + terminal: Terminal; + } + + /** + * A provider that enables detection and handling of links within terminals. + */ + export interface TerminalLinkProvider { + /** + * Provide terminal links for the given context. Note that this can be called multiple times + * even before previous calls resolve, make sure to not share global objects (eg. `RegExp`) + * that could have problems when asynchronous usage may overlap. + * @param context Information about what links are being provided for. + * @param token A cancellation token. + * @return A list of terminal links for the given line. + */ + provideTerminalLinks(context: TerminalLinkContext, token: CancellationToken): ProviderResult + + /** + * Handle an activated terminal link. + * @param link The link to handle. + */ + handleTerminalLink(link: T): ProviderResult; + } + + /** + * A link on a terminal line. + */ + export interface TerminalLink { + /** + * The start index of the link on [TerminalLinkContext.line](#TerminalLinkContext.line]. + */ + startIndex: number; + + /** + * The length of the link on [TerminalLinkContext.line](#TerminalLinkContext.line] + */ + length: number; + + /** + * The tooltip text when you hover over this link. + * + * If a tooltip is provided, is will be displayed in a string that includes instructions on + * how to trigger the link, such as `{0} (ctrl + click)`. The specific instructions vary + * depending on OS, user settings, and localization. + */ + tooltip?: string; + } + /** * In a remote window the extension kind describes if an extension * runs where the UI (window) runs or if an extension runs remotely. @@ -5564,11 +5642,28 @@ declare module 'vscode' { /** * Get the absolute path of a resource contained in the extension. * + * *Note* that an absolute uri can be constructed via [`Uri.joinPath`](#Uri.joinPath) and + * [`extensionUri`](#ExtensionContent.extensionUri), e.g. `vscode.Uri.joinPath(context.extensionUri, relativePath);` + * * @param relativePath A relative path to a resource contained in the extension. * @return The absolute path of the resource. */ asAbsolutePath(relativePath: string): string; + /** + * The uri of a workspace specific directory in which the extension + * can store private state. The directory might not exist and creation is + * up to the extension. However, the parent directory is guaranteed to be existent. + * The value is `undefined` when no workspace nor folder has been opened. + * + * Use [`workspaceState`](#ExtensionContext.workspaceState) or + * [`globalState`](#ExtensionContext.globalState) to store key value data. + * + * @see [`workspace.fs`](#FileSystem) for how to read and write files and folders from + * an uri. + */ + readonly storageUri: Uri | undefined; + /** * An absolute file path of a workspace specific directory in which the extension * can store private state. The directory might not exist on disk and creation is @@ -5576,22 +5671,50 @@ declare module 'vscode' { * * Use [`workspaceState`](#ExtensionContext.workspaceState) or * [`globalState`](#ExtensionContext.globalState) to store key value data. + * + * @deprecated Use [storagePath](#ExtensionContent.storageUri) instead. */ readonly storagePath: string | undefined; + /** + * The uri of a directory in which the extension can store global state. + * The directory might not exist on disk and creation is + * up to the extension. However, the parent directory is guaranteed to be existent. + * + * Use [`globalState`](#ExtensionContext.globalState) to store key value data. + * + * @see [`workspace.fs`](#FileSystem) for how to read and write files and folders from + * an uri. + */ + readonly globalStorageUri: Uri; + /** * An absolute file path in which the extension can store global state. * The directory might not exist on disk and creation is * up to the extension. However, the parent directory is guaranteed to be existent. * * Use [`globalState`](#ExtensionContext.globalState) to store key value data. + * + * @deprecated Use [globalStoragePath](#ExtensionContent.globalStorageUri) instead. */ readonly globalStoragePath: string; + /** + * The uri of a directory in which the extension can create log files. + * The directory might not exist on disk and creation is up to the extension. However, + * the parent directory is guaranteed to be existent. + * + * @see [`workspace.fs`](#FileSystem) for how to read and write files and folders from + * an uri. + */ + readonly logUri: Uri; + /** * An absolute file path of a directory in which the extension can create log files. * The directory might not exist on disk and creation is up to the extension. However, * the parent directory is guaranteed to be existent. + * + * @deprecated Use [logUri](#ExtensionContext.logUri) instead. */ readonly logPath: string; @@ -6021,9 +6144,10 @@ declare module 'vscode' { * [Pseudoterminal.close](#Pseudoterminal.close). When the task is complete fire * [Pseudoterminal.onDidClose](#Pseudoterminal.onDidClose). * @param process The [Pseudoterminal](#Pseudoterminal) to be used by the task to display output. - * @param callback The callback that will be called when the task is started by a user. + * @param callback The callback that will be called when the task is started by a user. Any ${} style variables that + * were in the task definition will be resolved and passed into the callback. */ - constructor(callback: () => Thenable); + constructor(callback: (resolvedDefinition: TaskDefinition) => Thenable); } /** @@ -6071,7 +6195,7 @@ declare module 'vscode' { constructor(taskDefinition: TaskDefinition, scope: WorkspaceFolder | TaskScope.Global | TaskScope.Workspace, name: string, source: string, execution?: ProcessExecution | ShellExecution | CustomExecution, problemMatchers?: string | string[]); /** - * ~~Creates a new task.~~ + * Creates a new task. * * @deprecated Use the new constructors that allow specifying a scope for the task. * @@ -6100,6 +6224,13 @@ declare module 'vscode' { */ name: string; + /** + * A human-readable string which is rendered less prominently on a separate line in places + * where the task's name is displayed. Supports rendering of [theme icons](#ThemeIcon) + * via the `$()`-syntax. + */ + detail?: string; + /** * The task's execution engine */ @@ -6151,7 +6282,7 @@ declare module 'vscode' { * @param token A cancellation token. * @return an array of tasks */ - provideTasks(token?: CancellationToken): ProviderResult; + provideTasks(token: CancellationToken): ProviderResult; /** * Resolves a task that has no [`execution`](#Task.execution) set. Tasks are @@ -6166,7 +6297,7 @@ declare module 'vscode' { * @param token A cancellation token. * @return The resolved task */ - resolveTask(task: T, token?: CancellationToken): ProviderResult; + resolveTask(task: T, token: CancellationToken): ProviderResult; } /** @@ -6285,6 +6416,10 @@ declare module 'vscode' { * Executes a task that is managed by VS Code. The returned * task execution can be used to terminate the task. * + * @throws When running a ShellExecution or a ProcessExecution + * task in an environment where a new process cannot be started. + * In such an environment, only CustomExecution tasks can be run. + * * @param task the task to execute */ export function executeTask(task: Task): Thenable; @@ -6974,8 +7109,10 @@ declare module 'vscode' { * VS Code will save off the state from `setState` of all webviews that have a serializer. When the * webview first becomes visible after the restart, this state is passed to `deserializeWebviewPanel`. * The extension can then restore the old `WebviewPanel` from this state. + * + * @param T Type of the webview's state. */ - interface WebviewPanelSerializer { + interface WebviewPanelSerializer { /** * Restore a webview panel from its serialized `state`. * @@ -6987,7 +7124,7 @@ declare module 'vscode' { * * @return Thenable indicating that the webview has been fully restored. */ - deserializeWebviewPanel(webviewPanel: WebviewPanel, state: any): Thenable; + deserializeWebviewPanel(webviewPanel: WebviewPanel, state: T): Thenable; } /** @@ -7346,6 +7483,9 @@ declare module 'vscode' { /** * The application root folder from which the editor is running. + * + * *Note* that the value is the empty string when running in an + * environment that has no representation of an application root folder. */ export const appRoot: string; @@ -7388,7 +7528,8 @@ declare module 'vscode' { /** * The detected default shell for the extension host, this is overridden by the - * `terminal.integrated.shell` setting for the extension host's platform. + * `terminal.integrated.shell` setting for the extension host's platform. Note that in + * environments that do not support a shell the value is the empty string. */ export const shell: string; @@ -7912,7 +8053,7 @@ declare module 'vscode' { * @param options Options that control the dialog. * @returns A promise that resolves to the selected resources or `undefined`. */ - export function showOpenDialog(options: OpenDialogOptions): Thenable; + export function showOpenDialog(options?: OpenDialogOptions): Thenable; /** * Shows a file save dialog to the user which allows to select a file @@ -7921,7 +8062,7 @@ declare module 'vscode' { * @param options Options that control the dialog. * @returns A promise that resolves to the selected resource or `undefined`. */ - export function showSaveDialog(options: SaveDialogOptions): Thenable; + export function showSaveDialog(options?: SaveDialogOptions): Thenable; /** * Opens an input box to ask the user for input. @@ -8011,8 +8152,8 @@ declare module 'vscode' { export function setStatusBarMessage(text: string): Disposable; /** - * ~~Show progress in the Source Control viewlet while running the given callback and while - * its returned promise isn't resolve or rejected.~~ + * Show progress in the Source Control viewlet while running the given callback and while + * its returned promise isn't resolve or rejected. * * @deprecated Use `withProgress` instead. * @@ -8062,6 +8203,7 @@ declare module 'vscode' { * allows specifying shell args in * [command-line format](https://msdn.microsoft.com/en-au/08dfcab2-eb6e-49a4-80eb-87d4076c98c6). * @return A new Terminal. + * @throws When running in an environment where a new process cannot be started. */ export function createTerminal(name?: string, shellPath?: string, shellArgs?: string[] | string): Terminal; @@ -8070,6 +8212,7 @@ declare module 'vscode' { * * @param options A TerminalOptions object describing the characteristics of the new terminal. * @return A new Terminal. + * @throws When running in an environment where a new process cannot be started. */ export function createTerminal(options: TerminalOptions): Terminal; @@ -8174,6 +8317,13 @@ declare module 'vscode' { readonly supportsMultipleEditorsPerDocument?: boolean; }): Disposable; + /** + * Register provider that enables the detection and handling of links within the terminal. + * @param provider The provider that provides the terminal links. + * @return Disposable that unregisters the provider. + */ + export function registerTerminalLinkProvider(provider: TerminalLinkProvider): Disposable; + /** * The currently active color theme as configured in the settings. The active * theme can be changed via the `workbench.colorTheme` setting. @@ -9439,8 +9589,8 @@ declare module 'vscode' { export const fs: FileSystem; /** - * ~~The folder that is open in the editor. `undefined` when no folder - * has been opened.~~ + * The folder that is open in the editor. `undefined` when no folder + * has been opened. * * @deprecated Use [`workspaceFolders`](#workspace.workspaceFolders) instead. */ @@ -9581,7 +9731,9 @@ declare module 'vscode' { /** * Find files across all [workspace folders](#workspace.workspaceFolders) in the workspace. * - * @sample `findFiles('**​/*.js', '**​/node_modules/**', 10)` + * @example + * findFiles('**​/*.js', '**​/node_modules/**', 10) + * * @param include A [glob pattern](#GlobPattern) that defines the files to search for. The glob pattern * will be matched against the file paths of resulting matches relative to their workspace. Use a [relative pattern](#RelativePattern) * to restrict the search results to a [workspace folder](#WorkspaceFolder). @@ -9820,7 +9972,7 @@ declare module 'vscode' { export const onDidChangeConfiguration: Event; /** - * ~~Register a task provider.~~ + * Register a task provider. * * @deprecated Use the corresponding function on the `tasks` namespace instead * @@ -9858,11 +10010,12 @@ declare module 'vscode' { export interface ConfigurationChangeEvent { /** - * Returns `true` if the given section is affected in the provided scope. + * Checks if the given section has changed. + * If scope is provided, checks if the section has changed for resources under the given scope. * * @param section Configuration name, supports _dotted_ names. * @param scope A scope in which to check. - * @return `true` if the given section is affected in the provided scope. + * @return `true` if the given section has changed. */ affectsConfiguration(section: string, scope?: ConfigurationScope): boolean; } @@ -10445,6 +10598,26 @@ declare module 'vscode' { * resource state. */ readonly decorations?: SourceControlResourceDecorations; + + /** + * Context value of the resource state. This can be used to contribute resource specific actions. + * For example, if a resource is given a context value as `diffable`. When contributing actions to `scm/resourceState/context` + * using `menus` extension point, you can specify context value for key `scmResourceState` in `when` expressions, like `scmResourceState == diffable`. + * ``` + * "contributes": { + * "menus": { + * "scm/resourceState/context": [ + * { + * "command": "extension.diff", + * "when": "scmResourceState == diffable" + * } + * ] + * } + * } + * ``` + * This will show action `extension.diff` only for resources with `contextValue` is `diffable`. + */ + readonly contextValue?: string; } /** @@ -10558,8 +10731,8 @@ declare module 'vscode' { export namespace scm { /** - * ~~The [input box](#SourceControlInputBox) for the last source control - * created by the extension.~~ + * The [input box](#SourceControlInputBox) for the last source control + * created by the extension. * * @deprecated Use SourceControl.inputBox instead */ @@ -10576,6 +10749,27 @@ declare module 'vscode' { export function createSourceControl(id: string, label: string, rootUri?: Uri): SourceControl; } + /** + * A DebugProtocolMessage is an opaque stand-in type for the [ProtocolMessage](https://microsoft.github.io/debug-adapter-protocol/specification#Base_Protocol_ProtocolMessage) type defined in the Debug Adapter Protocol. + */ + export interface DebugProtocolMessage { + // Properties: see details [here](https://microsoft.github.io/debug-adapter-protocol/specification#Base_Protocol_ProtocolMessage). + } + + /** + * A DebugProtocolSource is an opaque stand-in type for the [Source](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Source) type defined in the Debug Adapter Protocol. + */ + export interface DebugProtocolSource { + // Properties: see details [here](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Source). + } + + /** + * A DebugProtocolBreakpoint is an opaque stand-in type for the [Breakpoint](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Breakpoint) type defined in the Debug Adapter Protocol. + */ + export interface DebugProtocolBreakpoint { + // Properties: see details [here](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Breakpoint). + } + /** * Configuration for a debug session. */ @@ -10639,6 +10833,15 @@ declare module 'vscode' { * Send a custom request to the debug adapter. */ customRequest(command: string, args?: any): Thenable; + + /** + * Maps a VS Code breakpoint to the corresponding Debug Adapter Protocol (DAP) breakpoint that is managed by the debug adapter of the debug session. + * If no DAP breakpoint exists (either because the VS Code breakpoint was not yet registered or because the debug adapter is not interested in the breakpoint), the value `undefined` is returned. + * + * @param breakpoint A VS Code [breakpoint](#Breakpoint). + * @return A promise that resolves to the Debug Adapter Protocol breakpoint or `undefined`. + */ + getDebugProtocolBreakpoint(breakpoint: Breakpoint): Thenable; } /** @@ -10779,6 +10982,21 @@ declare module 'vscode' { constructor(port: number, host?: string); } + /** + * Represents a debug adapter running as a Named Pipe (on Windows)/UNIX Domain Socket (on non-Windows) based server. + */ + export class DebugAdapterNamedPipeServer { + /** + * The path to the NamedPipe/UNIX Domain Socket. + */ + readonly path: string; + + /** + * Create a description for a debug adapter running as a socket based server. + */ + constructor(path: string); + } + /** * A debug adapter that implements the Debug Adapter Protocol can be registered with VS Code if it implements the DebugAdapter interface. */ @@ -10799,13 +11017,6 @@ declare module 'vscode' { handleMessage(message: DebugProtocolMessage): void; } - /** - * A DebugProtocolMessage is an opaque stand-in type for the [ProtocolMessage](https://microsoft.github.io/debug-adapter-protocol/specification#Base_Protocol_ProtocolMessage) type defined in the Debug Adapter Protocol. - */ - export interface DebugProtocolMessage { - // Properties: see details [here](https://microsoft.github.io/debug-adapter-protocol/specification#Base_Protocol_ProtocolMessage). - } - /** * A debug adapter descriptor for an inline implementation. */ @@ -10817,7 +11028,7 @@ declare module 'vscode' { constructor(implementation: DebugAdapter); } - export type DebugAdapterDescriptor = DebugAdapterExecutable | DebugAdapterServer | DebugAdapterInlineImplementation; + export type DebugAdapterDescriptor = DebugAdapterExecutable | DebugAdapterServer | DebugAdapterNamedPipeServer | DebugAdapterInlineImplementation; export interface DebugAdapterDescriptorFactory { /** @@ -11012,13 +11223,19 @@ declare module 'vscode' { * Defaults to Separate. */ consoleMode?: DebugConsoleMode; - } - /** - * A DebugProtocolSource is an opaque stand-in type for the [Source](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Source) type defined in the Debug Adapter Protocol. - */ - export interface DebugProtocolSource { - // Properties: see details [here](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Source). + /** + * Controls whether this session should run without debugging, thus ignoring breakpoints. + * When this property is not specified, the value from the parent session (if there is one) is used. + */ + noDebug?: boolean; + + /** + * Controls if the debug session's parent session is shown in the CALL STACK view even if it has only a single child. + * By default, the debug session will never hide its parent. + * If compact is true, debug sessions with a single child are hidden in the CALL STACK view to make the tree more compact. + */ + compact?: boolean; } /** @@ -11137,6 +11354,12 @@ declare module 'vscode' { */ export function startDebugging(folder: WorkspaceFolder | undefined, nameOrConfiguration: string | DebugConfiguration, parentSessionOrOptions?: DebugSession | DebugSessionOptions): Thenable; + /** + * Stop the given debug session or stop all debug sessions if session is omitted. + * @param session The [debug session](#DebugSession) to stop; if omitted all sessions are stopped. + */ + export function stopDebugging(session?: DebugSession): Thenable; + /** * Add breakpoints. * @param breakpoints The breakpoints to add. @@ -11510,6 +11733,141 @@ declare module 'vscode' { } //#endregion + + /** + * Represents a session of a currently logged in user. + */ + export interface AuthenticationSession { + /** + * The identifier of the authentication session. + */ + readonly id: string; + + /** + * The access token. + */ + readonly accessToken: string; + + /** + * The account associated with the session. + */ + readonly account: AuthenticationSessionAccountInformation; + + /** + * The permissions granted by the session's access token. Available scopes + * are defined by the [AuthenticationProvider](#AuthenticationProvider). + */ + readonly scopes: ReadonlyArray; + } + + /** + * The information of an account associated with an [AuthenticationSession](#AuthenticationSession). + */ + export interface AuthenticationSessionAccountInformation { + /** + * The unique identifier of the account. + */ + readonly id: string; + + /** + * The human-readable name of the account. + */ + readonly label: string; + } + + + /** + * Options to be used when getting an [AuthenticationSession](#AuthenticationSession) from an [AuthenticationProvider](#AuthenticationProvider). + */ + export interface AuthenticationGetSessionOptions { + /** + * Whether login should be performed if there is no matching session. + * + * If true, a modal dialog will be shown asking the user to sign in. If false, a numbered badge will be shown + * on the accounts activity bar icon. An entry for the extension will be added under the menu to sign in. This + * allows quietly prompting the user to sign in. + * + * Defaults to false. + */ + createIfNone?: boolean; + + /** + * Whether the existing user session preference should be cleared. + * + * For authentication providers that support being signed into multiple accounts at once, the user will be + * prompted to select an account to use when [getSession](#authentication.getSession) is called. This preference + * is remembered until [getSession](#authentication.getSession) is called with this flag. + * + * Defaults to false. + */ + clearSessionPreference?: boolean; + } + + /** + * Basic information about an [authenticationProvider](#AuthenticationProvider) + */ + export interface AuthenticationProviderInformation { + /** + * The unique identifier of the authentication provider. + */ + readonly id: string; + + /** + * The human-readable name of the authentication provider. + */ + readonly label: string; + } + + /** + * An [event](#Event) which fires when an [AuthenticationSession](#AuthenticationSession) is added, removed, or changed. + */ + export interface AuthenticationSessionsChangeEvent { + /** + * The [authenticationProvider](#AuthenticationProvider) that has had its sessions change. + */ + readonly provider: AuthenticationProviderInformation; + } + + /** + * Namespace for authentication. + */ + export namespace authentication { + /** + * Get an authentication session matching the desired scopes. Rejects if a provider with providerId is not + * registered, or if the user does not consent to sharing authentication information with + * the extension. If there are multiple sessions with the same scopes, the user will be shown a + * quickpick to select which account they would like to use. + * + * Currently, there are only two authentication providers that are contributed from built in extensions + * to VS Code that implement GitHub and Microsoft authentication: their providerId's are 'github' and 'microsoft'. + * @param providerId The id of the provider to use + * @param scopes A list of scopes representing the permissions requested. These are dependent on the authentication provider + * @param options The [getSessionOptions](#GetSessionOptions) to use + * @returns A thenable that resolves to an authentication session + */ + export function getSession(providerId: string, scopes: string[], options: AuthenticationGetSessionOptions & { createIfNone: true }): Thenable; + + /** + * Get an authentication session matching the desired scopes. Rejects if a provider with providerId is not + * registered, or if the user does not consent to sharing authentication information with + * the extension. If there are multiple sessions with the same scopes, the user will be shown a + * quickpick to select which account they would like to use. + * + * Currently, there are only two authentication providers that are contributed from built in extensions + * to VS Code that implement GitHub and Microsoft authentication: their providerId's are 'github' and 'microsoft'. + * @param providerId The id of the provider to use + * @param scopes A list of scopes representing the permissions requested. These are dependent on the authentication provider + * @param options The [getSessionOptions](#GetSessionOptions) to use + * @returns A thenable that resolves to an authentication session if available, or undefined if there are no sessions + */ + export function getSession(providerId: string, scopes: string[], options?: AuthenticationGetSessionOptions): Thenable; + + /** + * An [event](#Event) which fires when the authentication sessions of an authentication provider have + * been added, removed, or changed. + */ + export const onDidChangeSessions: Event; + } } /** diff --git a/src/types/vscode.proposed.d.ts b/src/types/vscode.proposed.d.ts index 5bb65b9..2f27335 100644 --- a/src/types/vscode.proposed.d.ts +++ b/src/types/vscode.proposed.d.ts @@ -3,8 +3,6 @@ * Licensed under the MIT License. See License.txt in the project root for license information. *--------------------------------------------------------------------------------------------*/ -import { MarkdownString } from 'vscode'; - /** * This is the place for API experiments and proposals. * These API are NOT stable and subject to change. They are only available in the Insiders @@ -20,41 +18,6 @@ declare module 'vscode' { // #region auth provider: https://github.com/microsoft/vscode/issues/88309 - export class AuthenticationSession { - /** - * The identifier of the authentication session. - */ - readonly id: string; - - /** - * The access token. - */ - readonly accessToken: string; - - /** - * The account associated with the session. - */ - readonly account: { - /** - * The human-readable name of the account. - */ - readonly displayName: string; - - /** - * The unique identifier of the account. - */ - readonly id: string; - }; - - /** - * The permissions granted by the session's access token. Available scopes - * are defined by the authentication provider. - */ - readonly scopes: string[]; - - constructor(id: string, accessToken: string, account: { displayName: string, id: string }, scopes: string[]); - } - /** * An [event](#Event) which fires when an [AuthenticationProvider](#AuthenticationProvider) is added or removed. */ @@ -62,48 +25,32 @@ declare module 'vscode' { /** * The ids of the [authenticationProvider](#AuthenticationProvider)s that have been added. */ - readonly added: string[]; + readonly added: ReadonlyArray; /** * The ids of the [authenticationProvider](#AuthenticationProvider)s that have been removed. */ - readonly removed: string[]; - } - - /** - * Options to be used when getting a session from an [AuthenticationProvider](#AuthenticationProvider). - */ - export interface AuthenticationGetSessionOptions { - /** - * Whether login should be performed if there is no matching session. Defaults to false. - */ - createIfNone?: boolean; - - /** - * Whether the existing user session preference should be cleared. Set to allow the user to switch accounts. - * Defaults to false. - */ - clearSessionPreference?: boolean; + readonly removed: ReadonlyArray; } /** * An [event](#Event) which fires when an [AuthenticationSession](#AuthenticationSession) is added, removed, or changed. */ - export interface AuthenticationSessionsChangeEvent { + export interface AuthenticationProviderAuthenticationSessionsChangeEvent { /** * The ids of the [AuthenticationSession](#AuthenticationSession)s that have been added. */ - readonly added: string[]; + readonly added: ReadonlyArray; /** * The ids of the [AuthenticationSession](#AuthenticationSession)s that have been removed. */ - readonly removed: string[]; + readonly removed: ReadonlyArray; /** * The ids of the [AuthenticationSession](#AuthenticationSession)s that have been changed. */ - readonly changed: string[]; + readonly changed: ReadonlyArray; } /** @@ -122,7 +69,7 @@ declare module 'vscode' { /** * The human-readable name of the provider. */ - readonly displayName: string; + readonly label: string; /** * Whether it is possible to be signed into multiple accounts at once with this provider @@ -133,7 +80,7 @@ declare module 'vscode' { * An [event](#Event) which fires when the array of sessions has changed, or data * within a session has changed. */ - readonly onDidChangeSessions: Event; + readonly onDidChangeSessions: Event; /** * Returns an array of current sessions. @@ -165,11 +112,13 @@ declare module 'vscode' { export function registerAuthenticationProvider(provider: AuthenticationProvider): Disposable; /** + * @deprecated - getSession should now trigger extension activation. * Fires with the provider id that was registered or unregistered. */ export const onDidChangeAuthenticationProviders: Event; /** + * @deprecated * The ids of the currently registered authentication providers. * @returns An array of the ids of authentication providers that are currently registered. */ @@ -179,42 +128,12 @@ declare module 'vscode' { * @deprecated * An array of the ids of authentication providers that are currently registered. */ - export const providerIds: string[]; - - /** - * Returns whether a provider has any sessions matching the requested scopes. This request - * is transparent to the user, no UI is shown. Rejects if a provider with providerId is not - * registered. - * @param providerId The id of the provider - * @param scopes A list of scopes representing the permissions requested. These are dependent on the authentication - * provider - * @returns A thenable that resolve to whether the provider has sessions with the requested scopes. - */ - export function hasSessions(providerId: string, scopes: string[]): Thenable; - - /** - * Get an authentication session matching the desired scopes. Rejects if a provider with providerId is not - * registered, or if the user does not consent to sharing authentication information with - * the extension. If there are multiple sessions with the same scopes, the user will be shown a - * quickpick to select which account they would like to use. - * @param providerId The id of the provider to use - * @param scopes A list of scopes representing the permissions requested. These are dependent on the authentication provider - * @param options The [getSessionOptions](#GetSessionOptions) to use - * @returns A thenable that resolves to an authentication session - */ - export function getSession(providerId: string, scopes: string[], options: AuthenticationGetSessionOptions & { createIfNone: true }): Thenable; + export const providerIds: ReadonlyArray; /** - * Get an authentication session matching the desired scopes. Rejects if a provider with providerId is not - * registered, or if the user does not consent to sharing authentication information with - * the extension. If there are multiple sessions with the same scopes, the user will be shown a - * quickpick to select which account they would like to use. - * @param providerId The id of the provider to use - * @param scopes A list of scopes representing the permissions requested. These are dependent on the authentication provider - * @param options The [getSessionOptions](#GetSessionOptions) to use - * @returns A thenable that resolves to an authentication session if available, or undefined if there are no sessions + * An array of the information of authentication providers that are currently registered. */ - export function getSession(providerId: string, scopes: string[], options: AuthenticationGetSessionOptions): Thenable; + export const providers: ReadonlyArray; /** * @deprecated @@ -224,13 +143,6 @@ declare module 'vscode' { * provider */ export function logout(providerId: string, sessionId: string): Thenable; - - /** - * An [event](#Event) which fires when the array of sessions has changed, or data - * within a session has changed for a provider. Fires with the ids of the providers - * that have had session data change. - */ - export const onDidChangeSessions: Event<{ [providerId: string]: AuthenticationSessionsChangeEvent; }>; } //#endregion @@ -313,6 +225,9 @@ declare module 'vscode' { /** * Forwards a port. If the current resolver implements RemoteAuthorityResolver:forwardPort then that will be used to make the tunnel. * By default, openTunnel only support localhost; however, RemoteAuthorityResolver:tunnelFactory can be used to support other ips. + * + * @throws When run in an environment without a remote. + * * @param tunnelOptions The `localPort` is a suggestion only. If that port is not available another will be chosen. */ export function openTunnel(tunnelOptions: TunnelOptions): Thenable; @@ -337,13 +252,14 @@ declare module 'vscode' { export interface ResourceLabelFormatting { label: string; // myLabel:/${path} - // TODO@isidorn + // For historic reasons we use an or string here. Once we finalize this API we should start using enums instead and adopt it in extensions. // eslint-disable-next-line vscode-dts-literal-or-types separator: '/' | '\\' | ''; tildify?: boolean; normalizeDriveLetter?: boolean; workspaceSuffix?: string; authorityPrefix?: string; + stripPathStartingSeparator?: boolean; } export namespace workspace { @@ -801,16 +717,69 @@ declare module 'vscode' { //#region file-decorations: https://github.com/microsoft/vscode/issues/54938 + // TODO@jrieken FileDecoration, FileDecorationProvider etc. + // TODO@jrieken Add selector notion to limit decorations to a view. + // TODO@jrieken Rename `Decoration.letter` to `short` so that it could be used for coverage et al. + export class Decoration { + + /** + * A letter that represents this decoration. + */ letter?: string; + + /** + * The human-readable title for this decoration. + */ title?: string; + + /** + * The color of this decoration. + */ color?: ThemeColor; + + /** + * The priority of this decoration. + */ priority?: number; + + /** + * A flag expressing that this decoration should be + * propagted to its parents. + */ bubble?: boolean; + + /** + * Creates a new decoration. + * + * @param letter A letter that represents the decoration. + * @param title The title of the decoration. + * @param color The color of the decoration. + */ + constructor(letter?: string, title?: string, color?: ThemeColor); } + /** + * The decoration provider interfaces defines the contract between extensions and + * file decorations. + */ export interface DecorationProvider { + + /** + * An event to signal decorations for one or many files have changed. + * + * @see [EventEmitter](#EventEmitter + */ onDidChangeDecorations: Event; + + /** + * Provide decorations for a given uri. + * + * + * @param uri The uri of the file to provide a decoration for. + * @param token A cancellation token. + * @returns A decoration or a thenable that resolves to such. + */ provideDecoration(uri: Uri, token: CancellationToken): ProviderResult; } @@ -822,20 +791,20 @@ declare module 'vscode' { //#region debug - export interface DebugSessionOptions { - /** - * Controls whether this session should run without debugging, thus ignoring breakpoints. - * When this property is not specified, the value from the parent session (if there is one) is used. - */ - noDebug?: boolean; + /** + * A DebugProtocolVariableContainer is an opaque stand-in type for the intersection of the Scope and Variable types defined in the Debug Adapter Protocol. + * See https://microsoft.github.io/debug-adapter-protocol/specification#Types_Scope and https://microsoft.github.io/debug-adapter-protocol/specification#Types_Variable. + */ + export interface DebugProtocolVariableContainer { + // Properties: the intersection of DAP's Scope and Variable types. + } - /** - * Controls if the debug session created will be compacted with the parent in the CALL STACK view. - * Compact with the parent is only done if the session is the only child of it's parent session. - * Default is to compact. - * - */ - noCompact?: boolean; + /** + * A DebugProtocolVariable is an opaque stand-in type for the Variable type defined in the Debug Adapter Protocol. + * See https://microsoft.github.io/debug-adapter-protocol/specification#Types_Variable. + */ + export interface DebugProtocolVariable { + // Properties: see details [here](https://microsoft.github.io/debug-adapter-protocol/specification#Base_Protocol_Variable). } // deprecated debug API @@ -1004,89 +973,6 @@ declare module 'vscode' { //#endregion - //#region Terminal link handlers https://github.com/microsoft/vscode/issues/91606 - - export namespace window { - /** - * Register a [TerminalLinkHandler](#TerminalLinkHandler) that can be used to intercept and - * handle links that are activated within terminals. - * @param handler The link handler being registered. - * @return A disposable that unregisters the link handler. - */ - export function registerTerminalLinkHandler(handler: TerminalLinkHandler): Disposable; - } - - /** - * Describes how to handle terminal links. - */ - export interface TerminalLinkHandler { - /** - * Handles a link that is activated within the terminal. - * - * @param terminal The terminal the link was activated on. - * @param link The text of the link activated. - * @return Whether the link was handled, if the link was handled this link will not be - * considered by any other extension or by the default built-in link handler. - */ - handleLink(terminal: Terminal, link: string): ProviderResult; - } - - //#endregion - - //#region Terminal link provider https://github.com/microsoft/vscode/issues/91606 - - export namespace window { - export function registerTerminalLinkProvider(provider: TerminalLinkProvider): Disposable; - } - - export interface TerminalLinkContext { - /** - * This is the text from the unwrapped line in the terminal. - */ - line: string; - - /** - * The terminal the link belongs to. - */ - terminal: Terminal; - } - - export interface TerminalLinkProvider { - /** - * Provide terminal links for the given context. - * @param context Information about what links are being provided for. - */ - provideTerminalLinks(context: TerminalLinkContext): ProviderResult - - /** - * Handle an activated terminal link. - */ - handleTerminalLink(link: T): void; - } - - export interface TerminalLink { - /** - * The 0-based start index of the link on [TerminalLinkContext.line](#TerminalLinkContext.line]. - */ - startIndex: number; - - /** - * The 0-based end index of the link on [TerminalLinkContext.line](#TerminalLinkContext.line]. - */ - endIndex: number; - - /** - * The tooltip text when you hover over this link. - * - * If a tooltip is provided, is will be displayed in a string that includes instructions on - * how to trigger the link, such as `{0} (ctrl + click)`. The specific instructions vary - * depending on OS, user settings, and localization. - */ - tooltip?: string; - } - - //#endregion - //#region @jrieken -> exclusive document filters export interface DocumentFilter { @@ -1147,27 +1033,6 @@ declare module 'vscode' { } //#endregion - //#region CustomExecution: https://github.com/microsoft/vscode/issues/81007 - /** - * A task to execute - */ - export class Task2 extends Task { - detail?: string; - } - - export class CustomExecution2 extends CustomExecution { - /** - * Constructs a CustomExecution task object. The callback will be executed the task is run, at which point the - * extension should return the Pseudoterminal it will "run in". The task should wait to do further execution until - * [Pseudoterminal.open](#Pseudoterminal.open) is called. Task cancellation should be handled using - * [Pseudoterminal.close](#Pseudoterminal.close). When the task is complete fire - * [Pseudoterminal.onDidClose](#Pseudoterminal.onDidClose). - * @param callback The callback that will be called when the task is started by a user. - */ - constructor(callback: (resolvedDefinition?: TaskDefinition) => Thenable); - } - //#endregion - //#region Task presentation group: https://github.com/microsoft/vscode/issues/47265 export interface TaskPresentationOptions { /** @@ -1244,9 +1109,11 @@ declare module 'vscode' { * @param position The position at which the command was invoked. * @param token A cancellation token. * @return A list of ranges that can be live-renamed togehter. The ranges must have - * identical length and contain identical text content. The ranges cannot overlap. + * identical length and contain identical text content. The ranges cannot overlap. Optional a word pattern + * that overrides the word pattern defined when registering the provider. Live rename stops as soon as the renamed content + * no longer matches the word pattern. */ - provideOnTypeRenameRanges(document: TextDocument, position: Position, token: CancellationToken): ProviderResult; + provideOnTypeRenameRanges(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<{ ranges: Range[]; wordPattern?: RegExp; }>; } namespace languages { @@ -1259,10 +1126,10 @@ declare module 'vscode' { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider An on type rename provider. - * @param stopPattern Stop on type renaming when input text matches the regular expression. Defaults to `^\s`. + * @param wordPattern Word pattern for this provider. * @return A [disposable](#Disposable) that unregisters this provider when being disposed. */ - export function registerOnTypeRenameProvider(selector: DocumentSelector, provider: OnTypeRenameProvider, stopPattern?: RegExp): Disposable; + export function registerOnTypeRenameProvider(selector: DocumentSelector, provider: OnTypeRenameProvider, wordPattern?: RegExp): Disposable; } //#endregion @@ -1375,9 +1242,14 @@ declare module 'vscode' { Error = 4 } + export enum NotebookRunState { + Running = 1, + Idle = 2 + } + export interface NotebookCellMetadata { /** - * Controls if the content of a cell is editable or not. + * Controls whether a cell's editor is editable/readonly. */ editable?: boolean; @@ -1424,6 +1296,16 @@ declare module 'vscode' { */ lastRunDuration?: number; + /** + * Whether a code cell's editor is collapsed + */ + inputCollapsed?: boolean; + + /** + * Whether a code cell's outputs are collapsed + */ + outputCollapsed?: boolean; + /** * Additional attributes of a cell metadata. */ @@ -1431,11 +1313,12 @@ declare module 'vscode' { } export interface NotebookCell { + readonly index: number; readonly notebook: NotebookDocument; readonly uri: Uri; readonly cellKind: CellKind; readonly document: TextDocument; - language: string; + readonly language: string; outputs: CellOutput[]; metadata: NotebookCellMetadata; } @@ -1477,20 +1360,27 @@ declare module 'vscode' { * Additional attributes of the document metadata. */ custom?: { [key: string]: any }; + + /** + * The document's current run state + */ + runState?: NotebookRunState; } export interface NotebookDocument { readonly uri: Uri; + readonly version: number; readonly fileName: string; readonly viewType: string; readonly isDirty: boolean; - readonly cells: NotebookCell[]; + readonly isUntitled: boolean; + readonly cells: ReadonlyArray; languages: string[]; - displayOrder?: GlobPattern[]; metadata: NotebookDocumentMetadata; } export interface NotebookConcatTextDocument { + uri: Uri; isClosed: boolean; dispose(): void; onDidChange: Event; @@ -1508,9 +1398,39 @@ declare module 'vscode' { contains(uri: Uri): boolean } - export interface NotebookEditorCellEdit { - insert(index: number, content: string | string[], language: string, type: CellKind, outputs: CellOutput[], metadata: NotebookCellMetadata | undefined): void; - delete(index: number): void; + export interface WorkspaceEdit { + replaceNotebookMetadata(uri: Uri, value: NotebookDocumentMetadata): void; + replaceNotebookCells(uri: Uri, start: number, end: number, cells: NotebookCellData[], metadata?: WorkspaceEditEntryMetadata): void; + replaceNotebookCellOutput(uri: Uri, index: number, outputs: CellOutput[], metadata?: WorkspaceEditEntryMetadata): void; + replaceNotebookCellMetadata(uri: Uri, index: number, cellMetadata: NotebookCellMetadata, metadata?: WorkspaceEditEntryMetadata): void; + } + + export interface NotebookEditorEdit { + replaceMetadata(value: NotebookDocumentMetadata): void; + replaceCells(start: number, end: number, cells: NotebookCellData[]): void; + replaceCellOutput(index: number, outputs: CellOutput[]): void; + replaceCellMetadata(index: number, metadata: NotebookCellMetadata): void; + } + + export interface NotebookCellRange { + readonly start: number; + readonly end: number; + } + + export enum NotebookEditorRevealType { + /** + * The range will be revealed with as little scrolling as possible. + */ + Default = 0, + /** + * The range will always be revealed in the center of the viewport. + */ + InCenter = 1, + /** + * If the range is outside the viewport, it will be revealed in the center of the viewport. + * Otherwise, it will be revealed with as little scrolling as possible. + */ + InCenterIfOutsideViewport = 2, } export interface NotebookEditor { @@ -1524,10 +1444,16 @@ declare module 'vscode' { */ readonly selection?: NotebookCell; + + /** + * The current visible ranges in the editor (vertically). + */ + readonly visibleRanges: NotebookCellRange[]; + /** * The column in which this editor shows. */ - viewColumn?: ViewColumn; + readonly viewColumn?: ViewColumn; /** * Whether the panel is active (focused by the user). @@ -1544,6 +1470,11 @@ declare module 'vscode' { */ readonly onDidDispose: Event; + /** + * Active kernel used in the editor + */ + readonly kernel?: NotebookKernel; + /** * Fired when the output hosting webview posts a message. */ @@ -1562,7 +1493,19 @@ declare module 'vscode' { */ asWebviewUri(localResource: Uri): Uri; - edit(callback: (editBuilder: NotebookEditorCellEdit) => void): Thenable; + /** + * Perform an edit on the notebook associated with this notebook editor. + * + * The given callback-function is invoked with an [edit-builder](#NotebookEditorEdit) which must + * be used to make edits. Note that the edit-builder is only valid while the + * callback executes. + * + * @param callback A function which can create edits using an [edit-builder](#NotebookEditorEdit). + * @return A promise that resolves with a value indicating if the edits could be applied. + */ + edit(callback: (editBuilder: NotebookEditorEdit) => void): Thenable; + + revealRange(range: NotebookCellRange, revealType?: NotebookEditorRevealType): void; } export interface NotebookOutputSelector { @@ -1575,29 +1518,8 @@ declare module 'vscode' { outputId: string; } - export interface NotebookOutputRenderer { - /** - * - * @returns HTML fragment. We can probably return `CellOutput` instead of string ? - * - */ - render(document: NotebookDocument, request: NotebookRenderRequest): string; - - /** - * Call before HTML from the renderer is executed, and will be called for - * every editor associated with notebook documents where the renderer - * is or was used. - * - * The communication object will only send and receive messages to the - * render API, retrieved via `acquireNotebookRendererApi`, acquired with - * this specific renderer's ID. - * - * If you need to keep an association between the communication object - * and the document for use in the `render()` method, you can use a WeakMap. - */ - resolveNotebook?(document: NotebookDocument, communication: NotebookCommunication): void; - - readonly preloads?: Uri[]; + export interface NotebookDocumentMetadataChangeEvent { + readonly document: NotebookDocument; } export interface NotebookCellsChangeData { @@ -1645,12 +1567,27 @@ declare module 'vscode' { readonly language: string; } + export interface NotebookCellMetadataChangeEvent { + readonly document: NotebookDocument; + readonly cell: NotebookCell; + } + + export interface NotebookEditorSelectionChangeEvent { + readonly notebookEditor: NotebookEditor; + readonly selection?: NotebookCell; + } + + export interface NotebookEditorVisibleRangesChangeEvent { + readonly notebookEditor: NotebookEditor; + readonly visibleRanges: ReadonlyArray; + } + export interface NotebookCellData { readonly cellKind: CellKind; readonly source: string; - language: string; - outputs: CellOutput[]; - metadata: NotebookCellMetadata; + readonly language: string; + readonly outputs: CellOutput[]; + readonly metadata: NotebookCellMetadata | undefined; } export interface NotebookData { @@ -1704,7 +1641,7 @@ declare module 'vscode' { /** * Unique identifier for the backup. * - * This id is passed back to your extension in `openCustomDocument` when opening a custom editor from a backup. + * This id is passed back to your extension in `openCustomDocument` when opening a notebook editor from a backup. */ readonly id: string; @@ -1758,57 +1695,115 @@ declare module 'vscode' { } export interface NotebookContentProvider { + /** + * Content providers should always use [file system providers](#FileSystemProvider) to + * resolve the raw content for `uri` as the resouce is not necessarily a file on disk. + */ openNotebook(uri: Uri, openContext: NotebookDocumentOpenContext): NotebookData | Promise; resolveNotebook(document: NotebookDocument, webview: NotebookCommunication): Promise; saveNotebook(document: NotebookDocument, cancellation: CancellationToken): Promise; saveNotebookAs(targetResource: Uri, document: NotebookDocument, cancellation: CancellationToken): Promise; readonly onDidChangeNotebook: Event; backupNotebook(document: NotebookDocument, context: NotebookDocumentBackupContext, cancellation: CancellationToken): Promise; - - kernel?: NotebookKernel; } export interface NotebookKernel { + readonly id?: string; label: string; + description?: string; + detail?: string; + isPreferred?: boolean; preloads?: Uri[]; - executeCell(document: NotebookDocument, cell: NotebookCell, token: CancellationToken): Promise; - executeAllCells(document: NotebookDocument, token: CancellationToken): Promise; + executeCell(document: NotebookDocument, cell: NotebookCell): void; + cancelCellExecution(document: NotebookDocument, cell: NotebookCell): void; + executeAllCells(document: NotebookDocument): void; + cancelAllCellsExecution(document: NotebookDocument): void; + } + + export interface NotebookDocumentFilter { + viewType?: string | string[]; + filenamePattern?: GlobPattern | { include: GlobPattern; exclude: GlobPattern }; + } + + export interface NotebookKernelProvider { + onDidChangeKernels?: Event; + provideKernels(document: NotebookDocument, token: CancellationToken): ProviderResult; + resolveKernel?(kernel: T, document: NotebookDocument, webview: NotebookCommunication, token: CancellationToken): ProviderResult; + } + + /** + * Represents the alignment of status bar items. + */ + export enum NotebookCellStatusBarAlignment { + + /** + * Aligned to the left side. + */ + Left = 1, + + /** + * Aligned to the right side. + */ + Right = 2 + } + + export interface NotebookCellStatusBarItem { + readonly cell: NotebookCell; + readonly alignment: NotebookCellStatusBarAlignment; + readonly priority?: number; + text: string; + tooltip: string | undefined; + command: string | Command | undefined; + accessibilityInformation?: AccessibilityInformation; + show(): void; + hide(): void; + dispose(): void; } export namespace notebook { export function registerNotebookContentProvider( notebookType: string, - provider: NotebookContentProvider - ): Disposable; - - export function registerNotebookKernel( - id: string, - selectors: GlobPattern[], - kernel: NotebookKernel + provider: NotebookContentProvider, + options?: { + /** + * Controls if outputs change will trigger notebook document content change and if it will be used in the diff editor + * Default to false. If the content provider doesn't persisit the outputs in the file document, this should be set to true. + */ + transientOutputs: boolean; + /** + * Controls if a meetadata property change will trigger notebook document content change and if it will be used in the diff editor + * Default to false. If the content provider doesn't persisit a metadata property in the file document, it should be set to true. + */ + transientMetadata: { [K in keyof NotebookCellMetadata]?: boolean } + } ): Disposable; - export function registerNotebookOutputRenderer( - id: string, - outputSelector: NotebookOutputSelector, - renderer: NotebookOutputRenderer + export function registerNotebookKernelProvider( + selector: NotebookDocumentFilter, + provider: NotebookKernelProvider ): Disposable; export const onDidOpenNotebookDocument: Event; export const onDidCloseNotebookDocument: Event; + export const onDidSaveNotebookDocument: Event; /** * All currently known notebook documents. */ export const notebookDocuments: ReadonlyArray; - export let visibleNotebookEditors: NotebookEditor[]; + export const visibleNotebookEditors: NotebookEditor[]; export const onDidChangeVisibleNotebookEditors: Event; - export let activeNotebookEditor: NotebookEditor | undefined; + export const activeNotebookEditor: NotebookEditor | undefined; export const onDidChangeActiveNotebookEditor: Event; + export const onDidChangeNotebookEditorSelection: Event; + export const onDidChangeNotebookEditorVisibleRanges: Event; + export const onDidChangeNotebookDocumentMetadata: Event; export const onDidChangeNotebookCells: Event; export const onDidChangeCellOutputs: Event; export const onDidChangeCellLanguage: Event; + export const onDidChangeCellMetadata: Event; /** * Create a document that is the concatenation of all notebook cells. By default all code-cells are included * but a selector can be provided to narrow to down the set of cells. @@ -1817,6 +1812,19 @@ declare module 'vscode' { * @param selector */ export function createConcatTextDocument(notebook: NotebookDocument, selector?: DocumentSelector): NotebookConcatTextDocument; + + export const onDidChangeActiveNotebookKernel: Event<{ document: NotebookDocument, kernel: NotebookKernel | undefined }>; + + /** + * Creates a notebook cell status bar [item](#NotebookCellStatusBarItem). + * It will be disposed automatically when the notebook document is closed or the cell is deleted. + * + * @param cell The cell on which this item should be shown. + * @param alignment The alignment of the item. + * @param priority The priority of the item. Higher values mean the item should be shown more to the left. + * @return A new status bar item. + */ + export function createCellStatusBarItem(cell: NotebookCell, alignment?: NotebookCellStatusBarAlignment, priority?: number): NotebookCellStatusBarItem; } //#endregion @@ -2031,4 +2039,242 @@ declare module 'vscode' { } //#endregion + + //#region https://github.com/microsoft/vscode/issues/104436 + + export enum ExtensionRuntime { + /** + * The extension is running in a NodeJS extension host. Runtime access to NodeJS APIs is available. + */ + Node = 1, + /** + * The extension is running in a Webworker extension host. Runtime access is limited to Webworker APIs. + */ + Webworker = 2 + } + + export interface ExtensionContext { + readonly extensionRuntime: ExtensionRuntime; + } + + //#endregion + + + //#region https://github.com/microsoft/vscode/issues/102091 + + export interface TextDocument { + + /** + * The [notebook](#NotebookDocument) that contains this document as a notebook cell or `undefined` when + * the document is not contained by a notebook (this should be the more frequent case). + */ + notebook: NotebookDocument | undefined; + } + //#endregion + + + //#region https://github.com/microsoft/vscode/issues/46585 + + /** + * A webview based view. + */ + export interface WebviewView { + /** + * Identifies the type of the webview view, such as `'hexEditor.dataView'`. + */ + readonly viewType: string; + + /** + * The underlying webview for the view. + */ + readonly webview: Webview; + + /** + * View title displayed in the UI. + * + * The view title is initially taken from the extension `package.json` contribution. + */ + title?: string; + + /** + * Human-readable string which is rendered less prominently in the title. + */ + description?: string; + + /** + * Event fired when the view is disposed. + * + * Views are disposed when they are explicitly hidden by a user (this happens when a user + * right clicks in a view and unchecks the webview view). + * + * Trying to use the view after it has been disposed throws an exception. + */ + readonly onDidDispose: Event; + + /** + * Tracks if the webview is currently visible. + * + * Views are visible when they are on the screen and expanded. + */ + readonly visible: boolean; + + /** + * Event fired when the visibility of the view changes. + * + * Actions that trigger a visibility change: + * + * - The view is collapsed or expanded. + * - The user switches to a different view group in the sidebar or panel. + * + * Note that hiding a view using the context menu instead disposes of the view and fires `onDidDispose`. + */ + readonly onDidChangeVisibility: Event; + + /** + * Reveal the view in the UI. + * + * If the view is collapsed, this will expand it. + * + * @param preserveFocus When `true` the view will not take focus. + */ + show(preserveFocus?: boolean): void; + } + + /** + * Additional information the webview view being resolved. + * + * @param T Type of the webview's state. + */ + interface WebviewViewResolveContext { + /** + * Persisted state from the webview content. + * + * To save resources, VS Code normally deallocates webview documents (the iframe content) that are not visible. + * For example, when the user collapse a view or switches to another top level activity in the sidebar, the + * `WebviewView` itself is kept alive but the webview's underlying document is deallocated. It is recreated when + * the view becomes visible again. + * + * You can prevent this behavior by setting `retainContextWhenHidden` in the `WebviewOptions`. However this + * increases resource usage and should be avoided wherever possible. Instead, you can use persisted state to + * save off a webview's state so that it can be quickly recreated as needed. + * + * To save off a persisted state, inside the webview call `acquireVsCodeApi().setState()` with + * any json serializable object. To restore the state again, call `getState()`. For example: + * + * ```js + * // Within the webview + * const vscode = acquireVsCodeApi(); + * + * // Get existing state + * const oldState = vscode.getState() || { value: 0 }; + * + * // Update state + * setState({ value: oldState.value + 1 }) + * ``` + * + * VS Code ensures that the persisted state is saved correctly when a webview is hidden and across + * editor restarts. + */ + readonly state: T | undefined; + } + + /** + * Provider for creating `WebviewView` elements. + */ + export interface WebviewViewProvider { + /** + * Revolves a webview view. + * + * `resolveWebviewView` is called when a view first becomes visible. This may happen when the view is + * first loaded or when the user hides and then shows a view again. + * + * @param webviewView Webview view to restore. The serializer should take ownership of this view. The + * provider must set the webview's `.html` and hook up all webview events it is interested in. + * @param context Additional metadata about the view being resolved. + * @param token Cancellation token indicating that the view being provided is no longer needed. + * + * @return Optional thenable indicating that the view has been fully resolved. + */ + resolveWebviewView(webviewView: WebviewView, context: WebviewViewResolveContext, token: CancellationToken): Thenable | void; + } + + namespace window { + /** + * Register a new provider for webview views. + * + * @param viewId Unique id of the view. This should match the `id` from the + * `views` contribution in the package.json. + * @param provider Provider for the webview views. + * + * @return Disposable that unregisters the provider. + */ + export function registerWebviewViewProvider(viewId: string, provider: WebviewViewProvider, options?: { + /** + * Content settings for the webview created for this view. + */ + readonly webviewOptions?: { + /** + * Controls if the webview element itself (iframe) is kept around even when the view + * is no longer visible. + * + * Normally the webview's html context is created when the view becomes visible + * and destroyed when it is hidden. Extensions that have complex state + * or UI can set the `retainContextWhenHidden` to make VS Code keep the webview + * context around, even when the webview moves to a background tab. When a webview using + * `retainContextWhenHidden` becomes hidden, its scripts and other dynamic content are suspended. + * When the view becomes visible again, the context is automatically restored + * in the exact same state it was in originally. You cannot send messages to a + * hidden webview, even with `retainContextWhenHidden` enabled. + * + * `retainContextWhenHidden` has a high memory overhead and should only be used if + * your view's context cannot be quickly saved and restored. + */ + readonly retainContextWhenHidden?: boolean; + }; + }): Disposable; + } + //#endregion + + //#region + + export interface FileSystem { + /** + * Check if a given file system supports writing files. + * + * Keep in mind that just because a file system supports writing, that does + * not mean that writes will always succeed. There may be permissions issues + * or other errors that prevent writing a file. + * + * @param scheme The scheme of the filesystem, for example `file` or `git`. + * + * @return `true` if the file system supports writing, `false` if it does not + * support writing (i.e. it is readonly), and `undefined` if VS Code does not + * know about the filesystem. + */ + isWritableFileSystem(scheme: string): boolean | undefined; + } + + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/105667 + + export interface TreeView { + /** + * An optional human-readable description that will be rendered in the title of the view. + * Setting the title description to null, undefined, or empty string will remove the title description from the view. + */ + description?: string | undefined; + } + //#endregion + + //#region https://github.com/microsoft/vscode/issues/103120 @alexr00 + export class ThemeIcon2 extends ThemeIcon { + /** + * Returns a new `ThemeIcon` that will use the specified `ThemeColor` + * @param color The `ThemeColor` to use for the icon. + */ + with(color: ThemeColor): ThemeIcon2; + } + //#endregion }