@eclipse-glsp/vscode-integration/lib/common/glsp-vscode-connector.d.ts

Glue code to integrate GLSP diagrams in VSCode extensions (extension part)

/********************************************************************************
 * Copyright (c) 2021-2024 EclipseSource 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 WITH Classpath-exception-2.0
 ********************************************************************************/
import { Action, ActionMessage, Deferred, EndProgressAction, ExportSvgAction, MessageAction, NavigateToExternalTargetAction, SelectAction, SetDirtyStateAction, SetMarkersAction, StartProgressAction, UpdateProgressAction } from '@eclipse-glsp/protocol';
import * as vscode from 'vscode';
import { Messenger } from 'vscode-messenger';
import { GlspVscodeClient, GlspVscodeConnectorOptions } from './types';
export declare enum MessageOrigin {
    CLIENT = 0,
    SERVER = 1
}
export interface MessageProcessingResult {
    processedMessage: unknown;
    messageChanged: boolean;
}
export type SelectionState = Omit<SelectAction, 'kind'>;
interface ProgressReporter {
    deferred: Deferred<void>;
    progress: vscode.Progress<{
        message?: string;
        increment?: number;
    }>;
    currentPercentage?: number;
}
/**
 * The `GlspVscodeConnector` acts as the bridge between GLSP-Clients and the GLSP-Server
 * and is at the core of the Glsp-VSCode integration.
 *
 * It works by being providing a server that implements the `GlspVscodeServer`
 * interface and registering clients using the `GlspVscodeConnector.registerClient`
 * function. Messages sent between the clients and the server are then intercepted
 * by the connector to provide functionality based on the content of the messages.
 *
 * Messages can be intercepted using the interceptor properties in the options
 * argument.
 *
 * Selection updates can be listened to using the `onSelectionUpdate` property.
 */
export declare class GlspVscodeConnector<D extends vscode.CustomDocument = vscode.CustomDocument> implements vscode.Disposable {
    /** Maps clientId to corresponding GlspVscodeClient. */
    protected readonly clientMap: Map<string, GlspVscodeClient<D>>;
    /** Maps Documents to corresponding clientId. */
    protected readonly documentMap: Map<D, string>;
    /** Maps clientId to selected elementIDs for that client. */
    protected readonly clientSelectionMap: Map<string, SelectionState>;
    /** Maps clientId to ongoing progress (reporters) for that client */
    protected readonly clientProgressMap: Map<string, Map<string, ProgressReporter>>;
    protected readonly options: Required<GlspVscodeConnectorOptions>;
    protected readonly diagnostics: vscode.DiagnosticCollection;
    protected readonly selectionUpdateEmitter: vscode.EventEmitter<SelectionState>;
    protected readonly onDocumentSavedEmitter: vscode.EventEmitter<D>;
    protected readonly onDidChangeCustomDocumentEventEmitter: vscode.EventEmitter<vscode.CustomDocumentEditEvent<D> | vscode.CustomDocumentContentChangeEvent<D>>;
    protected readonly disposables: vscode.Disposable[];
    readonly messenger: Messenger;
    /**
     * A subscribable event which fires with an array containing the IDs of all
     * selected  & deselected elements when the selection of the editor changes.
     */
    onSelectionUpdate: vscode.Event<SelectionState>;
    /**
     * A subscribable event which fires when a document changed. The event body
     * will contain that document. Use this event for the `onDidChangeCustomDocument`
     * on your implementation of the `CustomEditorProvider`.
     */
    get onDidChangeCustomDocument(): vscode.Event<vscode.CustomDocumentEditEvent<D>> | vscode.Event<vscode.CustomDocumentContentChangeEvent<D>>;
    constructor(options: GlspVscodeConnectorOptions);
    /**
     * Register a client on the GLSP-VSCode connector. All communication will subsequently
     * run through the VSCode integration. Clients do not need to be unregistered
     * as they are automatically disposed of when the panel they belong to is closed.
     *
     * @param client The client to register.
     *
     */
    registerClient(client: GlspVscodeClient<D>): Promise<void>;
    /**
     * Send message to registered client by id.
     * Note that this method does not consider server-handled actions.
     * If you want to send an action that is potentially handled by both sides, use {@link dispatchAction} instead.
     *
     * @param clientId Id of client.
     * @param message Message to send.
     */
    protected sendMessageToClient(clientId: string, message: unknown): void;
    /**
     * Send action to registered client by id.
     *
     * @param clientId Id of client.
     * @param action Action to send.
     *
     * @deprecated Use  {@link dispatchAction} instead.
     */
    protected sendActionToClient(clientId: string, action: Action): void;
    /**
     * Send an action to the client/panel that is currently focused. If no registered
     * panel is focused, the message will not be sent.
     *
     * @param action The action to send to the active client.
     * @deprecated Use {@link dispatchAction} instead.
     */
    sendActionToActiveClient(action: Action): void;
    /**
     * Dispatches an action associated with the given client id. If no id is provided,
     * the action will be dispatched associated with the client of the active webview panel.
     * If no client id is passed and no registered panel is focused, the action will not be dispatched.
     * Dispatching an action will send the action to the client and/or server if
     * they can handle the action.
     * @param action The action to dispatch.
     * @param clientId The id of the client/session associated with the action.
     */
    dispatchAction(action: Action, clientId?: string): void;
    /**
     * Returns the currently active {@link GlspVscodeClient} i.e. the client whose webview panel is currently focused.
     * If no registered panel is focused, the method will return `undefined`.
     * @returns The active client or `undefined` if no client is active.
     */
    protected getActiveClient(): GlspVscodeClient<D> | undefined;
    /**
     * Provides the functionality of the VSCode integration.
     *
     * Incoming messages (unless intercepted) will run through this function and
     * be acted upon by providing default functionality for VSCode.
     *
     * @param message The original received message.
     * @param origin The origin of the received message.
     * @returns An object containing the processed message and an indicator wether
     * the message was modified.
     */
    protected processMessage(message: unknown, origin: MessageOrigin): MessageProcessingResult;
    protected handleMessageAction(message: ActionMessage<MessageAction>, _client: GlspVscodeClient<D> | undefined, _origin: MessageOrigin): MessageProcessingResult;
    protected handleStartProgressAction(actionMessage: ActionMessage<StartProgressAction>, client: GlspVscodeClient<D> | undefined, origin: MessageOrigin): MessageProcessingResult;
    protected handleUpdateProgressAction(actionMessage: ActionMessage<UpdateProgressAction>, client: GlspVscodeClient<D> | undefined, origin: MessageOrigin): MessageProcessingResult;
    protected handleEndProgressAction(actionMessage: ActionMessage<EndProgressAction>, client: GlspVscodeClient<D> | undefined, origin: MessageOrigin): MessageProcessingResult;
    protected progressReporterId(client: GlspVscodeClient<D>, progressId: string): string;
    protected handleSetDirtyStateAction(message: ActionMessage<SetDirtyStateAction>, client: GlspVscodeClient<D> | undefined, _origin: MessageOrigin): MessageProcessingResult;
    protected handleSetMarkersAction(message: ActionMessage<SetMarkersAction>, client: GlspVscodeClient<D> | undefined, _origin: MessageOrigin): MessageProcessingResult;
    protected handleNavigateToExternalTargetAction(message: ActionMessage<NavigateToExternalTargetAction>, _client: GlspVscodeClient<D> | undefined, _origin: MessageOrigin): MessageProcessingResult;
    protected handleSelectAction(message: ActionMessage<SelectAction>, client: GlspVscodeClient<D> | undefined, origin: MessageOrigin): MessageProcessingResult;
    protected handleExportSvgAction(message: ActionMessage<ExportSvgAction>, _client: GlspVscodeClient<D> | undefined, _origin: MessageOrigin): MessageProcessingResult;
    /**
     * Saves a document. Make sure to call this function in the `saveCustomDocument`
     * and `saveCustomDocumentAs` functions of your `CustomEditorProvider` implementation.
     *
     * @param document The document to save.
     * @param destination Optional parameter. When this parameter is provided the
     * file will instead be saved at this location.
     * @returns A promise that resolves when the file has been successfully saved.
     */
    saveDocument(document: D, destination?: vscode.Uri): Promise<void>;
    /**
     * Reverts a document. Make sure to call this function in the `revertCustomDocument`
     * functions of your `CustomEditorProvider` implementation.
     *
     * @param document Document to revert.
     * @param diagramType Diagram type as it is configured on the server.
     * @returns A promise that resolves when the file has been successfully reverted.
     */
    revertDocument(document: D, diagramType: string): Promise<void>;
    dispose(): void;
}
export {};
//# sourceMappingURL=glsp-vscode-connector.d.ts.map