@jupyterlab/application 4.0.0-alpha.2 → 4.0.0-alpha.20

package/lib/shell.d.ts

@@ -1,11 +1,11 @@
 import { DocumentRegistry } from '@jupyterlab/docregistry';
 import { ITranslator } from '@jupyterlab/translation';
-import { IIterator } from '@lumino/algorithm';
 import { Token } from '@lumino/coreutils';
 import { Message } from '@lumino/messaging';
 import { ISignal } from '@lumino/signaling';
-import { DockLayout, DockPanel, FocusTracker, Widget } from '@lumino/widgets';
+import { DockLayout, DockPanel, FocusTracker, TabBar, Widget } from '@lumino/widgets';
 import { JupyterFrontEnd } from './frontend';
+import { LayoutRestorer } from './layoutrestorer';
 /**
  * The JupyterLab application shell token.
  */
@@ -32,14 +32,58 @@ export declare namespace ILabShell {
      */
     type IOptions = {
         /**
-         * The application language translator.
+         * Whether the layout should wait to be restored before adding widgets or not.
+         *
+         * #### Notes
+         * It defaults to true
          */
-        translator?: ITranslator;
+        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.
      */
@@ -169,13 +213,18 @@ export declare class LabShell extends Widget implements JupyterFrontEnd.IShell {
      */
     get activeWidget(): Widget | null;
     /**
-     * A signal emitted when main area's current focus changes.
+     * Whether the add buttons for each main area tab bar are enabled.
      */
-    get currentChanged(): ISignal<this, ILabShell.IChangedArgs>;
+    get addButtonEnabled(): boolean;
+    set addButtonEnabled(value: boolean);
     /**
-     * A signal emitted when the shell/dock panel change modes (single/multiple document).
+     * A signal emitted when the add button on a main area tab bar is clicked.
      */
-    get modeChanged(): ISignal<this, DockPanel.Mode>;
+    get addRequested(): ISignal<DockPanel, TabBar<Widget>>;
+    /**
+     * A signal emitted when main area's current focus changes.
+     */
+    get currentChanged(): ISignal<this, ILabShell.IChangedArgs>;
     /**
      * A signal emitted when the path of the current document changes.
      *
@@ -203,30 +252,76 @@ export declare class LabShell extends Widget implements JupyterFrontEnd.IShell {
      * `jp-mod-presentationMode` CSS class.
      */
     get presentationMode(): boolean;
-    /**
-     * Enable/disable presentation mode (`jp-mod-presentationMode` CSS class) with
-     * a 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 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.
      */
@@ -277,9 +372,14 @@ export declare class LabShell extends Widget implements JupyterFrontEnd.IShell {
      */
     isEmpty(area: ILabShell.Area): boolean;
     /**
-     * Restore the layout state for the application shell.
+     * Restore the layout state and configuration for the application shell.
+     *
+     * #### Notes
+     * This should only be called once.
      */
-    restoreLayout(mode: DockPanel.Mode, layout: ILabShell.ILayout): void;
+    restoreLayout(mode: DockPanel.Mode, layoutRestorer: LayoutRestorer, configuration?: {
+        [m: string]: ILabShell.IUserLayout;
+    }): Promise<void>;
     /**
      * Save the dehydrated state of the application shell.
      */
@@ -296,10 +396,16 @@ export declare class LabShell extends Widget implements JupyterFrontEnd.IShell {
      * @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): IIterator<Widget>;
+    widgets(area?: ILabShell.Area): IterableIterator<Widget>;
     /**
      * Handle `after-attach` messages for the application shell.
      */
@@ -413,6 +519,11 @@ export declare class LabShell extends Widget implements JupyterFrontEnd.IShell {
     private _skipLinkWidget;
     private _titleHandler;
     private _bottomPanel;
+    private _idTypeMap;
     private _mainOptionsCache;
     private _sideOptionsCache;
+    private _userLayout;
+    private _delayedWidget;
+    private _translator;
+    private _layoutRestorer;
 }