@theia/core/lib/browser/perspective-service.d.ts

Theia is a cloud & desktop IDE framework implemented in TypeScript.

import { DockLayout } from '@lumino/widgets';
import { ApplicationShell, WidgetAreaResolver } from './shell/application-shell';
import { SidePanel } from './shell/side-panel-handler';
import { FrontendApplicationContribution } from './frontend-application-contribution';
import { WidgetManager } from './widget-manager';
import { ContributionProvider } from '../common/contribution-provider';
import { Command, CommandContribution, CommandRegistry } from '../common/command';
import { Emitter, Event } from '../common/event';
import { ILogger } from '../common/logger';
import { QuickInputService } from '../common/quick-pick-service';
import { ContextKeyService } from './context-key-service';
export declare const ACTIVE_PERSPECTIVE_CONTEXT_KEY = "activePerspectiveId";
export interface PerspectiveChromeOptions {
    /** Areas to collapse on first activation. User can re-expand freely. */
    collapseAreas?: ('left' | 'right' | 'bottom')[];
}
export interface PerspectiveDescriptor {
    id: string;
    label: string;
    /** Widget/view-container ID → target shell area */
    viewPlacements: Map<string, ApplicationShell.Area>;
    /** Chrome control options for this perspective */
    chromeOptions?: PerspectiveChromeOptions;
    /** Per-area primary view: the widget to activate last in each shell area, so it gets focus. */
    primaryViews?: Partial<Record<ApplicationShell.Area, string>>;
    /** Called when perspective is activated */
    onActivate?(shell: ApplicationShell): void;
    /** Called when switching away */
    onDeactivate?(shell: ApplicationShell): void;
}
export declare const PerspectiveService: unique symbol;
export interface PerspectiveService {
    /** Event fired whenever the active perspective changes. The payload is the new perspective ID. */
    readonly onDidChangePerspective: Event<string>;
    /**
     * Registers a new perspective descriptor.
     * Contributions should call this from their `PerspectiveContribution.registerPerspectives` callback.
     */
    registerPerspective(descriptor: PerspectiveDescriptor): void;
    /**
     * Switches the workbench to the given perspective.
     * Saves the current perspective's layout, then restores the target perspective's layout
     * (or applies its `viewPlacements` on first activation). Concurrent calls are serialized.
     */
    switchPerspective(id: string): Promise<void>;
    /** Returns the descriptor of the currently active perspective, or `undefined` if none. */
    getActivePerspective(): PerspectiveDescriptor | undefined;
    /** Returns the target shell area for a widget in the active perspective, or `undefined` if unmapped. */
    getAreaForView(viewId: string): ApplicationShell.Area | undefined;
    /** Returns all registered perspective descriptors. */
    getRegisteredPerspectives(): PerspectiveDescriptor[];
    /** Returns the ID of the currently active perspective. A convenient alternative to `getActivePerspective()?.id` that always returns a string. */
    getActivePerspectiveId(): string;
    /**
     * Resets the active perspective to its programmatic state (viewPlacements from its descriptor),
     * discarding the saved layout. Does not affect other perspectives.
     */
    resetCurrentPerspective(): Promise<void>;
}
export declare const PerspectiveServiceInternal: unique symbol;
/**
 * Internal plumbing API for layout persistence infrastructure.
 * General consumers should use {@link PerspectiveService} instead.
 */
export interface PerspectiveServiceInternal {
    /**
     * Returns the ID of the currently active perspective.
     * @internal Plumbing API, used by `ShellLayoutRestorer` for layout persistence.
     */
    getActivePerspectiveId(): string;
    /**
     * Returns the IDs of all perspectives that have a saved (in-memory) layout snapshot.
     * @internal Plumbing API, used by `ShellLayoutRestorer` for layout persistence.
     */
    getSavedPerspectiveIds(): string[];
    /**
     * Returns the saved in-memory layout for a perspective, or `undefined` if none exists.
     * @internal Plumbing API, used by `ShellLayoutRestorer` for layout persistence.
     */
    getSavedLayout(perspectiveId: string): ApplicationShell.LayoutData | undefined;
    /**
     * Stores an in-memory layout snapshot for a perspective.
     * @internal Plumbing API, used by `ShellLayoutRestorer` for layout persistence.
     */
    setSavedLayout(perspectiveId: string, layout: ApplicationShell.LayoutData): void;
    /**
     * Sets the active perspective ID (without triggering a switch).
     * Returns `true` if the ID corresponds to a registered perspective, `false` otherwise.
     * @internal Plumbing API, used by `ShellLayoutRestorer` during layout restore.
     */
    setActivePerspectiveId(id: string): boolean;
    /**
     * The ID of the built-in default perspective.
     * @internal Plumbing API, used by `ShellLayoutRestorer` for legacy migration.
     */
    readonly defaultPerspectiveId: string;
    /**
     * Clears all saved in-memory layout snapshots.
     * @internal Plumbing API, used by `ShellLayoutRestorer` during layout reset.
     */
    clearSavedLayouts(): void;
    /**
     * Called by `ShellLayoutRestorer` after restoring a persisted layout to apply chrome options
     * (e.g., status bar visibility) for the given perspective.
     * @internal Plumbing API, used by `ShellLayoutRestorer` after layout restore.
     */
    onLayoutRestored(activePerspectiveId: string): void;
}
export declare const PerspectiveContribution: unique symbol;
export interface PerspectiveContribution {
    registerPerspectives(service: PerspectiveService): void;
}
export declare class WidgetAreaResolverImpl implements WidgetAreaResolver {
    protected activePlacementMap: Map<string, ApplicationShell.Area>;
    setActivePlacementMap(map: Map<string, ApplicationShell.Area>): void;
    resolveArea(widgetId: string, requestedArea: ApplicationShell.Area): ApplicationShell.Area | undefined;
}
export declare class PerspectiveServiceImpl implements FrontendApplicationContribution, CommandContribution, PerspectiveService, PerspectiveServiceInternal {
    static readonly SWITCH_PERSPECTIVE_COMMAND: Command;
    static readonly RESET_PERSPECTIVE_COMMAND: Command;
    protected readonly shell: ApplicationShell;
    protected readonly widgetManager: WidgetManager;
    protected readonly contributions: ContributionProvider<PerspectiveContribution> | undefined;
    protected readonly appContributions: ContributionProvider<FrontendApplicationContribution>;
    protected readonly quickInputService: QuickInputService | undefined;
    protected readonly logger: ILogger;
    protected readonly widgetAreaResolver: WidgetAreaResolver;
    protected readonly contextKeyService: ContextKeyService | undefined;
    static readonly DEFAULT_PERSPECTIVE_ID = "default";
    readonly defaultPerspectiveId = "default";
    protected readonly perspectives: Map<string, PerspectiveDescriptor>;
    protected activePerspectiveId: string | undefined;
    protected readonly savedLayouts: Map<string, ApplicationShell.LayoutData>;
    protected readonly onDidChangePerspectiveEmitter: Emitter<string>;
    readonly onDidChangePerspective: Event<string>;
    protected switchInProgress: Promise<void> | undefined;
    onLayoutRestored(activePerspectiveId: string): void;
    initialize(): void;
    onStop(): void;
    protected updateActivePerspectiveContextKey(id: string): void;
    registerPerspective(descriptor: PerspectiveDescriptor): void;
    switchPerspective(id: string): Promise<void>;
    protected doSwitchPerspective(id: string): Promise<void>;
    protected applyViewPlacements(descriptor: PerspectiveDescriptor): Promise<void>;
    resetCurrentPerspective(): Promise<void>;
    protected doResetCurrentPerspective(): Promise<void>;
    protected resetDefaultPerspective(): Promise<void>;
    /**
     * Views may be shared between multiple perspective. If a view exists in two or more perspectives
     * and is closed in one of them, the shared widget is disposed. When switching back to the other
     * perspective, we need to restore this widget (i.e. reopen the view).
     * @param layout
     */
    protected healLayoutData(layout: ApplicationShell.LayoutData): Promise<void>;
    protected healSidePanelLayout(layout: SidePanel.LayoutData): Promise<void>;
    protected healDockAreaConfig(config: DockLayout.ITabAreaConfig | DockLayout.ISplitAreaConfig): Promise<void>;
    protected collectWidgetIds(layout: ApplicationShell.LayoutData): Set<string>;
    protected collectSidePanelWidgetIds(layout: SidePanel.LayoutData, ids: Set<string>): void;
    protected collectDockWidgetIds(config: DockLayout.ITabAreaConfig | DockLayout.ISplitAreaConfig, ids: Set<string>): void;
    protected detachStrayWidgets(layoutWidgetIds: Set<string>): void;
    getActivePerspective(): PerspectiveDescriptor | undefined;
    getAreaForView(viewId: string): ApplicationShell.Area | undefined;
    getRegisteredPerspectives(): PerspectiveDescriptor[];
    getActivePerspectiveId(): string;
    getSavedPerspectiveIds(): string[];
    getSavedLayout(perspectiveId: string): ApplicationShell.LayoutData | undefined;
    setSavedLayout(perspectiveId: string, layout: ApplicationShell.LayoutData): void;
    setActivePerspectiveId(id: string): boolean;
    clearSavedLayouts(): void;
    registerCommands(commands: CommandRegistry): void;
    protected showPerspectivePicker(): Promise<void>;
}
//# sourceMappingURL=perspective-service.d.ts.map