@jupyterlab/application
Version:
JupyterLab - Application
566 lines (565 loc) • 16.5 kB
TypeScript
import { DocumentRegistry } from '@jupyterlab/docregistry';
import { ITranslator } from '@jupyterlab/translation';
import { Token } from '@lumino/coreutils';
import { Message } from '@lumino/messaging';
import { ISignal } from '@lumino/signaling';
import { DockLayout, DockPanel, FocusTracker, TabBar, Widget } from '@lumino/widgets';
import { JupyterFrontEnd } from './frontend';
import { LayoutRestorer } from './layoutrestorer';
/**
* The JupyterLab application shell token.
*/
export declare const ILabShell: Token<ILabShell>;
/**
* The JupyterLab application shell interface.
*/
export interface ILabShell extends LabShell {
}
/**
* The namespace for `ILabShell` type information.
*/
export declare namespace ILabShell {
/**
* The areas of the application shell where widgets can reside.
*/
type Area = 'main' | 'header' | 'top' | 'menu' | 'left' | 'right' | 'bottom' | 'down';
/**
* The restorable description of an area within the main dock panel.
*/
type AreaConfig = DockLayout.AreaConfig;
/**
* An options object for creating a lab shell object.
*/
type IOptions = {
/**
* Whether the layout should wait to be restored before adding widgets or not.
*
* #### Notes
* It defaults to true
*/
waitForRestore?: boolean;
};
/**
* An arguments object for the changed signals.
*/
type IChangedArgs = FocusTracker.IChangedArgs<Widget>;
interface IConfig {
/**
* The method for hiding widgets in the dock panel.
*
* The default is `display`.
*
* Using `scale` will often increase performance as most browsers will not trigger style computation
* for the transform action.
*
* `contentVisibility` is only available in Chromium-based browsers.
*/
hiddenMode: 'display' | 'scale' | 'contentVisibility';
}
/**
* Widget position
*/
interface IWidgetPosition {
/**
* Widget area
*/
area?: Area;
/**
* Widget opening options
*/
options?: DocumentRegistry.IOpenOptions;
}
/**
* To-be-added widget and associated position
*/
interface IDelayedWidget extends IWidgetPosition {
widget: Widget;
}
/**
* Mapping of widget type identifier and their user customized position
*/
interface IUserLayout {
/**
* Widget customized position
*/
[]: IWidgetPosition;
}
/**
* The args for the current path change signal.
*/
interface ICurrentPathChangedArgs {
/**
* The new value of the tree path, not including '/tree'.
*/
oldValue: string;
/**
* The old value of the tree path, not including '/tree'.
*/
newValue: string;
}
/**
* A description of the application's user interface layout.
*/
interface ILayout {
/**
* Indicates whether fetched session restore data was actually retrieved
* from the state database or whether it is a fresh blank slate.
*
* #### Notes
* This attribute is only relevant when the layout data is retrieved via a
* `fetch` call. If it is set when being passed into `save`, it will be
* ignored.
*/
readonly fresh?: boolean;
/**
* The main area of the user interface.
*/
readonly mainArea: IMainArea | null;
/**
* The down area of the user interface.
*/
readonly downArea: IDownArea | null;
/**
* The left area of the user interface.
*/
readonly leftArea: ISideArea | null;
/**
* The right area of the user interface.
*/
readonly rightArea: ISideArea | null;
/**
* The top area of the user interface.
*/
readonly topArea: ITopArea | null;
/**
* The relatives sizes of the areas of the user interface.
*/
readonly relativeSizes: number[] | null;
}
/**
* The restorable description of the main application area.
*/
interface IMainArea {
/**
* The current widget that has application focus.
*/
readonly currentWidget: Widget | null;
/**
* The contents of the main application dock panel.
*/
readonly dock: DockLayout.ILayoutConfig | null;
}
interface IDownArea {
/**
* The current widget that has down area focus.
*/
readonly currentWidget: Widget | null;
/**
* The collection of widgets held by the panel.
*/
readonly widgets: Array<Widget> | null;
/**
* Vertical relative size of the down area
*
* The main area will take the rest of the height
*/
readonly size: number | null;
}
/**
* The restorable description of a sidebar in the user interface.
*/
interface ISideArea {
/**
* A flag denoting whether the sidebar has been collapsed.
*/
readonly collapsed: boolean;
/**
* The current widget that has side area focus.
*/
readonly currentWidget: Widget | null;
/**
* A flag denoting whether the side tab bar is visible.
*/
readonly visible: boolean;
/**
* The collection of widgets held by the sidebar.
*/
readonly widgets: Array<Widget> | null;
/**
* The collection of widgets states held by the sidebar.
*/
readonly widgetStates: {
[]: {
/**
* Vertical sizes of the widgets.
*/
readonly sizes: Array<number> | null;
/**
* Expansion states of the widgets.
*/
readonly expansionStates: Array<boolean> | null;
};
};
}
/**
* The restorable description of the top area in the user interface.
*/
interface ITopArea {
/**
* Top area visibility in simple mode.
*/
readonly simpleVisibility: boolean;
}
}
/**
* The restorable description of the top area in the user interface.
*
* @deprecated It has been moved to {@link ILabShell.ITopArea} for consistency.
*/
export interface ITopArea extends ILabShell.ITopArea {
}
/**
* The application shell for JupyterLab.
*/
export declare class LabShell extends Widget implements JupyterFrontEnd.IShell {
/**
* Construct a new application shell.
*/
constructor(options?: ILabShell.IOptions);
/**
* A signal emitted when main area's active focus changes.
*/
get activeChanged(): ISignal<this, ILabShell.IChangedArgs>;
/**
* The active widget in the shell's main area.
*/
get activeWidget(): Widget | null;
/**
* Whether the add buttons for each main area tab bar are enabled.
*/
get addButtonEnabled(): boolean;
set addButtonEnabled(value: boolean);
/**
* A signal emitted when the add button on a main area tab bar is clicked.
*/
get addRequested(): ISignal<DockPanel, TabBar<Widget>>;
/**
* A signal emitted when main area's current focus changes.
*/
get currentChanged(): ISignal<this, ILabShell.IChangedArgs>;
/**
* Current document path.
*/
get currentPath(): string | null | undefined;
/**
* A signal emitted when the path of the current document changes.
*
* This also fires when the current document itself changes.
*/
get currentPathChanged(): ISignal<this, ILabShell.ICurrentPathChangedArgs>;
/**
* The current widget in the shell's main area.
*/
get currentWidget(): Widget | null;
/**
* A signal emitted when the main area's layout is modified.
*/
get layoutModified(): ISignal<this, void>;
/**
* Whether the left area is collapsed.
*/
get leftCollapsed(): boolean;
/**
* Whether the left area is collapsed.
*/
get rightCollapsed(): boolean;
/**
* Whether JupyterLab is in presentation mode with the
* `jp-mod-presentationMode` CSS class.
*/
get presentationMode(): boolean;
set presentationMode(value: boolean);
/**
* The main dock area's user interface mode.
*/
get mode(): DockPanel.Mode;
set mode(mode: DockPanel.Mode);
/**
* A signal emitted when the shell/dock panel change modes (single/multiple document).
*/
get modeChanged(): ISignal<this, DockPanel.Mode>;
/**
* Promise that resolves when state is first restored, returning layout
* description.
*/
get restored(): Promise<ILabShell.ILayout>;
get translator(): ITranslator;
set translator(value: ITranslator);
/**
* User customized shell layout.
*/
get userLayout(): {
'single-document': ILabShell.IUserLayout;
'multiple-document': ILabShell.IUserLayout;
};
/**
* Activate a widget in its area.
*/
activateById(id: string): void;
/**
* Activate widget in specified area.
*
* ### Notes
* The alpha version of this method only supports activating the "main" area.
*
* @alpha
* @param area Name of area to activate
*/
activateArea(area?: ILabShell.Area): void;
/**
* Activate the next Tab in the active TabBar.
*/
activateNextTab(): void;
/**
* Activate the previous Tab in the active TabBar.
*/
activatePreviousTab(): void;
/**
* Activate the next TabBar.
*/
activateNextTabBar(): void;
/**
* Activate the next TabBar.
*/
activatePreviousTabBar(): void;
/**
* Add a widget to the JupyterLab shell
*
* @param widget Widget
* @param area Area
* @param options Options
*/
add(widget: Widget, area?: ILabShell.Area, options?: DocumentRegistry.IOpenOptions): void;
/**
* Move a widget type to a new area.
*
* The type is determined from the `widget.id` and fallback to `widget.id`.
*
* #### Notes
* If `mode` is undefined, both mode are updated.
* The new layout is now persisted.
*
* @param widget Widget to move
* @param area New area
* @param mode Mode to change
* @returns The new user layout
*/
move(widget: Widget, area: ILabShell.Area, mode?: DockPanel.Mode): {
'single-document': ILabShell.IUserLayout;
'multiple-document': ILabShell.IUserLayout;
};
/**
* Collapse the left area.
*/
collapseLeft(): void;
/**
* Collapse the right area.
*/
collapseRight(): void;
/**
* Dispose the shell.
*/
dispose(): void;
/**
* Expand the left area.
*
* #### Notes
* This will open the most recently used tab,
* or the first tab if there is no most recently used.
*/
expandLeft(): void;
/**
* Expand the right area.
*
* #### Notes
* This will open the most recently used tab,
* or the first tab if there is no most recently used.
*/
expandRight(): void;
/**
* Close all widgets in the main and down area.
*/
closeAll(): void;
/**
* Whether an side tab bar is visible or not.
*
* @param side Sidebar of interest
* @returns Side tab bar visibility
*/
isSideTabBarVisible(side: 'left' | 'right'): boolean;
/**
* Whether the top bar in simple mode is visible or not.
*
* @returns Top bar visibility
*/
isTopInSimpleModeVisible(): boolean;
/**
* True if the given area is empty.
*/
isEmpty(area: ILabShell.Area): boolean;
/**
* Restore the layout state and configuration for the application shell.
*
* #### Notes
* This should only be called once.
*/
restoreLayout(mode: DockPanel.Mode, layoutRestorer: LayoutRestorer, configuration?: {
[]: ILabShell.IUserLayout;
}): Promise<void>;
/**
* Save the dehydrated state of the application shell.
*/
saveLayout(): ILabShell.ILayout;
/**
* Toggle top header visibility in simple mode
*
* Note: Does nothing in multi-document mode
*/
toggleTopInSimpleModeVisibility(): void;
/**
* Toggle side tab bar visibility
*
* @param side Sidebar of interest
*/
toggleSideTabBarVisibility(side: 'right' | 'left'): void;
/**
* Update the shell configuration.
*
* @param config Shell configuration
*/
updateConfig(config: Partial<ILabShell.IConfig>): void;
/**
* Returns the widgets for an application area.
*/
widgets(area?: ILabShell.Area): IterableIterator<Widget>;
/**
* Handle `after-attach` messages for the application shell.
*/
protected onAfterAttach(msg: Message): void;
/**
* Update the title panel title based on the title of the current widget.
*/
private _updateTitlePanelTitle;
/**
* The path of the current widget changed, fire the _currentPathChanged signal.
*/
private _updateCurrentPath;
/**
* Add a widget to the left content area.
*
* #### Notes
* Widgets must have a unique `id` property, which will be used as the DOM id.
*/
private _addToLeftArea;
/**
* Add a widget to the main content area.
*
* #### Notes
* Widgets must have a unique `id` property, which will be used as the DOM id.
* All widgets added to the main area should be disposed after removal
* (disposal before removal will remove the widget automatically).
*
* In the options, `ref` defaults to `null`, `mode` defaults to `'tab-after'`,
* and `activate` defaults to `true`.
*/
private _addToMainArea;
/**
* Add a widget to the right content area.
*
* #### Notes
* Widgets must have a unique `id` property, which will be used as the DOM id.
*/
private _addToRightArea;
/**
* Add a widget to the top content area.
*
* #### Notes
* Widgets must have a unique `id` property, which will be used as the DOM id.
*/
private _addToTopArea;
/**
* Add a widget to the title content area.
*
* #### Notes
* Widgets must have a unique `id` property, which will be used as the DOM id.
*/
private _addToMenuArea;
/**
* Add a widget to the header content area.
*
* #### Notes
* Widgets must have a unique `id` property, which will be used as the DOM id.
*/
private _addToHeaderArea;
/**
* Add a widget to the bottom content area.
*
* #### Notes
* Widgets must have a unique `id` property, which will be used as the DOM id.
*/
private _addToBottomArea;
private _addToDownArea;
private _adjacentBar;
private _currentTabBar;
/**
* Handle a change to the dock area active widget.
*/
private _onActiveChanged;
/**
* Handle a change to the dock area current widget.
*/
private _onCurrentChanged;
/**
* Handle a change on the down panel widgets
*/
private _onTabPanelChanged;
/**
* Handle a change to the layout.
*/
private _onLayoutModified;
/**
* A message hook for child add/remove messages on the main area dock panel.
*/
private _dockChildHook;
private _activeChanged;
private _cachedLayout;
private _currentChanged;
private _currentPath;
private _currentPathChanged;
private _modeChanged;
private _dockPanel;
private _downPanel;
private _isRestored;
private _layoutModified;
private _layoutDebouncer;
private _leftHandler;
private _restored;
private _rightHandler;
private _tracker;
private _headerPanel;
private _hsplitPanel;
private _vsplitPanel;
private _topHandler;
private _topHandlerHiddenByUser;
private _menuHandler;
private _skipLinkWidget;
private _titleHandler;
private _bottomPanel;
private _idTypeMap;
private _mainOptionsCache;
private _sideOptionsCache;
private _userLayout;
private _delayedWidget;
private _translator;
private _layoutRestorer;
}