Class WidgetTracker<T>

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


T - The type of widget being tracked. Defaults to Widget.


The API surface area of this concrete implementation is substantially larger than the widget tracker interface it implements. The interface is intended for export by JupyterLab plugins that create widgets and have clients who may wish to keep track of newly created widgets. This class, however, can be used internally by plugins to restore state as well.

Type Parameters


  • WidgetTracker




    _currentChanged: Signal<WidgetTracker<T>, null | T> = ...
    _deferred: null | IRestorable.IOptions<T> = null
    _focusTracker: FocusTracker<T>
    _isDisposed: boolean = false
    _widgetAdded: Signal<WidgetTracker<T>, T> = ...
    _widgetUpdated: Signal<WidgetTracker<T>, T> = ...
    namespace: string

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



    • Add a new widget to the tracker.


      • widget: T

        The widget being added.


        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.

      Returns Promise<void>

    • Save the restore options for this tracker, but do not restore yet.


      • options: IRestorable.IOptions<T>

        The configuration options that describe restoration.


        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.

      Returns void

    • Find the first widget in the tracker that satisfies a filter function.


      • fn: ((widget) => boolean)

        The filter function to call on each widget.


        If no widget is found, the value returned is undefined.

          • (widget): boolean
          • Parameters

            • widget: T

            Returns boolean

      Returns undefined | T

    • Inject a foreign widget into the widget tracker.


      • widget: T

        The widget to inject into the tracker.


        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.

      Returns Promise<void>