diff --git a/extensions/css-language-features/package.json b/extensions/css-language-features/package.json index af75de5386b..0533881380c 100644 --- a/extensions/css-language-features/package.json +++ b/extensions/css-language-features/package.json @@ -23,9 +23,6 @@ "supported": true } }, - "enabledApiProposals": [ - "documentPaste" - ], "scripts": { "compile": "npx gulp compile-extension:css-language-features-client compile-extension:css-language-features-server", "watch": "npx gulp watch-extension:css-language-features-client watch-extension:css-language-features-server", diff --git a/extensions/ipynb/package.json b/extensions/ipynb/package.json index 4209ddc130a..d9a9dd7a514 100644 --- a/extensions/ipynb/package.json +++ b/extensions/ipynb/package.json @@ -10,7 +10,6 @@ "vscode": "^1.57.0" }, "enabledApiProposals": [ - "documentPaste", "diffContentOptions" ], "activationEvents": [ diff --git a/extensions/markdown-language-features/package.json b/extensions/markdown-language-features/package.json index d7eddbf31bd..6d097be5470 100644 --- a/extensions/markdown-language-features/package.json +++ b/extensions/markdown-language-features/package.json @@ -15,9 +15,6 @@ "categories": [ "Programming Languages" ], - "enabledApiProposals": [ - "documentPaste" - ], "activationEvents": [ "onLanguage:markdown", "onCommand:markdown.api.render", diff --git a/extensions/typescript-language-features/package.json b/extensions/typescript-language-features/package.json index 51ac7bd20c9..ac6d0487a4c 100644 --- a/extensions/typescript-language-features/package.json +++ b/extensions/typescript-language-features/package.json @@ -13,7 +13,6 @@ "mappedEditsProvider", "codeActionAI", "codeActionRanges", - "documentPaste", "editorHoverVerbosityLevel" ], "capabilities": { diff --git a/extensions/typescript-language-features/src/languageFeatures/copyPaste.ts b/extensions/typescript-language-features/src/languageFeatures/copyPaste.ts index 71b6797f585..30a73d0adf7 100644 --- a/extensions/typescript-language-features/src/languageFeatures/copyPaste.ts +++ b/extensions/typescript-language-features/src/languageFeatures/copyPaste.ts @@ -43,7 +43,7 @@ const enabledSettingId = 'updateImportsOnPaste.enabled'; class DocumentPasteProvider implements vscode.DocumentPasteEditProvider { - static readonly kind = vscode.DocumentDropOrPasteEditKind.Text.append('updateImports', 'jsts'); + static readonly kind = vscode.DocumentDropOrPasteEditKind.TextUpdateImports.append('jsts'); static readonly metadataMimeType = 'application/vnd.code.jsts.metadata'; constructor( diff --git a/extensions/vscode-api-tests/package.json b/extensions/vscode-api-tests/package.json index 5f7681bf9d6..60b35b4dd9e 100644 --- a/extensions/vscode-api-tests/package.json +++ b/extensions/vscode-api-tests/package.json @@ -17,7 +17,6 @@ "defaultChatParticipant", "diffCommand", "documentFiltersExclusive", - "documentPaste", "editorInsets", "embeddings", "extensionRuntime", diff --git a/src/vs/platform/extensions/common/extensionsApiProposals.ts b/src/vs/platform/extensions/common/extensionsApiProposals.ts index bd35500287e..cced7c27af0 100644 --- a/src/vs/platform/extensions/common/extensionsApiProposals.ts +++ b/src/vs/platform/extensions/common/extensionsApiProposals.ts @@ -165,9 +165,6 @@ const _allApiProposals = { documentFiltersExclusive: { proposal: 'https://raw.githubusercontent.com/microsoft/vscode/main/src/vscode-dts/vscode.proposed.documentFiltersExclusive.d.ts', }, - documentPaste: { - proposal: 'https://raw.githubusercontent.com/microsoft/vscode/main/src/vscode-dts/vscode.proposed.documentPaste.d.ts', - }, editSessionIdentityProvider: { proposal: 'https://raw.githubusercontent.com/microsoft/vscode/main/src/vscode-dts/vscode.proposed.editSessionIdentityProvider.d.ts', }, diff --git a/src/vs/workbench/api/common/extHost.api.impl.ts b/src/vs/workbench/api/common/extHost.api.impl.ts index 868906908ea..0ca018013ca 100644 --- a/src/vs/workbench/api/common/extHost.api.impl.ts +++ b/src/vs/workbench/api/common/extHost.api.impl.ts @@ -545,7 +545,6 @@ export function createApiFactoryAndRegisterActors(accessor: ServicesAccessor): I return extHostLanguageFeatures.registerCodeActionProvider(extension, checkSelector(selector), provider, metadata); }, registerDocumentPasteEditProvider(selector: vscode.DocumentSelector, provider: vscode.DocumentPasteEditProvider, metadata: vscode.DocumentPasteProviderMetadata): vscode.Disposable { - checkProposedApiEnabled(extension, 'documentPaste'); return extHostLanguageFeatures.registerDocumentPasteEditProvider(extension, checkSelector(selector), provider, metadata); }, registerCodeLensProvider(selector: vscode.DocumentSelector, provider: vscode.CodeLensProvider): vscode.Disposable { @@ -669,7 +668,7 @@ export function createApiFactoryAndRegisterActors(accessor: ServicesAccessor): I return extHostLanguages.createLanguageStatusItem(extension, id, selector); }, registerDocumentDropEditProvider(selector: vscode.DocumentSelector, provider: vscode.DocumentDropEditProvider, metadata?: vscode.DocumentDropEditProviderMetadata): vscode.Disposable { - return extHostLanguageFeatures.registerDocumentOnDropEditProvider(extension, selector, provider, isProposedApiEnabled(extension, 'documentPaste') ? metadata : undefined); + return extHostLanguageFeatures.registerDocumentOnDropEditProvider(extension, selector, provider, metadata); } }; diff --git a/src/vs/workbench/api/common/extHostLanguageFeatures.ts b/src/vs/workbench/api/common/extHostLanguageFeatures.ts index 9783b16e880..53a5c89264e 100644 --- a/src/vs/workbench/api/common/extHostLanguageFeatures.ts +++ b/src/vs/workbench/api/common/extHostLanguageFeatures.ts @@ -2914,7 +2914,7 @@ export class ExtHostLanguageFeatures implements extHostProtocol.ExtHostLanguageF const handle = this._nextHandle(); this._adapter.set(handle, new AdapterData(new DocumentDropEditAdapter(this._proxy, this._documents, provider, handle, extension), extension)); - this._proxy.$registerDocumentOnDropEditProvider(handle, this._transformDocumentSelector(selector, extension), isProposedApiEnabled(extension, 'documentPaste') && metadata ? { + this._proxy.$registerDocumentOnDropEditProvider(handle, this._transformDocumentSelector(selector, extension), metadata ? { supportsResolve: !!provider.resolveDocumentDropEdit, dropMimeTypes: metadata.dropMimeTypes, providedDropKinds: metadata.providedDropEditKinds?.map(x => x.value), diff --git a/src/vs/workbench/api/common/extHostTypes.ts b/src/vs/workbench/api/common/extHostTypes.ts index d388236e837..667b018aa33 100644 --- a/src/vs/workbench/api/common/extHostTypes.ts +++ b/src/vs/workbench/api/common/extHostTypes.ts @@ -2950,6 +2950,7 @@ export enum DocumentPasteTriggerKind { export class DocumentDropOrPasteEditKind { static Empty: DocumentDropOrPasteEditKind; static Text: DocumentDropOrPasteEditKind; + static TextUpdateImports: DocumentDropOrPasteEditKind; private static sep = '.'; @@ -2971,6 +2972,7 @@ export class DocumentDropOrPasteEditKind { } DocumentDropOrPasteEditKind.Empty = new DocumentDropOrPasteEditKind(''); DocumentDropOrPasteEditKind.Text = new DocumentDropOrPasteEditKind('text'); +DocumentDropOrPasteEditKind.TextUpdateImports = DocumentDropOrPasteEditKind.Text.append('updateImports'); export class DocumentPasteEdit { diff --git a/src/vscode-dts/vscode.d.ts b/src/vscode-dts/vscode.d.ts index cfe9d122609..580acdeb53b 100644 --- a/src/vscode-dts/vscode.d.ts +++ b/src/vscode-dts/vscode.d.ts @@ -6073,10 +6073,88 @@ declare module 'vscode' { provideLinkedEditingRanges(document: TextDocument, position: Position, token: CancellationToken): ProviderResult; } + /** + * Identifies a {@linkcode DocumentDropEdit} or {@linkcode DocumentPasteEdit} + */ + class DocumentDropOrPasteEditKind { + static readonly Empty: DocumentDropOrPasteEditKind; + + /** + * The root kind for basic text edits. + * + * This kind should be used for edits that insert basic text into the document. A good example of this is + * an edit that pastes the clipboard text while also updating imports in the file based on the pasted text. + * For this we could use a kind such as `text.updateImports.someLanguageId`. + * + * Even though most drop/paste edits ultimately insert text, you should not use {@linkcode Text} as the base kind + * for every edit as this is redundant. Instead a more specific kind that describes the type of content being + * inserted should be used instead. For example, if the edit adds a Markdown link, use `markdown.link` since even + * though the content being inserted is text, it's more important to know that the edit inserts Markdown syntax. + */ + static readonly Text: DocumentDropOrPasteEditKind; + + /** + * Root kind for edits that update imports in a document in addition to inserting text. + */ + static readonly TextUpdateImports: DocumentDropOrPasteEditKind; + + /** + * Use {@linkcode DocumentDropOrPasteEditKind.Empty} instead. + */ + private constructor(value: string); + + /** + * The raw string value of the kind. + */ + readonly value: string; + + /** + * Create a new kind by appending additional scopes to the current kind. + * + * Does not modify the current kind. + */ + append(...parts: string[]): DocumentDropOrPasteEditKind; + + /** + * Checks if this kind intersects `other`. + * + * The kind `"text.plain"` for example intersects `text`, `"text.plain"` and `"text.plain.list"`, + * but not `"unicorn"`, or `"textUnicorn.plain"`. + * + * @param other Kind to check. + */ + intersects(other: DocumentDropOrPasteEditKind): boolean; + + /** + * Checks if `other` is a sub-kind of this `DocumentDropOrPasteEditKind`. + * + * The kind `"text.plain"` for example contains `"text.plain"` and `"text.plain.list"`, + * but not `"text"` or `"unicorn.text.plain"`. + * + * @param other Kind to check. + */ + contains(other: DocumentDropOrPasteEditKind): boolean; + } + /** * An edit operation applied {@link DocumentDropEditProvider on drop}. */ export class DocumentDropEdit { + /** + * Human readable label that describes the edit. + */ + title?: string; + + /** + * {@link DocumentDropOrPasteEditKind Kind} of the edit. + */ + kind?: DocumentDropOrPasteEditKind; + + /** + * Controls the ordering or multiple edits. If this provider yield to edits, it will be shown lower in the list. + */ + yieldTo?: readonly DocumentDropOrPasteEditKind[]; + /** * The text or snippet to insert at the drop location. */ @@ -6089,8 +6167,10 @@ declare module 'vscode' { /** * @param insertText The text or snippet to insert at the drop location. + * @param title Human readable label that describes the edit. + * @param kind {@link DocumentDropOrPasteEditKind Kind} of the edit. */ - constructor(insertText: string | SnippetString); + constructor(insertText: string | SnippetString, title?: string, kind?: DocumentDropOrPasteEditKind); } /** @@ -6100,7 +6180,7 @@ declare module 'vscode' { * and dropping files, users can hold down `shift` to drop the file into the editor instead of opening it. * Requires `editor.dropIntoEditor.enabled` to be on. */ - export interface DocumentDropEditProvider { + export interface DocumentDropEditProvider { /** * Provide edits which inserts the content being dragged and dropped into the document. * @@ -6112,7 +6192,212 @@ declare module 'vscode' { * @returns A {@link DocumentDropEdit} or a thenable that resolves to such. The lack of a result can be * signaled by returning `undefined` or `null`. */ - provideDocumentDropEdits(document: TextDocument, position: Position, dataTransfer: DataTransfer, token: CancellationToken): ProviderResult; + provideDocumentDropEdits(document: TextDocument, position: Position, dataTransfer: DataTransfer, token: CancellationToken): ProviderResult; + + /** + * Optional method which fills in the {@linkcode DocumentDropEdit.additionalEdit} before the edit is applied. + * + * This is called once per edit and should be used if generating the complete edit may take a long time. + * Resolve can only be used to change {@link DocumentDropEdit.additionalEdit}. + * + * @param edit The {@linkcode DocumentDropEdit} to resolve. + * @param token A cancellation token. + * + * @returns The resolved edit or a thenable that resolves to such. It is OK to return the given + * `edit`. If no result is returned, the given `edit` is used. + */ + resolveDocumentDropEdit?(edit: T, token: CancellationToken): ProviderResult; + } + + /** + * Provides additional metadata about how a {@linkcode DocumentDropEditProvider} works. + */ + export interface DocumentDropEditProviderMetadata { + /** + * List of {@link DocumentDropOrPasteEditKind kinds} that the provider may return in {@linkcode DocumentDropEditProvider.provideDocumentDropEdits provideDocumentDropEdits}. + * + * This is used to filter out providers when a specific {@link DocumentDropOrPasteEditKind kind} of edit is requested. + */ + readonly providedDropEditKinds?: readonly DocumentDropOrPasteEditKind[]; + + /** + * List of {@link DataTransfer} mime types that the provider can handle. + * + * This can either be an exact mime type such as `image/png`, or a wildcard pattern such as `image/*`. + * + * Use `text/uri-list` for resources dropped from the explorer or other tree views in the workbench. + * + * Use `files` to indicate that the provider should be invoked if any {@link DataTransferFile files} are present in the {@link DataTransfer}. + * Note that {@link DataTransferFile} entries are only created when dropping content from outside the editor, such as + * from the operating system. + */ + readonly dropMimeTypes: readonly string[]; + } + + + /** + * The reason why paste edits were requested. + */ + export enum DocumentPasteTriggerKind { + /** + * Pasting was requested as part of a normal paste operation. + */ + Automatic = 0, + + /** + * Pasting was requested by the user with the `paste as` command. + */ + PasteAs = 1, + } + + /** + * Additional information about the paste operation. + */ + export interface DocumentPasteEditContext { + + /** + * Requested kind of paste edits to return. + * + * When a explicit kind if requested by {@linkcode DocumentPasteTriggerKind.PasteAs PasteAs}, providers are + * encourage to be more flexible when generating an edit of the requested kind. + */ + readonly only: DocumentDropOrPasteEditKind | undefined; + + /** + * The reason why paste edits were requested. + */ + readonly triggerKind: DocumentPasteTriggerKind; + } + + /** + * Provider invoked when the user copies or pastes in a {@linkcode TextDocument}. + */ + interface DocumentPasteEditProvider { + + /** + * Optional method invoked after the user copies from a {@link TextEditor text editor}. + * + * This allows the provider to attach metadata about the copied text to the {@link DataTransfer}. This data + * transfer is then passed back to providers in {@linkcode provideDocumentPasteEdits}. + * + * Note that currently any changes to the {@linkcode DataTransfer} are isolated to the current editor window. + * This means that any added metadata cannot be seen by other editor windows or by other applications. + * + * @param document Text document where the copy took place. + * @param ranges Ranges being copied in {@linkcode document}. + * @param dataTransfer The data transfer associated with the copy. You can store additional values on this for + * later use in {@linkcode provideDocumentPasteEdits}. This object is only valid for the duration of this method. + * @param token A cancellation token. + * + * @return Optional thenable that resolves when all changes to the `dataTransfer` are complete. + */ + prepareDocumentPaste?(document: TextDocument, ranges: readonly Range[], dataTransfer: DataTransfer, token: CancellationToken): void | Thenable; + + /** + * Invoked before the user pastes into a {@link TextEditor text editor}. + * + * Returned edits can replace the standard pasting behavior. + * + * @param document Document being pasted into + * @param ranges Range in the {@linkcode document} to paste into. + * @param dataTransfer The {@link DataTransfer data transfer} associated with the paste. This object is only + * valid for the duration of the paste operation. + * @param context Additional context for the paste. + * @param token A cancellation token. + * + * @return Set of potential {@link DocumentPasteEdit edits} that can apply the paste. Only a single returned + * {@linkcode DocumentPasteEdit} is applied at a time. If multiple edits are returned from all providers, then + * the first is automatically applied and a widget is shown that lets the user switch to the other edits. + */ + provideDocumentPasteEdits?(document: TextDocument, ranges: readonly Range[], dataTransfer: DataTransfer, context: DocumentPasteEditContext, token: CancellationToken): ProviderResult; + + /** + * Optional method which fills in the {@linkcode DocumentPasteEdit.additionalEdit} before the edit is applied. + * + * This is called once per edit and should be used if generating the complete edit may take a long time. + * Resolve can only be used to change {@linkcode DocumentPasteEdit.additionalEdit}. + * + * @param pasteEdit The {@linkcode DocumentPasteEdit} to resolve. + * @param token A cancellation token. + * + * @returns The resolved paste edit or a thenable that resolves to such. It is OK to return the given + * `pasteEdit`. If no result is returned, the given `pasteEdit` is used. + */ + resolveDocumentPasteEdit?(pasteEdit: T, token: CancellationToken): ProviderResult; + } + + /** + * An edit the applies a paste operation. + */ + class DocumentPasteEdit { + + /** + * Human readable label that describes the edit. + */ + title: string; + + /** + * {@link DocumentDropOrPasteEditKind Kind} of the edit. + */ + kind: DocumentDropOrPasteEditKind; + + /** + * The text or snippet to insert at the pasted locations. + * + * If your edit requires more advanced insertion logic, set this to an empty string and provide an {@link DocumentPasteEdit.additionalEdit additional edit} instead. + */ + insertText: string | SnippetString; + + /** + * An optional additional edit to apply on paste. + */ + additionalEdit?: WorkspaceEdit; + + /** + * Controls ordering when multiple paste edits can potentially be applied. + * + * If this edit yields to another, it will be shown lower in the list of possible paste edits shown to the user. + */ + yieldTo?: readonly DocumentDropOrPasteEditKind[]; + + /** + * Create a new paste edit. + * + * @param insertText The text or snippet to insert at the pasted locations. + * @param title Human readable label that describes the edit. + * @param kind {@link DocumentDropOrPasteEditKind Kind} of the edit. + */ + constructor(insertText: string | SnippetString, title: string, kind: DocumentDropOrPasteEditKind); + } + + /** + * Provides additional metadata about how a {@linkcode DocumentPasteEditProvider} works. + */ + interface DocumentPasteProviderMetadata { + /** + * List of {@link DocumentDropOrPasteEditKind kinds} that the provider may return in {@linkcode DocumentPasteEditProvider.provideDocumentPasteEdits provideDocumentPasteEdits}. + * + * This is used to filter out providers when a specific {@link DocumentDropOrPasteEditKind kind} of edit is requested. + */ + readonly providedPasteEditKinds: readonly DocumentDropOrPasteEditKind[]; + + /** + * Mime types that {@linkcode DocumentPasteEditProvider.prepareDocumentPaste prepareDocumentPaste} may add on copy. + */ + readonly copyMimeTypes?: readonly string[]; + + /** + * Mime types that {@linkcode DocumentPasteEditProvider.provideDocumentPasteEdits provideDocumentPasteEdits} should be invoked for. + * + * This can either be an exact mime type such as `image/png`, or a wildcard pattern such as `image/*`. + * + * Use `text/uri-list` for resources dropped from the explorer or other tree views in the workbench. + * + * Use `files` to indicate that the provider should be invoked if any {@link DataTransferFile files} are present in the {@linkcode DataTransfer}. + * Note that {@linkcode DataTransferFile} entries are only created when pasting content from outside the editor, such as + * from the operating system. + */ + readonly pasteMimeTypes?: readonly string[]; } /** @@ -14586,10 +14871,23 @@ declare module 'vscode' { * * @param selector A selector that defines the documents this provider applies to. * @param provider A drop provider. + * @param metadata Additional metadata about the provider. * * @returns A {@link Disposable} that unregisters this provider when disposed of. */ - export function registerDocumentDropEditProvider(selector: DocumentSelector, provider: DocumentDropEditProvider): Disposable; + export function registerDocumentDropEditProvider(selector: DocumentSelector, provider: DocumentDropEditProvider, metadata?: DocumentDropEditProviderMetadata): Disposable; + + /** + * Registers a new {@linkcode DocumentPasteEditProvider}. + * + * @param selector A selector that defines the documents this provider applies to. + * @param provider A paste editor provider. + * @param metadata Additional metadata about the provider. + * + * @returns A {@link Disposable} that unregisters this provider when disposed of. + */ + export function registerDocumentPasteEditProvider(selector: DocumentSelector, provider: DocumentPasteEditProvider, metadata: DocumentPasteProviderMetadata): Disposable; + /** * Set a {@link LanguageConfiguration language configuration} for a language. diff --git a/src/vscode-dts/vscode.proposed.documentPaste.d.ts b/src/vscode-dts/vscode.proposed.documentPaste.d.ts deleted file mode 100644 index 2318a15212b..00000000000 --- a/src/vscode-dts/vscode.proposed.documentPaste.d.ts +++ /dev/null @@ -1,316 +0,0 @@ -/*--------------------------------------------------------------------------------------------- - * Copyright (c) Microsoft Corporation. All rights reserved. - * Licensed under the MIT License. See License.txt in the project root for license information. - *--------------------------------------------------------------------------------------------*/ - -declare module 'vscode' { - - // https://github.com/microsoft/vscode/issues/30066/ - - /** - * Identifies a {@linkcode DocumentDropEdit} or {@linkcode DocumentPasteEdit} - */ - class DocumentDropOrPasteEditKind { - static readonly Empty: DocumentDropOrPasteEditKind; - - /** - * The root kind for basic text edits. - * - * This kind should be used for edits that insert basic text into the document. A good example of this is - * an edit that pastes the clipboard text while also updating imports in the file based on the pasted text. - * For this we could use a kind such as `text.updateImports.someLanguageId`. - * - * Even though most drop/paste edits ultimately insert text, you should not use {@linkcode Text} as the base kind - * for every edit as this is redundant. Instead a more specific kind that describes the type of content being - * inserted should be used instead For example, if the edit adds a Markdown link, use `markdown.link` since even - * though the content being inserted is text, it's more important to know that the edit inserts Markdown syntax. - */ - static readonly Text: DocumentDropOrPasteEditKind; - - private constructor(value: string); - - /** - * The raw string value of the kind. - */ - readonly value: string; - - /** - * Create a new kind by appending additional scopes to the current kind. - * - * Does not modify the current kind. - */ - append(...parts: string[]): DocumentDropOrPasteEditKind; - - /** - * Checks if this kind intersects `other`. - * - * The kind `"text.plain"` for example intersects `text`, `"text.plain"` and `"text.plain.list"`, - * but not `"unicorn"`, or `"textUnicorn.plain"`. - * - * @param other Kind to check. - */ - intersects(other: DocumentDropOrPasteEditKind): boolean; - - /** - * Checks if `other` is a sub-kind of this `DocumentDropOrPasteEditKind`. - * - * The kind `"text.plain"` for example contains `"text.plain"` and `"text.plain.list"`, - * but not `"text"` or `"unicorn.text.plain"`. - * - * @param other Kind to check. - */ - contains(other: DocumentDropOrPasteEditKind): boolean; - } - - /** - * The reason why paste edits were requested. - */ - export enum DocumentPasteTriggerKind { - /** - * Pasting was requested as part of a normal paste operation. - */ - Automatic = 0, - - /** - * Pasting was requested by the user with the `paste as` command. - */ - PasteAs = 1, - } - - /** - * Additional information about the paste operation. - */ - // TODO: Should we also have this for drop? - export interface DocumentPasteEditContext { - /** - * Requested kind of paste edits to return. - * - * When a explicit kind if requested by {@linkcode DocumentPasteTriggerKind.PasteAs PasteAs}, providers are - * encourage to be more flexible when generating an edit of the requested kind. - */ - readonly only: DocumentDropOrPasteEditKind | undefined; - - // TODO: should we also expose preferences? - - /** - * The reason why paste edits were requested. - */ - readonly triggerKind: DocumentPasteTriggerKind; - } - - /** - * Provider invoked when the user copies or pastes in a {@linkcode TextDocument}. - */ - interface DocumentPasteEditProvider { - - /** - * Optional method invoked after the user copies from a {@link TextEditor text editor}. - * - * This allows the provider to attach metadata about the copied text to the {@link DataTransfer}. This data - * transfer is then passed back to providers in {@linkcode provideDocumentPasteEdits}. - * - * Note that currently any changes to the {@linkcode DataTransfer} are isolated to the current editor window. - * This means that any added metadata cannot be seen by other editor windows or by other applications. - * - * @param document Text document where the copy took place. - * @param ranges Ranges being copied in {@linkcode document}. - * @param dataTransfer The data transfer associated with the copy. You can store additional values on this for - * later use in {@linkcode provideDocumentPasteEdits}. This object is only valid for the duration of this method. - * @param token A cancellation token. - * - * @return Optional thenable that resolves when all changes to the `dataTransfer` are complete. - */ - prepareDocumentPaste?(document: TextDocument, ranges: readonly Range[], dataTransfer: DataTransfer, token: CancellationToken): void | Thenable; - - /** - * Invoked before the user pastes into a {@link TextEditor text editor}. - * - * Returned edits can replace the standard pasting behavior. - * - * @param document Document being pasted into - * @param ranges Range in the {@linkcode document} to paste into. - * @param dataTransfer The {@link DataTransfer data transfer} associated with the paste. This object is only - * valid for the duration of the paste operation. - * @param context Additional context for the paste. - * @param token A cancellation token. - * - * @return Set of potential {@link DocumentPasteEdit edits} that can apply the paste. Only a single returned - * {@linkcode DocumentPasteEdit} is applied at a time. If multiple edits are returned from all providers, then - * the first is automatically applied and a widget is shown that lets the user switch to the other edits. - */ - provideDocumentPasteEdits?(document: TextDocument, ranges: readonly Range[], dataTransfer: DataTransfer, context: DocumentPasteEditContext, token: CancellationToken): ProviderResult; - - /** - * Optional method which fills in the {@linkcode DocumentPasteEdit.additionalEdit} before the edit is applied. - * - * This is called once per edit and should be used if generating the complete edit may take a long time. - * Resolve can only be used to change {@linkcode DocumentPasteEdit.additionalEdit}. - * - * @param pasteEdit The {@linkcode DocumentPasteEdit} to resolve. - * @param token A cancellation token. - * - * @returns The resolved paste edit or a thenable that resolves to such. It is OK to return the given - * `pasteEdit`. If no result is returned, the given `pasteEdit` is used. - */ - resolveDocumentPasteEdit?(pasteEdit: T, token: CancellationToken): ProviderResult; - } - - /** - * An edit the applies a paste operation. - */ - class DocumentPasteEdit { - - /** - * Human readable label that describes the edit. - */ - title: string; - - /** - * {@link DocumentDropOrPasteEditKind Kind} of the edit. - */ - kind: DocumentDropOrPasteEditKind; - - /** - * The text or snippet to insert at the pasted locations. - * - * If your edit requires more advanced insertion logic, set this to an empty string and provide an {@link DocumentPasteEdit.additionalEdit additional edit} instead. - */ - insertText: string | SnippetString; - - /** - * An optional additional edit to apply on paste. - */ - additionalEdit?: WorkspaceEdit; - - /** - * Controls ordering when multiple paste edits can potentially be applied. - * - * If this edit yields to another, it will be shown lower in the list of possible paste edits shown to the user. - */ - yieldTo?: readonly DocumentDropOrPasteEditKind[]; - - /** - * Create a new paste edit. - * - * @param insertText The text or snippet to insert at the pasted locations. - * @param title Human readable label that describes the edit. - * @param kind {@link DocumentDropOrPasteEditKind Kind} of the edit. - */ - constructor(insertText: string | SnippetString, title: string, kind: DocumentDropOrPasteEditKind); - } - - /** - * Provides additional metadata about how a {@linkcode DocumentPasteEditProvider} works. - */ - interface DocumentPasteProviderMetadata { - /** - * List of {@link DocumentDropOrPasteEditKind kinds} that the provider may return in {@linkcode DocumentPasteEditProvider.provideDocumentPasteEdits provideDocumentPasteEdits}. - * - * This is used to filter out providers when a specific {@link DocumentDropOrPasteEditKind kind} of edit is requested. - */ - readonly providedPasteEditKinds: readonly DocumentDropOrPasteEditKind[]; - - /** - * Mime types that {@linkcode DocumentPasteEditProvider.prepareDocumentPaste prepareDocumentPaste} may add on copy. - */ - readonly copyMimeTypes?: readonly string[]; - - /** - * Mime types that {@linkcode DocumentPasteEditProvider.provideDocumentPasteEdits provideDocumentPasteEdits} should be invoked for. - * - * This can either be an exact mime type such as `image/png`, or a wildcard pattern such as `image/*`. - * - * Use `text/uri-list` for resources dropped from the explorer or other tree views in the workbench. - * - * Use `files` to indicate that the provider should be invoked if any {@link DataTransferFile files} are present in the {@linkcode DataTransfer}. - * Note that {@linkcode DataTransferFile} entries are only created when pasting content from outside the editor, such as - * from the operating system. - */ - readonly pasteMimeTypes?: readonly string[]; - } - - /** - * TODO on finalization: - * - Add ctor(insertText: string | SnippetString, title?: string, kind?: DocumentDropOrPasteEditKind); Can't be done as this is an extension to an existing class - */ - - export interface DocumentDropEdit { - /** - * Human readable label that describes the edit. - */ - title?: string; - - /** - * {@link DocumentDropOrPasteEditKind Kind} of the edit. - */ - kind: DocumentDropOrPasteEditKind; - - /** - * Controls the ordering or multiple edits. If this provider yield to edits, it will be shown lower in the list. - */ - yieldTo?: readonly DocumentDropOrPasteEditKind[]; - } - - export interface DocumentDropEditProvider { - // Overload that allows returning multiple edits - // Will be merged in on finalization - provideDocumentDropEdits(document: TextDocument, position: Position, dataTransfer: DataTransfer, token: CancellationToken): ProviderResult; - - /** - * Optional method which fills in the {@linkcode DocumentDropEdit.additionalEdit} before the edit is applied. - * - * This is called once per edit and should be used if generating the complete edit may take a long time. - * Resolve can only be used to change {@link DocumentDropEdit.additionalEdit}. - * - * @param pasteEdit The {@linkcode DocumentDropEdit} to resolve. - * @param token A cancellation token. - * - * @returns The resolved edit or a thenable that resolves to such. It is OK to return the given - * `edit`. If no result is returned, the given `edit` is used. - */ - resolveDocumentDropEdit?(edit: T, token: CancellationToken): ProviderResult; - } - - /** - * Provides additional metadata about how a {@linkcode DocumentDropEditProvider} works. - */ - export interface DocumentDropEditProviderMetadata { - /** - * List of {@link DocumentDropOrPasteEditKind kinds} that the provider may return in {@linkcode DocumentDropEditProvider.provideDocumentDropEdits provideDocumentDropEdits}. - * - * This is used to filter out providers when a specific {@link DocumentDropOrPasteEditKind kind} of edit is requested. - */ - readonly providedDropEditKinds?: readonly DocumentDropOrPasteEditKind[]; - - /** - * List of {@link DataTransfer} mime types that the provider can handle. - * - * This can either be an exact mime type such as `image/png`, or a wildcard pattern such as `image/*`. - * - * Use `text/uri-list` for resources dropped from the explorer or other tree views in the workbench. - * - * Use `files` to indicate that the provider should be invoked if any {@link DataTransferFile files} are present in the {@link DataTransfer}. - * Note that {@link DataTransferFile} entries are only created when dropping content from outside the editor, such as - * from the operating system. - */ - readonly dropMimeTypes: readonly string[]; - } - - namespace languages { - /** - * Registers a new {@linkcode DocumentPasteEditProvider}. - * - * @param selector A selector that defines the documents this provider applies to. - * @param provider A paste editor provider. - * @param metadata Additional metadata about the provider. - * - * @returns A {@link Disposable} that unregisters this provider when disposed of. - */ - export function registerDocumentPasteEditProvider(selector: DocumentSelector, provider: DocumentPasteEditProvider, metadata: DocumentPasteProviderMetadata): Disposable; - - /** - * Overload which adds extra metadata. Will be removed on finalization. - */ - export function registerDocumentDropEditProvider(selector: DocumentSelector, provider: DocumentDropEditProvider, metadata?: DocumentDropEditProviderMetadata): Disposable; - } -}