@theia/core
Version:
Theia is a cloud & desktop IDE framework implemented in TypeScript.
566 lines • 25.3 kB
TypeScript
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