Source code

Revision control

Other Tools

1
/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2
/* This Source Code Form is subject to the terms of the Mozilla Public
3
* License, v. 2.0. If a copy of the MPL was not distributed with this
4
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5
6
#include "nsISupports.idl"
7
8
%{C++
9
#include "nsLiteralString.h"
10
%}
11
12
interface nsIObserver;
13
14
/**
15
* The nsIPrefBranch interface is used to manipulate the preferences data. This
16
* object may be obtained from the preferences service (nsIPrefService) and
17
* used to get and set default and/or user preferences across the application.
18
*
19
* This object is created with a "root" value which describes the base point in
20
* the preferences "tree" from which this "branch" stems. Preferences are
21
* accessed off of this root by using just the final portion of the preference.
22
* For example, if this object is created with the root "browser.startup.",
23
* the preferences "browser.startup.page", "browser.startup.homepage",
24
* and "browser.startup.homepage_override" can be accessed by simply passing
25
* "page", "homepage", or "homepage_override" to the various Get/Set methods.
26
*
27
* @see nsIPrefService
28
*/
29
30
[scriptable, builtinclass, uuid(55d25e49-793f-4727-a69f-de8b15f4b985)]
31
interface nsIPrefBranch : nsISupports
32
{
33
34
/**
35
* Values describing the basic preference types.
36
*
37
* @see getPrefType
38
*/
39
const long PREF_INVALID = 0;
40
const long PREF_STRING = 32;
41
const long PREF_INT = 64;
42
const long PREF_BOOL = 128;
43
44
/**
45
* Called to get the root on which this branch is based, such as
46
* "browser.startup."
47
*/
48
readonly attribute ACString root;
49
50
/**
51
* Called to determine the type of a specific preference.
52
*
53
* @param aPrefName The preference to get the type of.
54
*
55
* @return long A value representing the type of the preference. This
56
* value will be PREF_STRING, PREF_INT, or PREF_BOOL.
57
*/
58
long getPrefType(in string aPrefName);
59
60
/**
61
* Called to get the state of an individual boolean preference.
62
*
63
* @param aPrefName The boolean preference to get the state of.
64
* @param aDefaultValue The value to return if the preference is not set.
65
*
66
* @return boolean The value of the requested boolean preference.
67
*
68
* @see setBoolPref
69
*/
70
[optional_argc,binaryname(GetBoolPrefWithDefault)]
71
boolean getBoolPref(in string aPrefName, [optional] in boolean aDefaultValue);
72
[noscript,binaryname(GetBoolPref)]
73
boolean getBoolPrefXPCOM(in string aPrefName);
74
75
/**
76
* Called to set the state of an individual boolean preference.
77
*
78
* @param aPrefName The boolean preference to set the state of.
79
* @param aValue The boolean value to set the preference to.
80
*
81
* @throws Error if setting failed or the preference has a default
82
value of a type other than boolean.
83
*
84
* @see getBoolPref
85
*/
86
void setBoolPref(in string aPrefName, in boolean aValue);
87
88
/**
89
* Called to get the state of an individual floating-point preference.
90
* "Floating point" preferences are really string preferences that
91
* are converted to floating point numbers.
92
*
93
* @param aPrefName The floating point preference to get the state of.
94
* @param aDefaultValue The value to return if the preference is not set.
95
*
96
* @return float The value of the requested floating point preference.
97
*
98
* @see setCharPref
99
*/
100
[optional_argc,binaryname(GetFloatPrefWithDefault)]
101
float getFloatPref(in string aPrefName, [optional] in float aDefaultValue);
102
[noscript,binaryname(GetFloatPref)]
103
float getFloatPrefXPCOM(in string aPrefName);
104
105
/**
106
* Called to get the state of an individual ascii string preference.
107
*
108
* @param aPrefName The string preference to retrieve.
109
* @param aDefaultValue The string to return if the preference is not set.
110
*
111
* @return ACString The value of the requested string preference.
112
*
113
* @see setCharPref
114
*/
115
[optional_argc,binaryname(GetCharPrefWithDefault)]
116
ACString getCharPref(in string aPrefName,
117
[optional] in ACString aDefaultValue);
118
[noscript,binaryname(GetCharPref)]
119
ACString getCharPrefXPCOM(in string aPrefName);
120
121
/**
122
* Called to set the state of an individual ascii string preference.
123
*
124
* @param aPrefName The string preference to set.
125
* @param aValue The string value to set the preference to.
126
*
127
* @throws Error if setting failed or the preference has a default
128
value of a type other than string.
129
*
130
* @see getCharPref
131
*/
132
void setCharPref(in string aPrefName, in ACString aValue);
133
134
/**
135
* Called to get the state of an individual unicode string preference.
136
*
137
* @param aPrefName The string preference to retrieve.
138
* @param aDefaultValue The string to return if the preference is not set.
139
*
140
* @return AUTF8String The value of the requested string preference.
141
*
142
* @see setStringPref
143
*/
144
[optional_argc]
145
AUTF8String getStringPref(in string aPrefName,
146
[optional] in AUTF8String aDefaultValue);
147
148
/**
149
* Called to set the state of an individual unicode string preference.
150
*
151
* @param aPrefName The string preference to set.
152
* @param aValue The string value to set the preference to.
153
*
154
* @throws Error if setting failed or the preference has a default
155
value of a type other than string.
156
*
157
* @see getStringPref
158
*/
159
void setStringPref(in string aPrefName, in AUTF8String aValue);
160
161
/**
162
* Called to get the state of an individual integer preference.
163
*
164
* @param aPrefName The integer preference to get the value of.
165
* @param aDefaultValue The value to return if the preference is not set.
166
*
167
* @return long The value of the requested integer preference.
168
*
169
* @see setIntPref
170
*/
171
[optional_argc,binaryname(GetIntPrefWithDefault)]
172
long getIntPref(in string aPrefName, [optional] in long aDefaultValue);
173
[noscript,binaryname(GetIntPref)]
174
long getIntPrefXPCOM(in string aPrefName);
175
176
/**
177
* Called to set the state of an individual integer preference.
178
*
179
* @param aPrefName The integer preference to set the value of.
180
* @param aValue The integer value to set the preference to.
181
*
182
* @throws Error if setting failed or the preference has a default
183
value of a type other than integer.
184
*
185
* @see getIntPref
186
*/
187
void setIntPref(in string aPrefName, in long aValue);
188
189
/**
190
* Called to get the state of an individual complex preference. A complex
191
* preference is a preference which represents an XPCOM object that can not
192
* be easily represented using a standard boolean, integer or string value.
193
*
194
* @param aPrefName The complex preference to get the value of.
195
* @param aType The XPCOM interface that this complex preference
196
* represents. Interfaces currently supported are:
197
* - nsIFile
198
* - nsIPrefLocalizedString (Localized UniChar)
199
* @param aValue The XPCOM object into which to the complex preference
200
* value should be retrieved.
201
*
202
* @throws Error The value does not exist or is the wrong type.
203
*
204
* @see setComplexValue
205
*/
206
void getComplexValue(in string aPrefName, in nsIIDRef aType,
207
[iid_is(aType), retval] out nsQIResult aValue);
208
209
/**
210
* Called to set the state of an individual complex preference. A complex
211
* preference is a preference which represents an XPCOM object that can not
212
* be easily represented using a standard boolean, integer or string value.
213
*
214
* @param aPrefName The complex preference to set the value of.
215
* @param aType The XPCOM interface that this complex preference
216
* represents. Interfaces currently supported are:
217
* - nsIFile
218
* - nsISupportsString (UniChar)
219
* (deprecated; see setStringPref)
220
* - nsIPrefLocalizedString (Localized UniChar)
221
* @param aValue The XPCOM object from which to set the complex preference
222
* value.
223
*
224
* @throws Error if setting failed or the value is the wrong type.
225
*
226
* @see getComplexValue
227
*/
228
void setComplexValue(in string aPrefName, in nsIIDRef aType, in nsISupports aValue);
229
230
/**
231
* Called to clear a user set value from a specific preference. This will, in
232
* effect, reset the value to the default value. If no default value exists
233
* the preference will cease to exist.
234
*
235
* @param aPrefName The preference to be cleared.
236
*
237
* @note
238
* This method does nothing if this object is a default branch.
239
*/
240
void clearUserPref(in string aPrefName);
241
242
/**
243
* Called to lock a specific preference. Locking a preference will cause the
244
* preference service to always return the default value regardless of
245
* whether there is a user set value or not.
246
*
247
* @param aPrefName The preference to be locked.
248
*
249
* @note
250
* This method can be called on either a default or user branch but, in
251
* effect, always operates on the default branch.
252
*
253
* @throws Error The preference does not exist or an error occurred.
254
*
255
* @see unlockPref
256
*/
257
void lockPref(in string aPrefName);
258
259
/**
260
* Called to check if a specific preference has a user value associated to
261
* it.
262
*
263
* @param aPrefName The preference to be tested.
264
*
265
* @note
266
* This method can be called on either a default or user branch but, in
267
* effect, always operates on the user branch.
268
*
269
* @note
270
* If a preference was manually set to a value that equals the default value,
271
* then the preference no longer has a user set value, i.e. it is
272
* considered reset to its default value.
273
* In particular, this method will return false for such a preference and
274
* the preference will not be saved to a file by nsIPrefService.savePrefFile.
275
*
276
* @return boolean true The preference has a user set value.
277
* false The preference only has a default value.
278
*/
279
boolean prefHasUserValue(in string aPrefName);
280
281
/**
282
* Called to check if a specific preference is locked. If a preference is
283
* locked calling its Get method will always return the default value.
284
*
285
* @param aPrefName The preference to be tested.
286
*
287
* @note
288
* This method can be called on either a default or user branch but, in
289
* effect, always operates on the default branch.
290
*
291
* @return boolean true The preference is locked.
292
* false The preference is not locked.
293
*
294
* @see lockPref
295
* @see unlockPref
296
*/
297
boolean prefIsLocked(in string aPrefName);
298
299
/**
300
* Called to unlock a specific preference. Unlocking a previously locked
301
* preference allows the preference service to once again return the user set
302
* value of the preference.
303
*
304
* @param aPrefName The preference to be unlocked.
305
*
306
* @note
307
* This method can be called on either a default or user branch but, in
308
* effect, always operates on the default branch.
309
*
310
* @throws Error The preference does not exist or an error occurred.
311
*
312
* @see lockPref
313
*/
314
void unlockPref(in string aPrefName);
315
316
317
/**
318
* Called to remove all of the preferences referenced by this branch.
319
*
320
* @param aStartingAt The point on the branch at which to start the deleting
321
* preferences. Pass in "" to remove all preferences
322
* referenced by this branch.
323
*
324
* @note
325
* This method can be called on either a default or user branch but, in
326
* effect, always operates on both.
327
*
328
* @throws Error The preference(s) do not exist or an error occurred.
329
*/
330
void deleteBranch(in string aStartingAt);
331
332
/**
333
* Returns an array of strings representing the child preferences of the
334
* root of this branch.
335
*
336
* @param aStartingAt The point on the branch at which to start enumerating
337
* the child preferences. Pass in "" to enumerate all
338
* preferences referenced by this branch.
339
* @return The array of child preferences.
340
*
341
* @note
342
* This method can be called on either a default or user branch but, in
343
* effect, always operates on both.
344
*
345
* @throws Error The preference(s) do not exist or an error occurred.
346
*/
347
Array<ACString> getChildList(in string aStartingAt);
348
349
/**
350
* Called to reset all of the preferences referenced by this branch to their
351
* default values.
352
*
353
* @param aStartingAt The point on the branch at which to start the resetting
354
* preferences to their default values. Pass in "" to
355
* reset all preferences referenced by this branch.
356
*
357
* @note
358
* This method can be called on either a default or user branch but, in
359
* effect, always operates on the user branch.
360
*
361
* @throws Error The preference(s) do not exist or an error occurred.
362
*/
363
void resetBranch(in string aStartingAt);
364
365
/**
366
* Add a preference change observer. On preference changes, the following
367
* arguments will be passed to the nsIObserver.observe() method:
368
* aSubject - The nsIPrefBranch object (this)
369
* aTopic - The string defined by NS_PREFBRANCH_PREFCHANGE_TOPIC_ID
370
* aData - The name of the preference which has changed, relative to
371
* the |root| of the aSubject branch.
372
*
373
* aSubject.get*Pref(aData) will get the new value of the modified
374
* preference. For example, if your observer is registered with
375
* addObserver("bar.", ...) on a branch with root "foo.", modifying
376
* the preference "foo.bar.baz" will trigger the observer, and aData
377
* parameter will be "bar.baz".
378
*
379
* @param aDomain The preference on which to listen for changes. This can
380
* be the name of an entire branch to observe.
381
* e.g. Holding the "root" prefbranch and calling
382
* addObserver("foo.bar.", ...) will observe changes to
383
* foo.bar.baz and foo.bar.bzip
384
* @param aObserver The object to be notified if the preference changes.
385
* @param aHoldWeak true Hold a weak reference to |aObserver|. The object
386
* must implement the nsISupportsWeakReference
387
* interface or this will fail.
388
* false Hold a strong reference to |aObserver|.
389
*
390
* @note
391
* Registering as a preference observer can open an object to potential
392
* cyclical references which will cause memory leaks. These cycles generally
393
* occur because an object both registers itself as an observer (causing the
394
* branch to hold a reference to the observer) and holds a reference to the
395
* branch object for the purpose of getting/setting preference values. There
396
* are 3 approaches which have been implemented in an attempt to avoid these
397
* situations.
398
* 1) The nsPrefBranch object supports nsISupportsWeakReference. Any consumer
399
* may hold a weak reference to it instead of a strong one.
400
* 2) The nsPrefBranch object listens for xpcom-shutdown and frees all of the
401
* objects currently in its observer list. This ensures that long lived
402
* objects (services for example) will be freed correctly.
403
* 3) The observer can request to be held as a weak reference when it is
404
* registered. This insures that shorter lived objects (say one tied to an
405
* open window) will not fall into the cyclical reference trap.
406
*
407
* @note
408
* The list of registered observers may be changed during the dispatch of
409
* nsPref:changed notification. However, the observers are not guaranteed
410
* to be notified in any particular order, so you can't be sure whether the
411
* added/removed observer will be called during the notification when it
412
* is added/removed.
413
*
414
* @note
415
* It is possible to change preferences during the notification.
416
*
417
* @note
418
* It is not safe to change observers during this callback in Gecko
419
* releases before 1.9. If you want a safe way to remove a pref observer,
420
* please use an nsITimer.
421
*
422
* @see nsIObserver
423
* @see removeObserver
424
*/
425
[binaryname(AddObserverImpl)]
426
void addObserver(in ACString aDomain, in nsIObserver aObserver,
427
[optional] in boolean aHoldWeak);
428
429
/**
430
* Remove a preference change observer.
431
*
432
* @param aDomain The preference which is being observed for changes.
433
* @param aObserver An observer previously registered with addObserver().
434
*
435
* @note
436
* Note that you must call removeObserver() on the same nsIPrefBranch
437
* instance on which you called addObserver() in order to remove aObserver;
438
* otherwise, the observer will not be removed.
439
*
440
* @see nsIObserver
441
* @see addObserver
442
*/
443
[binaryname(RemoveObserverImpl)]
444
void removeObserver(in ACString aDomain, in nsIObserver aObserver);
445
446
%{C++
447
nsresult AddObserver(const nsACString& aDomain, nsIObserver* aObserver,
448
bool aHoldWeak = false)
449
{
450
return AddObserverImpl(aDomain, aObserver, aHoldWeak);
451
}
452
453
template <int N>
454
nsresult AddObserver(const char (&aDomain)[N], nsIObserver* aObserver,
455
bool aHoldWeak = false)
456
{
457
return AddObserverImpl(nsLiteralCString(aDomain), aObserver, aHoldWeak);
458
}
459
460
nsresult RemoveObserver(const nsACString& aDomain, nsIObserver* aObserver)
461
{
462
return RemoveObserverImpl(aDomain, aObserver);
463
}
464
465
template <int N>
466
nsresult RemoveObserver(const char (&aDomain)[N], nsIObserver* aObserver)
467
{
468
return RemoveObserverImpl(nsLiteralCString(aDomain), aObserver);
469
}
470
%}
471
};
472
473
474
%{C++
475
476
#define NS_PREFBRANCH_CONTRACTID "@mozilla.org/preferencesbranch;1"
477
/**
478
* Notification sent when a preference changes.
479
*/
480
#define NS_PREFBRANCH_PREFCHANGE_TOPIC_ID "nsPref:changed"
481
482
%}