@jupyterlab/notebook/lib/widget.d.ts

import { Cell, CodeCell, ICellModel, MarkdownCell, RawCell } from '@jupyterlab/cells';
import { IEditorMimeTypeService } from '@jupyterlab/codeeditor';
import { IChangedArgs } from '@jupyterlab/coreutils';
import * as nbformat from '@jupyterlab/nbformat';
import { IObservableList } from '@jupyterlab/observables';
import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
import type { IMapChange } from '@jupyter/ydoc';
import { ITranslator } from '@jupyterlab/translation';
import { WindowedList } from '@jupyterlab/ui-components';
import { Message } from '@lumino/messaging';
import { AttachedProperty } from '@lumino/properties';
import { ISignal } from '@lumino/signaling';
import { PanelLayout, Widget } from '@lumino/widgets';
import { CellList } from './celllist';
import { INotebookModel } from './model';
type RenderingLayout = 'default' | 'side-by-side';
/**
 * The interactivity modes for the notebook.
 */
export type NotebookMode = 'command' | 'edit';
/**
 * A widget which renders static non-interactive notebooks.
 *
 * #### Notes
 * The widget model must be set separately and can be changed
 * at any time.  Consumers of the widget must account for a
 * `null` model, and may want to listen to the `modelChanged`
 * signal.
 */
export declare class StaticNotebook extends WindowedList {
    /**
     * Construct a notebook widget.
     */
    constructor(options: StaticNotebook.IOptions);
    get cellCollapsed(): ISignal<this, Cell>;
    get cellInViewportChanged(): ISignal<this, Cell>;
    /**
     * A signal emitted when the model of the notebook changes.
     */
    get modelChanged(): ISignal<this, void>;
    /**
     * A signal emitted when the model content changes.
     *
     * #### Notes
     * This is a convenience signal that follows the current model.
     */
    get modelContentChanged(): ISignal<this, void>;
    /**
     * A signal emitted when the rendering layout of the notebook changes.
     */
    get renderingLayoutChanged(): ISignal<this, RenderingLayout>;
    /**
     * The cell factory used by the widget.
     */
    readonly contentFactory: StaticNotebook.IContentFactory;
    /**
     * The Rendermime instance used by the widget.
     */
    readonly rendermime: IRenderMimeRegistry;
    /**
     * Translator to be used by cell renderers
     */
    readonly translator: ITranslator;
    /**
     * The model for the widget.
     */
    get model(): INotebookModel | null;
    set model(newValue: INotebookModel | null);
    /**
     * Get the mimetype for code cells.
     */
    get codeMimetype(): string;
    /**
     * A read-only sequence of the widgets in the notebook.
     */
    get widgets(): ReadonlyArray<Cell>;
    /**
     * A configuration object for cell editor settings.
     */
    get editorConfig(): StaticNotebook.IEditorConfig;
    set editorConfig(value: StaticNotebook.IEditorConfig);
    /**
     * A configuration object for notebook settings.
     */
    get notebookConfig(): StaticNotebook.INotebookConfig;
    set notebookConfig(value: StaticNotebook.INotebookConfig);
    get renderingLayout(): RenderingLayout | undefined;
    set renderingLayout(value: RenderingLayout | undefined);
    /**
     * Dispose of the resources held by the widget.
     */
    dispose(): void;
    /**
     * Move cells preserving widget view state.
     *
     * #### Notes
     * This is required because at the model level a move is a deletion
     * followed by an insertion. Hence the view state is not preserved.
     *
     * @param from The index of the cell to move
     * @param to The new index of the cell
     * @param n Number of cells to move
     */
    moveCell(from: number, to: number, n?: number): void;
    /**
     * Force rendering the cell outputs of a given cell if it is still a placeholder.
     *
     * #### Notes
     * The goal of this method is to allow search on cell outputs (that is based
     * on DOM tree introspection).
     *
     * @param index The cell index
     */
    renderCellOutputs(index: number): void;
    /**
     * Adds a message to the notebook as a header.
     */
    protected addHeader(): void;
    /**
     * Removes the header.
     */
    protected removeHeader(): void;
    /**
     * Handle a new model.
     *
     * #### Notes
     * This method is called after the model change has been handled
     * internally and before the `modelChanged` signal is emitted.
     * The default implementation is a no-op.
     */
    protected onModelChanged(oldValue: INotebookModel | null, newValue: INotebookModel | null): void;
    /**
     * Handle changes to the notebook model content.
     *
     * #### Notes
     * The default implementation emits the `modelContentChanged` signal.
     */
    protected onModelContentChanged(model: INotebookModel, args: void): void;
    /**
     * Handle changes to the notebook model metadata.
     *
     * #### Notes
     * The default implementation updates the mimetypes of the code cells
     * when the `language_info` metadata changes.
     */
    protected onMetadataChanged(sender: INotebookModel, args: IMapChange): void;
    /**
     * Handle a cell being inserted.
     *
     * The default implementation is a no-op
     */
    protected onCellInserted(index: number, cell: Cell): void;
    /**
     * Handle a cell being removed.
     *
     * The default implementation is a no-op
     */
    protected onCellRemoved(index: number, cell: Cell): void;
    /**
     * A message handler invoked on an `'update-request'` message.
     *
     * #### Notes
     * The default implementation of this handler is a no-op.
     */
    protected onUpdateRequest(msg: Message): void;
    /**
     * Handle a new model on the widget.
     */
    private _onModelChanged;
    /**
     * Handle a change cells event.
     */
    protected _onCellsChanged(sender: CellList, args: IObservableList.IChangedArgs<ICellModel>): void;
    /**
     * Create a cell widget and insert into the notebook.
     */
    private _insertCell;
    /**
     * Create a code cell widget from a code cell model.
     */
    private _createCodeCell;
    /**
     * Create a markdown cell widget from a markdown cell model.
     */
    private _createMarkdownCell;
    /**
     * Create a raw cell widget from a raw cell model.
     */
    private _createRawCell;
    /**
     * Remove a cell widget.
     */
    private _removeCell;
    /**
     * Update the mimetype of the notebook.
     */
    private _updateMimetype;
    /**
     * Callback when a cell collapsed status changes.
     *
     * @param cell Cell changed
     * @param collapsed New collapsed status
     */
    private _onCellCollapsed;
    /**
     * Callback when a cell viewport status changes.
     *
     * @param cell Cell changed
     */
    private _onCellInViewportChanged;
    /**
     * Ensure to load in the DOM a cell requesting an user input
     *
     * @param cell Cell requesting an input
     */
    private _onInputRequested;
    private _scheduleCellRenderOnIdle;
    private _updateDataWindowedListIndex;
    /**
     * Update editor settings for notebook cells.
     */
    private _updateEditorConfig;
    private _runOnIdleTime;
    private _updateForDeferMode;
    private _renderCSSAndJSOutputs;
    /**
     * Apply updated notebook settings.
     */
    private _updateNotebookConfig;
    protected cellsArray: Array<Cell>;
    private _cellCollapsed;
    private _cellInViewportChanged;
    private _editorConfig;
    private _idleCallBack;
    private _mimetype;
    private _mimetypeService;
    private _modelChanged;
    private _modelContentChanged;
    private _notebookConfig;
    private _notebookModel;
    private _renderingLayout;
    private _renderingLayoutChanged;
}
/**
 * The namespace for the `StaticNotebook` class statics.
 */
export declare namespace StaticNotebook {
    /**
     * An options object for initializing a static notebook.
     */
    interface IOptions {
        /**
         * The rendermime instance used by the widget.
         */
        rendermime: IRenderMimeRegistry;
        /**
         * The language preference for the model.
         */
        languagePreference?: string;
        /**
         * A factory for creating content.
         */
        contentFactory: IContentFactory;
        /**
         * A configuration object for the cell editor settings.
         */
        editorConfig?: IEditorConfig;
        /**
         * A configuration object for notebook settings.
         */
        notebookConfig?: INotebookConfig;
        /**
         * The service used to look up mime types.
         */
        mimeTypeService: IEditorMimeTypeService;
        /**
         * The application language translator.
         */
        translator?: ITranslator;
    }
    /**
     * A factory for creating notebook content.
     *
     * #### Notes
     * This extends the content factory of the cell itself, which extends the content
     * factory of the output area and input area. The result is that there is a single
     * factory for creating all child content of a notebook.
     */
    interface IContentFactory extends Cell.IContentFactory {
        /**
         * Create a new code cell widget.
         */
        createCodeCell(options: CodeCell.IOptions): CodeCell;
        /**
         * Create a new markdown cell widget.
         */
        createMarkdownCell(options: MarkdownCell.IOptions): MarkdownCell;
        /**
         * Create a new raw cell widget.
         */
        createRawCell(options: RawCell.IOptions): RawCell;
    }
    /**
     * A config object for the cell editors.
     */
    interface IEditorConfig {
        /**
         * Config options for code cells.
         */
        readonly code: Record<string, any>;
        /**
         * Config options for markdown cells.
         */
        readonly markdown: Record<string, any>;
        /**
         * Config options for raw cells.
         */
        readonly raw: Record<string, any>;
    }
    /**
     * Default configuration options for cell editors.
     */
    const defaultEditorConfig: IEditorConfig;
    /**
     * A config object for the notebook widget
     */
    interface INotebookConfig {
        /**
         * The default type for new notebook cells.
         */
        defaultCell: nbformat.CellType;
        /**
         * Defines if the document can be undo/redo.
         */
        disableDocumentWideUndoRedo: boolean;
        /**
         * Defines the maximum number of outputs per cell.
         */
        maxNumberOutputs: number;
        /**
         * Whether to split stdin line history by kernel session or keep globally accessible.
         */
        inputHistoryScope: 'global' | 'session';
        /**
         * Number of cells to render in addition to those
         * visible in the viewport.
         *
         * ### Notes
         * In 'full' windowing mode, this is the number of cells above and below the
         * viewport.
         * In 'defer' windowing mode, this is the number of cells to render initially
         * in addition to the one of the viewport.
         */
        overscanCount: number;
        /**
         * Should timing be recorded in metadata
         */
        recordTiming: boolean;
        /**
         * Defines the rendering layout to use.
         */
        renderingLayout: RenderingLayout;
        /**
         * Enable scrolling past the last cell
         */
        scrollPastEnd: boolean;
        /**
         * Show hidden cells button if collapsed
         */
        showHiddenCellsButton: boolean;
        /**
         * Should an editor be shown for read-only markdown
         */
        showEditorForReadOnlyMarkdown?: boolean;
        /**
         * Override the side-by-side left margin.
         */
        sideBySideLeftMarginOverride: string;
        /**
         * Override the side-by-side right margin.
         */
        sideBySideRightMarginOverride: string;
        /**
         * Side-by-side output ratio.
         */
        sideBySideOutputRatio: number;
        /**
         * Windowing mode
         *
         * - 'defer': Wait for idle CPU cycles to attach out of viewport cells
         * - 'full': Attach to the DOM only cells in viewport
         * - 'none': Attach all cells to the viewport
         */
        windowingMode: 'defer' | 'full' | 'none';
    }
    /**
     * Default configuration options for notebooks.
     */
    const defaultNotebookConfig: INotebookConfig;
    /**
     * The default implementation of an `IContentFactory`.
     */
    class ContentFactory extends Cell.ContentFactory implements IContentFactory {
        /**
         * Create a new code cell widget.
         *
         * #### Notes
         * If no cell content factory is passed in with the options, the one on the
         * notebook content factory is used.
         */
        createCodeCell(options: CodeCell.IOptions): CodeCell;
        /**
         * Create a new markdown cell widget.
         *
         * #### Notes
         * If no cell content factory is passed in with the options, the one on the
         * notebook content factory is used.
         */
        createMarkdownCell(options: MarkdownCell.IOptions): MarkdownCell;
        /**
         * Create a new raw cell widget.
         *
         * #### Notes
         * If no cell content factory is passed in with the options, the one on the
         * notebook content factory is used.
         */
        createRawCell(options: RawCell.IOptions): RawCell;
    }
    /**
     * A namespace for the static notebook content factory.
     */
    namespace ContentFactory {
        /**
         * Options for the content factory.
         */
        interface IOptions extends Cell.ContentFactory.IOptions {
        }
    }
}
/**
 * A notebook widget that supports interactivity.
 */
export declare class Notebook extends StaticNotebook {
    /**
     * Construct a notebook widget.
     */
    constructor(options: Notebook.IOptions);
    /**
     * List of selected and active cells
     */
    get selectedCells(): Cell[];
    /**
     * Adds a footer to the notebook.
     */
    protected addFooter(): void;
    /**
     * Handle a change cells event.
     */
    protected _onCellsChanged(sender: CellList, args: IObservableList.IChangedArgs<ICellModel>): void;
    /**
     * A signal emitted when the active cell changes.
     *
     * #### Notes
     * This can be due to the active index changing or the
     * cell at the active index changing.
     */
    get activeCellChanged(): ISignal<this, Cell | null>;
    /**
     * A signal emitted when the state of the notebook changes.
     */
    get stateChanged(): ISignal<this, IChangedArgs<any>>;
    /**
     * A signal emitted when the selection state of the notebook changes.
     */
    get selectionChanged(): ISignal<this, void>;
    /**
     * The interactivity mode of the notebook.
     */
    get mode(): NotebookMode;
    set mode(newValue: NotebookMode);
    /**
     * The active cell index of the notebook.
     *
     * #### Notes
     * The index will be clamped to the bounds of the notebook cells.
     */
    get activeCellIndex(): number;
    set activeCellIndex(newValue: number);
    /**
     * Get the active cell widget.
     *
     * #### Notes
     * This is a cell or `null` if there is no active cell.
     */
    get activeCell(): Cell | null;
    get lastClipboardInteraction(): 'copy' | 'cut' | 'paste' | null;
    set lastClipboardInteraction(newValue: 'copy' | 'cut' | 'paste' | null);
    /**
     * Dispose of the resources held by the widget.
     */
    dispose(): void;
    /**
     * Move cells preserving widget view state.
     *
     * #### Notes
     * This is required because at the model level a move is a deletion
     * followed by an insertion. Hence the view state is not preserved.
     *
     * @param from The index of the cell to move
     * @param to The new index of the cell
     * @param n Number of cells to move
     */
    moveCell(from: number, to: number, n?: number): void;
    /**
     * Select a cell widget.
     *
     * #### Notes
     * It is a no-op if the value does not change.
     * It will emit the `selectionChanged` signal.
     */
    select(widget: Cell): void;
    /**
     * Deselect a cell widget.
     *
     * #### Notes
     * It is a no-op if the value does not change.
     * It will emit the `selectionChanged` signal.
     */
    deselect(widget: Cell): void;
    /**
     * Whether a cell is selected.
     */
    isSelected(widget: Cell): boolean;
    /**
     * Whether a cell is selected or is the active cell.
     */
    isSelectedOrActive(widget: Cell): boolean;
    /**
     * Deselect all of the cells.
     */
    deselectAll(): void;
    /**
     * Move the head of an existing contiguous selection to extend the selection.
     *
     * @param index - The new head of the existing selection.
     *
     * #### Notes
     * If there is no existing selection, the active cell is considered an
     * existing one-cell selection.
     *
     * If the new selection is a single cell, that cell becomes the active cell
     * and all cells are deselected.
     *
     * There is no change if there are no cells (i.e., activeCellIndex is -1).
     */
    extendContiguousSelectionTo(index: number): void;
    /**
     * Get the head and anchor of a contiguous cell selection.
     *
     * The head of a contiguous selection is always the active cell.
     *
     * If there are no cells selected, `{head: null, anchor: null}` is returned.
     *
     * Throws an error if the currently selected cells do not form a contiguous
     * selection.
     */
    getContiguousSelection(): {
        head: number;
        anchor: number;
    } | {
        head: null;
        anchor: null;
    };
    /**
     * Scroll so that the given cell is in view. Selects and activates cell.
     *
     * @param cell - A cell in the notebook widget.
     * @param align - Type of alignment.
     *
     */
    scrollToCell(cell: Cell, align?: WindowedList.ScrollToAlign): Promise<void>;
    private _parseFragment;
    /**
     * Set URI fragment identifier.
     */
    setFragment(fragment: string): Promise<void>;
    /**
     * Handle the DOM events for the widget.
     *
     * @param 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 notebook panel's node. It should
     * not be called directly by user code.
     */
    handleEvent(event: Event): void;
    /**
     * Handle `after-attach` messages for the widget.
     */
    protected onAfterAttach(msg: Message): void;
    /**
     * Handle `before-detach` messages for the widget.
     */
    protected onBeforeDetach(msg: Message): void;
    /**
     * A message handler invoked on an `'after-show'` message.
     */
    protected onAfterShow(msg: Message): void;
    /**
     * A message handler invoked on a `'resize'` message.
     */
    protected onResize(msg: Widget.ResizeMessage): void;
    /**
     * A message handler invoked on an `'before-hide'` message.
     */
    protected onBeforeHide(msg: Message): void;
    /**
     * Handle `'activate-request'` messages.
     */
    protected onActivateRequest(msg: Message): void;
    /**
     * Handle `update-request` messages sent to the widget.
     */
    protected onUpdateRequest(msg: Message): void;
    /**
     * Handle a cell being inserted.
     */
    protected onCellInserted(index: number, cell: Cell): void;
    /**
     * Handle a cell being removed.
     */
    protected onCellRemoved(index: number, cell: Cell): void;
    /**
     * Handle a new model.
     */
    protected onModelChanged(oldValue: INotebookModel, newValue: INotebookModel): void;
    /**
     * Handle edge request signals from cells.
     */
    private _onEdgeRequest;
    /**
     * Ensure that the notebook has proper focus.
     */
    private _ensureFocus;
    /**
     * Find the cell index containing the target html element.
     *
     * #### Notes
     * Returns -1 if the cell is not found.
     */
    private _findCell;
    /**
     * Find the target of html mouse event and cell index containing this target.
     *
     * #### Notes
     * Returned index is -1 if the cell is not found.
     */
    private _findEventTargetAndCell;
    /**
     * Find heading with given ID in any of the cells.
     */
    _findHeading(queryId: string): Promise<Private.IScrollTarget | null>;
    /**
     * Find cell by its unique ID.
     */
    _findCellById(queryId: string): Private.IScrollTarget | null;
    /**
     * Handle `contextmenu` event.
     */
    private _evtContextMenuCapture;
    /**
     * Handle `mousedown` event in the capture phase for the widget.
     */
    private _evtMouseDownCapture;
    /**
     * Handle `mousedown` events for the widget.
     */
    private _evtMouseDown;
    /**
     * Handle the `'mouseup'` event on the document.
     */
    private _evtDocumentMouseup;
    /**
     * Handle the `'mousemove'` event for the widget.
     */
    private _evtDocumentMousemove;
    /**
     * Handle the `'lm-dragenter'` event for the widget.
     */
    private _evtDragEnter;
    /**
     * Handle the `'lm-dragleave'` event for the widget.
     */
    private _evtDragLeave;
    /**
     * Handle the `'lm-dragover'` event for the widget.
     */
    private _evtDragOver;
    /**
     * Handle the `'lm-drop'` event for the widget.
     */
    private _evtDrop;
    /**
     * Start a drag event.
     */
    private _startDrag;
    /**
     * Handle `focus` events for the widget.
     */
    private _evtFocusIn;
    /**
     * Handle `focusout` events for the notebook.
     */
    private _evtFocusOut;
    /**
     * Handle `dblclick` events for the widget.
     */
    private _evtDblClick;
    /**
     * Remove selections from inactive cells to avoid
     * spurious cursors.
     */
    private _trimSelections;
    private _activeCellIndex;
    private _activeCell;
    private _mode;
    private _drag;
    private _dragData;
    private _mouseMode;
    private _activeCellChanged;
    private _stateChanged;
    private _selectionChanged;
    private _cellLayoutStateCache?;
    private _checkCacheOnNextResize;
    private _lastClipboardInteraction;
    private _updateSelectedCells;
    private _selectedCells;
}
/**
 * The namespace for the `Notebook` class statics.
 */
export declare namespace Notebook {
    /**
     * An options object for initializing a notebook widget.
     */
    interface IOptions extends StaticNotebook.IOptions {
    }
    /**
     * The content factory for the notebook widget.
     */
    interface IContentFactory extends StaticNotebook.IContentFactory {
    }
    /**
     * The default implementation of a notebook content factory..
     *
     * #### Notes
     * Override methods on this class to customize the default notebook factory
     * methods that create notebook content.
     */
    class ContentFactory extends StaticNotebook.ContentFactory {
    }
    /**
     * A namespace for the notebook content factory.
     */
    namespace ContentFactory {
        /**
         * An options object for initializing a notebook content factory.
         */
        interface IOptions extends StaticNotebook.ContentFactory.IOptions {
        }
    }
}
/**
 * A namespace for private data.
 */
declare namespace Private {
    /**
     * An attached property for the selected state of a cell.
     */
    const selectedProperty: AttachedProperty<Cell<ICellModel>, boolean>;
    /**
     * A custom panel layout for the notebook.
     */
    class NotebookPanelLayout extends PanelLayout {
        /**
         * A message handler invoked on an `'update-request'` message.
         *
         * #### Notes
         * This is a reimplementation of the base class method,
         * and is a no-op.
         */
        protected onUpdateRequest(msg: Message): void;
    }
    /**
     * Create a cell drag image.
     */
    function createDragImage(count: number, promptNumber: string, cellContent: string): HTMLElement;
    /**
     * Information about resolved scroll target defined by URL fragment.
     */
    interface IScrollTarget {
        /**
         * Target cell.
         */
        cell: Cell;
        /**
         * Element to scroll to within the cell.
         */
        element?: HTMLElement;
    }
    /**
     * Parsed fragment identifier data.
     */
    interface IFragmentData {
        /**
         * The kind of notebook element targetted by the fragment identifier.
         */
        kind: 'heading' | 'cell-id';
        value: string;
    }
}
export {};