1 | import { DocumentRegistry } from '@jupyterlab/docregistry';
|
2 | import { ITranslator } from '@jupyterlab/translation';
|
3 | import { Token } from '@lumino/coreutils';
|
4 | import { Message } from '@lumino/messaging';
|
5 | import { ISignal } from '@lumino/signaling';
|
6 | import { DockLayout, DockPanel, FocusTracker, TabBar, Widget } from '@lumino/widgets';
|
7 | import { JupyterFrontEnd } from './frontend';
|
8 | import { LayoutRestorer } from './layoutrestorer';
|
9 | /**
|
10 | * The JupyterLab application shell token.
|
11 | */
|
12 | export declare const ILabShell: Token<ILabShell>;
|
13 | /**
|
14 | * The JupyterLab application shell interface.
|
15 | */
|
16 | export interface ILabShell extends LabShell {
|
17 | }
|
18 | /**
|
19 | * The namespace for `ILabShell` type information.
|
20 | */
|
21 | export declare namespace ILabShell {
|
22 | /**
|
23 | * The areas of the application shell where widgets can reside.
|
24 | */
|
25 | type Area = 'main' | 'header' | 'top' | 'menu' | 'left' | 'right' | 'bottom' | 'down';
|
26 | /**
|
27 | * The restorable description of an area within the main dock panel.
|
28 | */
|
29 | type AreaConfig = DockLayout.AreaConfig;
|
30 | /**
|
31 | * An options object for creating a lab shell object.
|
32 | */
|
33 | type IOptions = {
|
34 | /**
|
35 | * Whether the layout should wait to be restored before adding widgets or not.
|
36 | *
|
37 | * #### Notes
|
38 | * It defaults to true
|
39 | */
|
40 | waitForRestore?: boolean;
|
41 | };
|
42 | /**
|
43 | * An arguments object for the changed signals.
|
44 | */
|
45 | type IChangedArgs = FocusTracker.IChangedArgs<Widget>;
|
46 | interface IConfig {
|
47 | /**
|
48 | * The method for hiding widgets in the dock panel.
|
49 | *
|
50 | * The default is `display`.
|
51 | *
|
52 | * Using `scale` will often increase performance as most browsers will not trigger style computation
|
53 | * for the transform action.
|
54 | *
|
55 | * `contentVisibility` is only available in Chromium-based browsers.
|
56 | */
|
57 | hiddenMode: 'display' | 'scale' | 'contentVisibility';
|
58 | }
|
59 | /**
|
60 | * Widget position
|
61 | */
|
62 | interface IWidgetPosition {
|
63 | /**
|
64 | * Widget area
|
65 | */
|
66 | area?: Area;
|
67 | /**
|
68 | * Widget opening options
|
69 | */
|
70 | options?: DocumentRegistry.IOpenOptions;
|
71 | }
|
72 | /**
|
73 | * To-be-added widget and associated position
|
74 | */
|
75 | interface IDelayedWidget extends IWidgetPosition {
|
76 | widget: Widget;
|
77 | }
|
78 | /**
|
79 | * Mapping of widget type identifier and their user customized position
|
80 | */
|
81 | interface IUserLayout {
|
82 | /**
|
83 | * Widget customized position
|
84 | */
|
85 | [k: string]: IWidgetPosition;
|
86 | }
|
87 | /**
|
88 | * The args for the current path change signal.
|
89 | */
|
90 | interface ICurrentPathChangedArgs {
|
91 | /**
|
92 | * The new value of the tree path, not including '/tree'.
|
93 | */
|
94 | oldValue: string;
|
95 | /**
|
96 | * The old value of the tree path, not including '/tree'.
|
97 | */
|
98 | newValue: string;
|
99 | }
|
100 | /**
|
101 | * A description of the application's user interface layout.
|
102 | */
|
103 | interface ILayout {
|
104 | /**
|
105 | * Indicates whether fetched session restore data was actually retrieved
|
106 | * from the state database or whether it is a fresh blank slate.
|
107 | *
|
108 | * #### Notes
|
109 | * This attribute is only relevant when the layout data is retrieved via a
|
110 | * `fetch` call. If it is set when being passed into `save`, it will be
|
111 | * ignored.
|
112 | */
|
113 | readonly fresh?: boolean;
|
114 | /**
|
115 | * The main area of the user interface.
|
116 | */
|
117 | readonly mainArea: IMainArea | null;
|
118 | /**
|
119 | * The down area of the user interface.
|
120 | */
|
121 | readonly downArea: IDownArea | null;
|
122 | /**
|
123 | * The left area of the user interface.
|
124 | */
|
125 | readonly leftArea: ISideArea | null;
|
126 | /**
|
127 | * The right area of the user interface.
|
128 | */
|
129 | readonly rightArea: ISideArea | null;
|
130 | /**
|
131 | * The top area of the user interface.
|
132 | */
|
133 | readonly topArea: ITopArea | null;
|
134 | /**
|
135 | * The relatives sizes of the areas of the user interface.
|
136 | */
|
137 | readonly relativeSizes: number[] | null;
|
138 | }
|
139 | /**
|
140 | * The restorable description of the main application area.
|
141 | */
|
142 | interface IMainArea {
|
143 | /**
|
144 | * The current widget that has application focus.
|
145 | */
|
146 | readonly currentWidget: Widget | null;
|
147 | /**
|
148 | * The contents of the main application dock panel.
|
149 | */
|
150 | readonly dock: DockLayout.ILayoutConfig | null;
|
151 | }
|
152 | interface IDownArea {
|
153 | /**
|
154 | * The current widget that has down area focus.
|
155 | */
|
156 | readonly currentWidget: Widget | null;
|
157 | /**
|
158 | * The collection of widgets held by the panel.
|
159 | */
|
160 | readonly widgets: Array<Widget> | null;
|
161 | /**
|
162 | * Vertical relative size of the down area
|
163 | *
|
164 | * The main area will take the rest of the height
|
165 | */
|
166 | readonly size: number | null;
|
167 | }
|
168 | /**
|
169 | * The restorable description of a sidebar in the user interface.
|
170 | */
|
171 | interface ISideArea {
|
172 | /**
|
173 | * A flag denoting whether the sidebar has been collapsed.
|
174 | */
|
175 | readonly collapsed: boolean;
|
176 | /**
|
177 | * The current widget that has side area focus.
|
178 | */
|
179 | readonly currentWidget: Widget | null;
|
180 | /**
|
181 | * A flag denoting whether the side tab bar is visible.
|
182 | */
|
183 | readonly visible: boolean;
|
184 | /**
|
185 | * The collection of widgets held by the sidebar.
|
186 | */
|
187 | readonly widgets: Array<Widget> | null;
|
188 | }
|
189 | }
|
190 | /**
|
191 | * The restorable description of the top area in the user interface.
|
192 | */
|
193 | export interface ITopArea {
|
194 | /**
|
195 | * Top area visibility in simple mode.
|
196 | */
|
197 | readonly simpleVisibility: boolean;
|
198 | }
|
199 | /**
|
200 | * The application shell for JupyterLab.
|
201 | */
|
202 | export declare class LabShell extends Widget implements JupyterFrontEnd.IShell {
|
203 | /**
|
204 | * Construct a new application shell.
|
205 | */
|
206 | constructor(options?: ILabShell.IOptions);
|
207 | /**
|
208 | * A signal emitted when main area's active focus changes.
|
209 | */
|
210 | get activeChanged(): ISignal<this, ILabShell.IChangedArgs>;
|
211 | /**
|
212 | * The active widget in the shell's main area.
|
213 | */
|
214 | get activeWidget(): Widget | null;
|
215 | /**
|
216 | * Whether the add buttons for each main area tab bar are enabled.
|
217 | */
|
218 | get addButtonEnabled(): boolean;
|
219 | set addButtonEnabled(value: boolean);
|
220 | /**
|
221 | * A signal emitted when the add button on a main area tab bar is clicked.
|
222 | */
|
223 | get addRequested(): ISignal<DockPanel, TabBar<Widget>>;
|
224 | /**
|
225 | * A signal emitted when main area's current focus changes.
|
226 | */
|
227 | get currentChanged(): ISignal<this, ILabShell.IChangedArgs>;
|
228 | /**
|
229 | * Current document path.
|
230 | */
|
231 | get currentPath(): string | null | undefined;
|
232 | /**
|
233 | * A signal emitted when the path of the current document changes.
|
234 | *
|
235 | * This also fires when the current document itself changes.
|
236 | */
|
237 | get currentPathChanged(): ISignal<this, ILabShell.ICurrentPathChangedArgs>;
|
238 | /**
|
239 | * The current widget in the shell's main area.
|
240 | */
|
241 | get currentWidget(): Widget | null;
|
242 | /**
|
243 | * A signal emitted when the main area's layout is modified.
|
244 | */
|
245 | get layoutModified(): ISignal<this, void>;
|
246 | /**
|
247 | * Whether the left area is collapsed.
|
248 | */
|
249 | get leftCollapsed(): boolean;
|
250 | /**
|
251 | * Whether the left area is collapsed.
|
252 | */
|
253 | get rightCollapsed(): boolean;
|
254 | /**
|
255 | * Whether JupyterLab is in presentation mode with the
|
256 | * `jp-mod-presentationMode` CSS class.
|
257 | */
|
258 | get presentationMode(): boolean;
|
259 | set presentationMode(value: boolean);
|
260 | /**
|
261 | * The main dock area's user interface mode.
|
262 | */
|
263 | get mode(): DockPanel.Mode;
|
264 | set mode(mode: DockPanel.Mode);
|
265 | /**
|
266 | * A signal emitted when the shell/dock panel change modes (single/multiple document).
|
267 | */
|
268 | get modeChanged(): ISignal<this, DockPanel.Mode>;
|
269 | /**
|
270 | * Promise that resolves when state is first restored, returning layout
|
271 | * description.
|
272 | */
|
273 | get restored(): Promise<ILabShell.ILayout>;
|
274 | get translator(): ITranslator;
|
275 | set translator(value: ITranslator);
|
276 | /**
|
277 | * User customized shell layout.
|
278 | */
|
279 | get userLayout(): {
|
280 | 'single-document': ILabShell.IUserLayout;
|
281 | 'multiple-document': ILabShell.IUserLayout;
|
282 | };
|
283 | /**
|
284 | * Activate a widget in its area.
|
285 | */
|
286 | activateById(id: string): void;
|
287 | /**
|
288 | * Activate the next Tab in the active TabBar.
|
289 | */
|
290 | activateNextTab(): void;
|
291 | /**
|
292 | * Activate the previous Tab in the active TabBar.
|
293 | */
|
294 | activatePreviousTab(): void;
|
295 | /**
|
296 | * Activate the next TabBar.
|
297 | */
|
298 | activateNextTabBar(): void;
|
299 | /**
|
300 | * Activate the next TabBar.
|
301 | */
|
302 | activatePreviousTabBar(): void;
|
303 | /**
|
304 | * Add a widget to the JupyterLab shell
|
305 | *
|
306 | * @param widget Widget
|
307 | * @param area Area
|
308 | * @param options Options
|
309 | */
|
310 | add(widget: Widget, area?: ILabShell.Area, options?: DocumentRegistry.IOpenOptions): void;
|
311 | /**
|
312 | * Move a widget type to a new area.
|
313 | *
|
314 | * The type is determined from the `widget.id` and fallback to `widget.id`.
|
315 | *
|
316 | * #### Notes
|
317 | * If `mode` is undefined, both mode are updated.
|
318 | * The new layout is now persisted.
|
319 | *
|
320 | * @param widget Widget to move
|
321 | * @param area New area
|
322 | * @param mode Mode to change
|
323 | * @returns The new user layout
|
324 | */
|
325 | move(widget: Widget, area: ILabShell.Area, mode?: DockPanel.Mode): {
|
326 | 'single-document': ILabShell.IUserLayout;
|
327 | 'multiple-document': ILabShell.IUserLayout;
|
328 | };
|
329 | /**
|
330 | * Collapse the left area.
|
331 | */
|
332 | collapseLeft(): void;
|
333 | /**
|
334 | * Collapse the right area.
|
335 | */
|
336 | collapseRight(): void;
|
337 | /**
|
338 | * Dispose the shell.
|
339 | */
|
340 | dispose(): void;
|
341 | /**
|
342 | * Expand the left area.
|
343 | *
|
344 | * #### Notes
|
345 | * This will open the most recently used tab,
|
346 | * or the first tab if there is no most recently used.
|
347 | */
|
348 | expandLeft(): void;
|
349 | /**
|
350 | * Expand the right area.
|
351 | *
|
352 | * #### Notes
|
353 | * This will open the most recently used tab,
|
354 | * or the first tab if there is no most recently used.
|
355 | */
|
356 | expandRight(): void;
|
357 | /**
|
358 | * Close all widgets in the main and down area.
|
359 | */
|
360 | closeAll(): void;
|
361 | /**
|
362 | * Whether an side tab bar is visible or not.
|
363 | *
|
364 | * @param side Sidebar of interest
|
365 | * @returns Side tab bar visibility
|
366 | */
|
367 | isSideTabBarVisible(side: 'left' | 'right'): boolean;
|
368 | /**
|
369 | * Whether the top bar in simple mode is visible or not.
|
370 | *
|
371 | * @returns Top bar visibility
|
372 | */
|
373 | isTopInSimpleModeVisible(): boolean;
|
374 | /**
|
375 | * True if the given area is empty.
|
376 | */
|
377 | isEmpty(area: ILabShell.Area): boolean;
|
378 | /**
|
379 | * Restore the layout state and configuration for the application shell.
|
380 | *
|
381 | * #### Notes
|
382 | * This should only be called once.
|
383 | */
|
384 | restoreLayout(mode: DockPanel.Mode, layoutRestorer: LayoutRestorer, configuration?: {
|
385 | [m: string]: ILabShell.IUserLayout;
|
386 | }): Promise<void>;
|
387 | /**
|
388 | * Save the dehydrated state of the application shell.
|
389 | */
|
390 | saveLayout(): ILabShell.ILayout;
|
391 | /**
|
392 | * Toggle top header visibility in simple mode
|
393 | *
|
394 | * Note: Does nothing in multi-document mode
|
395 | */
|
396 | toggleTopInSimpleModeVisibility(): void;
|
397 | /**
|
398 | * Toggle side tab bar visibility
|
399 | *
|
400 | * @param side Sidebar of interest
|
401 | */
|
402 | toggleSideTabBarVisibility(side: 'right' | 'left'): void;
|
403 | /**
|
404 | * Update the shell configuration.
|
405 | *
|
406 | * @param config Shell configuration
|
407 | */
|
408 | updateConfig(config: Partial<ILabShell.IConfig>): void;
|
409 | /**
|
410 | * Returns the widgets for an application area.
|
411 | */
|
412 | widgets(area?: ILabShell.Area): IterableIterator<Widget>;
|
413 | /**
|
414 | * Handle `after-attach` messages for the application shell.
|
415 | */
|
416 | protected onAfterAttach(msg: Message): void;
|
417 | /**
|
418 | * Update the title panel title based on the title of the current widget.
|
419 | */
|
420 | private _updateTitlePanelTitle;
|
421 | /**
|
422 | * The path of the current widget changed, fire the _currentPathChanged signal.
|
423 | */
|
424 | private _updateCurrentPath;
|
425 | /**
|
426 | * Add a widget to the left content area.
|
427 | *
|
428 | * #### Notes
|
429 | * Widgets must have a unique `id` property, which will be used as the DOM id.
|
430 | */
|
431 | private _addToLeftArea;
|
432 | /**
|
433 | * Add a widget to the main content area.
|
434 | *
|
435 | * #### Notes
|
436 | * Widgets must have a unique `id` property, which will be used as the DOM id.
|
437 | * All widgets added to the main area should be disposed after removal
|
438 | * (disposal before removal will remove the widget automatically).
|
439 | *
|
440 | * In the options, `ref` defaults to `null`, `mode` defaults to `'tab-after'`,
|
441 | * and `activate` defaults to `true`.
|
442 | */
|
443 | private _addToMainArea;
|
444 | /**
|
445 | * Add a widget to the right content area.
|
446 | *
|
447 | * #### Notes
|
448 | * Widgets must have a unique `id` property, which will be used as the DOM id.
|
449 | */
|
450 | private _addToRightArea;
|
451 | /**
|
452 | * Add a widget to the top content area.
|
453 | *
|
454 | * #### Notes
|
455 | * Widgets must have a unique `id` property, which will be used as the DOM id.
|
456 | */
|
457 | private _addToTopArea;
|
458 | /**
|
459 | * Add a widget to the title content area.
|
460 | *
|
461 | * #### Notes
|
462 | * Widgets must have a unique `id` property, which will be used as the DOM id.
|
463 | */
|
464 | private _addToMenuArea;
|
465 | /**
|
466 | * Add a widget to the header content area.
|
467 | *
|
468 | * #### Notes
|
469 | * Widgets must have a unique `id` property, which will be used as the DOM id.
|
470 | */
|
471 | private _addToHeaderArea;
|
472 | /**
|
473 | * Add a widget to the bottom content area.
|
474 | *
|
475 | * #### Notes
|
476 | * Widgets must have a unique `id` property, which will be used as the DOM id.
|
477 | */
|
478 | private _addToBottomArea;
|
479 | private _addToDownArea;
|
480 | private _adjacentBar;
|
481 | private _currentTabBar;
|
482 | /**
|
483 | * Handle a change to the dock area active widget.
|
484 | */
|
485 | private _onActiveChanged;
|
486 | /**
|
487 | * Handle a change to the dock area current widget.
|
488 | */
|
489 | private _onCurrentChanged;
|
490 | /**
|
491 | * Handle a change on the down panel widgets
|
492 | */
|
493 | private _onTabPanelChanged;
|
494 | /**
|
495 | * Handle a change to the layout.
|
496 | */
|
497 | private _onLayoutModified;
|
498 | /**
|
499 | * A message hook for child add/remove messages on the main area dock panel.
|
500 | */
|
501 | private _dockChildHook;
|
502 | private _activeChanged;
|
503 | private _cachedLayout;
|
504 | private _currentChanged;
|
505 | private _currentPath;
|
506 | private _currentPathChanged;
|
507 | private _modeChanged;
|
508 | private _dockPanel;
|
509 | private _downPanel;
|
510 | private _isRestored;
|
511 | private _layoutModified;
|
512 | private _layoutDebouncer;
|
513 | private _leftHandler;
|
514 | private _restored;
|
515 | private _rightHandler;
|
516 | private _tracker;
|
517 | private _headerPanel;
|
518 | private _hsplitPanel;
|
519 | private _vsplitPanel;
|
520 | private _topHandler;
|
521 | private _topHandlerHiddenByUser;
|
522 | private _menuHandler;
|
523 | private _skipLinkWidget;
|
524 | private _titleHandler;
|
525 | private _bottomPanel;
|
526 | private _idTypeMap;
|
527 | private _mainOptionsCache;
|
528 | private _sideOptionsCache;
|
529 | private _userLayout;
|
530 | private _delayedWidget;
|
531 | private _translator;
|
532 | private _layoutRestorer;
|
533 | }
|