UNPKG

11.2 kBTypeScriptView Raw
1import { ISessionContext } from '@jupyterlab/apputils';
2import { IChangedArgs } from '@jupyterlab/coreutils';
3import { DocumentRegistry, IDocumentWidget } from '@jupyterlab/docregistry';
4import { Contents, Kernel, ServiceManager } from '@jupyterlab/services';
5import { ITranslator } from '@jupyterlab/translation';
6import { IDisposable } from '@lumino/disposable';
7import { ISignal } from '@lumino/signaling';
8import { Widget } from '@lumino/widgets';
9import { IDocumentManager, IDocumentWidgetOpener, IRecentsManager } from './tokens';
10import { DocumentWidgetManager } from './widgetmanager';
11/**
12 * The document manager.
13 *
14 * #### Notes
15 * The document manager is used to register model and widget creators,
16 * and the file browser uses the document manager to create widgets. The
17 * document manager maintains a context for each path and model type that is
18 * open, and a list of widgets for each context. The document manager is in
19 * control of the proper closing and disposal of the widgets and contexts.
20 */
21export declare class DocumentManager implements IDocumentManager {
22 /**
23 * Construct a new document manager.
24 */
25 constructor(options: DocumentManager.IOptions);
26 /**
27 * The registry used by the manager.
28 */
29 readonly registry: DocumentRegistry;
30 /**
31 * The service manager used by the manager.
32 */
33 readonly services: ServiceManager.IManager;
34 /**
35 * A signal emitted when one of the documents is activated.
36 */
37 get activateRequested(): ISignal<this, string>;
38 /**
39 * Whether to autosave documents.
40 */
41 get autosave(): boolean;
42 set autosave(value: boolean);
43 /**
44 * Determines the time interval for autosave in seconds.
45 */
46 get autosaveInterval(): number;
47 set autosaveInterval(value: number);
48 /**
49 * Whether to ask confirmation to close a tab or not.
50 */
51 get confirmClosingDocument(): boolean;
52 set confirmClosingDocument(value: boolean);
53 /**
54 * Defines max acceptable difference, in milliseconds, between last modified timestamps on disk and client
55 */
56 get lastModifiedCheckMargin(): number;
57 set lastModifiedCheckMargin(value: number);
58 /**
59 * Whether to ask the user to rename untitled file on first manual save.
60 */
61 get renameUntitledFileOnSave(): boolean;
62 set renameUntitledFileOnSave(value: boolean);
63 /**
64 * Signal triggered when an attribute changes.
65 */
66 get stateChanged(): ISignal<IDocumentManager, IChangedArgs<any>>;
67 /**
68 * Get whether the document manager has been disposed.
69 */
70 get isDisposed(): boolean;
71 /**
72 * Dispose of the resources held by the document manager.
73 */
74 dispose(): void;
75 /**
76 * Clone a widget.
77 *
78 * @param widget - The source widget.
79 *
80 * @returns A new widget or `undefined`.
81 *
82 * #### Notes
83 * Uses the same widget factory and context as the source, or returns
84 * `undefined` if the source widget is not managed by this manager.
85 */
86 cloneWidget(widget: Widget): IDocumentWidget | undefined;
87 /**
88 * Close all of the open documents.
89 *
90 * @returns A promise resolving when the widgets are closed.
91 */
92 closeAll(): Promise<void>;
93 /**
94 * Close the widgets associated with a given path.
95 *
96 * @param path - The target path.
97 *
98 * @returns A promise resolving when the widgets are closed.
99 */
100 closeFile(path: string): Promise<void>;
101 /**
102 * Get the document context for a widget.
103 *
104 * @param widget - The widget of interest.
105 *
106 * @returns The context associated with the widget, or `undefined` if no such
107 * context exists.
108 */
109 contextForWidget(widget: Widget): DocumentRegistry.Context | undefined;
110 /**
111 * Copy a file.
112 *
113 * @param fromFile - The full path of the original file.
114 *
115 * @param toDir - The full path to the target directory.
116 *
117 * @returns A promise which resolves to the contents of the file.
118 */
119 copy(fromFile: string, toDir: string): Promise<Contents.IModel>;
120 /**
121 * Create a new file and return the widget used to view it.
122 *
123 * @param path - The file path to create.
124 *
125 * @param widgetName - The name of the widget factory to use. 'default' will use the default widget.
126 *
127 * @param kernel - An optional kernel name/id to override the default.
128 *
129 * @returns The created widget, or `undefined`.
130 *
131 * #### Notes
132 * This function will return `undefined` if a valid widget factory
133 * cannot be found.
134 */
135 createNew(path: string, widgetName?: string, kernel?: Partial<Kernel.IModel>): Widget | undefined;
136 /**
137 * Delete a file.
138 *
139 * @param path - The full path to the file to be deleted.
140 *
141 * @returns A promise which resolves when the file is deleted.
142 *
143 * #### Notes
144 * If there is a running session associated with the file and no other
145 * sessions are using the kernel, the session will be shut down.
146 */
147 deleteFile(path: string): Promise<void>;
148 /**
149 * Duplicate a file.
150 *
151 * @param path - The full path to the file to be duplicated.
152 *
153 * @returns A promise which resolves when the file is duplicated.
154 */
155 duplicate(path: string): Promise<Contents.IModel>;
156 /**
157 * See if a widget already exists for the given path and widget name.
158 *
159 * @param path - The file path to use.
160 *
161 * @param widgetName - The name of the widget factory to use. 'default' will use the default widget.
162 *
163 * @returns The found widget, or `undefined`.
164 *
165 * #### Notes
166 * This can be used to find an existing widget instead of opening
167 * a new widget.
168 */
169 findWidget(path: string, widgetName?: string | null): IDocumentWidget | undefined;
170 /**
171 * Create a new untitled file.
172 *
173 * @param options - The file content creation options.
174 */
175 newUntitled(options: Contents.ICreateOptions): Promise<Contents.IModel>;
176 /**
177 * Open a file and return the widget used to view it.
178 *
179 * @param path - The file path to open.
180 *
181 * @param widgetName - The name of the widget factory to use. 'default' will use the default widget.
182 *
183 * @param kernel - An optional kernel name/id to override the default.
184 *
185 * @returns The created widget, or `undefined`.
186 *
187 * #### Notes
188 * This function will return `undefined` if a valid widget factory
189 * cannot be found.
190 */
191 open(path: string, widgetName?: string, kernel?: Partial<Kernel.IModel>, options?: DocumentRegistry.IOpenOptions): IDocumentWidget | undefined;
192 /**
193 * Open a file and return the widget used to view it.
194 * Reveals an already existing editor.
195 *
196 * @param path - The file path to open.
197 *
198 * @param widgetName - The name of the widget factory to use. 'default' will use the default widget.
199 *
200 * @param kernel - An optional kernel name/id to override the default.
201 *
202 * @returns The created widget, or `undefined`.
203 *
204 * #### Notes
205 * This function will return `undefined` if a valid widget factory
206 * cannot be found.
207 */
208 openOrReveal(path: string, widgetName?: string, kernel?: Partial<Kernel.IModel>, options?: DocumentRegistry.IOpenOptions): IDocumentWidget | undefined;
209 /**
210 * Overwrite a file.
211 *
212 * @param oldPath - The full path to the original file.
213 *
214 * @param newPath - The full path to the new file.
215 *
216 * @returns A promise containing the new file contents model.
217 */
218 overwrite(oldPath: string, newPath: string): Promise<Contents.IModel>;
219 /**
220 * Rename a file or directory.
221 *
222 * @param oldPath - The full path to the original file.
223 *
224 * @param newPath - The full path to the new file.
225 *
226 * @returns A promise containing the new file contents model. The promise
227 * will reject if the newPath already exists. Use [[overwrite]] to overwrite
228 * a file.
229 */
230 rename(oldPath: string, newPath: string): Promise<Contents.IModel>;
231 /**
232 * Find a context for a given path and factory name.
233 */
234 private _findContext;
235 /**
236 * Get the contexts for a given path.
237 *
238 * #### Notes
239 * There may be more than one context for a given path if the path is open
240 * with multiple model factories (for example, a notebook can be open with a
241 * notebook model factory and a text model factory).
242 */
243 private _contextsForPath;
244 /**
245 * Create a context from a path and a model factory.
246 */
247 private _createContext;
248 /**
249 * Handle a context disposal.
250 */
251 private _onContextDisposed;
252 /**
253 * Get the widget factory for a given widget name.
254 */
255 private _widgetFactoryFor;
256 /**
257 * Creates a new document, or loads one from disk, depending on the `which` argument.
258 * If `which==='create'`, then it creates a new document. If `which==='open'`,
259 * then it loads the document from disk.
260 *
261 * The two cases differ in how the document context is handled, but the creation
262 * of the widget and launching of the kernel are identical.
263 */
264 private _createOrOpenDocument;
265 /**
266 * Handle an activateRequested signal from the widget manager.
267 */
268 private _onActivateRequested;
269 protected _onWidgetStateChanged(sender: DocumentWidgetManager, args: IChangedArgs<any>): void;
270 protected translator: ITranslator;
271 private _activateRequested;
272 private _contexts;
273 private _opener;
274 private _widgetManager;
275 private _isDisposed;
276 private _autosave;
277 private _autosaveInterval;
278 private _lastModifiedCheckMargin;
279 private _renameUntitledFileOnSave;
280 private _when;
281 private _setBusy;
282 private _dialogs;
283 private _isConnectedCallback;
284 private _stateChanged;
285}
286/**
287 * A namespace for document manager statics.
288 */
289export declare namespace DocumentManager {
290 /**
291 * The options used to initialize a document manager.
292 */
293 interface IOptions {
294 /**
295 * A document registry instance.
296 */
297 registry: DocumentRegistry;
298 /**
299 * A service manager instance.
300 */
301 manager: ServiceManager.IManager;
302 /**
303 * A widget opener for sibling widgets.
304 */
305 opener: IDocumentWidgetOpener;
306 /**
307 * A promise for when to start using the manager.
308 */
309 when?: Promise<void>;
310 /**
311 * A function called when a kernel is busy.
312 */
313 setBusy?: () => IDisposable;
314 /**
315 * The provider for session dialogs.
316 */
317 sessionDialogs?: ISessionContext.IDialogs;
318 /**
319 * The application language translator.
320 */
321 translator?: ITranslator;
322 /**
323 * Autosaving should be paused while this callback function returns `false`.
324 * By default, it always returns `true`.
325 */
326 isConnectedCallback?: () => boolean;
327 /**
328 * The manager for recent documents.
329 */
330 recentsManager?: IRecentsManager;
331 }
332}