1 | import { ISessionContext } from '@jupyterlab/apputils';
|
2 | import { Cell } from '@jupyterlab/cells';
|
3 | import * as nbformat from '@jupyterlab/nbformat';
|
4 | import { KernelMessage } from '@jupyterlab/services';
|
5 | import { ITranslator } from '@jupyterlab/translation';
|
6 | import { ISignal } from '@lumino/signaling';
|
7 | import { Notebook, StaticNotebook } from './widget';
|
8 | export declare class KernelError extends Error {
|
9 | /**
|
10 | * Exception name
|
11 | */
|
12 | readonly errorName: string;
|
13 | /**
|
14 | * Exception value
|
15 | */
|
16 | readonly errorValue: string;
|
17 | /**
|
18 | * Traceback
|
19 | */
|
20 | readonly traceback: string[];
|
21 | /**
|
22 | * Construct the kernel error.
|
23 | */
|
24 | constructor(content: KernelMessage.IExecuteReplyMsg['content']);
|
25 | }
|
26 | /**
|
27 | * A collection of actions that run against notebooks.
|
28 | *
|
29 | * #### Notes
|
30 | * All of the actions are a no-op if there is no model on the notebook.
|
31 | * The actions set the widget `mode` to `'command'` unless otherwise specified.
|
32 | * The actions will preserve the selection on the notebook widget unless
|
33 | * otherwise specified.
|
34 | */
|
35 | export declare class NotebookActions {
|
36 | /**
|
37 | * A signal that emits whenever a cell completes execution.
|
38 | */
|
39 | static get executed(): ISignal<any, {
|
40 | notebook: Notebook;
|
41 | cell: Cell;
|
42 | success: boolean;
|
43 | error?: KernelError | null;
|
44 | }>;
|
45 | /**
|
46 | * A signal that emits whenever a cell execution is scheduled.
|
47 | */
|
48 | static get executionScheduled(): ISignal<any, {
|
49 | notebook: Notebook;
|
50 | cell: Cell;
|
51 | }>;
|
52 | /**
|
53 | * A signal that emits whenever a cell execution is scheduled.
|
54 | */
|
55 | static get selectionExecuted(): ISignal<any, {
|
56 | notebook: Notebook;
|
57 | lastCell: Cell;
|
58 | }>;
|
59 | /**
|
60 | * A private constructor for the `NotebookActions` class.
|
61 | *
|
62 | * #### Notes
|
63 | * This class can never be instantiated. Its static member `executed` will be
|
64 | * merged with the `NotebookActions` namespace. The reason it exists as a
|
65 | * standalone class is because at run time, the `Private.executed` variable
|
66 | * does not yet exist, so it needs to be referenced via a getter.
|
67 | */
|
68 | private constructor();
|
69 | }
|
70 | /**
|
71 | * A namespace for `NotebookActions` static methods.
|
72 | */
|
73 | export declare namespace NotebookActions {
|
74 | /**
|
75 | * Split the active cell into two or more cells.
|
76 | *
|
77 | * @param notebook The target notebook widget.
|
78 | *
|
79 | * #### Notes
|
80 | * It will preserve the existing mode.
|
81 | * The last cell will be activated if no selection is found.
|
82 | * If text was selected, the cell containing the selection will
|
83 | * be activated.
|
84 | * The existing selection will be cleared.
|
85 | * The activated cell will have focus and the cursor will
|
86 | * remain in the initial position.
|
87 | * The leading whitespace in the second cell will be removed.
|
88 | * If there is no content, two empty cells will be created.
|
89 | * Both cells will have the same type as the original cell.
|
90 | * This action can be undone.
|
91 | */
|
92 | function splitCell(notebook: Notebook): void;
|
93 | /**
|
94 | * Merge the selected cells.
|
95 | *
|
96 | * @param notebook - The target notebook widget.
|
97 | *
|
98 | * @param mergeAbove - If only one cell is selected, indicates whether to merge it
|
99 | * with the cell above (true) or below (false, default).
|
100 | *
|
101 | * #### Notes
|
102 | * The widget mode will be preserved.
|
103 | * If only one cell is selected and `mergeAbove` is true, the above cell will be selected.
|
104 | * If only one cell is selected and `mergeAbove` is false, the below cell will be selected.
|
105 | * If the active cell is a code cell, its outputs will be cleared.
|
106 | * This action can be undone.
|
107 | * The final cell will have the same type as the active cell.
|
108 | * If the active cell is a markdown cell, it will be unrendered.
|
109 | */
|
110 | function mergeCells(notebook: Notebook, mergeAbove?: boolean): void;
|
111 | /**
|
112 | * Delete the selected cells.
|
113 | *
|
114 | * @param notebook - The target notebook widget.
|
115 | *
|
116 | * #### Notes
|
117 | * The cell after the last selected cell will be activated.
|
118 | * It will add a code cell if all cells are deleted.
|
119 | * This action can be undone.
|
120 | */
|
121 | function deleteCells(notebook: Notebook): void;
|
122 | /**
|
123 | * Insert a new code cell above the active cell.
|
124 | *
|
125 | * @param notebook - The target notebook widget.
|
126 | *
|
127 | * #### Notes
|
128 | * The widget mode will be preserved.
|
129 | * This action can be undone.
|
130 | * The existing selection will be cleared.
|
131 | * The new cell will the active cell.
|
132 | */
|
133 | function insertAbove(notebook: Notebook): void;
|
134 | /**
|
135 | * Insert a new code cell below the active cell.
|
136 | *
|
137 | * @param notebook - The target notebook widget.
|
138 | *
|
139 | * #### Notes
|
140 | * The widget mode will be preserved.
|
141 | * This action can be undone.
|
142 | * The existing selection will be cleared.
|
143 | * The new cell will be the active cell.
|
144 | */
|
145 | function insertBelow(notebook: Notebook): void;
|
146 | /**
|
147 | * Move the selected cell(s) down.
|
148 | *
|
149 | * @param notebook = The target notebook widget.
|
150 | */
|
151 | function moveDown(notebook: Notebook): void;
|
152 | /**
|
153 | * Move the selected cell(s) up.
|
154 | *
|
155 | * @param widget - The target notebook widget.
|
156 | */
|
157 | function moveUp(notebook: Notebook): void;
|
158 | /**
|
159 | * Change the selected cell type(s).
|
160 | *
|
161 | * @param notebook - The target notebook widget.
|
162 | *
|
163 | * @param value - The target cell type.
|
164 | *
|
165 | * #### Notes
|
166 | * It should preserve the widget mode.
|
167 | * This action can be undone.
|
168 | * The existing selection will be cleared.
|
169 | * Any cells converted to markdown will be unrendered.
|
170 | */
|
171 | function changeCellType(notebook: Notebook, value: nbformat.CellType): void;
|
172 | /**
|
173 | * Run the selected cell(s).
|
174 | *
|
175 | * @param notebook - The target notebook widget.
|
176 | *
|
177 | * @param sessionContext - The optional client session object.
|
178 | *
|
179 | * #### Notes
|
180 | * The last selected cell will be activated, but not scrolled into view.
|
181 | * The existing selection will be cleared.
|
182 | * An execution error will prevent the remaining code cells from executing.
|
183 | * All markdown cells will be rendered.
|
184 | */
|
185 | function run(notebook: Notebook, sessionContext?: ISessionContext): Promise<boolean>;
|
186 | /**
|
187 | * Run the selected cell(s) and advance to the next cell.
|
188 | *
|
189 | * @param notebook - The target notebook widget.
|
190 | *
|
191 | * @param sessionContext - The optional client session object.
|
192 | *
|
193 | * #### Notes
|
194 | * The existing selection will be cleared.
|
195 | * The cell after the last selected cell will be activated and scrolled into view.
|
196 | * An execution error will prevent the remaining code cells from executing.
|
197 | * All markdown cells will be rendered.
|
198 | * If the last selected cell is the last cell, a new code cell
|
199 | * will be created in `'edit'` mode. The new cell creation can be undone.
|
200 | */
|
201 | function runAndAdvance(notebook: Notebook, sessionContext?: ISessionContext): Promise<boolean>;
|
202 | /**
|
203 | * Run the selected cell(s) and insert a new code cell.
|
204 | *
|
205 | * @param notebook - The target notebook widget.
|
206 | *
|
207 | * @param sessionContext - The optional client session object.
|
208 | *
|
209 | * #### Notes
|
210 | * An execution error will prevent the remaining code cells from executing.
|
211 | * All markdown cells will be rendered.
|
212 | * The widget mode will be set to `'edit'` after running.
|
213 | * The existing selection will be cleared.
|
214 | * The cell insert can be undone.
|
215 | * The new cell will be scrolled into view.
|
216 | */
|
217 | function runAndInsert(notebook: Notebook, sessionContext?: ISessionContext): Promise<boolean>;
|
218 | /**
|
219 | * Run all of the cells in the notebook.
|
220 | *
|
221 | * @param notebook - The target notebook widget.
|
222 | *
|
223 | * @param sessionContext - The optional client session object.
|
224 | *
|
225 | * #### Notes
|
226 | * The existing selection will be cleared.
|
227 | * An execution error will prevent the remaining code cells from executing.
|
228 | * All markdown cells will be rendered.
|
229 | * The last cell in the notebook will be activated and scrolled into view.
|
230 | */
|
231 | function runAll(notebook: Notebook, sessionContext?: ISessionContext): Promise<boolean>;
|
232 | function renderAllMarkdown(notebook: Notebook, sessionContext?: ISessionContext): Promise<boolean>;
|
233 | /**
|
234 | * Run all of the cells before the currently active cell (exclusive).
|
235 | *
|
236 | * @param notebook - The target notebook widget.
|
237 | *
|
238 | * @param sessionContext - The optional client session object.
|
239 | *
|
240 | * #### Notes
|
241 | * The existing selection will be cleared.
|
242 | * An execution error will prevent the remaining code cells from executing.
|
243 | * All markdown cells will be rendered.
|
244 | * The currently active cell will remain selected.
|
245 | */
|
246 | function runAllAbove(notebook: Notebook, sessionContext?: ISessionContext): Promise<boolean>;
|
247 | /**
|
248 | * Run all of the cells after the currently active cell (inclusive).
|
249 | *
|
250 | * @param notebook - The target notebook widget.
|
251 | *
|
252 | * @param sessionContext - The optional client session object.
|
253 | *
|
254 | * #### Notes
|
255 | * The existing selection will be cleared.
|
256 | * An execution error will prevent the remaining code cells from executing.
|
257 | * All markdown cells will be rendered.
|
258 | * The last cell in the notebook will be activated and scrolled into view.
|
259 | */
|
260 | function runAllBelow(notebook: Notebook, sessionContext?: ISessionContext): Promise<boolean>;
|
261 | /**
|
262 | * Replaces the selection in the active cell of the notebook.
|
263 | *
|
264 | * @param notebook - The target notebook widget.
|
265 | * @param text - The text to replace the selection.
|
266 | */
|
267 | function replaceSelection(notebook: Notebook, text: string): void;
|
268 | /**
|
269 | * Select the above the active cell.
|
270 | *
|
271 | * @param notebook - The target notebook widget.
|
272 | *
|
273 | * #### Notes
|
274 | * The widget mode will be preserved.
|
275 | * This is a no-op if the first cell is the active cell.
|
276 | * This will skip any collapsed cells.
|
277 | * The existing selection will be cleared.
|
278 | */
|
279 | function selectAbove(notebook: Notebook): void;
|
280 | /**
|
281 | * Select the cell below the active cell.
|
282 | *
|
283 | * @param notebook - The target notebook widget.
|
284 | *
|
285 | * #### Notes
|
286 | * The widget mode will be preserved.
|
287 | * This is a no-op if the last cell is the active cell.
|
288 | * This will skip any collapsed cells.
|
289 | * The existing selection will be cleared.
|
290 | */
|
291 | function selectBelow(notebook: Notebook): void;
|
292 | /**
|
293 | * Extend the selection to the cell above.
|
294 | *
|
295 | * @param notebook - The target notebook widget.
|
296 | * @param toTop - If true, denotes selection to extend to the top.
|
297 | *
|
298 | * #### Notes
|
299 | * This is a no-op if the first cell is the active cell.
|
300 | * The new cell will be activated.
|
301 | */
|
302 | function extendSelectionAbove(notebook: Notebook, toTop?: boolean): void;
|
303 | /**
|
304 | * Extend the selection to the cell below.
|
305 | *
|
306 | * @param notebook - The target notebook widget.
|
307 | * @param toBottom - If true, denotes selection to extend to the bottom.
|
308 | *
|
309 | * #### Notes
|
310 | * This is a no-op if the last cell is the active cell.
|
311 | * The new cell will be activated.
|
312 | */
|
313 | function extendSelectionBelow(notebook: Notebook, toBottom?: boolean): void;
|
314 | /**
|
315 | * Select all of the cells of the notebook.
|
316 | *
|
317 | * @param notebook - the target notebook widget.
|
318 | */
|
319 | function selectAll(notebook: Notebook): void;
|
320 | /**
|
321 | * Deselect all of the cells of the notebook.
|
322 | *
|
323 | * @param notebook - the target notebook widget.
|
324 | */
|
325 | function deselectAll(notebook: Notebook): void;
|
326 | /**
|
327 | * Copy the selected cell(s) data to a clipboard.
|
328 | *
|
329 | * @param notebook - The target notebook widget.
|
330 | */
|
331 | function copy(notebook: Notebook): void;
|
332 | /**
|
333 | * Cut the selected cell data to a clipboard.
|
334 | *
|
335 | * @param notebook - The target notebook widget.
|
336 | *
|
337 | * #### Notes
|
338 | * This action can be undone.
|
339 | * A new code cell is added if all cells are cut.
|
340 | */
|
341 | function cut(notebook: Notebook): void;
|
342 | /**
|
343 | * Paste cells from the application clipboard.
|
344 | *
|
345 | * @param notebook - The target notebook widget.
|
346 | *
|
347 | * @param mode - the mode of adding cells:
|
348 | * 'below' (default) adds cells below the active cell,
|
349 | * 'belowSelected' adds cells below all selected cells,
|
350 | * 'above' adds cells above the active cell, and
|
351 | * 'replace' removes the currently selected cells and adds cells in their place.
|
352 | *
|
353 | * #### Notes
|
354 | * The last pasted cell becomes the active cell.
|
355 | * This is a no-op if there is no cell data on the clipboard.
|
356 | * This action can be undone.
|
357 | */
|
358 | function paste(notebook: Notebook, mode?: 'below' | 'belowSelected' | 'above' | 'replace'): void;
|
359 | /**
|
360 | * Duplicate selected cells in the notebook without using the application clipboard.
|
361 | *
|
362 | * @param notebook - The target notebook widget.
|
363 | *
|
364 | * @param mode - the mode of adding cells:
|
365 | * 'below' (default) adds cells below the active cell,
|
366 | * 'belowSelected' adds cells below all selected cells,
|
367 | * 'above' adds cells above the active cell, and
|
368 | * 'replace' removes the currently selected cells and adds cells in their place.
|
369 | *
|
370 | * #### Notes
|
371 | * The last pasted cell becomes the active cell.
|
372 | * This is a no-op if there is no cell data on the clipboard.
|
373 | * This action can be undone.
|
374 | */
|
375 | function duplicate(notebook: Notebook, mode?: 'below' | 'belowSelected' | 'above' | 'replace'): void;
|
376 | /**
|
377 | * Undo a cell action.
|
378 | *
|
379 | * @param notebook - The target notebook widget.
|
380 | *
|
381 | * #### Notes
|
382 | * This is a no-op if if there are no cell actions to undo.
|
383 | */
|
384 | function undo(notebook: Notebook): void;
|
385 | /**
|
386 | * Redo a cell action.
|
387 | *
|
388 | * @param notebook - The target notebook widget.
|
389 | *
|
390 | * #### Notes
|
391 | * This is a no-op if there are no cell actions to redo.
|
392 | */
|
393 | function redo(notebook: Notebook): void;
|
394 | /**
|
395 | * Toggle the line number of all cells.
|
396 | *
|
397 | * @param notebook - The target notebook widget.
|
398 | *
|
399 | * #### Notes
|
400 | * The original state is based on the state of the active cell.
|
401 | * The `mode` of the widget will be preserved.
|
402 | */
|
403 | function toggleAllLineNumbers(notebook: Notebook): void;
|
404 | /**
|
405 | * Clear the code outputs of the selected cells.
|
406 | *
|
407 | * @param notebook - The target notebook widget.
|
408 | *
|
409 | * #### Notes
|
410 | * The widget `mode` will be preserved.
|
411 | */
|
412 | function clearOutputs(notebook: Notebook): void;
|
413 | /**
|
414 | * Clear all the code outputs on the widget.
|
415 | *
|
416 | * @param notebook - The target notebook widget.
|
417 | *
|
418 | * #### Notes
|
419 | * The widget `mode` will be preserved.
|
420 | */
|
421 | function clearAllOutputs(notebook: Notebook): void;
|
422 | /**
|
423 | * Hide the code on selected code cells.
|
424 | *
|
425 | * @param notebook - The target notebook widget.
|
426 | */
|
427 | function hideCode(notebook: Notebook): void;
|
428 | /**
|
429 | * Show the code on selected code cells.
|
430 | *
|
431 | * @param notebook - The target notebook widget.
|
432 | */
|
433 | function showCode(notebook: Notebook): void;
|
434 | /**
|
435 | * Hide the code on all code cells.
|
436 | *
|
437 | * @param notebook - The target notebook widget.
|
438 | */
|
439 | function hideAllCode(notebook: Notebook): void;
|
440 | /**
|
441 | * Show the code on all code cells.
|
442 | *
|
443 | * @param widget - The target notebook widget.
|
444 | */
|
445 | function showAllCode(notebook: Notebook): void;
|
446 | /**
|
447 | * Hide the output on selected code cells.
|
448 | *
|
449 | * @param notebook - The target notebook widget.
|
450 | */
|
451 | function hideOutput(notebook: Notebook): void;
|
452 | /**
|
453 | * Show the output on selected code cells.
|
454 | *
|
455 | * @param notebook - The target notebook widget.
|
456 | */
|
457 | function showOutput(notebook: Notebook): void;
|
458 | /**
|
459 | * Hide the output on all code cells.
|
460 | *
|
461 | * @param notebook - The target notebook widget.
|
462 | */
|
463 | function hideAllOutputs(notebook: Notebook): void;
|
464 | /**
|
465 | * Render side-by-side.
|
466 | *
|
467 | * @param notebook - The target notebook widget.
|
468 | */
|
469 | function renderSideBySide(notebook: Notebook): void;
|
470 | /**
|
471 | * Render not side-by-side.
|
472 | *
|
473 | * @param notebook - The target notebook widget.
|
474 | */
|
475 | function renderDefault(notebook: Notebook): void;
|
476 | /**
|
477 | * Show the output on all code cells.
|
478 | *
|
479 | * @param notebook - The target notebook widget.
|
480 | */
|
481 | function showAllOutputs(notebook: Notebook): void;
|
482 | /**
|
483 | * Enable output scrolling for all selected cells.
|
484 | *
|
485 | * @param notebook - The target notebook widget.
|
486 | */
|
487 | function enableOutputScrolling(notebook: Notebook): void;
|
488 | /**
|
489 | * Disable output scrolling for all selected cells.
|
490 | *
|
491 | * @param notebook - The target notebook widget.
|
492 | */
|
493 | function disableOutputScrolling(notebook: Notebook): void;
|
494 | /**
|
495 | * Go to the last cell that is run or current if it is running.
|
496 | *
|
497 | * Note: This requires execution timing to be toggled on or this will have
|
498 | * no effect.
|
499 | *
|
500 | * @param notebook - The target notebook widget.
|
501 | */
|
502 | function selectLastRunCell(notebook: Notebook): void;
|
503 | /**
|
504 | * Set the markdown header level.
|
505 | *
|
506 | * @param notebook - The target notebook widget.
|
507 | *
|
508 | * @param level - The header level.
|
509 | *
|
510 | * #### Notes
|
511 | * All selected cells will be switched to markdown.
|
512 | * The level will be clamped between 1 and 6.
|
513 | * If there is an existing header, it will be replaced.
|
514 | * There will always be one blank space after the header.
|
515 | * The cells will be unrendered.
|
516 | */
|
517 | function setMarkdownHeader(notebook: Notebook, level: number): void;
|
518 | /**
|
519 | * Collapse all cells in given notebook.
|
520 | *
|
521 | * @param notebook - The target notebook widget.
|
522 | */
|
523 | function collapseAll(notebook: Notebook): any;
|
524 | /**
|
525 | * Un-collapse all cells in given notebook.
|
526 | *
|
527 | * @param notebook - The target notebook widget.
|
528 | */
|
529 | function expandAllHeadings(notebook: Notebook): any;
|
530 | /**
|
531 | * Finds the "parent" heading of the given cell and expands.
|
532 | * Used for the case that a cell becomes active that is within a collapsed heading.
|
533 | * @param cell - "Child" cell that has become the active cell
|
534 | * @param notebook - The target notebook widget.
|
535 | */
|
536 | function expandParent(cell: Cell, notebook: Notebook): void;
|
537 | /**
|
538 | * Finds the next heading that isn't a child of the given markdown heading.
|
539 | * @param cell - "Child" cell that has become the active cell
|
540 | * @param notebook - The target notebook widget.
|
541 | */
|
542 | function findNextParentHeading(cell: Cell, notebook: Notebook): number;
|
543 | /**
|
544 | * Set the given cell and ** all "child" cells **
|
545 | * to the given collapse / expand if cell is
|
546 | * a markdown header.
|
547 | *
|
548 | * @param cell - The cell
|
549 | * @param collapsing - Whether to collapse or expand the cell
|
550 | * @param notebook - The target notebook widget.
|
551 | */
|
552 | function setHeadingCollapse(cell: Cell, collapsing: boolean, notebook: StaticNotebook): number;
|
553 | /**
|
554 | * Toggles the collapse state of the active cell of the given notebook
|
555 | * and ** all of its "child" cells ** if the cell is a heading.
|
556 | *
|
557 | * @param notebook - The target notebook widget.
|
558 | */
|
559 | function toggleCurrentHeadingCollapse(notebook: Notebook): any;
|
560 | /**
|
561 | * If cell is a markdown heading, sets the headingCollapsed field,
|
562 | * and otherwise hides the cell.
|
563 | *
|
564 | * @param cell - The cell to collapse / expand
|
565 | * @param collapsing - Whether to collapse or expand the given cell
|
566 | */
|
567 | function setCellCollapse(cell: Cell, collapsing: boolean): any;
|
568 | /**
|
569 | * If given cell is a markdown heading, returns the heading level.
|
570 | * If given cell is not markdown, returns 7 (there are only 6 levels of markdown headings)
|
571 | *
|
572 | * @param cell - The target cell widget.
|
573 | */
|
574 | function getHeadingInfo(cell: Cell): {
|
575 | isHeading: boolean;
|
576 | headingLevel: number;
|
577 | collapsed?: boolean;
|
578 | };
|
579 | /**
|
580 | * Trust the notebook after prompting the user.
|
581 | *
|
582 | * @param notebook - The target notebook widget.
|
583 | *
|
584 | * @returns a promise that resolves when the transaction is finished.
|
585 | *
|
586 | * #### Notes
|
587 | * No dialog will be presented if the notebook is already trusted.
|
588 | */
|
589 | function trust(notebook: Notebook, translator?: ITranslator): Promise<void>;
|
590 | }
|