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 { INotebookHistory } from './history'; import { INotebookModel } from './model'; import { NotebookViewModel } from './windowing'; 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; get cellInViewportChanged(): ISignal; /** * A signal emitted when the model of the notebook changes. */ get modelChanged(): ISignal; /** * A signal emitted when the model content changes. * * #### Notes * This is a convenience signal that follows the current model. */ get modelContentChanged(): ISignal; /** * A signal emitted when the rendering layout of the notebook changes. */ get renderingLayoutChanged(): ISignal; /** * 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; /** * 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): 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; /** * Apply updated notebook settings. */ private _updateNotebookConfig; protected cellsArray: Array; private _cellCollapsed; private _cellInViewportChanged; private _editorConfig; private _idleCallBack; private _mimetype; private _mimetypeService; readonly kernelHistory: INotebookHistory | undefined; 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; /** * The kernel history retrieval object */ kernelHistory?: INotebookHistory; /** * The renderer used by the underlying windowed list. */ renderer?: WindowedList.IRenderer; } /** * 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; /** * Config options for markdown cells. */ readonly markdown: Record; /** * Config options for raw cells. */ readonly raw: Record; } /** * 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; /** * Whether to display notification if code cell is run while kernel is still initializing. */ enableKernelInitNotification: 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'; accessKernelHistory?: boolean; } /** * 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): 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; /** * A signal emitted when the state of the notebook changes. */ get stateChanged(): ISignal>; /** * A signal emitted when the selection state of the notebook changes. */ get selectionChanged(): ISignal; /** * The interactivity mode of the notebook. */ get mode(): NotebookMode; set mode(newValue: NotebookMode); /** * Set the notebook mode. * * @param newValue Notebook mode * @param options Control mode side-effect * @param options.focus Whether to ensure focus (default) or not when setting the mode. */ protected setMode(newValue: NotebookMode, options?: { focus?: boolean; }): void; /** * 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; private _parseFragment; /** * Set URI fragment identifier. */ setFragment(fragment: string): Promise; /** * 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; /** * 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; /** * Update the notebook node with class indicating read-write state. */ private _updateReadWrite; /** * 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 _selectData; 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, 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 targeted by the fragment identifier. */ kind: 'heading' | 'cell-id'; value: string; } } export {};