Stub implementation of proposed API for multiDocumentHighlightProvider.

CHANGELOG.md

@@ -6,6 +6,7 @@
 
 ## not yet released
 
+- [plugin] stub multiDocumentHighlightProvider proposed API [#13248](https://github.com/eclipse-theia/theia/pull/13248) - contributed on behalf of STMicroelectronics
 - [terminal] update terminalQuickFixProvider proposed API according to vscode 1.85 version [#13240](https://github.com/eclipse-theia/theia/pull/13240) - contributed on behalf of STMicroelectronics
 
 ## v1.45.0 - 12/21/2023

packages/plugin-ext/src/plugin/plugin-context.ts

@@ -87,6 +87,7 @@ import {
     InlineValueContext,
     DocumentHighlightKind,
     DocumentHighlight,
+    MultiDocumentHighlight,
     DocumentLink,
     DocumentDropEdit,
     CodeLens,
@@ -916,6 +917,13 @@ export function createAPIFactory(
             registerDocumentHighlightProvider(selector: theia.DocumentSelector, provider: theia.DocumentHighlightProvider): theia.Disposable {
                 return languagesExt.registerDocumentHighlightProvider(selector, provider, pluginToPluginInfo(plugin));
             },
+            /**
+             * @stubbed
+             * @monaco-uplift: wait until API is available in Monaco (1.85.0+)
+             */
+            registerMultiDocumentHighlightProvider(selector: theia.DocumentSelector, provider: theia.MultiDocumentHighlightProvider): theia.Disposable {
+                return Disposable.NULL;
+            },
             registerWorkspaceSymbolProvider(provider: theia.WorkspaceSymbolProvider): theia.Disposable {
                 return languagesExt.registerWorkspaceSymbolProvider(provider, pluginToPluginInfo(plugin));
             },
@@ -1261,6 +1269,7 @@ export function createAPIFactory(
             InlineValueContext,
             DocumentHighlightKind,
             DocumentHighlight,
+            MultiDocumentHighlight,
             DocumentLink,
             DocumentDropEdit,
             CodeLens,

packages/plugin-ext/src/plugin/types-impl.ts

@@ -1593,6 +1593,30 @@ export class DocumentHighlight {
     }
 }
 
+@es5ClassCompat
+export class MultiDocumentHighlight {
+
+    /**
+     * The URI of the document containing the highlights.
+     */
+    uri: URI;
+
+    /**
+     * The highlights for the document.
+     */
+    highlights: DocumentHighlight[];
+
+    /**
+     * Creates a new instance of MultiDocumentHighlight.
+     * @param uri The URI of the document containing the highlights.
+     * @param highlights The highlights for the document.
+     */
+    constructor(uri: URI, highlights: DocumentHighlight[]) {
+        this.uri = uri;
+        this.highlights = highlights;
+    }
+}
+
 export type Definition = Location | Location[];
 
 @es5ClassCompat

packages/plugin/src/theia.d.ts

@@ -35,6 +35,7 @@ import './theia.proposed.notebookKernelSource';
 import './theia.proposed.notebookMessaging';
 import './theia.proposed.findTextInFiles';
 import './theia.proposed.fsChunks';
+import './theia.proposed.multiDocumentHighlightProvider';
 import './theia.proposed.profileContentHandlers';
 import './theia.proposed.resolvers';
 import './theia.proposed.scmValidation';

packages/plugin/src/theia.proposed.multiDocumentHighlightProvider.ts

@@ -0,0 +1,82 @@
+// *****************************************************************************
+// Copyright (C) 2023 STMicroelectronics and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+// code copied and modified from https://github.com/microsoft/vscode/blob/1.85.1/src/vscode-dts/vscode.proposed.multiDocumentHighlightProvider.d.ts
+
+declare module '@theia/plugin' {
+
+    /**
+     * Represents a collection of document highlights from multiple documents.
+     */
+    export class MultiDocumentHighlight {
+
+        /**
+         * The URI of the document containing the highlights.
+         */
+        uri: Uri;
+
+        /**
+         * The highlights for the document.
+         */
+        highlights: DocumentHighlight[];
+
+        /**
+         * Creates a new instance of MultiDocumentHighlight.
+         * @param uri The URI of the document containing the highlights.
+         * @param highlights The highlights for the document.
+         */
+        constructor(uri: Uri, highlights: DocumentHighlight[]);
+    }
+
+    export interface MultiDocumentHighlightProvider {
+
+        /**
+         * Provide a set of document highlights, like all occurrences of a variable or
+         * all exit-points of a function.
+         *
+         * @param document The document in which the command was invoked.
+         * @param position The position at which the command was invoked.
+         * @param otherDocuments An array of additional valid documents for which highlights should be provided.
+         * @param token A cancellation token.
+         * @returns A Map containing a mapping of the Uri of a document to the document highlights or a thenable that resolves to such. The lack of a result can be
+         * signaled by returning `undefined`, `null`, or an empty map.
+         */
+        provideMultiDocumentHighlights(document: TextDocument, position: Position, otherDocuments: TextDocument[], token: CancellationToken):
+            ProviderResult<MultiDocumentHighlight[]>;
+    }
+
+    namespace languages {
+
+        /**
+         * Register a multi document highlight provider.
+         *
+         * Multiple providers can be registered for a language. In that case providers are sorted
+         * by their {@link languages.match score} and groups sequentially asked for document highlights.
+         * The process stops when a provider returns a `non-falsy` or `non-failure` result.
+         *
+         * @param selector A selector that defines the documents this provider is applicable to.
+         * @param provider A multi-document highlight provider.
+         * @returns A {@link Disposable} that unregisters this provider when being disposed.
+         * @stubbed
+         */
+        export function registerMultiDocumentHighlightProvider(selector: DocumentSelector, provider: MultiDocumentHighlightProvider): Disposable;
+    }
+
+}