@jupyterlab/apputils

@jupyterlab/apputils

Version 4.7.0
Published 5 days ago
1.02 MB
21 dependencies
BSD-3-Clause license

Install

npm i @jupyterlab/apputils

yarn add @jupyterlab/apputils

pnpm add @jupyterlab/apputils

Overview

apputils

Index

Variables

variable ICommandPalette

const ICommandPalette: Token<ICommandPalette>;

The command palette token.

variable IKernelStatusModel

const IKernelStatusModel: Token<IKernelStatusModel>;

The kernel status indicator model.

variable ILicensesClient

const ILicensesClient: Token<ILicensesClient>;

The license client for fetching licenses.

variable IMovableSectionRegistry

const IMovableSectionRegistry: Token<IMovableSectionRegistry>;

The movable section registry token.

variable ISanitizer

const ISanitizer: Token<IRenderMime.ISanitizer>;

The sanitizer token.

variable ISessionContextDialogs

const ISessionContextDialogs: Token<ISessionContext.IDialogs>;

The session context dialogs token.

variable ISplashScreen

const ISplashScreen: Token<ISplashScreen>;

The main menu token.

variable IThemeManager

const IThemeManager: Token<IThemeManager>;

The theme manager token.

variable IToolbarWidgetRegistry

const IToolbarWidgetRegistry: Token<IToolbarWidgetRegistry>;

The toolbar registry token.

variable IWindowResolver

const IWindowResolver: Token<IWindowResolver>;

The default window resolver token.

Functions

function createDefaultFactory

createDefaultFactory: (
    commands: CommandRegistry
) => (
    widgetFactory: string,
    widget: Widget,
    toolbarItem: ToolbarRegistry.IWidget
) => Widget;

Create the default toolbar item widget factory
Parameter commands
Application commands registry
Returns
Default factory

function createToolbarFactory

createToolbarFactory: (
    toolbarRegistry: IToolbarWidgetRegistry,
    settingsRegistry: ISettingRegistry,
    factoryName: string,
    pluginId: string,
    translator: ITranslator,
    propertyId?: string
) => (widget: Widget) => IObservableList<ToolbarRegistry.IToolbarItem>;

Create the toolbar factory for a given container widget based on a data description stored in settings
Parameter toolbarRegistry
Toolbar widgets registry
Parameter settingsRegistry
Settings registry
Parameter factoryName
Toolbar container factory name
Parameter pluginId
Settings plugin id
Parameter translator
Translator
Parameter propertyId
Toolbar definition key in the settings plugin
Returns
List of toolbar widgets factory

function setToolbar

setToolbar: (
    widget: Toolbar.IWidgetToolbar | Widget,
    factory: (
        widget: Widget
    ) =>
        | IObservableList<ToolbarRegistry.IToolbarItem>
        | ToolbarRegistry.IToolbarItem[],
    toolbar?: Toolbar
) => void;

Set the toolbar items of a widget from a factory
Parameter widget
Widget with the toolbar to set
Parameter factory
Toolbar items factory
Parameter toolbar
Separated toolbar if widget is a raw widget

function showDialog

showDialog: <T>(
    options?: Partial<Dialog.IOptions<T>>
) => Promise<Dialog.IResult<T>>;

Create and show a dialog.
Parameter options
The dialog setup options.
Returns
A promise that resolves with whether the dialog was accepted.

function showErrorMessage

showErrorMessage: (
    title: string,
    error: string | Dialog.IError,
    buttons?: ReadonlyArray<Dialog.IButton>
) => Promise<void>;

Show an error message dialog.
Parameter title
The title of the dialog box.
Parameter error
the error to show in the dialog body (either a string or an object with a string message property).

function translateKernelStatuses

translateKernelStatuses: (
    translator?: ITranslator
) => Record<ISessionContext.KernelDisplayStatus, string>;

Helper function to translate kernel statuses mapping by using input translator.
Parameter translator
Language translator. The translated kernel status mapping.

Classes

class CommandLinker

class CommandLinker implements IDisposable {}

A static class that provides helper methods to generate clickable nodes that execute registered commands with pre-populated arguments.

constructor

constructor(options: CommandLinker.IOptions);

Instantiate a new command linker.

property isDisposed

readonly isDisposed: boolean;

Test whether the linker is disposed.

method connectNode

connectNode: (
    node: HTMLElement,
    command: string,
    args?: ReadonlyPartialJSONObject
) => HTMLElement;

Connect a command/argument pair to a given node so that when it is clicked, the command will execute.
Parameter node
The node being connected.
Parameter command
The command ID to execute upon click.
Parameter args
The arguments with which to invoke the command.
Returns
The same node that was passed in, after it has been connected.
#### Notes Only click events will execute the command on a connected node. So, there are two considerations that are relevant: 1. If a node is connected, the default click action will be prevented. 2. The HTMLElement passed in should be clickable.

method disconnectNode

disconnectNode: (node: HTMLElement) => HTMLElement;

Disconnect a node that has been connected to execute a command on click.
Parameter node
The node being disconnected.
Returns
The same node that was passed in, after it has been disconnected.
#### Notes This method is safe to call multiple times and is safe to call on nodes that were never connected.
This method can be called on rendered virtual DOM nodes that were populated using the populateVNodeDataset method in order to disconnect them from executing their command/argument pair.

method dispose

dispose: () => void;

Dispose of the resources held by the linker.

method handleEvent

handleEvent: (event: Event) => void;

Handle the DOM events for the command linker helper class.
Parameter event
The DOM event sent to the class.
#### Notes This method implements the DOM EventListener interface and is called in response to events on the panel's DOM node. It should not be called directly by user code.

method markTrusted

markTrusted: (node: HTMLElement) => HTMLElement;

Mark a node as trusted for command execution.
#### Notes This trust marker is kept in-memory and cannot be forged from untrusted DOM content. The mark applies to the node and all of its descendants.

method populateVNodeDataset

populateVNodeDataset: (
    command: string,
    args?: ReadonlyPartialJSONObject
) => ElementDataset;

Populate the dataset attribute within the collection of attributes used to instantiate a virtual DOM node with the values necessary for its rendered DOM node to respond to clicks by executing a command/argument pair.
Parameter command
The command ID to execute upon click.
Parameter args
The arguments with which to invoke the command.
Returns
A dataset collection for use within virtual node attributes.
#### Notes The return value can be used on its own as the value for the dataset attribute of a virtual element, or it can be added to an existing dataset as in the example below.
#### Example
let command = 'some:command-id'; let args = { alpha: 'beta' }; let anchor = h.a({ className: 'some-class', dataset: { foo: '1', bar: '2', ../...linker.populateVNodeDataset(command, args) } }, 'some text');

method unmarkTrusted

unmarkTrusted: (node: HTMLElement) => HTMLElement;

Remove the trusted boundary marker from a node.
#### Notes This method is safe to call on nodes that were never marked as trusted.

class Dialog

class Dialog<T> extends Widget {}

A modal dialog widget.

constructor

constructor(options?: Partial<Dialog.IOptions<T>>);

Create a dialog panel instance.
Parameter options
The dialog setup options.

property ready

readonly ready: Promise<void>;

A promise that resolves when the Dialog first rendering is done.

method dispose

dispose: () => void;

Dispose of the resources used by the dialog.

method handleEvent

handleEvent: (event: Event) => void;

Handle the DOM events for the directory listing.
Parameter event
The DOM event sent to the widget.
#### Notes This method implements the DOM EventListener interface and is called in response to events on the panel's DOM node. It should not be called directly by user code.

method launch

launch: () => Promise<Dialog.IResult<T>>;

Launch the dialog as a modal window.
Returns
a promise that resolves with the result of the dialog.

method onAfterAttach

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

A message handler invoked on an 'after-attach' message.

method onAfterDetach

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

A message handler invoked on an 'after-detach' message.

method onCloseRequest

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

A message handler invoked on a 'close-request' message.

method reject

reject: () => void;

Reject the current dialog with a default reject value.
#### Notes Will be a no-op if the dialog is not shown.

method resolve

resolve: (index?: number) => void;

Resolve the current dialog.
Parameter index
An optional index to the button to resolve.
#### Notes Will default to the defaultIndex. Will resolve the current show() with the button value. Will be a no-op if the dialog is not shown.

class KernelStatus

class KernelStatus extends VDomRenderer<KernelStatus.Model> {}

A VDomRenderer widget for displaying the status of a kernel.

constructor

constructor(opts: KernelStatus.IOptions, translator?: ITranslator);

Construct the kernel status widget.

property translator

translator: ITranslator;

method render

render: () => JSX.Element | null;

Render the kernel status item.

class Licenses

class Licenses extends SplitPanel {}

A license viewer

constructor

constructor(options: Licenses.IOptions);

property model

readonly model: Licenses.Model;

method dispose

dispose: () => void;

Handle disposing of the widget

method initBundles

protected initBundles: () => void;

Initialize the listing of available bundles

method initFilters

protected initFilters: () => void;

Initialize the filters

method initGrid

protected initGrid: () => void;

Initialize the listing of packages within the current bundle

method initLeftPanel

protected initLeftPanel: () => void;

Initialize the left area for filters and bundles

method initLicenseText

protected initLicenseText: () => void;

Initialize the full text of the current package

method onBundleSelected

protected onBundleSelected: () => void;

Event handler for updating the model with the current bundle

class MainAreaWidget

class MainAreaWidget<T extends Widget = Widget>
    extends Widget
    implements Printing.IPrintable {}

A widget meant to be contained in the JupyterLab main area.
#### Notes Mirrors all of the title attributes of the content. This widget is closable by default. This widget is automatically disposed when closed. This widget ensures its own focus when activated.

constructor

constructor(options: MainAreaWidget.IOptions<T>);

Construct a new main area widget.
Parameter options
The options for initializing the widget.

property content

readonly content: Widget;

The content hosted by the widget.

property contentHeader

readonly contentHeader: BoxPanel;

A panel for widgets that sit between the toolbar and the content. Imagine a formatting toolbar, notification headers, etc.

property isRevealed

readonly isRevealed: boolean;

Whether the content widget or an error is revealed.

property revealed

readonly revealed: Promise<void>;

A promise that resolves when the widget is revealed.

readonly toolbar: Toolbar;

The toolbar hosted by the widget.

method [Printing.symbol]

[Printing.symbol]: () => Printing.OptionalAsyncThunk;

Print method. Deferred to content.

method onActivateRequest

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

Handle 'activate-request' messages.

method onAfterAttach

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

Handle after-attach messages for the widget.

method onBeforeDetach

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

Handle before-detach messages for the widget.

method onCloseRequest

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

Handle 'close-request' messages.

method onUpdateRequest

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

Handle 'update-request' messages by forwarding them to the content.

class ModalCommandPalette

class ModalCommandPalette extends Panel {}

Wrap the command palette in a modal to make it more usable.

constructor

constructor(options: ModalCommandPalette.IOptions);

property palette

palette: CommandPalette;

property searchIconGroup

readonly searchIconGroup: HTMLDivElement;

Find the element with search icon group.

method attach

attach: () => void;

method createSearchIconGroup

protected createSearchIconGroup: () => HTMLDivElement;

Create element with search icon group.

method detach

detach: () => void;

method handleEvent

handleEvent: (event: Event) => void;

Handle incoming events.

method hideAndReset

hideAndReset: () => void;

Hide the modal command palette and reset its search.

method onActivateRequest

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

A message handler invoked on an 'activate-request' message.

method onAfterAttach

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

A message handler invoked on an 'after-attach' message.

method onAfterDetach

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

A message handler invoked on an 'after-detach' message.

method onAfterShow

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

method onBeforeHide

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

class MovableSectionRegistry

class MovableSectionRegistry implements IMovableSectionRegistry {}

Source and target panels register themselves here so that generic section-moving commands can discover them.

property sourcePanelRegistered

readonly sourcePanelRegistered: Signal<
    this,
    { id: string; label: string; sidebar: IMovableSectionSource }
>;

property targetPanelRegistered

readonly targetPanelRegistered: Signal<
    this,
    { id: string; label: string; panel: IMovableSectionDestination }
>;

method getSources

getSources: () => ReadonlyMap<
    string,
    { label: string; sidebar: IMovableSectionSource }
>;

method getTargets

getTargets: () => ReadonlyMap<
    string,
    { label: string; panel: IMovableSectionDestination }
>;

method registerSource

registerSource: (
    id: string,
    label: string,
    sidebar: IMovableSectionSource
) => void;

method registerTarget

registerTarget: (
    id: string,
    label: string,
    panel: IMovableSectionDestination
) => void;

class NotificationManager

class NotificationManager implements IDisposable {}

Notification manager

constructor

constructor();

property changed

readonly changed: ISignal<NotificationManager, Notification.IChange>;

Signal emitted whenever a notification changes.

property count

readonly count: number;

Total number of notifications.

property isDisposed

readonly isDisposed: boolean;

Whether the manager is disposed or not.

property notifications

readonly notifications: Notification.INotification<ReadonlyJSONValue>[];

The list of notifications.

method dismiss

dismiss: (id?: string) => void;

Dismiss one notification (specified by its id) or all if no id provided.
Parameter id
Notification id

method dispose

dispose: () => void;

Dispose the manager.

method has

has: (id: string) => boolean;

Test whether a notification exists or not.
Parameter id
Notification id
Returns
Notification status

method notify

notify: <T extends ReadonlyJSONValue = ReadonlyJSONValue>(
    message: string,
    type: Notification.TypeOptions,
    options: Notification.IOptions<T>
) => string;

Add a new notification.
This will trigger the changed signal with an added event.
Parameter message
Notification message
Parameter type
Notification type
Parameter options
Notification option
Returns
Notification unique id

method update

update: <T extends ReadonlyJSONValue = ReadonlyJSONValue>(
    args: Notification.IUpdate<T>
) => boolean;

Update an existing notification.
If the notification does not exists this won't do anything.
Once updated the notification will be moved at the begin of the notification stack.
Parameter args
Update options
Returns
Whether the update was successful or not.

class RunningSessions

class RunningSessions extends VDomRenderer<RunningSessions.Model> {}

A VDomRenderer for a RunningSessions status item.

constructor

constructor(opts: RunningSessions.IOptions);

Create a new RunningSessions widget.

property translator

protected translator: ITranslator;

method dispose

dispose: () => void;

Dispose of the status item.

method render

render: () => JSX.Element | null;

Render the running sessions widget.

class Sanitizer

class Sanitizer implements IRenderMime.ISanitizer {}

A class to sanitize HTML strings.

constructor

constructor();

property allowCommandLinker

readonly allowCommandLinker: boolean;

Returns
Whether to allow command linker attributes.

property allowNamedProperties

readonly allowNamedProperties: boolean;

Returns
Whether to allow name and id attributes.

method getAutolink

getAutolink: () => boolean;

Returns
Whether to replace URLs by HTML anchors.

method sanitize

sanitize: (dirty: string, options?: IRenderMime.ISanitizerOptions) => string;

Sanitize an HTML string.
Parameter dirty
The dirty text.
Parameter options
The optional sanitization options.
Returns
The sanitized string.

method setAllowCommandLinker

setAllowCommandLinker: (allowCommandLinker: boolean) => void;

Set whether to allow command linker attributes.
Parameter allowCommandLinker
Whether to allow command linker attributes.

method setAllowedSchemes

setAllowedSchemes: (scheme: Array<string>) => void;

Set the allowed schemes
Parameter scheme
Allowed schemes. Automatically regenerates sanitizer options to apply the change. Note: the schemes merge into the current config and does not get overwritten.

method setAllowNamedProperties

setAllowNamedProperties: (allowNamedProperties: boolean) => void;

Set the whether to allow name and id attributes.

method setAutolink

setAutolink: (autolink: boolean) => void;

Set the URL replacement boolean.
Parameter autolink
URL replacement boolean.

class SemanticCommand

class SemanticCommand {}

Semantic group of commands

property DEFAULT_RANK

static readonly DEFAULT_RANK: number;

Default rank for semantic command

property ids

readonly ids: string[];

The command IDs used by this semantic command.

static readonly WIDGET: string;

The args key for a semantic command's current widget ID.

method add

add: (command: ISemanticCommand) => void;

Add a command to the semantic group
Parameter command
Command to add

method getActiveCommandId

getActiveCommandId: (widget: Widget) => string | null;

Get the command id of the enabled command from this group for the given widget.
Parameter widget
Widget
Returns
Command id

method remove

remove: (id: string) => void;

Remove a command ID.
Parameter id
Command ID to remove

class SessionContext

class SessionContext implements ISessionContext {}

The default implementation for a session context object.

constructor

constructor(options: SessionContext.IOptions);

Construct a new session context.

property connectionStatusChanged

readonly connectionStatusChanged: ISignal<this, Kernel.ConnectionStatus>;

A signal emitted when the kernel status changes, proxied from the kernel.

property disposed

readonly disposed: ISignal<this, void>;

A signal emitted when the poll is disposed.

property hasNoKernel

readonly hasNoKernel: boolean;

Whether the kernel is "No Kernel" or not.
#### Notes As the displayed name is translated, this can be used directly.

property iopubMessage

readonly iopubMessage: ISignal<this, KernelMessage.IIOPubMessage>;

A signal emitted for iopub kernel messages, proxied from the kernel.

property isDisposed

readonly isDisposed: boolean;

Test whether the context is disposed.

property isReady

readonly isReady: boolean;

Whether the context is ready.

property isRestarting

readonly isRestarting: boolean;

Whether the context is restarting.

property isTerminating

readonly isTerminating: boolean;

Whether the context is terminating.

property kernelChanged

readonly kernelChanged: ISignal<
    this,
    Session.ISessionConnection.IKernelChangedArgs
>;

A signal emitted when the kernel connection changes, proxied from the session connection.

property kernelDisplayName

readonly kernelDisplayName: string;

The display name of the current kernel, or a sensible alternative.
#### Notes This is a convenience function to have a consistent sensible name for the kernel.

property kernelDisplayStatus

readonly kernelDisplayStatus: any;

A sensible status to display
#### Notes This combines the status and connection status into a single status for the user.

property kernelManager

readonly kernelManager?: Kernel.IManager;

The kernel manager

property kernelPreference

kernelPreference: ISessionContext.IKernelPreference;

The kernel preference of this client session.
This is used when selecting a new kernel, and should reflect the sort of kernel the activity prefers.

property kernelPreferenceChanged

readonly kernelPreferenceChanged: ISignal<
    this,
    IChangedArgs<ISessionContext.IKernelPreference>
>;

Signal emitted if the kernel preference changes.

property name

readonly name: string;

The session name.
#### Notes Typically .session.name should be used. This attribute is useful if there is no current session.

property noKernelName

readonly noKernelName: string;

Get the constant displayed name for "No Kernel"

property path

readonly path: string;

The session path.
#### Notes Typically .session.path should be used. This attribute is useful if there is no current session.

property pendingInput

readonly pendingInput: boolean;

A flag indicating if the session has pending input, proxied from the kernel.

property prevKernelName

readonly prevKernelName: string;

The name of the previously started kernel.

property propertyChanged

readonly propertyChanged: ISignal<this, 'name' | 'path' | 'type'>;

A signal emitted when a session property changes, proxied from the current session.

property ready

readonly ready: Promise<void>;

A promise that is fulfilled when the context is ready.

property session

readonly session: any;

The current session connection.

property sessionChanged

readonly sessionChanged: ISignal<this, IChangedArgs<any, any, 'session'>>;

A signal emitted when the session connection changes.

property sessionManager

readonly sessionManager: Session.IManager;

The session manager used by the session.

property specsManager

readonly specsManager: KernelSpec.IManager;

The kernel spec manager

property statusChanged

readonly statusChanged: ISignal<this, Kernel.Status>;

A signal emitted when the kernel status changes, proxied from the kernel.

property type

readonly type: string;

The session type.
#### Notes Typically .session.type should be used. This attribute is useful if there is no current session.

property unhandledMessage

readonly unhandledMessage: ISignal<this, KernelMessage.IMessage>;

A signal emitted for an unhandled kernel message, proxied from the kernel.

method changeKernel

changeKernel: (
    options?: Kernel.IModel
) => Promise<Kernel.IKernelConnection | null>;

Change the current kernel associated with the session.

method dispose

dispose: () => void;

Dispose of the resources held by the context.

method initialize

initialize: () => Promise<boolean>;

Initialize the session context
Returns
A promise that resolves with whether to ask the user to select a kernel.
#### Notes If a server session exists on the current path, we will connect to it unless kernelPreference.shouldReuse === false. If preferences include disabling canStart or shouldStart, no server session will be started. If a kernel id is given, we attempt to start a session with that id. If a default kernel is available, we connect to it. Otherwise we ask the user to select a kernel.

method restartKernel

restartKernel: () => Promise<void>;

Restart the current Kernel.
Returns
A promise that resolves when the kernel is restarted.

method shutdown

shutdown: () => Promise<void>;

Kill the kernel and shutdown the session.
Returns
A promise that resolves when the session is shut down.

method startKernel

startKernel: () => Promise<boolean>;

Starts new Kernel.
Returns
Whether to ask the user to pick a kernel.

class SessionContextDialogs

class SessionContextDialogs implements ISessionContext.IDialogs {}

The default implementation of the client session dialog provider.

constructor

constructor(options?: ISessionContext.IDialogsOptions);

method restart

restart: (
    sessionContext: ISessionContext,
    restartOptions?: ISessionContext.IRestartOptions
) => Promise<boolean>;

Restart the session.
Returns
A promise that resolves with whether the kernel has restarted.
#### Notes If there is a running kernel, present a dialog. If there is no kernel, we start a kernel with the last run kernel name and resolves with true.

method selectKernel

selectKernel: (sessionContext: ISessionContext) => Promise<void>;

Select a kernel for the session.

class ThemeManager

class ThemeManager implements IThemeManager {}

A class that provides theme management.

constructor

constructor(options: ThemeManager.IOptions);

Construct a new theme manager.

property darkThemes

readonly darkThemes: readonly string[];

Get the names of the dark themes.

property lightThemes

readonly lightThemes: readonly string[];

Get the names of the light themes.

property preferredDarkTheme

readonly preferredDarkTheme: string;

Get the name of the preferred dark theme.

property preferredLightTheme

readonly preferredLightTheme: string;

Get the name of the preferred light theme.

property preferredTheme

readonly preferredTheme: string;

Get the name of the preferred theme When adaptive-theme is disabled, get current theme; Else, depending on the system settings, get preferred light or dark theme.

property theme

readonly theme: string;

Get the name of the current theme.

property themeChanged

readonly themeChanged: ISignal<this, IChangedArgs<string, string>>;

A signal fired when the application theme changes.

property themes

readonly themes: readonly string[];

The names of the registered themes.

property translator

protected translator: ITranslator;

method decrFontSize

decrFontSize: (key: string) => Promise<void>;

Decrease a font size w.r.t. its current setting or its value in the current theme.
Parameter key
A Jupyterlab font size CSS variable, without the leading '--jp-'.

method getCSS

getCSS: (key: string) => string;

Get the value of a CSS variable from its key.
Parameter key
A Jupyterlab CSS variable, without the leading '--jp-'.
Returns
value - The current value of the Jupyterlab CSS variable

method getDisplayName

getDisplayName: (name: string) => string;

Get the display name of the theme.

method incrFontSize

incrFontSize: (key: string) => Promise<void>;

Increase a font size w.r.t. its current setting or its value in the current theme.
Parameter key
A Jupyterlab font size CSS variable, without the leading '--jp-'.

method isLight

isLight: (name: string) => boolean;

Test whether a given theme is light.

method isSystemColorSchemeDark

isSystemColorSchemeDark: () => boolean;

Test if the system's preferred color scheme is dark

method isToggledAdaptiveTheme

isToggledAdaptiveTheme: () => boolean;

Test if the user enables adaptive theme.

method isToggledThemeScrollbars

isToggledThemeScrollbars: () => boolean;

Test if the user has scrollbar styling enabled.

method loadCSS

loadCSS: (path: string) => Promise<void>;

Load a theme CSS file by path.
Parameter path
The path of the file to load.

method loadCSSOverrides

loadCSSOverrides: () => void;

Loads all current CSS overrides from settings. If an override has been removed or is invalid, this function unloads it instead.

method register

register: (theme: IThemeManager.ITheme) => IDisposable;

Register a theme with the theme manager.
Parameter theme
The theme to register.
Returns
A disposable that can be used to unregister the theme.

method setCSSOverride

setCSSOverride: (key: string, value: string) => Promise<void>;

Add a CSS override to the settings.

method setPreferredDarkTheme

setPreferredDarkTheme: (name: string) => Promise<void>;

Set the preferred dark theme.

method setPreferredLightTheme

setPreferredLightTheme: (name: string) => Promise<void>;

Set the preferred light theme.

method setTheme

setTheme: (name: string) => Promise<void>;

Set the current theme.

method themeScrollbars

themeScrollbars: (name: string) => boolean;

Test whether a given theme styles scrollbars, and if the user has scrollbar styling enabled.

method toggleAdaptiveTheme

toggleAdaptiveTheme: () => Promise<void>;

Toggle the adaptive-theme setting.

method toggleThemeScrollbars

toggleThemeScrollbars: () => Promise<void>;

Toggle the theme-scrollbars setting.

method validateCSS

validateCSS: (key: string, val: string) => boolean;

Validate a CSS value w.r.t. a key
Parameter key
A Jupyterlab CSS variable, without the leading '--jp-'.
Parameter val
A candidate CSS value

class Toolbar<T extends Widget = Widget> extends UIToolbar<T> {}

Deprecated
since v4 This class is in @jupyterlab/ui-components

class ToolbarWidgetRegistry

class ToolbarWidgetRegistry implements IToolbarWidgetRegistry {}

Concrete implementation of IToolbarWidgetRegistry interface

constructor

constructor(options: ToolbarRegistry.IOptions);

property defaultFactory

defaultFactory: (
    widgetFactory: string,
    widget: Widget,
    toolbarItem: ToolbarRegistry.IWidget
) => Widget;

Default toolbar item factory

property factoryAdded

readonly factoryAdded: ISignal<this, string>;

A signal emitted when a factory widget has been added.

method addFactory

addFactory: <T extends Widget = Widget>(
    widgetFactory: string,
    toolbarItemName: string,
    factory: (main: T) => Widget
) => (main: T) => Widget;

Add a new toolbar item factory
Parameter widgetFactory
The widget factory name that creates the toolbar
Parameter toolbarItemName
The unique toolbar item
Parameter factory
The factory function that receives the widget containing the toolbar and returns the toolbar widget.
Returns
The previously defined factory

method createWidget

createWidget: (
    widgetFactory: string,
    widget: Widget,
    toolbarItem: ToolbarRegistry.IWidget
) => Widget;

Create a toolbar item widget
Parameter widgetFactory
The widget factory name that creates the toolbar
Parameter widget
The newly widget containing the toolbar
Parameter toolbarItem
The toolbar item definition
Returns
The widget to be inserted in the toolbar.

method registerFactory

registerFactory: <T extends Widget = Widget>(
    widgetFactory: string,
    toolbarItemName: string,
    factory: (main: T) => Widget
) => (main: T) => Widget;

Register a new toolbar item factory
Parameter widgetFactory
The widget factory name that creates the toolbar
Parameter toolbarItemName
The unique toolbar item
Parameter factory
The factory function that receives the widget containing the toolbar and returns the toolbar widget.
Returns
The previously defined factory
Deprecated
since v4 use addFactory instead

class WidgetTracker

class WidgetTracker<T extends Widget = Widget>
    implements IWidgetTracker<T>, IRestorable<T> {}

A class that keeps track of widget instances on an Application shell.

constructor

constructor(options: WidgetTracker.IOptions);

Create a new widget tracker.
Parameter options
The instantiation options for a widget tracker.

property currentChanged

readonly currentChanged: ISignal<this, T>;

A signal emitted when the current widget changes.

property currentWidget

readonly currentWidget: Widget;

The current widget is the most recently focused or added widget.
#### Notes It is the most recently focused widget, or the most recently added widget if no widget has taken focus.

property isDisposed

readonly isDisposed: boolean;

Test whether the tracker is disposed.

property namespace

readonly namespace: string;

A namespace for all tracked widgets, (e.g., notebook).

property restored

readonly restored: Promise<void>;

A promise resolved when the tracker has been restored.

property size

readonly size: number;

The number of widgets held by the tracker.

property widgetAdded

readonly widgetAdded: ISignal<this, T>;

A signal emitted when a widget is added.
#### Notes This signal will only fire when a widget is added to the tracker. It will not fire if a widget is injected into the tracker.

property widgetUpdated

readonly widgetUpdated: ISignal<this, T>;

A signal emitted when a widget is updated.

method add

add: (widget: T) => Promise<void>;

Add a new widget to the tracker.
Parameter widget
The widget being added.
#### Notes The widget passed into the tracker is added synchronously; its existence in the tracker can be checked with the has() method. The promise this method returns resolves after the widget has been added and saved to an underlying restoration connector, if one is available.
The newly added widget becomes the current widget unless the focus tracker already had a focused widget.

method defer

defer: (options: IRestorable.IOptions<T>) => void;

Save the restore options for this tracker, but do not restore yet.
Parameter options
The configuration options that describe restoration.
### Notes This function is useful when starting the shell in 'single-document' mode, to avoid restoring all useless widgets. It should not ordinarily be called by client code.

method dispose

dispose: () => void;

Dispose of the resources held by the tracker.

method filter

filter: (fn: (widget: T) => boolean) => T[];

Filter the widgets in the tracker based on a predicate.
Parameter fn
The function by which to filter.

method find

find: (fn: (widget: T) => boolean) => T | undefined;

Find the first widget in the tracker that satisfies a filter function.
Parameter fn
The filter function to call on each widget.
#### Notes If no widget is found, the value returned is undefined.

method forEach

forEach: (fn: (widget: T) => void) => void;

Iterate through each widget in the tracker.
Parameter fn
The function to call on each widget.

method has

has: (widget: Widget) => boolean;

Check if this tracker has the specified widget.
Parameter widget
The widget whose existence is being checked.

method inject

inject: (widget: T) => Promise<void>;

Inject a foreign widget into the widget tracker.
Parameter widget
The widget to inject into the tracker.
#### Notes Injected widgets will not have their state saved by the tracker.
The primary use case for widget injection is for a plugin that offers a sub-class of an extant plugin to have its instances share the same commands as the parent plugin (since most relevant commands will use the currentWidget of the parent plugin's widget tracker). In this situation, the sub-class plugin may well have its own widget tracker for layout and state restoration in addition to injecting its widgets into the parent plugin's widget tracker.

method onCurrentChanged

protected onCurrentChanged: (value: T | null) => void;

Handle the current change event.
#### Notes The default implementation is a no-op.

method restore

restore: (options?: IRestorable.IOptions<T>) => Promise<any>;

Restore the widgets in this tracker's namespace.
Parameter options
The configuration options that describe restoration.
Returns
A promise that resolves when restoration has completed.
#### Notes This function should not typically be invoked by client code. Its primary use case is to be invoked by a restorer.

method save

save: (widget: T) => Promise<void>;

Save the restore data for a given widget.
Parameter widget
The widget being saved.

class WindowResolver

class WindowResolver implements IWindowResolver {}

A concrete implementation of a window name resolver.

property name

readonly name: string;

The resolved window name.
#### Notes If the resolve promise has not resolved, the behavior is undefined.

method resolve

resolve: (candidate: string) => Promise<void>;

Resolve a window name to use as a handle among shared resources.
Parameter candidate
The potential window name being resolved.
#### Notes Typically, the name candidate should be a JupyterLab workspace name or an empty string if there is no workspace.
If the returned promise rejects, a window name cannot be resolved without user intervention, which typically means navigation to a new URL.

Interfaces

interface ICommandPalette

interface ICommandPalette {}

The interface for a Jupyter Lab command palette.

property placeholder

placeholder: string;

The placeholder text of the command palette's search input.

method activate

activate: () => void;

Activate the command palette for user input.

method addItem

addItem: (options: IPaletteItem) => IDisposable;

Add a command item to the command palette.
Parameter options
The options for creating the command item.
Returns
A disposable that will remove the item from the palette.

interface IKernelStatusModel

interface IKernelStatusModel {}

Kernel status indicator model.

property addSessionProvider

addSessionProvider: (
    provider: (widget: Widget | null) => ISessionContext | null
) => void;

Add a session context provider.
A provider will receive the currently active widget and must return the associated session context if it can or null otherwise.

interface ILicensesClient

interface ILicensesClient {}

An interface for the license client.

method download

download: (options: Licenses.IDownloadOptions) => Promise<void>;

Download the licenses in the requested format.

method getBundles

getBundles: () => Promise<Licenses.ILicenseResponse>;

Fetch the license bundles from the server.

interface IMovableSectionDestination

interface IMovableSectionDestination {}

Implemented by panels that can host sections moved in from another sidebar.
Register an implementation with IMovableSectionRegistry.registerTarget.

property accordionPanel

readonly accordionPanel: AccordionPanel | null;

The AccordionPanel that wraps the hosted sections, or null if none has been created yet.
The move plugin reads this to set up drag-to-reorder handles and to access the title elements of hosted sections.

property sections

readonly sections: ReadonlyArray<Widget>;

All section widgets currently hosted by this panel.
Queried by the move plugin during state restoration to find sections that were persisted as belonging to this panel. Must stay in sync with addSection and removeSectionWidget calls.

method addSection

addSection: (widget: Widget) => void;

Insert a section widget into this panel.
Called by the move plugin when the user selects "Move to …" from the context menu. A typical implementation calls this.addWidget(widget).
Parameter widget
The widget detached from its source panel.

method removeSectionWidget

removeSectionWidget: (widget: Widget) => void;

Remove a section widget that was previously added via addSection.
Called by the move plugin when the user moves the section back to its original panel. A typical implementation sets widget.parent = null.
Parameter widget
The widget to detach.

interface IMovableSectionRegistry

interface IMovableSectionRegistry {}

Registry that pairs source and target panels so the move plugin can wire up context-menu "Move to …" actions between them.

property sourcePanelRegistered

readonly sourcePanelRegistered: ISignal<
    IMovableSectionRegistry,
    {
        id: string;
        label: string;
        sidebar: IMovableSectionSource;
    }
>;

Fired each time a new source sidebar is registered via registerSource.
The move plugin listens to this signal to retroactively wire up context menus for sources that register after the plugin has already activated.

property targetPanelRegistered

readonly targetPanelRegistered: ISignal<
    IMovableSectionRegistry,
    {
        id: string;
        label: string;
        panel: IMovableSectionDestination;
    }
>;

Fired each time a new target panel is registered via registerTarget.
The move plugin listens to this signal to add the new target as an option in the context menus of all currently-registered source panels.

method getSources

getSources: () => ReadonlyMap<
    string,
    { label: string; sidebar: IMovableSectionSource }
>;

Return all registered source sidebars keyed by their id.

method getTargets

getTargets: () => ReadonlyMap<
    string,
    { label: string; panel: IMovableSectionDestination }
>;

Return all registered target panels keyed by their id.

method registerSource

registerSource: (
    id: string,
    label: string,
    sidebar: IMovableSectionSource
) => void;

Register a sidebar as a source of moveable sections.
After registration the move plugin adds a "Move to " context-menu item to each section header in sidebar. The label appears in the menu as "Move back to " on the destination side.
Parameter id
Stable plugin-scoped identifier, e.g. '@my-org/my-ext:panel'. Must be unique across all registered sources.
Parameter label
Human-readable panel name shown in the context menu.
Parameter sidebar
The panel implementing IMovableSectionSource.

method registerTarget

registerTarget: (
    id: string,
    label: string,
    panel: IMovableSectionDestination
) => void;

Register a panel as a destination that can receive sections.
After registration the move plugin adds a "Move to " context-menu item to eligible section headers in all registered source panels.
Parameter id
Stable plugin-scoped identifier. Must be unique across all registered targets.
Parameter label
Human-readable panel name shown in the context menu.
Parameter panel
The panel implementing IMovableSectionDestination.

interface IMovableSectionSource

interface IMovableSectionSource {}

Implemented by sidebar panels whose accordion sections can be moved to another panel by the user.
Register an implementation with IMovableSectionRegistry.registerSource.

property accordionPanel

readonly accordionPanel: AccordionPanel | null;

The AccordionPanel that renders this sidebar's sections.
The move plugin reads this to set up drag-to-reorder handles after a section is moved.

property sectionAdded

readonly sectionAdded: ISignal<this, ISectionEntry>;

Emitted each time a new section widget is added to this panel.
Implementations should emit this signal from addWidget (or equivalent) with a fully-populated ISectionEntry for the newly added widget.

method getSections

getSections: () => ReadonlyArray<ISectionEntry>;

Return the currently-available sections with their title DOM nodes.

method reinsertSection

reinsertSection: (widget: Widget) => void;

Re-attach a widget that was previously removed by removeSectionById.
Called when the user chooses "Move back to …" on a section that was originally owned by this panel. A typical implementation calls this.addWidget(widget).
Parameter widget
The widget returned by an earlier removeSectionById call.

method removeSectionById

removeSectionById: (sectionId: string) => Widget | null;

Detach the section identified by sectionId and return its widget so the move plugin can hand it to a target panel.
A typical implementation sets widget.parent = null, which detaches the widget from the AccordionPanel without destroying it. Returns null if no section with the given id currently exists in this panel.
Parameter sectionId
The ISectionEntry.id of the section to remove.

interface IPaletteItem

interface IPaletteItem extends CommandPalette.IItemOptions {}

The options for creating a command palette item.

interface ISectionEntry

interface ISectionEntry {}

A section entry returned by IMovableSectionSource.getSections.
Bundles the three pieces of information the move plugin needs to identify, display, and transfer a sidebar section.

property id

readonly id: string;

Stable identifier for this section, equal to the widget's Lumino id.
The move plugin uses this to persist which sections have been moved and to restore them to the correct panel on reload.

property titleNode

readonly titleNode: HTMLElement;

The .jp-AccordionPanel-title DOM element rendered by Lumino as the visual header of this section.
The move plugin attaches the jp-movable-section CSS class to this node so that Lumino's context-menu selector fires when the user right-clicks the header.

readonly widget: Widget;

The content widget for this section.

interface ISessionContext

interface ISessionContext extends IObservableDisposable {}

A context object to manage a widget's kernel session connection.
#### Notes The current session connection is .session, the current session's kernel connection is .session.kernel. For convenience, we proxy several kernel connection and session connection signals up to the session context so that you do not have to manage slots as sessions and kernels change. For example, to act on whatever the current kernel's iopubMessage signal is producing, connect to the session context .iopubMessage signal.

property connectionStatusChanged

readonly connectionStatusChanged: ISignal<this, Kernel.ConnectionStatus>;

A signal emitted when the kernel connection status changes, proxied from the session connection.

property hasNoKernel

readonly hasNoKernel: boolean;

Whether the kernel is "No Kernel" or not.
#### Notes As the displayed name is translated, this can be used directly.

property iopubMessage

readonly iopubMessage: ISignal<this, KernelMessage.IMessage>;

A signal emitted for a kernel messages, proxied from the session connection.

property isReady

readonly isReady: boolean;

Whether the session context is ready.

property isRestarting

readonly isRestarting: boolean;

Whether the session context is restarting.

property isTerminating

readonly isTerminating: boolean;

Whether the session context is terminating.

property kernelChanged

readonly kernelChanged: ISignal<
    this,
    IChangedArgs<
        Kernel.IKernelConnection | null,
        Kernel.IKernelConnection | null,
        'kernel'
    >
>;

A signal emitted when the kernel changes, proxied from the session connection.

property kernelDisplayName

readonly kernelDisplayName: string;

The sensible display name for the kernel, or translated "No Kernel"
#### Notes This is at this level since the underlying kernel connection does not have access to the kernel spec manager.

property kernelDisplayStatus

readonly kernelDisplayStatus: ISessionContext.KernelDisplayStatus;

A sensible status to display
#### Notes This combines the status and connection status into a single status for the user.

property kernelManager

readonly kernelManager?: Kernel.IManager;

The kernel manager
#### Notes In the next major version of this interface, a kernel manager is required.

property kernelPreference

kernelPreference: ISessionContext.IKernelPreference;

The kernel preference for starting new kernels.

property kernelPreferenceChanged

readonly kernelPreferenceChanged: ISignal<
    this,
    IChangedArgs<ISessionContext.IKernelPreference>
>;

Signal emitted if the kernel preference changes.

property name

readonly name: string;

The session name.
#### Notes Typically .session.name should be used. This attribute is useful if there is no current session.

property path

readonly path: string;

The session path.
#### Notes Typically .session.path should be used. This attribute is useful if there is no current session.

property pendingInput

readonly pendingInput: boolean;

A flag indicating if session is has pending input, proxied from the session connection.

property prevKernelName

readonly prevKernelName: string;

The previous kernel name.

property propertyChanged

readonly propertyChanged: ISignal<this, 'path' | 'name' | 'type'>;

A signal emitted when a session property changes, proxied from the session connection.

property ready

readonly ready: Promise<void>;

A promise that is fulfilled when the session context is ready.

property session

session: Session.ISessionConnection | null;

The current session connection.

property sessionChanged

readonly sessionChanged: ISignal<
    this,
    IChangedArgs<
        Session.ISessionConnection | null,
        Session.ISessionConnection | null,
        'session'
    >
>;

A signal emitted when the session connection changes.

property sessionManager

readonly sessionManager: Session.IManager;

The session manager used by the session.

property specsManager

readonly specsManager: KernelSpec.IManager;

The kernel spec manager

property statusChanged

readonly statusChanged: ISignal<this, Kernel.Status>;

A signal emitted when the kernel status changes, proxied from the session connection.

property type

readonly type: string;

The session type.
#### Notes Typically .session.type should be used. This attribute is useful if there is no current session.

property unhandledMessage

readonly unhandledMessage: ISignal<this, KernelMessage.IMessage>;

A signal emitted for an unhandled kernel message, proxied from the session connection.

method changeKernel

changeKernel: (
    options?: Kernel.IModel
) => Promise<Kernel.IKernelConnection | null>;

Change the kernel associated with the session.
Parameter options
The optional kernel model parameters to use for the new kernel.
Returns
A promise that resolves with the new kernel connection.

method initialize

initialize: () => Promise<boolean>;

Initialize the session context.
Returns
A promise that resolves with whether to ask the user to select a kernel.
#### Notes This includes starting up an initial kernel if needed.

method restartKernel

restartKernel: () => Promise<void>;

Restart the current Kernel.
Returns
A promise that resolves when the kernel is restarted.

method shutdown

shutdown: () => Promise<void>;

Kill the kernel and shutdown the session.
Returns
A promise that resolves when the session is shut down.

method startKernel

startKernel: () => Promise<boolean>;

Starts new Kernel.
Returns
Whether to ask the user to pick a kernel.

interface ISessionContextDialogs

interface ISessionContextDialogs extends ISessionContext.IDialogs {}

An interface for the session context dialogs.

interface ISplashScreen

interface ISplashScreen {}

The interface for an application splash screen.

method show

show: (light?: boolean) => IDisposable;

Show the application splash screen.
Parameter light
Whether to show the light splash screen or the dark one.
Returns
A disposable used to clear the splash screen.

interface IThemeManager

interface IThemeManager {}

An interface for a theme manager.

property darkThemes

readonly darkThemes?: ReadonlyArray<string> | undefined;

Get the names of the registered dark themes.

property lightThemes

readonly lightThemes?: ReadonlyArray<string> | undefined;

Get the names of the registered light themes.

property preferredDarkTheme

readonly preferredDarkTheme?: string | undefined;

Get the name of the preferred dark theme.

property preferredLightTheme

readonly preferredLightTheme?: string | undefined;

Get the name of the preferred light theme.

property preferredTheme

readonly preferredTheme?: string | null | undefined;

Get the name of the preferred theme.

property theme

readonly theme: string | null;

Get the name of the current theme.

property themeChanged

readonly themeChanged: ISignal<this, IChangedArgs<string, string | null>>;

A signal fired when the application theme changes.

property themes

readonly themes: ReadonlyArray<string>;

The names of the registered themes.

method getDisplayName

getDisplayName: (name: string) => string;

Get display name for theme.

method isLight

isLight: (name: string) => boolean;

Test whether a given theme is light.

method loadCSS

loadCSS: (path: string) => Promise<void>;

Load a theme CSS file by path.
Parameter path
The path of the file to load.

method register

register: (theme: IThemeManager.ITheme) => IDisposable;

Register a theme with the theme manager.
Parameter theme
The theme to register.
Returns
A disposable that can be used to unregister the theme.

method setTheme

setTheme: (name: string) => Promise<void>;

Set the current theme.

method themeScrollbars

themeScrollbars: (name: string) => boolean;

Test whether a given theme styles scrollbars, and if the user has scrollbar styling enabled.

interface IToolbarWidgetRegistry

interface IToolbarWidgetRegistry {}

Toolbar widget registry interface

property defaultFactory

defaultFactory: (
    widgetFactory: string,
    widget: Widget,
    toolbarItem: ToolbarRegistry.IWidget
) => Widget;

Default toolbar item factory

property factoryAdded

readonly factoryAdded: ISignal<this, string>;

A signal emitted when a factory widget has been added.

method addFactory

addFactory: <T extends Widget = Widget>(
    widgetFactory: string,
    toolbarItemName: string,
    factory: (main: T) => Widget
) => (main: T) => Widget;

Add a new toolbar item factory
Parameter widgetFactory
The widget factory name that creates the toolbar
Parameter toolbarItemName
The unique toolbar item
Parameter factory
The factory function that receives the widget containing the toolbar and returns the toolbar widget.
Returns
The previously defined factory

method createWidget

createWidget: (
    widgetFactory: string,
    widget: Widget,
    toolbarItem: ToolbarRegistry.IWidget
) => Widget;

Create a toolbar item widget
Parameter widgetFactory
The widget factory name that creates the toolbar
Parameter widget
The newly widget containing the toolbar
Parameter toolbarItem
The toolbar item definition
Returns
The widget to be inserted in the toolbar.

method registerFactory

registerFactory: <T extends Widget = Widget>(
    widgetFactory: string,
    toolbarItemName: string,
    factory: (main: T) => Widget
) => (main: T) => Widget;

Register a new toolbar item factory
Parameter widgetFactory
The widget factory name that creates the toolbar
Parameter toolbarItemName
The unique toolbar item
Parameter factory
The factory function that receives the widget containing the toolbar and returns the toolbar widget.
Returns
The previously defined factory
Deprecated
since v4 use addFactory instead

interface IWidgetTracker

interface IWidgetTracker<T extends Widget = Widget> extends IDisposable {}

A tracker that tracks widgets.

property currentChanged

readonly currentChanged: ISignal<this, T | null>;

A signal emitted when the current instance changes.
#### Notes If the last instance being tracked is disposed, null will be emitted.

property currentWidget

readonly currentWidget: T | null;

The current widget is the most recently focused or added widget.
#### Notes It is the most recently focused widget, or the most recently added widget if no widget has taken focus.

property restored

readonly restored: Promise<void>;

A promise that is resolved when the widget tracker has been restored from a serialized state.
#### Notes Most client code will not need to use this, since they can wait for the whole application to restore. However, if an extension wants to perform actions during the application restoration, but after the restoration of another widget tracker, they can use this promise.

property size

readonly size: number;

The number of instances held by the tracker.

property widgetAdded

readonly widgetAdded: ISignal<this, T>;

A signal emitted when a widget is added.

property widgetUpdated

readonly widgetUpdated: ISignal<this, T>;

A signal emitted when a widget is updated.

method filter

filter: (fn: (obj: T) => boolean) => T[];

Filter the instances in the tracker based on a predicate.
Parameter fn
The function by which to filter.

method find

find: (fn: (obj: T) => boolean) => T | undefined;

Find the first instance in the tracker that satisfies a filter function.
Parameter fn
The filter function to call on each instance.
#### Notes If nothing is found, the value returned is undefined.

method forEach

forEach: (fn: (obj: T) => void) => void;

Iterate through each instance in the tracker.
Parameter fn
The function to call on each instance.

method has

has: (obj: Widget) => boolean;

Check if this tracker has the specified instance.
Parameter obj
The object whose existence is being checked.

method inject

inject: (obj: T) => void;

Inject an instance into the widget tracker without the tracker handling its restoration lifecycle.
Parameter obj
The instance to inject into the tracker.

interface IWindowResolver

interface IWindowResolver {}

The description of a window name resolver.

property name

readonly name: string;

A window name to use as a handle among shared resources.

Type Aliases

type ClipboardData

type ClipboardData = string | MimeData;

type ISanitizer

type ISanitizer = IRenderMime.ISanitizer;

Deprecated
since v4 use IRenderMime.ISanitizer

Namespaces

namespace Clipboard

namespace Clipboard {}

The clipboard interface.

function copyToSystem

copyToSystem: (clipboardData: ClipboardData) => void;

Copy text to the system clipboard.
#### Notes This can only be called in response to a user input event.

function generateEvent

generateEvent: (node: HTMLElement, type?: 'copy' | 'cut') => void;

Generate a clipboard event on a node.
Parameter node
The element on which to generate the event.
Parameter type
The type of event to generate. 'paste' events cannot be programmatically generated.
#### Notes This can only be called in response to a user input event.

function getInstance

getInstance: () => MimeData;

Get the application clipboard instance.

function setInstance

setInstance: (value: MimeData) => void;

Set the application clipboard instance.
Deprecated
will be removed in a future release. Use SystemClipboard.getInstance.

function showPasteUnavailableDialog

showPasteUnavailableDialog: (trans: TranslationBundle) => void;

namespace CommandLinker

namespace CommandLinker {}

A namespace for command linker statics.

interface IOptions

interface IOptions {}

The instantiation options for a command linker.

property commands

commands: CommandRegistry;

The command registry instance that all linked commands will use.

namespace Dialog

namespace Dialog {}

The namespace for Dialog class statics.

variable defaultRenderer

const defaultRenderer: Renderer;

The default renderer instance.

variable tracker

const tracker: WidgetTracker<Dialog<any>>;

The dialog widget tracker.

variable translator

let translator: ITranslator;

Translator object.

function cancelButton

cancelButton: (options?: Partial<IButton>) => Readonly<IButton>;

Create a reject button.

function createButton

createButton: (value: Partial<IButton>) => Readonly<IButton>;

Create a button item.

function flush

flush: () => void;

Disposes all dialog instances.
#### Notes This function should only be used in tests or cases where application state may be discarded.

function okButton

okButton: (options?: Partial<IButton>) => Readonly<IButton>;

Create an accept button.

function warnButton

warnButton: (options?: Partial<IButton>) => Readonly<IButton>;

Create a warn button.

class Renderer

class Renderer {}

The default implementation of a dialog renderer.

method createBody

createBody: (value: Body<any>) => Widget;

Create the body of the dialog.
Parameter value
The input value for the body.
Returns
A widget for the body.

method createButtonNode

createButtonNode: (button: IButton) => HTMLButtonElement;

Create a button node for the dialog.
Parameter button
The button data.
Returns
A node for the button.

method createCheckboxNode

createCheckboxNode: (checkbox: ICheckbox) => HTMLElement;

Create a checkbox node for the dialog.
Parameter checkbox
The checkbox data.
Returns
A node for the checkbox.

method createFooter

createFooter: (
    buttons: ReadonlyArray<HTMLElement>,
    checkbox: HTMLElement | null
) => Widget;

Create the footer of the dialog.
Parameter buttons
The buttons nodes to add to the footer.
Parameter checkbox
The checkbox node to add to the footer.
Returns
A widget for the footer.

method createHeader

createHeader: <T>(
    title: Header,
    reject?: () => void,
    options?: Partial<Dialog.IOptions<T>>
) => Widget;

Create the header of the dialog.
Parameter title
The title of the dialog.
Returns
A widget for the dialog header.

method createIconClass

createIconClass: (data: IButton) => string;

Create the class name for the button icon.
Parameter data
The data to use for the class name.
Returns
The full class name for the item icon.

method createItemClass

createItemClass: (data: IButton) => string;

Create the class name for the button.
Parameter data
The data to use for the class name.
Returns
The full class name for the button.

method renderIcon

renderIcon: (data: IButton) => HTMLElement;

Render an icon element for a dialog item.
Parameter data
The data to use for rendering the icon.
Returns
An HTML element representing the icon.

method renderLabel

renderLabel: (data: IButton) => HTMLElement;

Render the label element for a button.
Parameter data
The data to use for rendering the label.
Returns
An HTML element representing the item label.

interface IBodyWidget

interface IBodyWidget<T = string> extends Widget {}

A widget used as a dialog body.

method getValue

getValue: () => T;

Get the serialized value of the widget.

interface IButton

interface IButton {}

The options used to make a button item.

property accept

accept: boolean;

The dialog action to perform when the button is clicked.

property actions

actions: Array<string>;

The additional dialog actions to perform when the button is clicked.

property ariaLabel

ariaLabel: string;

The aria label for the button.

property caption

caption: string;

The caption for the button.

property className

className: string;

The extra class name for the button.

property displayType

displayType: 'default' | 'warn';

The button display type.

property iconClass

iconClass: string;

The icon class for the button.

property iconLabel

iconLabel: string;

The icon label for the button.

property label

label: string;

The label for the button.

interface ICheckbox

interface ICheckbox {}

The options used to make a checkbox item.

property caption

caption: string;

The caption for the checkbox.

property checked

checked: boolean;

The initial checkbox state.

property className

className: string;

The extra class name for the checkbox.

property label

label: string;

The label for the checkbox.

interface IError

interface IError {}

Error object interface

property message

message: string | React.ReactElement<any>;

Error message

interface IOptions

interface IOptions<T> {}

The options used to create a dialog.

property body

body: Body<T>;

The main body element for the dialog or a message to display. Defaults to an empty string.
#### Notes If a widget is given as the body, it will be disposed after the dialog is resolved. If the widget has a getValue() method, the method will be called prior to disposal and the value will be provided as part of the dialog result. A string argument will be used as raw textContent. All input and select nodes will be wrapped and styled.

property buttons

buttons: ReadonlyArray<IButton>;

The buttons to display. Defaults to cancel and accept buttons.

property checkbox

checkbox: Partial<ICheckbox> | null;

The checkbox to display in the footer. Defaults no checkbox.

property defaultButton

defaultButton: number;

The index of the default button. Defaults to the last button.

property focusNodeSelector

focusNodeSelector: string;

A selector for the primary element that should take focus in the dialog. Defaults to an empty string, causing the [[defaultButton]] to take focus.

property hasClose

hasClose: boolean;

When "false", disallows user from dismissing the dialog by clicking outside it or pressing escape. Defaults to "true", which renders a close button.

property host

host: HTMLElement;

The host element for the dialog. Defaults to document.body.

property renderer

renderer: IRenderer;

An optional renderer for dialog items. Defaults to a shared default renderer.

property title

title: Header;

The top level text for the dialog. Defaults to an empty string.

interface IRenderer

interface IRenderer {}

A dialog renderer.

method createBody

createBody: (body: Body<any>) => Widget;

Create the body of the dialog.
Parameter body
The input value for the body.
Returns
A widget for the body.

method createButtonNode

createButtonNode: (button: IButton) => HTMLButtonElement;

Create a button node for the dialog.
Parameter button
The button data.
Returns
A node for the button.

method createCheckboxNode

createCheckboxNode: (checkbox: ICheckbox) => HTMLElement;

Create a checkbox node for the dialog.
Parameter checkbox
The checkbox data.
Returns
A node for the checkbox.

method createFooter

createFooter: (
    buttons: ReadonlyArray<HTMLElement>,
    checkbox: HTMLElement | null
) => Widget;

Create the footer of the dialog.
Parameter buttons
The button nodes to add to the footer.
Parameter checkbox
The checkbox node to add to the footer.
Returns
A widget for the footer.

method createHeader

createHeader: <T>(
    title: Header,
    reject: () => void,
    options: Partial<Dialog.IOptions<T>>
) => Widget;

Create the header of the dialog.
Parameter title
The title of the dialog.
Returns
A widget for the dialog header.

interface IResult

interface IResult<T> {}

The result of a dialog.

property button

button: IButton;

The button that was pressed.

property isChecked

isChecked: boolean | null;

State of the dialog checkbox.
#### Notes It will be null if no checkbox is defined for the dialog.

property value

value: T | null;

The value retrieved from .getValue() if given on the widget.

type Body

type Body<T> = IBodyWidget<T> | React.ReactElement<any> | string;

The body input types.

type Header = React.ReactElement<any> | string;

The header input types.

namespace DOMUtils

namespace DOMUtils {}

The namespace for DOM utilities.

function createDomID

createDomID: () => string;

Create a DOM id with prefix "id-" to solve bug for UUIDs beginning with numbers.

function findElement

findElement: (parent: HTMLElement, className: string) => HTMLElement;

Find the first element matching a class name. Only use this function when the element existence is guaranteed.

function findElements

findElements: (
    parent: HTMLElement,
    className: string
) => HTMLCollectionOf<HTMLElement>;

Find the first element matching a class name.

function hasActiveEditableElement

hasActiveEditableElement: (
    parent: Node | DocumentFragment,
    root?: ShadowRoot | Document
) => boolean;

Check whether the active element descendant from given parent is editable. When checking active elements it includes elements in the open shadow DOM.

function hitTestNodes

hitTestNodes: (
    nodes: HTMLElement[] | HTMLCollection,
    x: number,
    y: number
) => number;

Get the index of the node at a client position, or -1.

namespace InputDialog

namespace InputDialog {}

Namespace for input dialogs

function getBoolean

getBoolean: (options: IBooleanOptions) => Promise<Dialog.IResult<boolean>>;

Create and show a input dialog for a boolean.
Parameter options
The dialog setup options.
Returns
A promise that resolves with whether the dialog was accepted

function getItem

getItem: (options: IItemOptions) => Promise<Dialog.IResult<string>>;

Create and show a input dialog for a choice.
Parameter options
The dialog setup options.
Returns
A promise that resolves with whether the dialog was accepted

function getMultipleItems

getMultipleItems: (
    options: IMultipleItemsOptions
) => Promise<Dialog.IResult<string[]>>;

Create and show a input dialog for a choice.
Parameter options
The dialog setup options.
Returns
A promise that resolves with whether the dialog was accepted

function getNumber

getNumber: (options: INumberOptions) => Promise<Dialog.IResult<number>>;

Create and show a input dialog for a number.
Parameter options
The dialog setup options.
Returns
A promise that resolves with whether the dialog was accepted

function getPassword

getPassword: (
    options: Omit<ITextOptions, 'selectionRange'>
) => Promise<Dialog.IResult<string>>;

Create and show a input dialog for a password.
Parameter options
The dialog setup options.
Returns
A promise that resolves with whether the dialog was accepted

function getText

getText: (options: ITextOptions) => Promise<Dialog.IResult<string>>;

Create and show a input dialog for a text.
Parameter options
The dialog setup options.
Returns
A promise that resolves with whether the dialog was accepted

interface IBooleanOptions

interface IBooleanOptions extends IOptions {}

Constructor options for boolean input dialogs

property value

value?: boolean;

Default value

interface IItemOptions

interface IItemOptions extends IOptions {}

Constructor options for item selection input dialogs

property current

current?: number | string;

Default choice
If the list is editable a string with a default value can be provided otherwise the index of the default choice should be given.

property editable

editable?: boolean;

Is the item editable?

property items

items: Array<string>;

List of choices

property placeholder

placeholder?: string;

Placeholder text for editable input

interface IMultipleItemsOptions

interface IMultipleItemsOptions extends IOptions {}

Constructor options for item selection input dialogs

property defaults

defaults?: string[];

Default choices

property items

items: Array<string>;

List of choices

interface INumberOptions

interface INumberOptions extends IOptions {}

Constructor options for number input dialogs

property value

value?: number;

Default value

interface IOptions

interface IOptions extends IBaseOptions {}

Common constructor options for input dialogs

property cancelLabel

cancelLabel?: string;

Label for cancel button.

property checkbox

checkbox?: Partial<Dialog.ICheckbox> | null;

The checkbox to display in the footer. Defaults no checkbox.

property defaultButton

defaultButton?: number;

The index of the default button. Defaults to the last button.

property host

host?: HTMLElement;

The host element for the dialog. Defaults to document.body.

property okLabel

okLabel?: string;

Label for ok button.

property renderer

renderer?: Dialog.IRenderer;

An optional renderer for dialog items. Defaults to a shared default renderer.

property title

title: Dialog.Header;

The top level text for the dialog. Defaults to an empty string.

interface ITextOptions

interface ITextOptions extends IOptions {}

Constructor options for text input dialogs

property pattern

pattern?: string;

Pattern used by the browser to validate the input value.

property placeholder

placeholder?: string;

Placeholder text

property required

required?: boolean;

Whether the input is required (has to be non-empty).

property selectionRange

selectionRange?: number;

Selection range
Number of characters to pre-select when dialog opens. Default is to select the whole input text if present.

property text

text?: string;

Default input text

namespace ISanitizer

namespace ISanitizer {}

The namespace for ISanitizer related interfaces.

type IOptions

type IOptions = IRenderMime.ISanitizerOptions;

The options used to sanitize.
Deprecated
in v4 use IRenderMime.ISanitizerOptions

namespace ISessionContext

namespace ISessionContext {}

The namespace for session context related interfaces.

interface IDialogs

interface IDialogs {}

An interface for a session context dialog provider.

method restart

restart: (
    session: ISessionContext,
    restartOptions?: ISessionContext.IRestartOptions
) => Promise<boolean>;

Restart the session context.
Returns
A promise that resolves with whether the kernel has restarted.
#### Notes If there is a running kernel, present a dialog. If there is no kernel, we start a kernel with the last run kernel name and resolves with true. If no kernel has been started, this is a no-op, and resolves with false.

method selectKernel

selectKernel: (session: ISessionContext) => Promise<void>;

Select a kernel for the session.

interface IDialogsOptions

interface IDialogsOptions {}

Session context dialog options

property settingRegistry

settingRegistry?: ISettingRegistry | null;

Optional setting registry used to access restart dialog preference.

property translator

translator?: ITranslator;

Application translator object

interface IKernelPreference

interface IKernelPreference {}

A kernel preference.
#### Notes Preferences for a kernel are considered in the order id, name, language. If no matching kernels can be found and autoStartDefault is true, then the default kernel for the server is preferred.

property autoStartDefault

readonly autoStartDefault?: boolean;

Automatically start the default kernel if no other matching kernel is found (default false).

property canStart

readonly canStart?: boolean;

A kernel can be started (default true).

property id

readonly id?: string;

The id of an existing kernel.

property language

readonly language?: string;

The preferred kernel language.

property name

readonly name?: string;

The name of the kernel.

property shouldReuse

readonly shouldReuse?: boolean;

Reuse an existing session on the current path (default true).

property shouldStart

readonly shouldStart?: boolean;

A kernel should be started automatically (default true).

property shutdownOnDispose

readonly shutdownOnDispose?: boolean;

Shut down the session when session context is disposed (default false).

property skipKernelRestartDialog

readonly skipKernelRestartDialog?: boolean;

Skip showing the kernel restart dialog if checked (default false).

interface IRestartOptions

interface IRestartOptions {}

On before restarting the kernel options

property onBeforeRestart

onBeforeRestart: () => Promise<void>;

Method to be called before restarting the kernel

type KernelDisplayStatus

type KernelDisplayStatus =
    | Kernel.Status
    | Kernel.ConnectionStatus
    | 'initializing'
    | '';

namespace IThemeManager

namespace IThemeManager {}

A namespace for the IThemeManager sub-types.

interface ITheme

interface ITheme {}

An interface for a theme.

property displayName

displayName?: string;

The display name of the theme.

property isLight

isLight: boolean;

Whether the theme is light or dark. Downstream authors of extensions can use this information to customize their UI depending upon the current theme.

property name

name: string;

The unique identifier name of the theme.

property themeScrollbars

themeScrollbars?: boolean;

Whether the theme includes styling for the scrollbar. If set to false, this theme will leave the native scrollbar untouched.

method load

load: () => Promise<void>;

Load the theme.
Returns
A promise that resolves when the theme has loaded.

method unload

unload: () => Promise<void>;

Unload the theme.
Returns
A promise that resolves when the theme has unloaded.

namespace KernelStatus

namespace KernelStatus {}

A namespace for KernelStatus statics.

class Model

class Model extends VDomModel {}

A VDomModel for the kernel status indicator.

constructor

constructor(translator?: ITranslator);

property activityName

activityName: string;

A display name for the activity.

property kernelName

readonly kernelName: string;

The name of the kernel.

property sessionContext

sessionContext: ISessionContext;

The current client session associated with the kernel status indicator.

property status

readonly status: string;

The current status of the kernel.

property translation

protected translation: ITranslator;

interface IOptions

interface IOptions {}

Options for creating a KernelStatus object.

property onClick

onClick: () => void;

A click handler for the item. By default we launch a kernel selection dialog.

property onKeyDown

onKeyDown: (event: KeyboardEvent<HTMLImageElement>) => void;

A key press handler for the item. By default we launch a kernel selection dialog.

namespace Licenses

namespace Licenses {}

A namespace for license components

variable DEFAULT_FORMAT

const DEFAULT_FORMAT: string;

The default format (most human-readable)

variable REPORT_FORMATS

const REPORT_FORMATS: Record<string, IReportFormat>;

License report formats understood by the server (once lower-cased)

class BundleTabRenderer

class BundleTabRenderer extends TabBar.Renderer {}

A fancy bundle renderer with the package count

constructor

constructor(model: Model);

property closeIconSelector

readonly closeIconSelector: string;

property model

model: Model;

A model of the state of license viewing as well as the underlying data

method renderCountBadge

renderCountBadge: (data: TabBar.IRenderData<Widget>) => VirtualElement;

Render the package count

method renderTab

renderTab: (data: TabBar.IRenderData<Widget>) => VirtualElement;

Render a full bundle

class Filters

class Filters extends VDomRenderer<Model> {}

A filter form for limiting the packages displayed

constructor

constructor(model: Model);

property onFilterInput

protected onFilterInput: (evt: React.ChangeEvent<HTMLInputElement>) => void;

Handle a filter input changing

property renderFilter

protected renderFilter: (key: TFilterKey) => JSX.Element;

Render a filter input

method render

protected render: () => JSX.Element;

class FullText

class FullText extends VDomRenderer<Model> {}

A package's full license text

constructor

constructor(model: Model);

method render

protected render: () => JSX.Element[];

Render the license text, or a null state if no package is selected

class Grid

class Grid extends VDomRenderer<Licenses.Model> {}

A grid of licenses

constructor

constructor(model: Model);

property renderRow

protected renderRow: (
    row: Licenses.IPackageLicenseInfo,
    index: number
) => JSX.Element;

Render a single package's license information

method render

protected render: () => JSX.Element;

Render a grid of package license information

class LicensesClient

class LicensesClient implements ILicensesClient {}

A class used for fetching licenses from the server.

constructor

constructor(options?: ILicenseClientOptions);

Create a new license client.

method download

download: (options: IDownloadOptions) => Promise<void>;

Download the licenses in the requested format.

method getBundles

getBundles: () => Promise<ILicenseResponse>;

Fetch the license bundles from the server.

class Model

class Model extends VDomModel implements ICreateArgs {}

A model for license data

constructor

constructor(options: IModelOptions);

property bundleNames

readonly bundleNames: string[];

The names of the license bundles available

property bundles

readonly bundles: { [key: string]: ILicenseBundle };

All the license bundles, keyed by the distributing packages

property currentBundleName

currentBundleName: string;

The current license bundle

property currentPackage

readonly currentPackage: IPackageLicenseInfo;

The license data for the currently-selected package

property currentPackageIndex

currentPackageIndex: number;

The index of the currently-selected package within its license bundle

property licensesReady

readonly licensesReady: Promise<void>;

A promise that resolves when the licenses are available from the server

property packageFilter

packageFilter: Partial<IPackageLicenseInfo>;

The current package filter

property selectedPackageChanged

readonly selectedPackageChanged: ISignal<Model, void>;

A promise that resolves when the licenses from the server change

property title

readonly title: string;

property trackerDataChanged

readonly trackerDataChanged: ISignal<Model, void>;

A promise that resolves when the trackable data changes

property trans

readonly trans: TranslationBundle;

A translation bundle

method download

download: (options: IDownloadOptions) => Promise<void>;

Download the licenses in the requested format.

method getFilteredPackages

getFilteredPackages: (allRows: IPackageLicenseInfo[]) => IPackageLicenseInfo[];

Get filtered packages from current bundle where at least one token of each key is present.

method initLicenses

initLicenses: () => Promise<void>;

Handle the initial request for the licenses from the server.

interface ICreateArgs

interface ICreateArgs {}

property currentBundleName

currentBundleName?: string | null;

property currentPackageIndex

currentPackageIndex?: number | null;

property packageFilter

packageFilter?: Partial<IPackageLicenseInfo> | null;

interface IDownloadOptions

interface IDownloadOptions {}

The format information for a download

property format

format: string;

interface ILicenseBundle

interface ILicenseBundle extends ReadonlyJSONObject {}

A top-level report of the licenses for all code included in a bundle
### Note
This is roughly informed by the terms defined in the SPDX spec, though is not an SPDX Document, since there seem to be several (incompatible) specs in that repo.
See Also
- https://github.com/spdx/spdx-spec/blob/development/v2.2.1/schemas/spdx-schema.json

property packages

packages: IPackageLicenseInfo[];

interface ILicenseClientOptions

interface ILicenseClientOptions {}

The options for a new license client.

property licensesUrl

licensesUrl?: string;

The URL for the licenses API

property serverSettings

serverSettings?: ServerConnection.ISettings;

The server settings

interface ILicenseResponse

interface ILicenseResponse {}

The JSON response from the API

property bundles

bundles: {
    [key: string]: Licenses.ILicenseBundle;
};

interface IModelOptions

interface IModelOptions extends ICreateArgs {}

Options for instantiating a license model

property client

client: ILicensesClient;

property trans

trans: TranslationBundle;

interface IOptions

interface IOptions {}

Options for instantiating a license viewer

property model

model: Model;

interface IPackageLicenseInfo

interface IPackageLicenseInfo extends ReadonlyJSONObject {}

A best-effort single bundled package's information.
### Note
This is roughly informed by SPDX packages and hasExtractedLicenseInfos, as making it conformant would vastly complicate the structure.
See Also
- https://github.com/spdx/spdx-spec/blob/development/v2.2.1/schemas/spdx-schema.json

property extractedText

extractedText: string;

the verbatim extracted text of the license, or an empty string if unknown

property licenseId

licenseId: string;

an SPDX license identifier or LicenseRef, or an empty string if unknown

property name

name: string;

the name of the package as it appears in package.json

property versionInfo

versionInfo: string;

the version of the package, or an empty string if unknown

interface IReportFormat

interface IReportFormat {}

The information about a license report format

property icon

icon: LabIcon;

property id

id: string;

property title

title: string;

type TFilterKey

type TFilterKey = 'name' | 'versionInfo' | 'licenseId';

The fields which can be filtered

namespace MainAreaWidget

namespace MainAreaWidget {}

The namespace for the MainAreaWidget class statics.

interface IOptions

interface IOptions<T extends Widget = Widget> extends Widget.IOptions {}

An options object for creating a main area widget.

property content

content: T;

The child widget to wrap.

property contentHeader

contentHeader?: BoxPanel;

The layout to sit underneath the toolbar and above the content, and that extensions can populate. Defaults to an empty BoxPanel.

property reveal

reveal?: Promise<any>;

An optional promise for when the content is ready to be revealed.

toolbar?: Toolbar;

The toolbar to use for the widget. Defaults to an empty toolbar.

property translator

translator?: ITranslator;

The application language translator.

interface IOptionsOptionalContent

interface IOptionsOptionalContent<T extends Widget = Widget>
    extends Widget.IOptions {}

An options object for main area widget subclasses providing their own default content.
#### Notes This makes it easier to have a subclass that provides its own default content. This can go away once we upgrade to TypeScript 2.8 and have an easy way to make a single property optional, ala https://stackoverflow.com/a/46941824

property content

content?: T;

The child widget to wrap.

property reveal

reveal?: Promise<any>;

An optional promise for when the content is ready to be revealed.

toolbar?: Toolbar;

The toolbar to use for the widget. Defaults to an empty toolbar.

namespace MenuFactory

namespace MenuFactory {}

Helper functions to build a menu from the settings

function addContextItem

addContextItem: (
    item: ISettingRegistry.IContextMenuItem,
    menu: ContextMenu,
    menuFactory: (options: IMenuOptions) => Menu
) => void;

Convert an item description in a context menu item object
Parameter item
Context menu item
Parameter menu
Context menu to populate
Parameter menuFactory
Empty menu factory

function createMenus

createMenus: (
    data: ISettingRegistry.IMenu[],
    menuFactory: (options: IMenuOptions) => Menu
) => Menu[];

Create menus from their description
Parameter data
Menubar description
Parameter menuFactory
Factory for empty menu

function updateMenus

updateMenus: (
    menus: Menu[],
    data: ISettingRegistry.IMenu[],
    menuFactory: (options: IMenuOptions) => Menu
) => Menu[];

Update an existing list of menu and returns the new elements.
#### Note New elements are added to the current menu list.
Parameter menus
Current menus
Parameter data
New description to take into account
Parameter menuFactory
Empty menu factory
Returns
Newly created menus

interface IMenuOptions

interface IMenuOptions {}

Menu constructor options

property id

id: string;

The unique menu identifier.

property label

label?: string;

The menu label.

property rank

rank?: number;

The menu rank.

namespace ModalCommandPalette

namespace ModalCommandPalette {}

interface IOptions

interface IOptions {}

property commandPalette

commandPalette: CommandPalette;

property restore

restore?: () => void;

A callback executed when the modal palette is closed. Used to restore focus to the previously active widget.

namespace Notification

namespace Notification {}

Notification namespace

variable manager

const manager: NotificationManager;

The global notification manager.

function dismiss

dismiss: (id?: string) => void;

Dismiss one notification (specified by its id) or all if no id provided
Parameter id
notification id

function emit

emit: <T extends ReadonlyJSONValue = ReadonlyJSONValue>(
    message: string,
    type?: TypeOptions,
    options?: IOptions<T>
) => string;

Helper function to emit a notification.
#### Notes The message will be truncated if longer than 140 characters.
Parameter message
Notification message
Parameter type
Notification type
Parameter options
Options for the error notification
Returns
Notification unique id

function error

error: <T extends ReadonlyJSONValue = ReadonlyJSONValue>(
    message: string,
    options?: IOptions<T>
) => string;

Helper function to emit an error notification.
#### Notes The message will be truncated if longer than 140 characters.
Parameter message
Notification message
Parameter options
Options for the error notification
Returns
Notification unique id

function info

info: <T extends ReadonlyJSONValue = ReadonlyJSONValue>(
    message: string,
    options?: IOptions<T>
) => string;

Helper function to emit an info notification.
#### Notes The message will be truncated if longer than 140 characters.
Parameter message
Notification message
Parameter options
Options for the info notification
Returns
Notification unique id

function promise

promise: <
    Pending extends ReadonlyJSONValue = ReadonlyJSONValue,
    Success extends ReadonlyJSONValue = Pending,
    Error extends ReadonlyJSONValue = Pending
>(
    promise: Promise<Success>,
    options: IPromiseOptions<Pending, Success, Error>
) => string;

Helper function to show an in-progress notification.
#### Notes The message will be truncated if longer than 140 characters.
Parameter promise
Promise to wait for
Parameter options
Options for the in-progress notification
Returns
Notification unique id

function success

success: <T extends ReadonlyJSONValue = ReadonlyJSONValue>(
    message: string,
    options?: IOptions<T>
) => string;

Helper function to emit a success notification.
#### Notes The message will be truncated if longer than 140 characters.
Parameter message
Notification message
Parameter options
Options for the success notification
Returns
Notification unique id

function update

update: <T extends ReadonlyJSONValue = ReadonlyJSONValue>(
    args: IUpdate<T>
) => boolean;

Helper function to update a notification.
If the notification does not exists, nothing will happen.
Once updated the notification will be moved at the begin of the notification stack.
#### Notes The message will be truncated if longer than 140 characters.
Parameter args
Update options
Returns
Whether the update was successful or not.

function warning

warning: <T extends ReadonlyJSONValue = ReadonlyJSONValue>(
    message: string,
    options?: IOptions<T>
) => string;

Helper function to emit a warning notification.
#### Notes The message will be truncated if longer than 140 characters.
Parameter message
Notification message
Parameter options
Options for the warning notification
Returns
Notification unique id

interface IAction

interface IAction {}

Interface describing an action linked to a notification.

property callback

callback: (event: MouseEvent) => void;

Callback function to trigger
### Notes By default execution of the callback will close the toast and dismiss the notification. You can prevent this by calling event.preventDefault() in the callback.

property caption

caption?: string;

The action caption.
This can be a longer description of the action.

property displayType

displayType?: ActionDisplayType;

The action display type.
This will be used to modify the action button style.

property label

label: string;

The action label.
This should be a short description.

interface IChange

interface IChange {}

Notification change interface

property notification

notification: INotification;

Notification that changed

property type

type: 'added' | 'removed' | 'updated';

Change type

interface INotification

interface INotification<T extends ReadonlyJSONValue = ReadonlyJSONValue> {}

Notification interface

property createdAt

createdAt: number;

Notification creation date

property id

id: string;

Notification unique identifier

property message

message: string;

Notification message
#### Notes The message will be truncated if longer than 140 characters.

property modifiedAt

modifiedAt: number;

Notification modification date

property options

options: IOptions<T>;

Notification options

property type

type: TypeOptions;

Notification type

interface IOptions

interface IOptions<T extends ReadonlyJSONValue> {}

Notification options

property actions

actions?: Array<IAction>;

List of associated actions

property autoClose

autoClose?: number | false;

Autoclosing behavior - false (not closing automatically) or number (time in milliseconds before hiding the notification)
Set to zero if you want the notification to be retained in the notification center but not displayed as toast. This is the default behavior.

property data

data?: T;

Data associated with a notification

property progress

progress?: number;

Task progression
### Notes This should be a number between 0 (not started) and 1 (completed).

interface IPromiseOptions

interface IPromiseOptions<
    Pending extends ReadonlyJSONValue,
    Success extends ReadonlyJSONValue = Pending,
    Error extends ReadonlyJSONValue = Pending
> {}

Parameters for notification depending on a promise.

property error

error: {
    message: (reason: unknown, data?: Error) => string;
    options?: IOptions<Error>;
};

Message when promise rejects and options
The message factory receives as first argument the error of the promise and as second the error options.data.
#### Notes The message will be truncated if longer than 140 characters.

property pending

pending: {
    message: string;
    options?: IOptions<Pending>;
};

Promise pending message and options
#### Notes The message will be truncated if longer than 140 characters.

property success

success: {
    message: (result: unknown, data?: Success) => string;
    options?: IOptions<Success>;
};

Message when promise resolves and options
The message factory receives as first argument the result of the promise and as second the success options.data.
#### Notes The message will be truncated if longer than 140 characters.

interface IUpdate

interface IUpdate<T extends ReadonlyJSONValue> extends IOptions<T> {}

Options for updating a notification

property id

id: string;

Notification unique id

property message

message?: string;

New notification message

property type

type?: TypeOptions;

New notification type

type ActionDisplayType

type ActionDisplayType = 'default' | 'accent' | 'warn' | 'link';

Enumeration of available action display type.

type TypeOptions

type TypeOptions =
    | 'info'
    | 'in-progress'
    | 'success'
    | 'warning'
    | 'error'
    | 'default';

Type of notifications

namespace Printing

namespace Printing {}

Any object is "printable" if it implements the IPrintable interface.
To do this it, it must have a method called Printing.symbol which returns either a function to print the object or null if it cannot be printed.
One way of printing is to use the printWidget function, which creates a hidden iframe and copies the DOM nodes from your widget to that iframe and printing just that iframe.
Another way to print is to use the printURL function, which takes a URL and prints that page.

variable symbol

const symbol: Symbol;

Symbol to use for a method that returns a function to print an object.

function getPrintFunction

getPrintFunction: (val: unknown) => OptionalAsyncThunk;

Returns the print function for an object, or null if it does not provide a handler.

function isPrintable

isPrintable: (a: unknown) => a is IPrintable;

Returns whether an object implements a print method.

function printURL

printURL: (
    url: string,
    serverSettings?: ServerConnection.ISettings
) => Promise<void>;

Prints a URL by loading it into an iframe.
Parameter url
URL to load into an iframe.
Parameter serverSettings
The server settings to use for the request.

function printWidget

printWidget: (widget: Widget) => Promise<void>;

Prints a widget by copying it's DOM node to a hidden iframe and printing that iframe.

interface IPrintable

interface IPrintable {}

Objects who provide a custom way of printing themselves should implement this interface.

property [symbol]

[symbol]: () => OptionalAsyncThunk;

Returns a function to print this object or null if it cannot be printed.

type OptionalAsyncThunk

type OptionalAsyncThunk = (() => Promise<void>) | null;

Function that takes no arguments and when invoked prints out some object or null if printing is not defined.

namespace RunningSessions

namespace RunningSessions {}

A namespace for RunningSessions statics.

class Model

class Model extends VDomModel {}

A VDomModel for the RunningSessions status item.

property sessions

sessions: number;

The number of active kernel sessions.

property terminals

terminals: number;

The number of active terminal sessions.

interface IOptions

interface IOptions {}

Options for creating a RunningSessions item.

property onClick

onClick: () => void;

A click handler for the item. By default this is used to activate the running sessions side panel.

property onKeyDown

onKeyDown: (event: KeyboardEvent<HTMLImageElement>) => void;

A key down handler for the item. By default this is used to activate the running sessions side panel.

property serviceManager

serviceManager: ServiceManager.IManager;

The application service manager.

property showKernels

showKernels?: boolean;

Whether to show kernels, true by default.

property showTerminals

showTerminals?: boolean;

Whether to show terminals.
The default is true if one or more terminals are open, false otherwise.

property translator

translator?: ITranslator;

The application language translator.

namespace SessionContext

namespace SessionContext {}

A namespace for SessionContext statics.

function getDefaultKernel

getDefaultKernel: (options: IKernelSearch) => string | null;

Get the default kernel name given select options.

interface IKernelSearch

interface IKernelSearch {}

An interface for populating a kernel selector.

property kernels

kernels?: Iterable<Kernel.IModel>;

The current running kernels.

property preference

preference: ISessionContext.IKernelPreference;

The kernel preference.

property sessions

sessions?: Iterable<Session.IModel>;

The current running sessions.

property specs

specs: KernelSpec.ISpecModels | null;

The Kernel specs.

interface IOptions

interface IOptions {}

The options used to initialize a context.

property kernelManager

kernelManager?: Kernel.IManager;

A kernel manager instance.
#### Notes In the next version of this package, kernelManager will be required.

property kernelPreference

kernelPreference?: ISessionContext.IKernelPreference;

A kernel preference.

property name

name?: string;

The name of the session.

property path

path?: string;

The initial path of the file.

property sessionManager

sessionManager: Session.IManager;

A session manager instance.

property setBusy

setBusy?: () => IDisposable;

A function to call when the session becomes busy.

property specsManager

specsManager: KernelSpec.IManager;

A kernel spec manager instance.

property translator

translator?: ITranslator;

The application language translator.

property type

type?: string;

The type of the session.

namespace SessionContextDialogs

namespace SessionContextDialogs {}

function kernelOptions

kernelOptions: (
    sessionContext: ISessionContext,
    translator?: ITranslator | null
) => IKernelOptions;

Returns available kernel options grouped based on session context.
#### Notes If a language preference is set in the given session context, the options returned are grouped with the language preference at the top:
- (Start %1 Kernel, language) - { all kernelspecs whose language matches in alphabetical order } - (Use No Kernel) - No Kernel - (Start Kernel) - { all other kernelspecs in alphabetical order } - (Connect to Existing %1 Kernel, language) - { all running kernels whose language matches in alphabetical order } - (Connect to Kernel) - { all other running kernels in alphabetical order }
If no language preference is set, these groups and options are returned:
- (Start Kernel) - { all kernelspecs in alphabetical order } - (Use No Kernel) - No Kernel - (Connect to Existing Kernel) - { all running kernels in alphabetical order }
If the session has a kernel ID and a kernel exists with that id, its corresponding option has selected set to true. Otherwise if the session context language preference is set, the first kernelspec that matches it is selected.

interface IKernelOptions

interface IKernelOptions {}

An interface that abstracts the available kernel switching choices.

property disabled

disabled?: boolean;

Whether kernel options should be disabled.

property groups

groups: Array<{
    /**
     * The option group label.
     */
    label: string;
    /**
     * Individual kernel (and spec) options that correspond with `<option>`.
     */
    options: Array<{
        /**
         * Whether the option is selected.
         */
        selected?: boolean;
        /**
         * The display text of the option.
         */
        text: string;
        /**
         * The display title of the option.
         */
        title?: string;
        /**
         * The underlying (stringified JSON) value of the option.
         */
        value: string;
    }>;
}>;

An array of kernel option groups that correspond with <optgroup>.

namespace SystemClipboard

namespace SystemClipboard {}

The clipboard interface supporting the native clipboard API.

function getInstance

getInstance: () => IClipboard;

Get the system clipboard instance.

interface IClipboard

interface IClipboard {}

The interface for the system clipboard.

method clear

clear: () => void;

Clear the clipboard.

method getData

getData: (mime: string) => Promise<unknown | null>;

Retrieve the data for a given mime type. Returns null if the data does not exist.
Parameter mime
The mime type to retrieve.

method hasData

hasData: (mime: string) => Promise<boolean>;

Whether the clipboard has data for a given mime type. Returns false if the data does not exist.
Parameter mime
The mime type to check.

method setData

setData: (mime: string, data: unknown) => Promise<void>;

Set the data for a given mime type.
Parameter mime
The mime type to set.
Parameter data
The data to set.

namespace ThemeManager

namespace ThemeManager {}

interface IOptions

interface IOptions {}

The options used to create a theme manager.

property host

host: Widget;

The host widget for the theme manager.

property key

key: string;

The setting registry key that holds theme setting data.

property settings

settings: ISettingRegistry;

The settings registry.

property splash

splash?: ISplashScreen;

The splash screen to show when loading themes.

property translator

translator?: ITranslator;

The application language translator.

property url

url: string;

The url for local theme loading.

namespace Toolbar {}

const createInterruptButton: (
    sessionContext: ISessionContext,
    translator?: ITranslator
) => Widget;

const createKernelNameItem: (
    sessionContext: ISessionContext,
    dialogs?: ISessionContext.IDialogs,
    translator?: ITranslator
) => Widget;

const createKernelStatusItem: (
    sessionContext: ISessionContext,
    translator?: ITranslator
) => Widget;

const createRestartButton: (
    sessionContext: ISessionContext,
    dialogs?: ISessionContext.IDialogs,
    translator?: ITranslator
) => Widget;

const createSpacerItem: any;

Deprecated
since v4 This helper function is in @jupyterlab/ui-components

namespace ToolbarRegistry

namespace ToolbarRegistry {}

The namespace for IToolbarWidgetRegistry related interfaces

interface IOptions

interface IOptions {}

Options to set up the toolbar widget registry

property defaultFactory

defaultFactory: (
    widgetFactory: string,
    widget: Widget,
    toolbarItem: IWidget
) => Widget;

Default toolbar widget factory
The factory is receiving 3 arguments:
Parameter widgetFactory
The widget factory name that creates the toolbar
Parameter widget
The newly widget containing the toolbar
Parameter toolbarItem
The toolbar item definition
Returns
The widget to be inserted in the toolbar.

interface IToolbarItem

interface IToolbarItem extends IRenderMime.IToolbarItem {}

Interface of item to be inserted in a toolbar

interface IWidget

interface IWidget extends ISettingRegistry.IToolbarItem {}

Interface describing a toolbar item widget

namespace WidgetTracker

namespace WidgetTracker {}

A namespace for WidgetTracker statics.

interface IOptions

interface IOptions {}

The instantiation options for a widget tracker.

property namespace

namespace: string;

A namespace for all tracked widgets, (e.g., notebook).

Dev Dependencies (6)

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@jupyterlab/apputils.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@jupyterlab/apputils)

HTML

<a href="https://www.jsdocs.io/package/@jupyterlab/apputils"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated just now.
Package analyzed in 11000 ms.
Missing or incorrect documentation? Open an issue for this package.

@jupyterlab/apputils

Install

Overview

Index

Variables

Functions

Classes

Interfaces

Type Aliases

Namespaces

Variables

variable ICommandPalette

variable IKernelStatusModel

variable ILicensesClient

variable IMovableSectionRegistry

variable ISanitizer

variable ISessionContextDialogs

variable ISplashScreen

variable IThemeManager

variable IToolbarWidgetRegistry

variable IWindowResolver

Functions

function createDefaultFactory

Parameter commands

Returns

function createToolbarFactory

Parameter toolbarRegistry

Parameter settingsRegistry

Parameter factoryName

Parameter pluginId

Parameter translator

Parameter propertyId

Returns

function setToolbar

Parameter widget

Parameter factory

Parameter toolbar

function showDialog

Parameter options

Returns

function showErrorMessage

Parameter title

Parameter error

function translateKernelStatuses

Parameter translator

Classes

class CommandLinker

constructor

property isDisposed

method connectNode

Parameter node

Parameter command

Parameter args

Returns

method disconnectNode

Parameter node

Returns

method dispose

method handleEvent

Parameter event

method markTrusted

method populateVNodeDataset

Parameter command

Parameter args

Returns

method unmarkTrusted

class Dialog

constructor

Parameter options

property ready

method dispose

method handleEvent

Parameter event

method launch

Returns

method onAfterAttach

method onAfterDetach

method onCloseRequest

method reject

method resolve