@jupyterlab/application

constructor

constructor(options: JupyterFrontEnd.IOptions<T, any>);

• Construct a new JupyterFrontEnd object.

property commandLinker

readonly commandLinker: CommandLinker;

• The command linker used by the application.

property contextMenu

readonly contextMenu: ContextMenuSvg;

• The application context menu.

property docRegistry

readonly docRegistry: DocumentRegistry;

• The document registry instance used by the application.

property format

format: string;

• The application form factor, e.g., desktop or mobile.

property formatChanged

readonly formatChanged: ISignal<this, U>;

• A signal that emits when the application form factor changes.

property name

abstract readonly name: string;

• The name of this Jupyter front-end application.

property namespace

abstract readonly namespace: string;

• A namespace/prefix plugins may use to denote their provenance.

property restored

readonly restored: Promise<void>;

• Promise that resolves when state is first restored.

property serviceManager

readonly serviceManager: ServiceManager.IManager;

• The service manager used by the application.

property version

abstract readonly version: string;

• The version of this Jupyter front-end application.

method contextMenuHitTest

contextMenuHitTest: (
    fn: (node: HTMLElement) => boolean
) => HTMLElement | undefined;

• Walks up the DOM hierarchy of the target of the active contextmenu event, testing each HTMLElement ancestor for a user-supplied function. This can be used to find an HTMLElement on which to operate, given a context menu click.

  Parameter fn

  a function that takes an HTMLElement and returns a boolean for whether it is the element the requester is seeking.

  Returns

  an HTMLElement or undefined, if none is found.

method evtContextMenu

protected evtContextMenu: (event: MouseEvent) => void;

• A method invoked on a document 'contextmenu' event.

constructor

constructor(options?: JupyterLab.IOptions);

• Construct a new JupyterLab object.

property allPluginsActivated

readonly allPluginsActivated: Promise<void>;

• Promise that resolves when all the plugins are activated, including the deferred.

property info

readonly info: JupyterLab.IInfo;

• The JupyterLab application information dictionary.

property name

readonly name: string;

• The name of the JupyterLab application.

property namespace

readonly namespace: string;

• A namespace/prefix plugins may use to denote their provenance.

property paths

readonly paths: JupyterFrontEnd.IPaths;

• The JupyterLab application paths dictionary.

property registerPluginErrors

readonly registerPluginErrors: Error[];

• A list of all errors encountered when registering plugins.

property restored

readonly restored: Promise<void>;

• Promise that resolves when state is first restored, returning layout description.

property status

readonly status: LabStatus;

• The application busy and dirty status signals and flags.

property version

readonly version: string;

• The version of the JupyterLab application.

method evtKeydown

protected evtKeydown: (keyDownEvent: KeyboardEvent) => void;

• Override keydown handling to prevent command shortcuts from preventing user input.

  This introduces a slight delay to the command invocation, but no delay to user input.

method registerPluginModule

registerPluginModule: (mod: JupyterLab.IPluginModule) => void;

• Register plugins from a plugin module.

  Parameter mod

  The plugin module to register.

method registerPluginModules

registerPluginModules: (mods: JupyterLab.IPluginModule[]) => void;

• Register the plugins from multiple plugin modules.

  Parameter mods

  The plugin modules to register.

constructor

constructor(options?: ILabShell.IOptions);

• Construct a new application shell.

property activeChanged

readonly activeChanged: ISignal<this, FocusTracker.IChangedArgs<Widget>>;

• A signal emitted when main area's active focus changes.

property activeWidget

readonly activeWidget: any;

• The active widget in the shell's main area.

property addButtonEnabled

addButtonEnabled: boolean;

• Whether the add buttons for each main area tab bar are enabled.

property addRequested

readonly addRequested: ISignal<DockPanel, TabBar<Widget>>;

• A signal emitted when the add button on a main area tab bar is clicked.

property currentChanged

readonly currentChanged: ISignal<this, FocusTracker.IChangedArgs<Widget>>;

• A signal emitted when main area's current focus changes.

property currentPath

readonly currentPath: string;

• Current document path.

property currentPathChanged

readonly currentPathChanged: ISignal<this, ILabShell.ICurrentPathChangedArgs>;

• A signal emitted when the path of the current document changes.

  This also fires when the current document itself changes.

property currentWidget

readonly currentWidget: any;

• The current widget in the shell's main area.

property layoutModified

readonly layoutModified: ISignal<this, void>;

• A signal emitted when the main area's layout is modified.

property leftCollapsed

readonly leftCollapsed: boolean;

• Whether the left area is collapsed.

property mode

mode: DockPanel.Mode;

• The main dock area's user interface mode.

property modeChanged

readonly modeChanged: ISignal<this, DockPanel.Mode>;

• A signal emitted when the shell/dock panel change modes (single/multiple document).

property presentationMode

presentationMode: boolean;

• Whether JupyterLab is in presentation mode with the jp-mod-presentationMode CSS class.

property restored

readonly restored: Promise<ILabShell.ILayout>;

• Promise that resolves when state is first restored, returning layout description.

property rightCollapsed

readonly rightCollapsed: boolean;

• Whether the left area is collapsed.

property translator

translator: ITranslator;

property userLayout

readonly userLayout: {
    'single-document': ILabShell.IUserLayout;
    'multiple-document': ILabShell.IUserLayout;
};

• User customized shell layout.

method activateArea

activateArea: (area?: ILabShell.Area) => void;

• Activate widget in specified area.

  ### Notes The alpha version of this method only supports activating the "main" area.

  Parameter area

  Name of area to activate

  Modifiers

  • @alpha

method activateById

activateById: (id: string) => void;

• Activate a widget in its area.

method activateNextTab

activateNextTab: () => void;

• Activate the next Tab in the active TabBar.

method activateNextTabBar

activateNextTabBar: () => void;

• Activate the next TabBar.

method activatePreviousTab

activatePreviousTab: () => void;

• Activate the previous Tab in the active TabBar.

method activatePreviousTabBar

activatePreviousTabBar: () => void;

• Activate the next TabBar.

method add

add: (
    widget: Widget,
    area?: ILabShell.Area,
    options?: DocumentRegistry.IOpenOptions
) => void;

• Add a widget to the JupyterLab shell

  Parameter widget

  Widget

  Parameter area

  Area

  Parameter options

  Options

method closeAll

closeAll: () => void;

• Close all widgets in the main and down area.

method collapseLeft

collapseLeft: () => void;

• Collapse the left area.

method collapseRight

collapseRight: () => void;

• Collapse the right area.

method dispose

dispose: () => void;

• Dispose the shell.

method expandLeft

expandLeft: () => 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.

method expandRight

expandRight: () => 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.

method isEmpty

isEmpty: (area: ILabShell.Area) => boolean;

• True if the given area is empty.

method isSideTabBarVisible

isSideTabBarVisible: (side: 'left' | 'right') => boolean;

• Whether an side tab bar is visible or not.

  Parameter side

  Sidebar of interest

  Returns

  Side tab bar visibility

method isTopInSimpleModeVisible

isTopInSimpleModeVisible: () => boolean;

• Whether the top bar in simple mode is visible or not.

  Returns

  Top bar visibility

method move

move: (
    widget: Widget,
    area: ILabShell.Area,
    mode?: DockPanel.Mode
) => {
    'single-document': ILabShell.IUserLayout;
    'multiple-document': ILabShell.IUserLayout;
};

• 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.

  Parameter widget

  Widget to move

  Parameter area

  New area

  Parameter mode

  Mode to change

  Returns

  The new user layout

method onAfterAttach

protected onAfterAttach: (msg: Message) => void;

• Handle after-attach messages for the application shell.

method restoreLayout

restoreLayout: (
    mode: DockPanel.Mode,
    layoutRestorer: LayoutRestorer,
    configuration?: { [m: string]: ILabShell.IUserLayout }
) => Promise<void>;

• Restore the layout state and configuration for the application shell.

  #### Notes This should only be called once.

method saveLayout

saveLayout: () => ILabShell.ILayout;

• Save the dehydrated state of the application shell.

method toggleSideTabBarVisibility

toggleSideTabBarVisibility: (side: 'right' | 'left') => void;

• Toggle side tab bar visibility

  Parameter side

  Sidebar of interest

method toggleTopInSimpleModeVisibility

toggleTopInSimpleModeVisibility: () => void;

• Toggle top header visibility in simple mode

  Note: Does nothing in multi-document mode

method updateConfig

updateConfig: (config: Partial<ILabShell.IConfig>) => void;

• Update the shell configuration.

  Parameter config

  Shell configuration

method widgets

widgets: (area?: ILabShell.Area) => IterableIterator<Widget>;

• Returns the widgets for an application area.

constructor

constructor(app: JupyterFrontEnd<any, any>);

• Construct a new status object.

property busySignal

readonly busySignal: ISignal<
    JupyterFrontEnd<JupyterFrontEnd.IShell, 'desktop' | 'mobile'>,
    boolean
>;

• Returns a signal for when application changes its busy status.

property dirtySignal

readonly dirtySignal: ISignal<
    JupyterFrontEnd<JupyterFrontEnd.IShell, 'desktop' | 'mobile'>,
    boolean
>;

• Returns a signal for when application changes its dirty status.

property isBusy

readonly isBusy: boolean;

• Whether the application is busy.

property isDirty

readonly isDirty: boolean;

• Whether the application is dirty.

method setBusy

setBusy: () => IDisposable;

• Set the application state to busy.

  Returns

  A disposable used to clear the busy state for the caller.

method setDirty

setDirty: () => IDisposable;

• Set the application state to dirty.

  Returns

  A disposable used to clear the dirty state for the caller.

constructor

constructor(options: LayoutRestorer.IOptions);

• Create a layout restorer.

property isDeferred

readonly isDeferred: boolean;

• Whether full layout restoration is deferred and is currently incomplete.

  #### Notes This flag is useful for tracking when the application has started in 'single-document' mode and the main area has not yet been restored.

property restored

readonly restored: Promise<void>;

• A promise resolved when the layout restorer is ready to receive signals.

method add

add: (widget: Widget, name: string) => void;

• Add a widget to be tracked by the layout restorer.

method fetch

fetch: () => Promise<ILabShell.ILayout>;

• Fetch the layout state for the application.

  #### Notes Fetching the layout relies on all widget restoration to be complete, so calls to fetch are guaranteed to return after restoration is complete.

method restore

restore: (
    tracker: WidgetTracker,
    options: IRestorer.IOptions<Widget>
) => Promise<any>;

• Restore the widgets of a particular widget tracker.

  Parameter tracker

  The widget tracker whose widgets will be restored.

  Parameter options

  The restoration options.

method restoreDeferred

restoreDeferred: () => Promise<ILabShell.IMainArea | null>;

• Restore the application layout if its restoration has been deferred.

  Returns

  - the rehydrated main area.

method save

save: (layout: ILabShell.ILayout) => Promise<void>;

• Save the layout state for the application.

constructor

constructor(options: Router.IOptions);

• Create a URL router.

property base

readonly base: string;

• The base URL for the router.

property commands

readonly commands: CommandRegistry;

• The command registry used by the router.

property current

readonly current: IRouter.ILocation;

• Returns the parsed current URL of the application.

property routed

readonly routed: ISignal<this, IRouter.ILocation>;

• A signal emitted when the router routes a route.

property stop

readonly stop: Token<void>;

• If a matching rule's command resolves with the stop token during routing, no further matches will execute.

method navigate

navigate: (path: string, options?: IRouter.INavOptions) => void;

• Navigate to a new path within the application.

  Parameter path

  The new path or empty string if redirecting to root.

  Parameter options

  The navigation options.

method register

register: (options: IRouter.IRegisterOptions) => IDisposable;

• Register to route a path pattern to a command.

  Parameter options

  The route registration options.

  Returns

  A disposable that removes the registered rule from the router.

method reload

reload: () => void;

• Cause a hard reload of the document.

method route

route: () => Promise<void>;

• Route a specific path to an action.

  #### Notes If a pattern is matched, its command will be invoked with arguments that match the IRouter.ILocation interface.

property busySignal

readonly busySignal: ISignal<JupyterFrontEnd<any, any>, boolean>;

• A signal for when application changes its busy status.

property dirtySignal

readonly dirtySignal: ISignal<JupyterFrontEnd<any, any>, boolean>;

• A signal for when application changes its dirty status.

property isBusy

readonly isBusy: boolean;

• Whether the application is busy.

property isDirty

readonly isDirty: boolean;

• Whether the application is dirty.

method setBusy

setBusy: () => IDisposable;

• Set the application state to busy.

  Returns

  A disposable used to clear the busy state for the caller.

method setDirty

setDirty: () => IDisposable;

• Set the application state to dirty.

  Returns

  A disposable used to clear the dirty state for the caller.

property restored

restored: Promise<void>;

• A promise resolved when the layout restorer is ready to receive signals.

method add

add: (widget: Widget, name: string) => void;

• Add a widget to be tracked by the layout restorer.

method restore

restore: <T extends Widget>(
    tracker: WidgetTracker<T>,
    options: IRestorer.IOptions<T>
) => Promise<any>;

• Restore the widgets of a particular widget tracker.

  Parameter tracker

  The widget tracker whose widgets will be restored.

  Parameter options

  The restoration options.

property base

readonly base: string;

• The base URL for the router.

property commands

readonly commands: CommandRegistry;

• The command registry used by the router.

property current

readonly current: IRouter.ILocation;

• The parsed current URL of the application.

property routed

readonly routed: ISignal<IRouter, IRouter.ILocation>;

• A signal emitted when the router routes a route.

property stop

readonly stop: Token<void>;

• If a matching rule's command resolves with the stop token during routing, no further matches will execute.

method navigate

navigate: (path: string, options?: IRouter.INavOptions) => void;

• Navigate to a new path within the application.

  Parameter path

  The new path or empty string if redirecting to root.

  Parameter options

  The navigation options.

method register

register: (options: IRouter.IRegisterOptions) => IDisposable;

• Register a rule that maps a path pattern to a command.

  Parameter options

  The route registration options.

  Returns

  A disposable that removes the registered rule from the router.

method reload

reload: () => void;

• Cause a hard reload of the document.

method route

route: (url: string) => void;

• Route a specific path to an action.

  Parameter url

  The URL string that will be routed.

  #### Notes If a pattern is matched, its command will be invoked with arguments that match the IRouter.ILocation interface.

property caption

caption?: string;

• Default command caption

property execute

execute?: string;

• Default command id to execute if no command is enabled

property isEnabled

isEnabled?: boolean;

• Whether the default command is enabled.

property isToggled

isToggled?: boolean;

• Whether the default command is toggled.

property isVisible

isVisible?: boolean;

• Whether the default command is visible.

property label

label?: string;

• Default command label

property commands

commands: CommandRegistry;

• Application command registry

property default

default?: ISemanticCommandDefault;

• Default commands options

  It will be used if the enabled command is not defining one or if no command is enabled.

property id

id: string;

• Semantic command ID

property overrides

overrides?: Omit<CommandRegistry.ICommandOptions, 'execute'>;

• Override commands options

  It will override the enabled command attribute.

property semanticCommands

semanticCommands: SemanticCommand | SemanticCommand[];

• Semantic commands

property shell

shell: JupyterFrontEnd.IShell;

• Application shell

property trans

trans?: TranslationBundle;

• Domain specific translation object.

call signature

(treePath: string): void;

type Area

type Area =
    | 'main'
    | 'header'
    | 'top'
    | 'menu'
    | 'left'
    | 'right'
    | 'bottom'
    | 'down';

• The areas of the application shell where widgets can reside.

type AreaConfig

type AreaConfig = DockLayout.AreaConfig;

• The restorable description of an area within the main dock panel.

type IChangedArgs

type IChangedArgs = FocusTracker.IChangedArgs<Widget>;

• An arguments object for the changed signals.

type IOptions

type IOptions = {
    /**
     * Whether the layout should wait to be restored before adding widgets or not.
     *
     * #### Notes
     * It defaults to true
     */
    waitForRestore?: boolean;
};

• An options object for creating a lab shell object.

variable IPaths

const IPaths: Token<IPaths>;

• The application paths dictionary token.

variable ITreeResolver

const ITreeResolver: Token<ITreeResolver>;

• The application tree resolver token.

  #### Notes Not all Jupyter front-end applications will have a tree resolver implemented on the client-side. This token should not be required as a dependency if it is possible to make it an optional dependency.

function inDocMode

inDocMode: (path: string, paths: IPaths) => boolean;

• Is JupyterLab in document mode?

  Parameter path

  Full URL of JupyterLab

  Parameter paths

  The current IPaths object hydrated from PageConfig.

type Paths

type Paths = {
    browser: string;
    file: string;
} | null;

• The browser and file paths if the tree resolver encountered and handled a tree URL or null if not. Empty string paths should be ignored.

variable contextMenu

const contextMenu: string;

• An id for a private context-menu-info ersatz command.

variable defaultInfo

const defaultInfo: IInfo;

• The default JupyterLab application info.

variable defaultPaths

const defaultPaths: JupyterFrontEnd.IPaths;

• The default JupyterLab application paths.

variable IInfo

const IInfo: Token<IInfo>;

• The layout restorer token.