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

    Service to manage preferences including, among others, getting and setting preference values as well as listening to preference changes.

    Depending on your use case you might also want to look at createPreferenceProxy with which you can easily create a typesafe schema-based interface for your preferences. Internally the proxy uses the PreferenceService so both approaches are compatible.

    interface PreferenceService {
        isReady: boolean;
        onPreferenceChanged: Event<PreferenceChange>;
        onPreferencesChanged: Event<PreferenceChanges>;
        ready: Promise<void>;
        dispose(): void;
        get(preferenceName: string, defaultValue: string): string;
        get(preferenceName: string, defaultValue: number): number;
        get(preferenceName: string, defaultValue: boolean): boolean;
        get<T extends string | number | boolean>(
            preferenceName: string,
            defaultValue: T,
        ): T;
        get<T extends unknown[]>(preferenceName: string, defaultValue: T): T;
        get<T>(
            preferenceName: string,
            options: PreferenceGetOptions<T> & { fallback: T },
        ): T;
        get<T>(
            preferenceName: string,
            options?: PreferenceGetOptions<T>,
        ): T | undefined;
        getConfigUri(
            scope: PreferenceScope,
            resourceUri?: string,
            sectionName?: string,
        ): URI | undefined;
        inspect<T extends JSONValue>(
            preferenceName: string,
            resourceUri?: string,
            overrideIdentifier?: string,
        ): PreferenceInspection<T> | undefined;
        inspectInScope<T extends JSONValue>(
            preferenceName: string,
            scope: PreferenceScope,
            resourceUri?: string,
            overrideIdentifier?: string,
        ): T | undefined;
        resolve<T>(
            preferenceName: string,
            defaultValue?: T,
            resourceUri?: string,
            overrideIdentifier?: string,
        ): PreferenceResolveResult<T>;
        set(
            preferenceName: string,
            value: any,
            scope?: PreferenceScope,
            resourceUri?: string,
            overrideIdentifier?: string,
        ): Promise<void>;
        updateValue(
            preferenceName: string,
            value: any,
            resourceUri?: string,
            overrideIdentifier?: string,
        ): Promise<void>;
    }

    Hierarchy (View Summary)

    Implemented by

    Index
    isReady: boolean

    Indicates whether the service has successfully initialized. Will be true when the ready Promise resolves.

    onPreferenceChanged: Event<PreferenceChange>

    Registers a callback which will be called whenever a preference is changed.

    onPreferencesChanged: Event<PreferenceChanges>

    Registers a callback which will be called whenever one or more preferences are changed.

    ready: Promise<void>

    Promise indicating whether the service successfully initialized.

    • Returns the uri of the configuration resource for the given scope and optional resource uri.

      Parameters

      • scope: PreferenceScope

        the PreferenceScope to query for.

      • OptionalresourceUri: string

        the optional uri of the resource-specific preference handling

      • OptionalsectionName: string

        the optional preference section to query for.

      Returns URI | undefined

      the uri of the configuration resource for the given scope and optional resource uri it it exists, undefined otherwise.

    • Retrieve the stored value for the given preference and resourceUri in all available scopes.

      Type Parameters

      • T extends JSONValue

      Parameters

      • preferenceName: string

        the preference identifier.

      • OptionalresourceUri: string

        the uri of the resource for which the preference is stored.

      • OptionaloverrideIdentifier: string

        the identifier of the override to use. Values for the override are returned where defined, values of the base preference otherwise.

      Returns PreferenceInspection<T> | undefined

      an object containing the value of the given preference for all scopes.

    • Retrieve the stored value for the given preference and resourceUri.

      Type Parameters

      • T

      Parameters

      • preferenceName: string

        the preference identifier.

      • OptionaldefaultValue: T

        the value to return when no value for the given preference is stored.

      • OptionalresourceUri: string

        the uri of the resource for which the preference is stored. This used to retrieve a potentially different value for the same preference for different resources, for example files.encoding.

      • OptionaloverrideIdentifier: string

        the identifier of the override to use.

      Returns PreferenceResolveResult<T>

      an object containing the value stored for the given preference and resourceUri when it exists, otherwise the given default value. If determinable the object will also contain the uri of the configuration resource in which the preference was stored.

    • Sets the given preference to the given value.

      Parameters

      • preferenceName: string

        the preference identifier.

      • value: any

        the new value of the preference.

      • Optionalscope: PreferenceScope

        the scope for which the value shall be set, i.e. user, workspace etc. When the folder scope is specified a resourceUri must be provided.

      • OptionalresourceUri: string

        the uri of the resource for which the preference is stored. This used to store a potentially different value for the same preference for different resources, for example files.encoding.

      • OptionaloverrideIdentifier: string

        the identifier of the override to use.

      Returns Promise<void>

      a promise which resolves to undefined when setting the preference was successful. Otherwise it rejects with an error.

    • Determines and applies the changes necessary to apply value to either the resourceUri supplied or the active session. If there is no setting for the preferenceName, the change will be applied in user scope. If there is a setting conflicting with the specified value, the change will be applied in the most specific scope with a conflicting value.

      Parameters

      • preferenceName: string

        the identifier of the preference to modify.

      • value: any

        the value to which to set the preference. undefined will reset the preference to its default value.

      • OptionalresourceUri: string

        the uri of the resource to which the change is to apply. If none is provided, folder scope will be ignored.

      • OptionaloverrideIdentifier: string

        the identifier of the override to use.

      Returns Promise<void>