Options
All
  • Public
  • Public/Protected
  • All
Menu

Namespace workspace

Index

Variables

Functions

Variables

Const fs

fs: FileSystem

A file system instance that allows to interact with local and remote files, e.g. workspace.fs.readDirectory(someUri) allows to retrieve all entries of a directory or workspace.fs.stat(anotherUri) returns the meta data for a file.

Const isTrusted

isTrusted: boolean

When true, the user has explicitly trusted the contents of the workspace.

name

name: string | undefined

The name of the workspace. undefined when no folder has been opened.

readonly

notebookDocuments

notebookDocuments: readonly NotebookDocument[]

All notebook documents currently known to the editor.

readonly
stubbed

Const rootPath

rootPath: string | undefined

The folder that is open in the editor. undefined when no folder has been opened.

deprecated

Use workspaceFolders instead.

readonly

textDocuments

textDocuments: readonly TextDocument[]

All text documents currently known to the system.

readonly

Const workspaceFile

workspaceFile: Uri | undefined

The location of the workspace file, for example:

file:///Users/name/Development/myProject.code-workspace

Depending on the workspace that is opened, the value will be:

  • undefined when no workspace or a single folder is opened
  • the path of the workspace file as Uri otherwise.

Note: it is not advised to use workspace.workspaceFile to write configuration data into the file.

readonly

Const workspaceFolders

workspaceFolders: readonly WorkspaceFolder[] | undefined

List of workspace folders or undefined when no folder is open. Note that the first entry corresponds to the value of rootPath.

readonly

Functions

applyEdit

  • Make changes to one or many resources or create, delete, and rename resources as defined by the given workspace edit.

    All changes of a workspace edit are applied in the same order in which they have been added. If multiple textual inserts are made at the same position, these strings appear in the resulting text in the order the 'inserts' were made. Invalid sequences like 'delete file a' -> 'insert text in file a' cause failure of the operation.

    When applying a workspace edit that consists only of text edits an 'all-or-nothing'-strategy is used. A workspace edit with resource creations or deletions aborts the operation, e.g. consecutive edits will not be attempted, when a single edit fails.

    Parameters

    Returns Thenable<boolean>

    A thenable that resolves when the edit could be applied.

asRelativePath

  • asRelativePath(pathOrUri: string | Uri, includeWorkspaceFolder?: boolean): string | undefined

  • Returns a path that is relative to the workspace folder or folders.

    When there are no workspace folders or when the path is not contained in them, the input is returned.

    Parameters

    • pathOrUri: string | Uri

      A path or uri. When a uri is given its fsPath is used.

    • Optional includeWorkspaceFolder: boolean

      When true and when the given path is contained inside a workspace folder the name of the workspace is prepended. Defaults to true when there are multiple workspace folders and false otherwise.

    Returns string | undefined

    A path relative to the root or the input.

createFileSystemWatcher

  • createFileSystemWatcher(globPattern: GlobPattern, ignoreCreateEvents?: boolean, ignoreChangeEvents?: boolean, ignoreDeleteEvents?: boolean): FileSystemWatcher

findFiles

  • Find files across all workspace folders in the workspace.

    sample

    findFiles('**​/*.js', '**​/node_modules/**', 10)

    Parameters

    • include: GlobPattern

      A glob pattern that defines the files to search for. The glob pattern will be matched against the file paths of resulting matches relative to their workspace. Use a relative pattern to restrict the search results to a workspace folder.

    • Optional exclude: null | GlobPattern

      A glob pattern that defines files and folders to exclude. The glob pattern will be matched against the file paths of resulting matches relative to their workspace. When undefined only default excludes will apply, when null no excludes will apply.

    • Optional maxResults: number

      An upper-bound for the result.

    • Optional token: CancellationToken

      A token that can be used to signal cancellation to the underlying search engine.

    Returns Thenable<Uri[]>

    A thenable that resolves to an array of resource identifiers. Will return no results if no workspace folders are opened.

findTextInFiles

getConfiguration

  • Get a workspace configuration object.

    When a section-identifier is provided only that part of the configuration is returned. Dots in the section-identifier are interpreted as child-access, like { myExt: { setting: { doIt: true }}} and getConfiguration('myExt.setting').get('doIt') === true.

    When a scope is provided configuration confined to that scope is returned. Scope can be a resource or a language identifier or both.

    Parameters

    • Optional section: string

      A dot-separated identifier.

    • Optional scope: null | ConfigurationScope

      A scope for which the configuration is asked for.

    Returns WorkspaceConfiguration

    The full configuration or a subset.

getWorkspaceFolder

onDidChangeConfiguration

onDidChangeNotebookDocument

onDidChangeTextDocument

onDidChangeWorkspaceFolders

onDidCloseNotebookDocument

  • An event that is emitted when a notebook is disposed.

    Note 1: There is no guarantee that this event fires when an editor tab is closed.

    Note 2: A notebook can be open but not shown in an editor which means this event can fire for a notebook that has not been shown in an editor.

    stubbed

    Parameters

    Returns Disposable

onDidCloseTextDocument

onDidCreateFiles

onDidDeleteFiles

onDidGrantWorkspaceTrust

  • onDidGrantWorkspaceTrust(listener: ((e: void) => any), thisArgs?: any, disposables?: Disposable[]): Disposable

onDidOpenNotebookDocument

onDidOpenTextDocument

onDidRenameFiles

onDidSaveNotebookDocument

onDidSaveTextDocument

onWillCreateEditSessionIdentity

onWillCreateFiles

onWillDeleteFiles

onWillRenameFiles

onWillSaveNotebookDocument

  • An event that is emitted when a notebook document will be saved to disk.

    Note 1: Subscribers can delay saving by registering asynchronous work. For the sake of data integrity the editor might save without firing this event. For instance when shutting down with dirty files.

    Note 2: Subscribers are called sequentially and they can delay saving by registering asynchronous work. Protection against misbehaving listeners is implemented as such:

    • there is an overall time budget that all listeners share and if that is exhausted no further listener is called
    • listeners that take a long time or produce errors frequently will not be called anymore

    The current thresholds are 1.5 seconds as overall time budget and a listener can misbehave 3 times before being ignored.

    stubbed

    Parameters

    Returns Disposable

onWillSaveTextDocument

  • An event that is emitted when a text document will be saved to disk.

    Note 1: Subscribers can delay saving by registering asynchronous work. For the sake of data integrity the editor might save without firing this event. For instance when shutting down with dirty files.

    Note 2: Subscribers are called sequentially and they can delay saving by registering asynchronous work. Protection against misbehaving listeners is implemented as such:

    • there is an overall time budget that all listeners share and if that is exhausted no further listener is called
    • listeners that take a long time or produce errors frequently will not be called anymore

    The current thresholds are 1.5 seconds as overall time budget and a listener can misbehave 3 times before being ignored.

    Parameters

    Returns Disposable

openNotebookDocument

  • Open a notebook. Will return early if this notebook is already loaded. Otherwise the notebook is loaded and the onDidOpenNotebookDocument-event fires.

    Note that the lifecycle of the returned notebook is owned by the editor and not by the extension. That means an onDidCloseNotebookDocument-event can occur at any time after. Note that opening a notebook does not show a notebook editor. This function only returns a notebook document which can be shown in a notebook editor but it can also be used for other things.

    stubbed

    Parameters

    • uri: Uri

      The resource to open.

    Returns Thenable<NotebookDocument> | undefined

    A promise that resolves to a notebook.

  • Open an untitled notebook. The editor will prompt the user for a file path when the document is to be saved.

    stubbed

    Parameters

    • notebookType: string

      The notebook type that should be used.

    • Optional content: NotebookData

      The initial contents of the notebook.

    Returns Thenable<NotebookDocument> | undefined

    A promise that resolves to a notebook.

openTextDocument

  • Opens a document. Will return early if this document is already open. Otherwise the document is loaded and the didOpen-event fires.

    The document is denoted by an uri. Depending on the scheme the following rules apply:

    • file-scheme: Open a file on disk, will be rejected if the file does not exist or cannot be loaded.
    • untitled-scheme: A new file that should be saved on disk, e.g. untitled:c:\frodo\new.js. The language will be derived from the file name.
    • For all other schemes the registered text document content providers are consulted.

    Note that the lifecycle of the returned document is owned by the editor and not by the extension. That means an onDidClose-event can occur at any time after opening it.

    Parameters

    • uri: Uri

      Identifies the resource to open.

    Returns Thenable<TextDocument | undefined>

    A promise that resolves to a document.

  • A short-hand for openTextDocument(Uri.file(fileName)).

    see

    openTextDocument

    Parameters

    • fileName: string

      A name of a file on disk.

    Returns Thenable<TextDocument | undefined>

    A promise that resolves to a document.

  • Opens an untitled text document. The editor will prompt the user for a file path when the document is to be saved. The options parameter allows to specify the language and/or the content of the document.

    Parameters

    • Optional options: { content?: string; language?: string }

      Options to control how the document will be created.

      • Optional content?: string
      • Optional language?: string

    Returns Thenable<TextDocument | undefined>

    A promise that resolves to a document.

registerEditSessionIdentityProvider

registerFileSystemProvider

  • registerFileSystemProvider(scheme: string, provider: FileSystemProvider, options?: { isCaseSensitive?: boolean; isReadonly?: boolean }): Disposable

  • Register a filesystem provider for a given scheme, e.g. ftp.

    There can only be one provider per scheme and an error is being thrown when a scheme has been claimed by another provider or when it is reserved.

    Parameters

    • scheme: string

      The uri-scheme the provider registers for.

    • provider: FileSystemProvider

      The filesystem provider.

    • Optional options: { isCaseSensitive?: boolean; isReadonly?: boolean }

      Immutable metadata about the provider.

      • Optional Readonly isCaseSensitive?: boolean
      • Optional Readonly isReadonly?: boolean

    Returns Disposable

    A disposable that unregisters this provider when being disposed.

registerNotebookSerializer

  • Register a notebook serializer.

    A notebook serializer must be contributed through the notebooks extension point. When opening a notebook file, the editor will send the onNotebook: activation event, and extensions must register their serializer in return.

    stubbed

    Parameters

    Returns Disposable

    A disposable that unregisters this serializer when being disposed.

registerResourceLabelFormatter

registerTaskProvider

registerTextDocumentContentProvider

registerTimelineProvider

  • Register a timeline provider.

    Multiple providers can be registered. In that case, providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.

    Parameters

    • scheme: string | string[]

      A scheme or schemes that defines which documents this provider is applicable to. Can be * to target all documents.

    • provider: TimelineProvider

      A timeline provider.

    Returns Disposable

    A disposable that unregisters this provider when being disposed.

requestWorkspaceTrust

saveAll

  • saveAll(includeUntitled?: boolean): Thenable<boolean>

  • Save all dirty files.

    Parameters

    • Optional includeUntitled: boolean

      Also save files that have been created during this session.

    Returns Thenable<boolean>

    A thenable that resolves when the files have been saved.

updateWorkspaceFolders

  • updateWorkspaceFolders(start: number, deleteCount: undefined | null | number, ...workspaceFoldersToAdd: { name?: string; uri: Uri }[]): boolean

  • This method replaces deleteCount workspace folders starting at index start by an optional set of workspaceFoldersToAdd on the theia.workspace.workspaceFolders array. This "splice" behavior can be used to add, remove and change workspace folders in a single operation.

    If the first workspace folder is added, removed or changed, the currently executing extensions (including the one that called this method) will be terminated and restarted so that the (deprecated) rootPath property is updated to point to the first workspace folder.

    Use the onDidChangeWorkspaceFolders() event to get notified when the workspace folders have been updated.

    Example: adding a new workspace folder at the end of workspace folders

    workspace.updateWorkspaceFolders(workspace.workspaceFolders ? workspace.workspaceFolders.length : 0, null, { uri: ...});

    Example: removing the first workspace folder

    workspace.updateWorkspaceFolders(0, 1);

    Example: replacing an existing workspace folder with a new one

    workspace.updateWorkspaceFolders(0, 1, { uri: ...});

    It is valid to remove an existing workspace folder and add it again with a different name to rename that folder.

    Note: it is not valid to call updateWorkspaceFolders() multiple times without waiting for the onDidChangeWorkspaceFolders() to fire.

    Parameters

    • start: number

      the zero-based location in the list of currently opened workspace folders from which to start deleting workspace folders.

    • deleteCount: undefined | null | number

      the optional number of workspace folders to remove.

    • Rest ...workspaceFoldersToAdd: { name?: string; uri: Uri }[]

      the optional variable set of workspace folders to add in place of the deleted ones. Each workspace is identified with a mandatory URI and an optional name.

    Returns boolean

    true if the operation was successfully started and false otherwise if arguments were used that would result in invalid workspace folder state (e.g. 2 folders with the same URI).