1 | import { Event, Emitter, DisposableCollection, Disposable } from '../../common';
|
2 | import { Deferred } from '../../common/promise-util';
|
3 | import { PreferenceProvider, PreferenceProviderDataChange, PreferenceProviderDataChanges, PreferenceResolveResult } from './preference-provider';
|
4 | import { PreferenceSchemaProvider } from './preference-contribution';
|
5 | import URI from '../../common/uri';
|
6 | import { PreferenceScope } from './preference-scope';
|
7 | import { PreferenceConfigurations } from './preference-configurations';
|
8 | import { JSONValue } from '@phosphor/coreutils/lib/json';
|
9 | import { OverridePreferenceName, PreferenceLanguageOverrideService } from './preference-language-override-service';
|
10 | export { PreferenceScope };
|
11 | /**
|
12 | * Representation of a preference change. A preference value can be set to `undefined` for a specific scope.
|
13 | * This means that the value from a more general scope will be used.
|
14 | */
|
15 | export interface PreferenceChange extends PreferenceProviderDataChange {
|
16 | /**
|
17 | * Tests wether the given resource is affected by the preference change.
|
18 | * @param resourceUri the uri of the resource to test.
|
19 | */
|
20 | affects(resourceUri?: string): boolean;
|
21 | }
|
22 | export declare class PreferenceChangeImpl implements PreferenceChange {
|
23 | protected readonly change: PreferenceProviderDataChange;
|
24 | constructor(change: PreferenceProviderDataChange);
|
25 | get preferenceName(): string;
|
26 | get newValue(): string;
|
27 | get oldValue(): string;
|
28 | get scope(): PreferenceScope;
|
29 | get domain(): string[] | undefined;
|
30 | affects(resourceUri?: string): boolean;
|
31 | }
|
32 | /**
|
33 | * A key-value storage for { PreferenceChange}s. Used to aggregate multiple simultaneous preference changes.
|
34 | */
|
35 | export interface PreferenceChanges {
|
36 | [preferenceName: string]: PreferenceChange;
|
37 | }
|
38 | export declare const PreferenceService: unique symbol;
|
39 | /**
|
40 | * Service to manage preferences including, among others, getting and setting preference values as well
|
41 | * as listening to preference changes.
|
42 | *
|
43 | * Depending on your use case you might also want to look at {@link createPreferenceProxy} with which
|
44 | * you can easily create a typesafe schema-based interface for your preferences. Internally the proxy
|
45 | * uses the PreferenceService so both approaches are compatible.
|
46 | */
|
47 | export interface PreferenceService extends Disposable {
|
48 | /**
|
49 | * Promise indicating whether the service successfully initialized.
|
50 | */
|
51 | readonly ready: Promise<void>;
|
52 | /**
|
53 | * Indicates whether the service has successfully initialized. Will be `true` when {@link PreferenceService.ready the `ready` Promise} resolves.
|
54 | */
|
55 | readonly isReady: boolean;
|
56 | /**
|
57 | * Retrieve the stored value for the given preference.
|
58 | *
|
59 | * @param preferenceName the preference identifier.
|
60 | *
|
61 | * @returns the value stored for the given preference when it exists, `undefined` otherwise.
|
62 | */
|
63 | get<T>(preferenceName: string): T | undefined;
|
64 | /**
|
65 | * Retrieve the stored value for the given preference.
|
66 | *
|
67 | * @param preferenceName the preference identifier.
|
68 | * @param defaultValue the value to return when no value for the given preference is stored.
|
69 | *
|
70 | * @returns the value stored for the given preference when it exists, otherwise the given default value.
|
71 | */
|
72 | get<T>(preferenceName: string, defaultValue: T): T;
|
73 | /**
|
74 | * Retrieve the stored value for the given preference and resourceUri.
|
75 | *
|
76 | * @param preferenceName the preference identifier.
|
77 | * @param defaultValue the value to return when no value for the given preference is stored.
|
78 | * @param resourceUri the uri of the resource for which the preference is stored. This used to retrieve
|
79 | * a potentially different value for the same preference for different resources, for example `files.encoding`.
|
80 | *
|
81 | * @returns the value stored for the given preference and resourceUri when it exists, otherwise the given
|
82 | * default value.
|
83 | */
|
84 | get<T>(preferenceName: string, defaultValue: T, resourceUri?: string): T;
|
85 | /**
|
86 | * Retrieve the stored value for the given preference and resourceUri.
|
87 | *
|
88 | * @param preferenceName the preference identifier.
|
89 | * @param defaultValue the value to return when no value for the given preference is stored.
|
90 | * @param resourceUri the uri of the resource for which the preference is stored. This used to retrieve
|
91 | * a potentially different value for the same preference for different resources, for example `files.encoding`.
|
92 | *
|
93 | * @returns the value stored for the given preference and resourceUri when it exists, otherwise the given
|
94 | * default value.
|
95 | */
|
96 | get<T>(preferenceName: string, defaultValue?: T, resourceUri?: string): T | undefined;
|
97 | /**
|
98 | * Sets the given preference to the given value.
|
99 | *
|
100 | * @param preferenceName the preference identifier.
|
101 | * @param value the new value of the preference.
|
102 | * @param scope the scope for which the value shall be set, i.e. user, workspace etc.
|
103 | * When the folder scope is specified a resourceUri must be provided.
|
104 | * @param resourceUri the uri of the resource for which the preference is stored. This used to store
|
105 | * a potentially different value for the same preference for different resources, for example `files.encoding`.
|
106 | *
|
107 | * @returns a promise which resolves to `undefined` when setting the preference was successful. Otherwise it rejects
|
108 | * with an error.
|
109 | */
|
110 | set(preferenceName: string, value: any, scope?: PreferenceScope, resourceUri?: string): Promise<void>;
|
111 | /**
|
112 | * Determines and applies the changes necessary to apply `value` to either the `resourceUri` supplied or the active session.
|
113 | * If there is no setting for the `preferenceName`, the change will be applied in user scope.
|
114 | * If there is a setting conflicting with the specified `value`, the change will be applied in the most specific scope with a conflicting value.
|
115 | *
|
116 | * @param preferenceName the identifier of the preference to modify.
|
117 | * @param value the value to which to set the preference. `undefined` will reset the preference to its default value.
|
118 | * @param resourceUri the uri of the resource to which the change is to apply. If none is provided, folder scope will be ignored.
|
119 | */
|
120 | updateValue(preferenceName: string, value: any, resourceUri?: string): Promise<void>;
|
121 | /**
|
122 | * Registers a callback which will be called whenever a preference is changed.
|
123 | */
|
124 | onPreferenceChanged: Event<PreferenceChange>;
|
125 | /**
|
126 | * Registers a callback which will be called whenever one or more preferences are changed.
|
127 | */
|
128 | onPreferencesChanged: Event<PreferenceChanges>;
|
129 | /**
|
130 | * Retrieve the stored value for the given preference and resourceUri in all available scopes.
|
131 | *
|
132 | * @param preferenceName the preference identifier.
|
133 | * @param resourceUri the uri of the resource for which the preference is stored.
|
134 | * @param forceLanguageOverride if `true` and `preferenceName` is a language override, only values for the specified override will be returned.
|
135 | * Otherwise, values for the override will be returned where defined, and values from the base preference will be returned otherwise.
|
136 | *
|
137 | * @return an object containing the value of the given preference for all scopes.
|
138 | */
|
139 | inspect<T extends JSONValue>(preferenceName: string, resourceUri?: string, forceLanguageOverride?: boolean): PreferenceInspection<T> | undefined;
|
140 | /**
|
141 | * For behavior, see {@link PreferenceService.inspect}.
|
142 | *
|
143 | * @returns the value in the scope specified.
|
144 | */
|
145 | inspectInScope<T extends JSONValue>(preferenceName: string, scope: PreferenceScope, resourceUri?: string, forceLanguageOverride?: boolean): T | undefined;
|
146 | /**
|
147 | * Returns a new preference identifier based on the given OverridePreferenceName.
|
148 | *
|
149 | * @param options the override specification.
|
150 | *
|
151 | * @returns the calculated string based on the given OverridePreferenceName.
|
152 | */
|
153 | overridePreferenceName(options: OverridePreferenceName): string;
|
154 | /**
|
155 | * Tries to split the given preference identifier into the original OverridePreferenceName attributes
|
156 | * with which this identifier was created. Returns `undefined` if this is not possible, for example
|
157 | * when the given preference identifier was not generated by `overridePreferenceName`.
|
158 | *
|
159 | * This method is checked when resolving preferences. Therefore together with "overridePreferenceName"
|
160 | * this can be used to handle specialized preferences, e.g. "[markdown].editor.autoIndent" and "editor.autoIndent".
|
161 | *
|
162 | * @param preferenceName the preferenceName which might have been created via {@link PreferenceService.overridePreferenceName}.
|
163 | *
|
164 | * @returns the OverridePreferenceName which was used to create the given `preferenceName` if this was the case,
|
165 | * `undefined` otherwise.
|
166 | */
|
167 | overriddenPreferenceName(preferenceName: string): OverridePreferenceName | undefined;
|
168 | /**
|
169 | * Retrieve the stored value for the given preference and resourceUri.
|
170 | *
|
171 | * @param preferenceName the preference identifier.
|
172 | * @param defaultValue the value to return when no value for the given preference is stored.
|
173 | * @param resourceUri the uri of the resource for which the preference is stored. This used to retrieve
|
174 | * a potentially different value for the same preference for different resources, for example `files.encoding`.
|
175 | *
|
176 | * @returns an object containing the value stored for the given preference and resourceUri when it exists,
|
177 | * otherwise the given default value. If determinable the object will also contain the uri of the configuration
|
178 | * resource in which the preference was stored.
|
179 | */
|
180 | resolve<T>(preferenceName: string, defaultValue?: T, resourceUri?: string): PreferenceResolveResult<T>;
|
181 | /**
|
182 | * Returns the uri of the configuration resource for the given scope and optional resource uri.
|
183 | *
|
184 | * @param scope the PreferenceScope to query for.
|
185 | * @param resourceUri the optional uri of the resource-specific preference handling
|
186 | * @param sectionName the optional preference section to query for.
|
187 | *
|
188 | * @returns the uri of the configuration resource for the given scope and optional resource uri it it exists,
|
189 | * `undefined` otherwise.
|
190 | */
|
191 | getConfigUri(scope: PreferenceScope, resourceUri?: string, sectionName?: string): URI | undefined;
|
192 | }
|
193 | /**
|
194 | * Return type of the {@link PreferenceService.inspect} call.
|
195 | */
|
196 | export interface PreferenceInspection<T = JSONValue> {
|
197 | /**
|
198 | * The preference identifier.
|
199 | */
|
200 | preferenceName: string;
|
201 | /**
|
202 | * Value in default scope.
|
203 | */
|
204 | defaultValue: T | undefined;
|
205 | /**
|
206 | * Value in user scope.
|
207 | */
|
208 | globalValue: T | undefined;
|
209 | /**
|
210 | * Value in workspace scope.
|
211 | */
|
212 | workspaceValue: T | undefined;
|
213 | /**
|
214 | * Value in folder scope.
|
215 | */
|
216 | workspaceFolderValue: T | undefined;
|
217 | /**
|
218 | * The value that is active, i.e. the value set in the lowest scope available.
|
219 | */
|
220 | value: T | undefined;
|
221 | }
|
222 | export declare type PreferenceInspectionScope = keyof Omit<PreferenceInspection<unknown>, 'preferenceName'>;
|
223 | /**
|
224 | * We cannot load providers directly in the case if they depend on `PreferenceService` somehow.
|
225 | * It allows to load them lazily after DI is configured.
|
226 | */
|
227 | export declare const PreferenceProviderProvider: unique symbol;
|
228 | export declare type PreferenceProviderProvider = (scope: PreferenceScope, uri?: URI) => PreferenceProvider;
|
229 | export declare class PreferenceServiceImpl implements PreferenceService {
|
230 | protected readonly onPreferenceChangedEmitter: Emitter<PreferenceChange>;
|
231 | readonly onPreferenceChanged: Event<PreferenceChange>;
|
232 | protected readonly onPreferencesChangedEmitter: Emitter<PreferenceChanges>;
|
233 | readonly onPreferencesChanged: Event<PreferenceChanges>;
|
234 | protected readonly toDispose: DisposableCollection;
|
235 | protected readonly schema: PreferenceSchemaProvider;
|
236 | protected readonly providerProvider: PreferenceProviderProvider;
|
237 | protected readonly configurations: PreferenceConfigurations;
|
238 | protected readonly preferenceOverrideService: PreferenceLanguageOverrideService;
|
239 | protected readonly preferenceProviders: Map<PreferenceScope, PreferenceProvider>;
|
240 | protected initializeProviders(): Promise<void>;
|
241 | protected init(): void;
|
242 | dispose(): void;
|
243 | protected readonly _ready: Deferred<void>;
|
244 | get ready(): Promise<void>;
|
245 | protected _isReady: boolean;
|
246 | get isReady(): boolean;
|
247 | protected reconcilePreferences(changes: PreferenceProviderDataChanges): void;
|
248 | protected getAffectedPreferenceNames(change: PreferenceProviderDataChange, accept: (affectedPreferenceName: string) => void): void;
|
249 | protected getProvider(scope: PreferenceScope): PreferenceProvider | undefined;
|
250 | has(preferenceName: string, resourceUri?: string): boolean;
|
251 | get<T>(preferenceName: string): T | undefined;
|
252 | get<T>(preferenceName: string, defaultValue: T): T;
|
253 | get<T>(preferenceName: string, defaultValue: T, resourceUri: string): T;
|
254 | get<T>(preferenceName: string, defaultValue?: T, resourceUri?: string): T | undefined;
|
255 | resolve<T>(preferenceName: string, defaultValue?: T, resourceUri?: string): PreferenceResolveResult<T>;
|
256 | set(preferenceName: string, value: any, scope: PreferenceScope | undefined, resourceUri?: string): Promise<void>;
|
257 | getBoolean(preferenceName: string): boolean | undefined;
|
258 | getBoolean(preferenceName: string, defaultValue: boolean): boolean;
|
259 | getBoolean(preferenceName: string, defaultValue: boolean, resourceUri: string): boolean;
|
260 | getString(preferenceName: string): string | undefined;
|
261 | getString(preferenceName: string, defaultValue: string): string;
|
262 | getString(preferenceName: string, defaultValue: string, resourceUri: string): string;
|
263 | getNumber(preferenceName: string): number | undefined;
|
264 | getNumber(preferenceName: string, defaultValue: number): number;
|
265 | getNumber(preferenceName: string, defaultValue: number, resourceUri: string): number;
|
266 | inspect<T extends JSONValue>(preferenceName: string, resourceUri?: string, forceLanguageOverride?: boolean): PreferenceInspection<T> | undefined;
|
267 | inspectInScope<T extends JSONValue>(preferenceName: string, scope: PreferenceScope, resourceUri?: string, forceLanguageOverride?: boolean): T | undefined;
|
268 | protected getScopedValueFromInspection<T>(inspection: PreferenceInspection<T>, scope: PreferenceScope): T | undefined;
|
269 | updateValue(preferenceName: string, value: any, resourceUri?: string): Promise<void>;
|
270 | protected getScopesToChange(inspection: PreferenceInspection<any>, intendedValue: any): PreferenceScope[];
|
271 | overridePreferenceName(options: OverridePreferenceName): string;
|
272 | overriddenPreferenceName(preferenceName: string): OverridePreferenceName | undefined;
|
273 | protected doHas(preferenceName: string, resourceUri?: string): boolean;
|
274 | protected doInspectInScope<T>(preferenceName: string, scope: PreferenceScope, resourceUri?: string): T | undefined;
|
275 | protected doGet<T>(preferenceName: string, defaultValue?: T, resourceUri?: string): T | undefined;
|
276 | protected doResolve<T>(preferenceName: string, defaultValue?: T, resourceUri?: string): PreferenceResolveResult<T>;
|
277 | getConfigUri(scope: PreferenceScope, resourceUri?: string, sectionName?: string): URI | undefined;
|
278 | }
|
279 | //# sourceMappingURL=preference-service.d.ts.map |
\ | No newline at end of file |