@jupyterlab/docmanager
- Version 4.2.5
- Published
- 232 kB
- 17 dependencies
- BSD-3-Clause license
Install
npm i @jupyterlab/docmanager
yarn add @jupyterlab/docmanager
pnpm add @jupyterlab/docmanager
Overview
docmanager
Index
Variables
Functions
Classes
DocumentManager
- activateRequested
- autosave
- autosaveInterval
- cloneWidget()
- closeAll()
- closeFile()
- confirmClosingDocument
- contextForWidget()
- copy()
- createNew()
- deleteFile()
- dispose()
- duplicate()
- findWidget()
- isDisposed
- lastModifiedCheckMargin
- newUntitled()
- open()
- openOrReveal()
- overwrite()
- registry
- rename()
- renameUntitledFileOnSave
- services
- stateChanged
- translator
Interfaces
Type Aliases
Namespaces
Variables
variable IDocumentManager
const IDocumentManager: Token<IDocumentManager>;
The document registry token.
variable IDocumentWidgetOpener
const IDocumentWidgetOpener: Token<IDocumentWidgetOpener>;
The document widget opener token.
variable IRecentsManager
const IRecentsManager: Token<IRecentsManager>;
The recent documents database token.
Functions
function isValidFileName
isValidFileName: (name: string) => boolean;
Test whether a name is a valid file name
Disallows "/", "", and ":" in file names, as well as names with zero length.
function renameDialog
renameDialog: ( manager: IDocumentManager, context: DocumentRegistry.Context, translator?: ITranslator) => Promise<void | null>;
Rename a file with a dialog.
function renameFile
renameFile: ( manager: IDocumentManager, oldPath: string, newPath: string) => Promise<Contents.IModel | null>;
Rename a file, asking for confirmation if it is overwriting another.
function shouldOverwrite
shouldOverwrite: (path: string, translator?: ITranslator) => Promise<boolean>;
Ask the user whether to overwrite a file.
Classes
class DocumentManager
class DocumentManager implements IDocumentManager {}
The document manager.
#### Notes The document manager is used to register model and widget creators, and the file browser uses the document manager to create widgets. The document manager maintains a context for each path and model type that is open, and a list of widgets for each context. The document manager is in control of the proper closing and disposal of the widgets and contexts.
constructor
constructor(options: DocumentManager.IOptions);
Construct a new document manager.
property activateRequested
readonly activateRequested: ISignal<this, string>;
A signal emitted when one of the documents is activated.
property autosave
autosave: boolean;
Whether to autosave documents.
property autosaveInterval
autosaveInterval: number;
Determines the time interval for autosave in seconds.
property confirmClosingDocument
confirmClosingDocument: boolean;
Whether to ask confirmation to close a tab or not.
property isDisposed
readonly isDisposed: boolean;
Get whether the document manager has been disposed.
property lastModifiedCheckMargin
lastModifiedCheckMargin: number;
Defines max acceptable difference, in milliseconds, between last modified timestamps on disk and client
property registry
readonly registry: DocumentRegistry;
The registry used by the manager.
property renameUntitledFileOnSave
renameUntitledFileOnSave: boolean;
Whether to ask the user to rename untitled file on first manual save.
property services
readonly services: ServiceManager.IManager;
The service manager used by the manager.
property stateChanged
readonly stateChanged: ISignal<IDocumentManager, IChangedArgs<any>>;
Signal triggered when an attribute changes.
property translator
protected translator: ITranslator;
method cloneWidget
cloneWidget: (widget: Widget) => IDocumentWidget | undefined;
Clone a widget.
Parameter widget
The source widget.
Returns
A new widget or
undefined
.#### Notes Uses the same widget factory and context as the source, or returns
undefined
if the source widget is not managed by this manager.
method closeAll
closeAll: () => Promise<void>;
Close all of the open documents.
Returns
A promise resolving when the widgets are closed.
method closeFile
closeFile: (path: string) => Promise<void>;
Close the widgets associated with a given path.
Parameter path
The target path.
Returns
A promise resolving when the widgets are closed.
method contextForWidget
contextForWidget: (widget: Widget) => DocumentRegistry.Context | undefined;
Get the document context for a widget.
Parameter widget
The widget of interest.
Returns
The context associated with the widget, or
undefined
if no such context exists.
method copy
copy: (fromFile: string, toDir: string) => Promise<Contents.IModel>;
Copy a file.
Parameter fromFile
The full path of the original file.
Parameter toDir
The full path to the target directory.
Returns
A promise which resolves to the contents of the file.
method createNew
createNew: ( path: string, widgetName?: string, kernel?: Kernel.IModel) => Widget | undefined;
Create a new file and return the widget used to view it.
Parameter path
The file path to create.
Parameter widgetName
The name of the widget factory to use. 'default' will use the default widget.
Parameter kernel
An optional kernel name/id to override the default.
Returns
The created widget, or
undefined
.#### Notes This function will return
undefined
if a valid widget factory cannot be found.
method deleteFile
deleteFile: (path: string) => Promise<void>;
Delete a file.
Parameter path
The full path to the file to be deleted.
Returns
A promise which resolves when the file is deleted.
#### Notes If there is a running session associated with the file and no other sessions are using the kernel, the session will be shut down.
method dispose
dispose: () => void;
Dispose of the resources held by the document manager.
method duplicate
duplicate: (path: string) => Promise<Contents.IModel>;
Duplicate a file.
Parameter path
The full path to the file to be duplicated.
Returns
A promise which resolves when the file is duplicated.
method findWidget
findWidget: ( path: string, widgetName?: string | null) => IDocumentWidget | undefined;
See if a widget already exists for the given path and widget name.
Parameter path
The file path to use.
Parameter widgetName
The name of the widget factory to use. 'default' will use the default widget.
Returns
The found widget, or
undefined
.#### Notes This can be used to find an existing widget instead of opening a new widget.
method newUntitled
newUntitled: (options: Contents.ICreateOptions) => Promise<Contents.IModel>;
Create a new untitled file.
Parameter options
The file content creation options.
method open
open: ( path: string, widgetName?: string, kernel?: Kernel.IModel, options?: DocumentRegistry.IOpenOptions) => IDocumentWidget | undefined;
Open a file and return the widget used to view it.
Parameter path
The file path to open.
Parameter widgetName
The name of the widget factory to use. 'default' will use the default widget.
Parameter kernel
An optional kernel name/id to override the default.
Returns
The created widget, or
undefined
.#### Notes This function will return
undefined
if a valid widget factory cannot be found.
method openOrReveal
openOrReveal: ( path: string, widgetName?: string, kernel?: Kernel.IModel, options?: DocumentRegistry.IOpenOptions) => IDocumentWidget | undefined;
Open a file and return the widget used to view it. Reveals an already existing editor.
Parameter path
The file path to open.
Parameter widgetName
The name of the widget factory to use. 'default' will use the default widget.
Parameter kernel
An optional kernel name/id to override the default.
Returns
The created widget, or
undefined
.#### Notes This function will return
undefined
if a valid widget factory cannot be found.
method overwrite
overwrite: (oldPath: string, newPath: string) => Promise<Contents.IModel>;
Overwrite a file.
Parameter oldPath
The full path to the original file.
Parameter newPath
The full path to the new file.
Returns
A promise containing the new file contents model.
method rename
rename: (oldPath: string, newPath: string) => Promise<Contents.IModel>;
Rename a file or directory.
Parameter oldPath
The full path to the original file.
Parameter newPath
The full path to the new file.
Returns
A promise containing the new file contents model. The promise will reject if the newPath already exists. Use [[overwrite]] to overwrite a file.
class DocumentWidgetManager
class DocumentWidgetManager implements IDisposable {}
A class that maintains the lifecycle of file-backed widgets.
constructor
constructor(options: DocumentWidgetManager.IOptions);
Construct a new document widget manager.
property activateRequested
readonly activateRequested: ISignal<this, string>;
A signal emitted when one of the documents is activated.
property confirmClosingDocument
confirmClosingDocument: boolean;
Whether to ask confirmation to close a tab or not.
property isDisposed
readonly isDisposed: boolean;
Test whether the document widget manager is disposed.
property stateChanged
readonly stateChanged: ISignal<DocumentWidgetManager, IChangedArgs<any>>;
Signal triggered when an attribute changes.
property translator
protected translator: ITranslator;
method adoptWidget
adoptWidget: ( context: DocumentRegistry.Context, widget: IDocumentWidget) => void;
Install the message hook for the widget and add to list of known widgets.
Parameter context
The document context object.
Parameter widget
The widget to adopt.
method cloneWidget
cloneWidget: (widget: Widget) => IDocumentWidget | undefined;
Clone a widget.
Parameter widget
The source widget.
Returns
A new widget or
undefined
.#### Notes Uses the same widget factory and context as the source, or throws if the source widget is not managed by this manager.
method closeWidgets
closeWidgets: (context: DocumentRegistry.Context) => Promise<void>;
Close the widgets associated with a given context.
Parameter context
The document context object.
method contextForWidget
contextForWidget: (widget: Widget) => DocumentRegistry.Context | undefined;
Get the document context for a widget.
Parameter widget
The widget of interest.
Returns
The context associated with the widget, or
undefined
.
method createWidget
createWidget: ( factory: DocumentRegistry.WidgetFactory, context: DocumentRegistry.Context) => IDocumentWidget;
Create a widget for a document and handle its lifecycle.
Parameter factory
The widget factory.
Parameter context
The document context object.
Returns
A widget created by the factory.
Throws
If the factory is not registered.
method deleteWidgets
deleteWidgets: (context: DocumentRegistry.Context) => Promise<void>;
Dispose of the widgets associated with a given context regardless of the widget's dirty state.
Parameter context
The document context object.
method dispose
dispose: () => void;
Dispose of the resources used by the widget manager.
method findWidget
findWidget: ( context: DocumentRegistry.Context, widgetName: string) => IDocumentWidget | undefined;
See if a widget already exists for the given context and widget name.
Parameter context
The document context object.
Returns
The found widget, or
undefined
.#### Notes This can be used to use an existing widget instead of opening a new widget.
method messageHook
messageHook: (handler: IMessageHandler, msg: Message) => boolean;
Filter a message sent to a message handler.
Parameter handler
The target handler of the message.
Parameter msg
The message dispatched to the handler.
Returns
false
if the message should be filtered, oftrue
if the message should be dispatched to the handler as normal.
method onClose
protected onClose: (widget: Widget) => Promise<boolean>;
Handle
'close-request'
messages.Parameter widget
The target widget.
Returns
A promise that resolves with whether the widget was closed.
method onDelete
protected onDelete: (widget: Widget) => Promise<void>;
Dispose of widget regardless of widget's dirty state.
Parameter widget
The target widget.
method setCaption
protected setCaption: (widget: Widget) => Promise<void>;
Set the caption for widget title.
Parameter widget
The target widget.
class PathStatus
class PathStatus extends VDomRenderer<PathStatus.Model> {}
A status bar item for the current file path (or activity name).
constructor
constructor(opts: PathStatus.IOptions);
Construct a new PathStatus status item.
method render
render: () => JSX.Element;
Render the status item.
class RecentsManager
class RecentsManager implements IRecentsManager {}
Manager for recently opened and closed documents.
constructor
constructor(options: RecentsManager.IOptions);
property changed
readonly changed: ISignal<IRecentsManager, void>;
Signal emitted when the recent list changes.
property isDisposed
readonly isDisposed: boolean;
Whether the manager is disposed or not.
property maximalRecentsLength
maximalRecentsLength: number;
Maximal number of recent items to list.
property recentlyClosed
readonly recentlyClosed: RecentDocument[];
List of recently opened items
property recentlyOpened
readonly recentlyOpened: RecentDocument[];
List of recently opened items
method addRecent
addRecent: ( document: Omit<RecentDocument, 'root'>, event: 'opened' | 'closed') => void;
Add a new path to the recent list.
method clearRecents
clearRecents: () => void;
Clear the recents list
method dispose
dispose: () => void;
Dispose recent manager resources
method removeRecent
removeRecent: (document: RecentDocument, event: 'opened' | 'closed') => void;
Remove the document from recents list.
method updateRootDir
protected updateRootDir: () => void;
Set server root dir.
Note: protected to allow unit-testing.
method validate
validate: (recent: RecentDocument) => Promise<boolean>;
Check if the recent item is valid, remove if it from both lists if it is not.
class SaveHandler
class SaveHandler implements IDisposable {}
A class that manages the auto saving of a document.
#### Notes Implements https://github.com/ipython/ipython/wiki/IPEP-15:-Autosaving-the-IPython-Notebook.
constructor
constructor(options: SaveHandler.IOptions);
Construct a new save handler.
property isActive
readonly isActive: boolean;
Get whether the handler is active.
property isDisposed
readonly isDisposed: boolean;
Get whether the save handler is disposed.
property saveInterval
saveInterval: number;
The save interval used by the timer (in seconds).
method dispose
dispose: () => void;
Dispose of the resources used by the save handler.
method start
start: () => void;
Start the autosaver.
method stop
stop: () => void;
Stop the autosaver.
class SavingStatus
class SavingStatus extends VDomRenderer<SavingStatus.Model> {}
A VDomRenderer for a saving status item.
constructor
constructor(opts: SavingStatus.IOptions);
Create a new SavingStatus item.
method render
render: () => JSX.Element | null;
Render the SavingStatus item.
Interfaces
interface IDocumentManager
interface IDocumentManager extends IDisposable {}
The interface for a document manager.
property activateRequested
readonly activateRequested: ISignal<this, string>;
A signal emitted when one of the documents is activated.
property autosave
autosave: boolean;
Whether to autosave documents.
property autosaveInterval
autosaveInterval: number;
Determines the time interval for autosave in seconds.
property confirmClosingDocument
confirmClosingDocument: boolean;
Whether to ask confirmation to close a tab or not.
property lastModifiedCheckMargin
lastModifiedCheckMargin: number;
Defines max acceptable difference, in milliseconds, between last modified timestamps on disk and client.
property registry
readonly registry: DocumentRegistry;
The registry used by the manager.
property renameUntitledFileOnSave
renameUntitledFileOnSave: boolean;
Whether to ask the user to rename untitled file on first manual save.
property services
readonly services: ServiceManager.IManager;
The service manager used by the manager.
property stateChanged
readonly stateChanged: ISignal<IDocumentManager, IChangedArgs<any>>;
Signal triggered when an attribute changes.
method cloneWidget
cloneWidget: (widget: Widget) => IDocumentWidget | undefined;
Clone a widget.
Parameter widget
The source widget.
Returns
A new widget or
undefined
.#### Notes Uses the same widget factory and context as the source, or returns
undefined
if the source widget is not managed by this manager.
method closeAll
closeAll: () => Promise<void>;
Close all of the open documents.
Returns
A promise resolving when the widgets are closed.
method closeFile
closeFile: (path: string) => Promise<void>;
Close the widgets associated with a given path.
Parameter path
The target path.
Returns
A promise resolving when the widgets are closed.
method contextForWidget
contextForWidget: (widget: Widget) => DocumentRegistry.Context | undefined;
Get the document context for a widget.
Parameter widget
The widget of interest.
Returns
The context associated with the widget, or
undefined
if no such context exists.
method copy
copy: (fromFile: string, toDir: string) => Promise<Contents.IModel>;
Copy a file.
Parameter fromFile
The full path of the original file.
Parameter toDir
The full path to the target directory.
Returns
A promise which resolves to the contents of the file.
method createNew
createNew: ( path: string, widgetName?: string, kernel?: Kernel.IModel) => Widget | undefined;
Create a new file and return the widget used to view it.
Parameter path
The file path to create.
Parameter widgetName
The name of the widget factory to use. 'default' will use the default widget.
Parameter kernel
An optional kernel name/id to override the default.
Returns
The created widget, or
undefined
.#### Notes This function will return
undefined
if a valid widget factory cannot be found.
method deleteFile
deleteFile: (path: string) => Promise<void>;
Delete a file.
Parameter path
The full path to the file to be deleted.
Returns
A promise which resolves when the file is deleted.
#### Notes If there is a running session associated with the file and no other sessions are using the kernel, the session will be shut down.
method duplicate
duplicate: (path: string) => Promise<Contents.IModel>;
Duplicate a file.
Parameter path
The full path to the file to be duplicated.
Returns
A promise which resolves when the file is duplicated.
method findWidget
findWidget: ( path: string, widgetName?: string | null) => IDocumentWidget | undefined;
See if a widget already exists for the given path and widget name.
Parameter path
The file path to use.
Parameter widgetName
The name of the widget factory to use. 'default' will use the default widget.
Returns
The found widget, or
undefined
.#### Notes This can be used to find an existing widget instead of opening a new widget.
method newUntitled
newUntitled: (options: Contents.ICreateOptions) => Promise<Contents.IModel>;
Create a new untitled file.
Parameter options
The file content creation options.
method open
open: ( path: string, widgetName?: string, kernel?: Kernel.IModel, options?: DocumentRegistry.IOpenOptions) => IDocumentWidget | undefined;
Open a file and return the widget used to view it.
Parameter path
The file path to open.
Parameter widgetName
The name of the widget factory to use. 'default' will use the default widget.
Parameter kernel
An optional kernel name/id to override the default.
Returns
The created widget, or
undefined
.#### Notes This function will return
undefined
if a valid widget factory cannot be found.
method openOrReveal
openOrReveal: ( path: string, widgetName?: string, kernel?: Kernel.IModel, options?: DocumentRegistry.IOpenOptions) => IDocumentWidget | undefined;
Open a file and return the widget used to view it. Reveals an already existing editor.
Parameter path
The file path to open.
Parameter widgetName
The name of the widget factory to use. 'default' will use the default widget.
Parameter kernel
An optional kernel name/id to override the default.
Returns
The created widget, or
undefined
.#### Notes This function will return
undefined
if a valid widget factory cannot be found.
method overwrite
overwrite: (oldPath: string, newPath: string) => Promise<Contents.IModel>;
Overwrite a file.
Parameter oldPath
The full path to the original file.
Parameter newPath
The full path to the new file.
Returns
A promise containing the new file contents model.
method rename
rename: (oldPath: string, newPath: string) => Promise<Contents.IModel>;
Rename a file or directory.
Parameter oldPath
The full path to the original file.
Parameter newPath
The full path to the new file.
Returns
A promise containing the new file contents model. The promise will reject if the newPath already exists. Use [[overwrite]] to overwrite a file.
interface IDocumentWidgetOpener
interface IDocumentWidgetOpener {}
The interface for a widget opener.
interface IFileContainer
interface IFileContainer extends JSONObject {}
A stripped-down interface for a file container.
interface IRecentsManager
interface IRecentsManager extends IDisposable {}
Recent opened items manager.
property changed
readonly changed: ISignal<IRecentsManager, void>;
Signal emitted when either of the list changes.
property recentlyClosed
readonly recentlyClosed: RecentDocument[];
Get the recently closed items.
property recentlyOpened
readonly recentlyOpened: RecentDocument[];
Get the recently opened documents.
method addRecent
addRecent: ( document: Omit<RecentDocument, 'root'>, event: 'opened' | 'closed') => void;
Add a new path to the recent list.
method removeRecent
removeRecent: (document: RecentDocument, event: 'opened' | 'closed') => void;
Remove the document from recents list.
method validate
validate: (recent: RecentDocument) => Promise<boolean>;
Check if the recent item is valid, remove if it from both lists if it is not.
Type Aliases
type RecentDocument
type RecentDocument = { /** * The server root path. * * Allows to select only the currently accessible documents. */ root: string; /** * The path to the document. */ path: string; /** * The document content type or `directory` literal for directories. */ contentType: string; /** * The factory that was used when the document was most recently opened or closed. */ factory?: string;};
The interface for a recent document.
Namespaces
namespace DocumentManager
namespace DocumentManager {}
A namespace for document manager statics.
interface IOptions
interface IOptions {}
The options used to initialize a document manager.
property isConnectedCallback
isConnectedCallback?: () => boolean;
Autosaving should be paused while this callback function returns
false
. By default, it always returnstrue
.
property manager
manager: ServiceManager.IManager;
A service manager instance.
property opener
opener: IDocumentWidgetOpener;
A widget opener for sibling widgets.
property recentsManager
recentsManager?: IRecentsManager;
The manager for recent documents.
property registry
registry: DocumentRegistry;
A document registry instance.
property sessionDialogs
sessionDialogs?: ISessionContext.IDialogs;
The provider for session dialogs.
property setBusy
setBusy?: () => IDisposable;
A function called when a kernel is busy.
property translator
translator?: ITranslator;
The application language translator.
property when
when?: Promise<void>;
A promise for when to start using the manager.
namespace DocumentWidgetManager
namespace DocumentWidgetManager {}
A namespace for document widget manager statics.
interface IOptions
interface IOptions {}
The options used to initialize a document widget manager.
property recentsManager
recentsManager?: IRecentsManager;
The manager for recent documents.
property registry
registry: DocumentRegistry;
A document registry instance.
property translator
translator?: ITranslator;
The application language translator.
namespace PathStatus
namespace PathStatus {}
A namespace for PathStatus statics.
class Model
class Model extends VDomModel {}
A VDomModel for rendering the PathStatus status item.
constructor
constructor(docManager: IDocumentManager);
Construct a new model.
Parameter docManager
the application document manager. Used to check whether the current widget is a document.
property name
readonly name: string;
The name of the current activity.
property path
readonly path: string;
The current path for the application.
property widget
widget: any;
The current widget for the application.
interface IOptions
interface IOptions {}
Options for creating the PathStatus widget.
property docManager
docManager: IDocumentManager;
The application document manager.
namespace RecentsManager
namespace RecentsManager {}
Namespace for RecentsManager statics.
namespace SaveHandler
namespace SaveHandler {}
A namespace for
SaveHandler
statics.
interface IOptions
interface IOptions {}
The options used to create a save handler.
property context
context: DocumentRegistry.Context;
The context associated with the file.
property isConnectedCallback
isConnectedCallback?: () => boolean;
Autosaving should be paused while this callback function returns
false
. By default, it always returnstrue
.
property saveInterval
saveInterval?: number;
The minimum save interval in seconds (default is two minutes).
namespace SavingStatus
namespace SavingStatus {}
A namespace for SavingStatus statics.
class Model
class Model extends VDomModel {}
A VDomModel for the SavingStatus item.
constructor
constructor(docManager: IDocumentManager);
Create a new SavingStatus model.
property status
readonly status: any;
The current status of the model.
property widget
widget: any;
The current widget for the model. Any widget can be assigned, but it only has any effect if the widget is an IDocument widget known to the application document manager.
interface IOptions
interface IOptions {}
Options for creating a new SaveStatus item
property docManager
docManager: IDocumentManager;
The application document manager.
property translator
translator?: ITranslator;
The application language translator.
Package Files (9)
Dependencies (17)
- @jupyterlab/apputils
- @jupyterlab/coreutils
- @jupyterlab/docregistry
- @jupyterlab/services
- @jupyterlab/statedb
- @jupyterlab/statusbar
- @jupyterlab/translation
- @jupyterlab/ui-components
- @lumino/algorithm
- @lumino/coreutils
- @lumino/disposable
- @lumino/messaging
- @lumino/polling
- @lumino/properties
- @lumino/signaling
- @lumino/widgets
- react
Dev Dependencies (5)
Peer Dependencies (0)
No peer dependencies.
Badge
To add a badge like this oneto your package's README, use the codes available below.
You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@jupyterlab/docmanager
.
- Markdown[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@jupyterlab/docmanager)
- HTML<a href="https://www.jsdocs.io/package/@jupyterlab/docmanager"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>
- Updated .
Package analyzed in 5560 ms. - Missing or incorrect documentation? Open an issue for this package.