@jupyterlab/application/lib/shell.d.ts

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
         */
        [k: string]: 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: {
            [id: string]: {
                /**
                 * 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.
 */
export interface ITopArea {
    /**
     * Top area visibility in simple mode.
     */
    readonly simpleVisibility: boolean;
}
/**
 * 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?: {
        [m: string]: 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;
}