Theia API Documentation v1.77.0
    Preparing search index...

    The workspace service.

    Hierarchy (View Summary)

    Index
    _ready: Deferred<void>
    _roots: FileStat[]
    _workspace: FileStat | undefined
    collabWorkspace?: Workspace
    computedRootNames: Map<string, string>

    The names of the roots read by the last computeRoots, not yet published.

    configuredRootNames: Map<string, string>

    The names of the roots, published together with _roots when onWorkspaceChanged fires.

    configuredRootNamesByUri:
        | { byUri: Map<string, string | undefined>; names: Map<string, string> }
        | undefined

    The configured root names by the string of a root URI as passed to getConfiguredRootName, for the configuredRootNames they were looked up in.

    connection?: ProtocolBroadcastConnection
    deferredRoots: Deferred<FileStat[]>
    envVariableServer: EnvVariablesServer
    fileService: FileService
    fsPreferences: FileSystemPreferences
    labelProvider: LabelProvider
    logger: ILogger
    messageService: MessageService
    onWorkspaceChangeEmitter: Emitter<FileStat[]>
    onWorkspaceLocationChangedEmitter: Emitter<FileStat | undefined>
    preferenceImpl: PreferenceService
    rootNamesCache:
        | {
            names: ReadonlyMap<string, URI>;
            namesByRoot: ReadonlyMap<string, string>;
        }
        | undefined

    The root names, and the names by root URI, which depend on each other. Reset whenever the roots change.

    rootWatchers: Map<string, Disposable>
    schemaUpdater: WorkspaceSchemaUpdater
    toDisposeOnWorkspace: DisposableCollection
    untitledWorkspaceService: UntitledWorkspaceService
    windowService: WindowService
    windowTitleService: WindowTitleService
    workspaceFileService: WorkspaceFileService
    workspaceHandlingContribution: ContributionProvider<
        WorkspaceHandlingContribution,
    >
    • get isMultiRootWorkspaceOpened(): boolean

      Returns true if a multiple-root workspace is currently open.

      Returns boolean

    • get onWorkspaceChanged(): Event<FileStat[]>

      Returns Event<FileStat[]>

    • get onWorkspaceLocationChanged(): Event<FileStat | undefined>

      Returns Event<FileStat | undefined>

    • get opened(): boolean

      Returns true if theia has an opened workspace or folder

      Returns boolean

    • get ready(): Promise<void>

      Returns Promise<void>

    • get roots(): Promise<FileStat[]>

      Returns Promise<FileStat[]>

    • get saved(): boolean

      true if the current workspace is configured using a configuration file.

      false if there is no workspace or the workspace is simply a folder.

      Returns boolean

    • get workspace(): FileStat | undefined

      Returns FileStat | undefined

    • Adds root folder(s) to the workspace

      Parameters

      • uris: URI | URI[]

        URI or URIs of the root folder(s) to add

      Returns Promise<void>

    • Parameters

      • names: Map<string, string>
      • otherNames: Map<string, string>

      Returns boolean

    • Parameters

      Returns boolean

    • Clears current workspace root.

      Returns Promise<void>

    • Computes the name of a root from the roots that share its basename (including itself).

      Parameters

      Returns string

    • Return true if one of the paths in paths array is present in the workspace NOTE: You should always explicitly use / as the separator between the path segments.

      Parameters

      • paths: string[]

      Returns Promise<boolean>

    • Returns Promise<string | undefined>

    • Returns Promise<void>

    • Returns the name given to the workspace root by the name property of its folder entry in the workspace file. This is the name shown for the root, as WorkspaceFolder.name in VS Code. Unlike the unique names of getRootNames, it is chosen by the user and not used to address files.

      Parameters

      • rootUri: URI

        URI of the workspace root

      Returns string | undefined

      the name of the root, or undefined if the root has no name or is not a workspace root

    • Resolves to the default workspace URI as string.

      The default implementation tries to extract the default workspace location from the window.location.hash, then falls-back to the most recently used workspace root from the server.

      It is not ensured that the resolved workspace URI is valid, it can point to a non-existing location.

      Returns MaybePromise<string | undefined>

    • Parameters

      • uri: string

      Returns string[]

    • Returns the name of the given workspace root, as assigned by getRootNames, or undefined if the URI is not a workspace root.

      Parameters

      Returns string | undefined

    • Returns a unique name for each workspace root, in workspace order.

      A root is named after its directory basename, e.g. backend. Roots that share a basename are treated as peers: each of them is named after the shortest tail of its path that tells them apart, e.g. alice/app and bob/app. A name that another name starts with, e.g. alice next to alice/app, is qualified in the same way, e.g. work/alice, so that every path resolves to the root it came from. The names are thus always the ending of the real path, so they match what appears in terminal output, compiler errors and the like.

      These are the root names used by getRootPrefixedPath and resolved by resolveRootPrefixedPath.

      Returns ReadonlyMap<string, URI>

    • Returns { names: ReadonlyMap<string, URI>; namesByRoot: ReadonlyMap<string, string> }

    • Returns a workspace-relative path prefixed with the containing root's directory name, e.g. backend/src/index.ts.

      In a single-root workspace the root name is still included so that the format is consistent regardless of how many roots are open.

      Falls back to the absolute filesystem path if the URI is not contained in any workspace root.

      Parameters

      • uri: URI

        URI of the file

      Returns string

    • Returns the relative path of the given file to the workspace root.

      Parameters

      • uri: URI

        URI of the file

      Returns Promise<string>

      getWorkspaceRootUri(uri)

    • Returns the workspace root uri that the given file belongs to. In case that the file is found in more than one workspace roots, returns the root that is closest to the file. If the file is not from the current workspace, returns undefined.

      Parameters

      • uri: URI | undefined

        URI of the file

      Returns URI | undefined

    • Returns void

    • Returns true if the current window is connected to a remote backend. In remote sessions, we must not overwrite the local MRU with the remote workspace's file URI, as the local MRU should retain the remote connection URI (e.g. devcontainer://...) so the session can be restored on restart.

      Detection: the backend port is always in ?port=. When connected to a remote, the URL also has ?localPort= (the original backend port).

      Returns boolean

    • Parameters

      • OptionalwithURI: URI

      Returns Promise<boolean>

    • Parameters

      • Optionalcandidate: URI

      Returns boolean

    • Check if the file should be considered as a workspace file.

      Example: We should not try to read the contents of an .exe file.

      Parameters

      Returns boolean

    • On unload, we set our workspace root as the last recently used on the backend.

      In the browser, we use onStop (fire-and-forget) because onWillStop actions are never executed during browser tab close and returning an OnWillStopAction would trigger an unwanted "Leave site?" confirmation dialog.

      In Electron, we use onWillStop so the workspace is persisted before the window closes.

      Returns void

    • Called on beforeunload event, right before the window closes. Return true or an OnWillStopAction in order to prevent exit. Note: No async code allowed, this function has to run on one tick.

      Returns OnWillStopAction<unknown> | undefined

    • Opens directory, or recreates a workspace from the file that uri points to.

      Parameters

      Returns void

    • Adds the next parent segment to the name of a root, unless the name is its whole path or its URI already.

      Parameters

      • entry: { name: string; root: URI }

      Returns boolean

      whether the name was qualified

    • Qualifies a root name that another root name starts with, e.g. alice next to alice/app, by more segments of its path, as a path in the one root would otherwise resolve to the other. If the root named alice/app is the app folder of the root named alice, the names are left as they are: the nested root is then also the one that getRootPrefixedPath names its files after.

      Parameters

      • names: Map<string, URI>

      Returns Map<string, URI>

    • Returns Promise<string[]>

    • Parameters

      • uri: string

      Returns Promise<void>

    • Removes root folder(s) from workspace.

      Parameters

      Returns Promise<void>

    • Resolves a path in the format of getRootPrefixedPath, i.e. <rootName>/<relativePath> or a bare <rootName>, to a URI. If more than one root name is a prefix of the path, which is the case when a root named a has a subfolder b and another root is named a/b, the longest one wins.

      Parameters

      • rootPrefixedPath: string

      Returns URI | undefined

      undefined if the path is absolute, does not start with a root name or leaves its root.

    • Resolves a path that contains the basename of a workspace root, preceded by nothing or by the trailing segments of the root's parent path, e.g. bob/app/src for the root /home/bob/app. Unlike resolveRootPrefixedPath, this does not depend on the current root names, so it also resolves paths that were prefixed with a root name before the workspace roots changed.

      Parameters

      • supraRelativePath: string

      Returns URI[]

      the distinct candidates in workspace order, which are several if the path is ambiguous, or none if the path is absolute, leaves its root or does not contain the basename of a root.

    • Save workspace data into a file

      Parameters

      • uri: URI | FileStat

        URI or FileStat of the workspace file

      Returns Promise<void>

    • Set the URL fragment to the given workspace path.

      Parameters

      • workspacePath: string

      Returns void

    • Parameters

      Returns Promise<void>

    • Removes deleteCount roots starting at start and inserts the given roots there, and writes the result to the workspace file. A root to add can be given a name, which is written to the workspace file as the name of its folder entry.

      Parameters

      Returns Promise<URI[]>

      the URIs of the removed roots

    • Splits a /-separated path that starts with a root name, as in getRootPrefixedPath, into that root and the rest of the path, which is empty for a bare root name. The rest is not normalized, so it may as well be a glob. If more than one root name is a prefix of the path, the longest one wins.

      Parameters

      • rootPrefixedPath: string

      Returns { rest: string; rootName: string; rootUri: URI } | undefined

      undefined if the path does not start with a root name.

    • returns a FileStat if the argument URI points to a file or directory. Otherwise, undefined.

      Parameters

      • uri: string | URI | undefined

      Returns Promise<FileStat | undefined>

    • returns a FileStat if the argument URI points to an existing directory. Otherwise, undefined.

      Parameters

      • uri: string | URI | undefined

      Returns Promise<FileStat | undefined>

    • Returns Promise<void>

    • Parameters

      • key: string

        the property key under which to store the schema (e.g. tasks, launch)

      • Optionalschema: IJSONSchema

        the schema for the property. If none is supplied, the update is treated as a deletion.

      Returns Promise<boolean>

    • Returns void

    • Returns Promise<void>

    • Returns Promise<void>