@theia/core

import { BoxLayout, BoxPanel, DockLayout, DockPanel, FocusTracker, Layout, Panel, SplitLayout, TabBar, Widget, Title } from '@phosphor/widgets'; import { Message } from '@phosphor/messaging'; import { IDragEvent } from '@phosphor/dragdrop'; import { RecursivePartial, Event as CommonEvent, DisposableCollection } from '../../common'; import { SaveOptions } from '../saveable'; import { StatusBarImpl } from '../status-bar/status-bar'; import { TheiaDockPanel } from './theia-dock-panel'; import { SidePanelHandler, SidePanel } from './side-panel-handler'; import { TabBarRendererFactory, ToolbarAwareTabBar } from './tab-bars'; import { SplitPositionHandler } from './split-panels'; import { FrontendApplicationStateService } from '../frontend-application-state'; import { TabBarToolbarRegistry, TabBarToolbarFactory } from './tab-bar-toolbar'; import { ContextKeyService } from '../context-key-service'; import { Emitter } from '../../common/event'; import { CorePreferences } from '../core-preferences'; import { BreadcrumbsRendererFactory } from '../breadcrumbs/breadcrumbs-renderer'; import { SaveResourceService } from '../save-resource-service'; import { SecondaryWindowHandler } from '../secondary-window-handler'; import URI from '../../common/uri'; import { OpenerService } from '../opener-service'; export declare type ApplicationShellLayoutVersion = /** layout versioning is introduced, unversioned layout are not compatible */ 2.0 | /** view containers are introduced, backward compatible to 2.0 */ 3.0 | /** git history view is replaced by a more generic scm history view, backward compatible to 3.0 */ 4.0 | /** Replace custom/font-awesome icons with codicons */ 5.0 | /** added the ability to drag and drop view parts between view containers */ 6.0; /** * When a version is increased, make sure to introduce a migration (ApplicationShellLayoutMigration) to this version. */ export declare const applicationShellLayoutVersion: ApplicationShellLayoutVersion; export declare const ApplicationShellOptions: unique symbol; export declare const DockPanelRendererFactory: unique symbol; export interface DockPanelRendererFactory { (): DockPanelRenderer; } /** * A renderer for dock panels that supports context menus on tabs. */ export declare class DockPanelRenderer implements DockLayout.IRenderer { protected readonly tabBarRendererFactory: TabBarRendererFactory; protected readonly tabBarToolbarRegistry: TabBarToolbarRegistry; protected readonly tabBarToolbarFactory: TabBarToolbarFactory; protected readonly breadcrumbsRendererFactory: BreadcrumbsRendererFactory; protected readonly dockPanelFactory: TheiaDockPanel.Factory; readonly tabBarClasses: string[]; private readonly onDidCreateTabBarEmitter; constructor(tabBarRendererFactory: TabBarRendererFactory, tabBarToolbarRegistry: TabBarToolbarRegistry, tabBarToolbarFactory: TabBarToolbarFactory, breadcrumbsRendererFactory: BreadcrumbsRendererFactory); get onDidCreateTabBar(): CommonEvent<TabBar<Widget>>; createTabBar(): TabBar<Widget>; createHandle(): HTMLDivElement; protected onCurrentTabChanged(sender: ToolbarAwareTabBar, { currentIndex }: TabBar.ICurrentChangedArgs<Widget>): void; } /** * The application shell manages the top-level widgets of the application. Use this class to * add, remove, or activate a widget. */ export declare class ApplicationShell extends Widget { protected dockPanelRendererFactory: () => DockPanelRenderer; protected readonly statusBar: StatusBarImpl; protected readonly sidePanelHandlerFactory: () => SidePanelHandler; protected splitPositionHandler: SplitPositionHandler; protected readonly applicationStateService: FrontendApplicationStateService; protected readonly corePreferences: CorePreferences; protected readonly saveResourceService: SaveResourceService; protected readonly secondaryWindowHandler: SecondaryWindowHandler; /** * The dock panel in the main shell area. This is where editors usually go to. */ mainPanel: TheiaDockPanel; /** * The dock panel in the bottom shell area. In contrast to the main panel, the bottom panel * can be collapsed and expanded. */ bottomPanel: TheiaDockPanel; /** * Handler for the left side panel. The primary application views go here, such as the * file explorer and the git view. */ leftPanelHandler: SidePanelHandler; /** * Handler for the right side panel. The secondary application views go here, such as the * outline view. */ rightPanelHandler: SidePanelHandler; /** * General options for the application shell. */ protected options: ApplicationShell.Options; /** * The fixed-size panel shown on top. This one usually holds the main menu. */ topPanel: Panel; /** * The current state of the bottom panel. */ protected readonly bottomPanelState: SidePanel.State; private readonly tracker; private dragState?; additionalDraggedUris: URI[] | undefined; protected readonly contextKeyService: ContextKeyService; protected readonly openerService: OpenerService; protected readonly onDidAddWidgetEmitter: Emitter<Widget>; readonly onDidAddWidget: CommonEvent<Widget>; protected fireDidAddWidget(widget: Widget): void; protected readonly onDidRemoveWidgetEmitter: Emitter<Widget>; readonly onDidRemoveWidget: CommonEvent<Widget>; protected fireDidRemoveWidget(widget: Widget): void; protected readonly onDidChangeActiveWidgetEmitter: Emitter<FocusTracker.IChangedArgs<Widget>>; readonly onDidChangeActiveWidget: CommonEvent<FocusTracker.IChangedArgs<Widget>>; protected readonly onDidChangeCurrentWidgetEmitter: Emitter<FocusTracker.IChangedArgs<Widget>>; readonly onDidChangeCurrentWidget: CommonEvent<FocusTracker.IChangedArgs<Widget>>; protected readonly dockPanelFactory: TheiaDockPanel.Factory; private _mainPanelRenderer; get mainPanelRenderer(): DockPanelRenderer; /** * Construct a new application shell. */ constructor(dockPanelRendererFactory: () => DockPanelRenderer, statusBar: StatusBarImpl, sidePanelHandlerFactory: () => SidePanelHandler, splitPositionHandler: SplitPositionHandler, applicationStateService: FrontendApplicationStateService, options: RecursivePartial<ApplicationShell.Options> | undefined, corePreferences: CorePreferences, saveResourceService: SaveResourceService, secondaryWindowHandler: SecondaryWindowHandler); protected init(): void; protected initializeShell(): void; protected initSidebarVisibleKeyContext(): void; protected initFocusKeyContexts(): void; protected setTopPanelVisibility(preference: string): void; protected onBeforeAttach(msg: Message): void; protected onAfterDetach(msg: Message): void; handleEvent(event: Event): void; protected onDragEnter({ mimeData }: IDragEvent): void; protected onDragOver(event: IDragEvent): void; /** * This method is called after a side panel has been expanded while dragging a widget. It fires * a `mousemove` event so that the drag overlay markers are updated correctly in all dock panels. */ private dispatchMouseMove; protected onDrop(event: IDragEvent): void; protected onDragLeave(event: IDragEvent): void; /** * Create the dock panel in the main shell area. */ protected createMainPanel(): TheiaDockPanel; addAdditionalDraggedEditorUris(uris: URI[]): void; clearAdditionalDraggedEditorUris(): void; protected static getDraggedEditorUris(dataTransfer: DataTransfer): URI[]; static setDraggedEditorUris(dataTransfer: DataTransfer, uris: URI[]): void; /** * Create the dock panel in the bottom shell area. */ protected createBottomPanel(): TheiaDockPanel; /** * Create the top panel, which is used to hold the main menu. */ protected createTopPanel(): Panel; /** * Create a box layout to assemble the application shell layout. */ protected createBoxLayout(widgets: Widget[], stretch?: number[], options?: BoxPanel.IOptions): BoxLayout; /** * Create a split layout to assemble the application shell layout. */ protected createSplitLayout(widgets: Widget[], stretch?: number[], options?: Partial<SplitLayout.IOptions>): SplitLayout; /** * Assemble the application shell layout. Override this method in order to change the arrangement * of the main area and the side panels. */ protected createLayout(): Layout; /** * Create an object that describes the current shell layout. This object may contain references * to widgets; these need to be transformed before the layout can be serialized. */ getLayoutData(): ApplicationShell.LayoutData; getPinnedMainWidgets(): boolean[]; getPinnedBottomWidgets(): boolean[]; /** * Compute the current height of the bottom panel. This implementation assumes that the container * of the bottom panel is a `SplitPanel`. */ protected getBottomPanelSize(): number | undefined; /** * Determine the default size to apply when the bottom panel is expanded for the first time. */ protected getDefaultBottomPanelSize(): number | undefined; /** * Apply a shell layout that has been previously created with `getLayoutData`. */ setLayoutData(layoutData: ApplicationShell.LayoutData): Promise<void>; /** * Modify the height of the bottom panel. This implementation assumes that the container of the * bottom panel is a `SplitPanel`. */ protected setBottomPanelSize(size: number): Promise<void>; /** * A promise that is resolved when all currently pending updates are done. */ get pendingUpdates(): Promise<void>; /** * Track all widgets that are referenced by the given layout data. */ protected registerWithFocusTracker(data: DockLayout.ITabAreaConfig | DockLayout.ISplitAreaConfig | SidePanel.LayoutData | null): void; /** * Add a widget to the application shell. The given widget must have a unique `id` property, * which will be used as the DOM id. * * Widgets are removed from the shell by calling their `close` or `dispose` methods. * * Widgets added to the top area are not tracked regarding the _current_ and _active_ states. */ addWidget(widget: Widget, options?: Readonly<ApplicationShell.WidgetOptions>): Promise<void>; getInsertionOptions(options?: Readonly<ApplicationShell.WidgetOptions>): { area: string; addOptions: DockLayout.IAddOptions; }; /** * The widgets contained in the given shell area. */ getWidgets(area: ApplicationShell.Area): Widget[]; /** * Find the widget that contains the given HTML element. The returned widget may be one * that is managed by the application shell, or one that is embedded in another widget and * not directly managed by the shell, or a tab bar. */ findWidgetForElement(element: HTMLElement): Widget | undefined; private findWidgetForNode; /** * Finds the title widget from the tab-bar. * @param tabBar used for providing an array of titles. * @returns the selected title widget, else returns the currentTitle or undefined. */ findTitle(tabBar: TabBar<Widget>, event?: Event): Title<Widget> | undefined; /** * Finds the tab-bar widget. * @returns the selected tab-bar, else returns the currentTabBar. */ findTabBar(event?: Event): TabBar<Widget> | undefined; /** * @returns the widget whose title has been targeted by a DOM event on a tabbar, or undefined if none can be found. */ findTargetedWidget(event?: Event): Widget | undefined; /** * The current widget in the application shell. The current widget is the last widget that * was active and not yet closed. See the remarks to `activeWidget` on what _active_ means. */ get currentWidget(): Widget | undefined; /** * The active widget in the application shell. The active widget is the one that has focus * (either the widget itself or any of its contents). * * _Note:_ Focus is taken by a widget through the `onActivateRequest` method. It is up to the * widget implementation which DOM element will get the focus. The default implementation * does not take any focus; in that case the widget is never returned by this property. */ get activeWidget(): Widget | undefined; /** * Returns the last active widget in the given shell area. */ getCurrentWidget(area: ApplicationShell.Area): Widget | undefined; /** * Handle a change to the current widget. */ private onCurrentChanged; protected readonly toDisposeOnActiveChanged: DisposableCollection; /** * Handle a change to the active widget. */ private onActiveChanged; /** * Set the z-index of the given element and its ancestors to the value `z`. */ private setZIndex; /** * Track the given widget so it is considered in the `current` and `active` state of the shell. */ protected track(widget: Widget): void; /** * @returns an array of Widgets, all of which are tracked by the focus tracker * The first member of the array is the widget whose id is passed in, and the other widgets * are its tracked parents in ascending order */ protected toTrackedStack(id: string): Widget[]; /** * Activate a widget in the application shell. This makes the widget visible and usually * also assigns focus to it. * * _Note:_ Focus is taken by a widget through the `onActivateRequest` method. It is up to the * widget implementation which DOM element will get the focus. The default implementation * does not take any focus. * * @returns the activated widget if it was found */ activateWidget(id: string): Promise<Widget | undefined>; waitForActivation(id: string): Promise<void>; /** * Activate top-level area widget. */ protected doActivateWidget(id: string): Widget | undefined; /** * Focus is taken by a widget through the `onActivateRequest` method. It is up to the * widget implementation which DOM element will get the focus. The default implementation * of Widget does not take any focus. This method can help finding such problems by logging * a warning in case a widget was explicitly activated, but did not trigger a change of the * `activeWidget` property. */ private checkActivation; private readonly activationTimeout; private readonly toDisposeOnActivationCheck; private assertActivated; /** * Reveal a widget in the application shell. This makes the widget visible, * but does not activate it. * * @returns the revealed widget if it was found */ revealWidget(id: string): Promise<Widget | undefined>; /** * Reveal top-level area widget. */ protected doRevealWidget(id: string): Widget | undefined; /** * Expand the named side panel area. This makes sure that the panel is visible, even if there * are no widgets in it. If the panel is already visible, nothing happens. If the panel is currently * collapsed (see `collapsePanel`) and it contains widgets, the widgets are revealed that were * visible before it was collapsed. */ expandPanel(area: ApplicationShell.Area): void; /** * Adjusts the size of the given area in the application shell. * * @param size the desired size of the panel in pixels. * @param area the area to resize. */ resize(size: number, area: ApplicationShell.Area): void; /** * Expand the bottom panel. See `expandPanel` regarding the exact behavior. */ protected expandBottomPanel(): void; /** * Collapse the named side panel area. This makes sure that the panel is hidden, * increasing the space that is available for other shell areas. */ collapsePanel(area: ApplicationShell.Area): Promise<void>; /** * Collapse the bottom panel. All contained widgets are hidden, but not closed. * They can be restored by calling `expandBottomPanel`. */ protected collapseBottomPanel(): Promise<void>; /** * Refresh the toggle button for the bottom panel. This implementation creates a status bar entry * and refers to the command `core.toggle.bottom.panel`. */ protected refreshBottomPanelToggleButton(): void; /** * Check whether the named side panel area is expanded (returns `true`) or collapsed (returns `false`). */ isExpanded(area: ApplicationShell.Area): boolean; /** * Close all tabs or a selection of tabs in a specific part of the application shell. * * @param tabBarOrArea * Either the name of a shell area or a `TabBar` that is contained in such an area. * @param filter * If undefined, all tabs are closed; otherwise only those tabs that match the filter are closed. */ closeTabs(tabBarOrArea: TabBar<Widget> | ApplicationShell.Area, filter?: (title: Title<Widget>, index: number) => boolean): Promise<void>; saveTabs(tabBarOrArea: TabBar<Widget> | ApplicationShell.Area, filter?: (title: Title<Widget>, index: number) => boolean): void; /** * Collects all widget titles for the given tab bar or area and optionally filters them. * * @param tabBarOrArea The tab bar or area to retrieve the widget titles for * @param filter The filter to apply to the result * @returns The filtered array of widget titles or an empty array */ protected getWidgetTitles(tabBarOrArea: TabBar<Widget> | ApplicationShell.Area, filter?: (title: Title<Widget>, index: number) => boolean): Title<Widget>[]; /** * @param targets the widgets to be closed * @return an array of all the widgets that were actually closed. */ closeMany(targets: Widget[], options?: ApplicationShell.CloseOptions): Promise<Widget[]>; /** * @returns the widget that was closed, if any, `undefined` otherwise. * * If your use case requires closing multiple widgets, use {@link ApplicationShell#closeMany} instead. That method handles closing saveable widgets more reliably. */ closeWidget(id: string, options?: ApplicationShell.CloseOptions): Promise<Widget | undefined>; /** * The shell area name of the currently active tab, or undefined. */ get currentTabArea(): ApplicationShell.Area | undefined; /** * Determine the name of the shell area where the given widget resides. The result is * undefined if the widget does not reside directly in the shell. */ getAreaFor(input: TabBar<Widget> | Widget): ApplicationShell.Area | undefined; protected getAreaPanelFor(input: Widget): DockPanel | undefined; /** * Return the tab bar that has the currently active widget, or undefined. */ get currentTabBar(): TabBar<Widget> | undefined; /** * Return the tab bar in the given shell area, or the tab bar that has the given widget, or undefined. */ getTabBarFor(widgetOrArea: Widget | ApplicationShell.Area): TabBar<Widget> | undefined; /** * The tab bars contained in the main shell area. If there is no widget in the main area, the * returned array is empty. */ get mainAreaTabBars(): TabBar<Widget>[]; /** * The tab bars contained in the bottom shell area. If there is no widget in the bottom area, * the returned array is empty. */ get bottomAreaTabBars(): TabBar<Widget>[]; /** * The tab bars contained in all shell areas. */ get allTabBars(): TabBar<Widget>[]; activateNextTabInTabBar(current?: TabBar<Widget> | undefined): boolean; nextTabIndexInTabBar(current?: TabBar<Widget> | undefined): number; activateNextTab(): boolean; activateNextTabBar(current?: TabBar<Widget> | undefined): boolean; /** * Return the tab bar next to the given tab bar; return the given tab bar if there is no adjacent one. */ nextTabBar(current?: TabBar<Widget> | undefined): TabBar<Widget> | undefined; activatePreviousTabInTabBar(current?: TabBar<Widget> | undefined): boolean; previousTabIndexInTabBar(current?: TabBar<Widget> | undefined): number; activatePreviousTab(): boolean; activatePreviousTabBar(current?: TabBar<Widget> | undefined): boolean; /** * Return the tab bar previous to the given tab bar; return the given tab bar if there is no adjacent one. */ previousTabBar(current?: TabBar<Widget> | undefined): TabBar<Widget> | undefined; /** * Test whether the current widget is dirty. */ canSave(): boolean; /** * Save the current widget if it is dirty. */ save(options?: SaveOptions): Promise<void>; /** * Test whether there is a dirty widget. */ canSaveAll(): boolean; /** * Save all dirty widgets. */ saveAll(options?: SaveOptions): Promise<void>; /** * Returns a snapshot of all tracked widgets to allow async modifications. */ get widgets(): ReadonlyArray<Widget>; getWidgetById(id: string): Widget | undefined; canToggleMaximized(widget?: Widget | undefined): boolean; toggleMaximized(widget?: Widget | undefined): void; } /** * The namespace for `ApplicationShell` class statics. */ export declare namespace ApplicationShell { /** * The areas of the application shell where widgets can reside. */ type Area = 'main' | 'top' | 'left' | 'right' | 'bottom' | 'secondaryWindow'; const areaLabels: Record<Area, string>; /** * The _side areas_ are those shell areas that can be collapsed and expanded, * i.e. `left`, `right`, and `bottom`. */ function isSideArea(area?: string): area is 'left' | 'right' | 'bottom'; function isValidArea(area?: unknown): area is ApplicationShell.Area; /** * General options for the application shell. These are passed on construction and can be modified * through dependency injection (`ApplicationShellOptions` symbol). */ interface Options extends Widget.IOptions { bottomPanel: BottomPanelOptions; leftPanel: SidePanel.Options; rightPanel: SidePanel.Options; } interface BottomPanelOptions extends SidePanel.Options { } /** * The default values for application shell options. */ const DEFAULT_OPTIONS: Readonly<Options>; /** * Whether a widget should be opened to the side tab bar relatively to the reference widget. */ type OpenToSideMode = 'open-to-left' | 'open-to-right'; function isOpenToSideMode(mode: unknown): mode is OpenToSideMode; /** * Options for adding a widget to the application shell. */ interface WidgetOptions extends SidePanel.WidgetOptions { /** * The area of the application shell where the widget will reside. */ area?: Area; /** * The insertion mode for adding the widget. * * The default is `'tab-after'`. */ mode?: DockLayout.InsertMode | OpenToSideMode; /** * The reference widget for the insert location. * * The default is `undefined`. */ ref?: Widget; } interface CloseOptions { /** * if optional then a user will be prompted * if undefined then close will be canceled * if true then will be saved on close * if false then won't be saved on close */ save?: boolean | undefined; } /** * Data to save and load the application shell layout. */ interface LayoutData { version?: string | ApplicationShellLayoutVersion; mainPanel?: DockPanel.ILayoutConfig; mainPanelPinned?: boolean[]; bottomPanel?: BottomPanelLayoutData; leftPanel?: SidePanel.LayoutData; rightPanel?: SidePanel.LayoutData; activeWidgetId?: string; } /** * Data to save and load the bottom panel layout. */ interface BottomPanelLayoutData { config?: DockPanel.ILayoutConfig; size?: number; expanded?: boolean; pinned?: boolean[]; } /** * Exposes widgets which activation state should be tracked by shell. */ interface TrackableWidgetProvider { getTrackableWidgets(): Widget[]; readonly onDidChangeTrackableWidgets?: CommonEvent<Widget[]>; /** * Make visible and focus a trackable widget for the given id. * If not implemented then `activate` request will be sent to a child widget directly. */ activateWidget?(id: string): Widget | undefined; /** * Make visible a trackable widget for the given id. * If not implemented then a widget should be always visible when an owner is visible. */ revealWidget?(id: string): Widget | undefined; } namespace TrackableWidgetProvider { function is(widget: unknown): widget is TrackableWidgetProvider; } } //# sourceMappingURL=application-shell.d.ts.map