Interface PreferenceService

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<T>(preferenceName): undefined | T;
    get<T>(preferenceName, defaultValue): T;
    get<T>(preferenceName, defaultValue, resourceUri?): T;
    get<T>(preferenceName, defaultValue?, resourceUri?): undefined | T;
    getConfigUri(scope, resourceUri?, sectionName?): undefined | URI;
    inspect<T>(preferenceName, resourceUri?, forceLanguageOverride?): undefined | PreferenceInspection<T>;
    inspectInScope<T>(preferenceName, scope, resourceUri?, forceLanguageOverride?): undefined | T;
    overriddenPreferenceName(preferenceName): undefined | OverridePreferenceName;
    overridePreferenceName(options): string;
    resolve<T>(preferenceName, defaultValue?, resourceUri?): PreferenceResolveResult<T>;
    set(preferenceName, value, scope?, resourceUri?): Promise<void>;
    updateValue(preferenceName, value, resourceUri?): Promise<void>;
}

Hierarchy (view full)

Implemented by

Properties

isReady onPreferenceChanged onPreferencesChanged ready

Methods

dispose get getConfigUri inspect inspectInScope overriddenPreferenceName overridePreferenceName resolve set updateValue

Properties

Readonly isReady

isReady: boolean

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

onPreferenceChanged

onPreferenceChanged: Event<PreferenceChange>

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

onPreferencesChanged

onPreferencesChanged: Event<PreferenceChanges>

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

Readonly ready

ready: Promise<void>

Promise indicating whether the service successfully initialized.

Methods

dispose

get

  • get<T>(preferenceName): undefined | T

  • Retrieve the stored value for the given preference.

    Type Parameters

    • T

    Parameters

    • preferenceName: string

      the preference identifier.

    Returns undefined | T

    the value stored for the given preference when it exists, undefined otherwise.

  • get<T>(preferenceName, defaultValue): T

  • Retrieve the stored value for the given preference.

    Type Parameters

    • T

    Parameters

    • preferenceName: string

      the preference identifier.

    • defaultValue: T

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

    Returns T

    the value stored for the given preference when it exists, otherwise the given default value.

  • get<T>(preferenceName, defaultValue, resourceUri?): T

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

    Type Parameters

    • T

    Parameters

    • preferenceName: string

      the preference identifier.

    • defaultValue: T

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

    • Optional resourceUri: 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.

    Returns T

    the value stored for the given preference and resourceUri when it exists, otherwise the given default value.

  • get<T>(preferenceName, defaultValue?, resourceUri?): undefined | T

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

    Type Parameters

    • T

    Parameters

    • preferenceName: string

      the preference identifier.

    • Optional defaultValue: T

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

    • Optional resourceUri: 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.

    Returns undefined | T

    the value stored for the given preference and resourceUri when it exists, otherwise the given default value.

getConfigUri

  • getConfigUri(scope, resourceUri?, sectionName?): undefined | URI

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

    Parameters

    • scope: PreferenceScope

      the PreferenceScope to query for.

    • Optional resourceUri: string

      the optional uri of the resource-specific preference handling

    • Optional sectionName: string

      the optional preference section to query for.

    Returns undefined | URI

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

inspect

  • inspect<T>(preferenceName, resourceUri?, forceLanguageOverride?): undefined | PreferenceInspection<T>

  • 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.

    • Optional resourceUri: string

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

    • Optional forceLanguageOverride: boolean

      if true and preferenceName is a language override, only values for the specified override will be returned. Otherwise, values for the override will be returned where defined, and values from the base preference will be returned otherwise.

    Returns undefined | PreferenceInspection<T>

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

inspectInScope

overriddenPreferenceName

  • overriddenPreferenceName(preferenceName): undefined | OverridePreferenceName

  • Tries to split the given preference identifier into the original OverridePreferenceName attributes with which this identifier was created. Returns undefined if this is not possible, for example when the given preference identifier was not generated by overridePreferenceName.

    This method is checked when resolving preferences. Therefore together with "overridePreferenceName" this can be used to handle specialized preferences, e.g. "[markdown].editor.autoIndent" and "editor.autoIndent".

    Parameters

    Returns undefined | OverridePreferenceName

    the OverridePreferenceName which was used to create the given preferenceName if this was the case, undefined otherwise.

overridePreferenceName

resolve

  • resolve<T>(preferenceName, defaultValue?, resourceUri?): PreferenceResolveResult<T>

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

    Type Parameters

    • T

    Parameters

    • preferenceName: string

      the preference identifier.

    • Optional defaultValue: T

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

    • Optional resourceUri: 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.

    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.

set

  • set(preferenceName, value, scope?, resourceUri?): Promise<void>

  • Sets the given preference to the given value.

    Parameters

    • preferenceName: string

      the preference identifier.

    • value: any

      the new value of the preference.

    • Optional scope: 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.

    • Optional resourceUri: 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.

    Returns Promise<void>

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

updateValue

  • updateValue(preferenceName, value, resourceUri?): Promise<void>

  • 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.

    • Optional resourceUri: string

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

    Returns Promise<void>

Settings

Member Visibility

Theme

On This Page

isReadyonPreferenceChangedonPreferencesChangedreadydisposegetgetConfigUriinspectinspectInScopeoverriddenPreferenceNameoverridePreferenceNameresolvesetupdateValue