Java > Open Source Codes > org > eclipse > jface > preference > IPreferenceStore


1 /*******************************************************************************
2  * Copyright (c) 2000, 2006 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11 package org.eclipse.jface.preference;
12
13 import org.eclipse.jface.util.IPropertyChangeListener;
14
15 /**
16  * The <code>IPreferenceStore</code> interface represents a table mapping
17  * named preferences to values. If there is no value for a given name,
18  * then that preferences's default value is returned; and if there is no
19  * default value for that preference, then a default-default value is returned.
20  * The default-default values for the primitive types are as follows:
21  * <ul>
22  * <li><code>boolean</code> = <code>false</code></li>
23  * <li><code>double</code> = <code>0.0</code></li>
24  * <li><code>float</code> = <code>0.0f</code></li>
25  * <li><code>int</code> = <code>0</code></li>
26  * <li><code>long</code> = <code>0</code></li>
27  * <li><code>String</code> = <code>""</code> (the empty string)</li>
28  * </ul>
29  * <p>
30  * Thus a preference store maintains two values for each of a set of
31  * names: a current value and a default value.
32  * The typical usage is to establish the defaults for all known preferences
33  * and then restore previously stored values for preferences whose values
34  * were different from their defaults. After the current values of
35  * the preferences have been modified, it is a simple matter to write
36  * out only those preferences whose values are different from their defaults.
37  * This two-tiered approach to saving and restoring preference setting
38  * minimized the number of preferences that need to be persisted; indeed,
39  * the normal starting state does not require storing any preferences
40  * at all.
41  * </p>
42  * <p>
43  * A property change event is reported whenever a preferences current
44  * value actually changes (whether through <code>setValue</code>,
45  * <code>setToDefault</code>, or other unspecified means). Note, however,
46  * that manipulating default values (with <code>setDefault</code>)
47  * does not cause such events to be reported.
48  * </p>
49  * <p>
50  * Clients who need a preference store may implement this interface or
51  * instantiate the standard implementation <code>PreferenceStore</code>.
52  * </p>
53  *
54  * @see PreferenceStore
55  */
56 public interface IPreferenceStore {
57
58     /**
59      * The default-default value for boolean preferences (<code>false</code>).
60      */
61     public static final boolean BOOLEAN_DEFAULT_DEFAULT = false;
62
63     /**
64      * The default-default value for double preferences (<code>0.0</code>).
65      */
66     public static final double DOUBLE_DEFAULT_DEFAULT = 0.0;
67
68     /**
69      * The default-default value for float preferences (<code>0.0f</code>).
70      */
71     public static final float FLOAT_DEFAULT_DEFAULT = 0.0f;
72
73     /**
74      * The default-default value for int preferences (<code>0</code>).
75      */
76     public static final int INT_DEFAULT_DEFAULT = 0;
77
78     /**
79      * The default-default value for long preferences (<code>0L</code>).
80      */
81     public static final long LONG_DEFAULT_DEFAULT = 0L;
82
83     /**
84      * The default-default value for String preferences (<code>""</code>).
85      */
86     public static final String STRING_DEFAULT_DEFAULT = ""; //$NON-NLS-1$
87
88     /**
89      * The string representation used for <code>true</code> (<code>"true"</code>).
90      */
91     public static final String TRUE = "true"; //$NON-NLS-1$
92
93     /**
94      * The string representation used for <code>false</code> (<code>"false"</code>).
95      */
96     public static final String FALSE = "false"; //$NON-NLS-1$
97
98     /**
99      * <p>
100      * Adds a property change listener to this preference store.
101      * </p>
102      * <p>
103      * <b>Note</b> The types of the oldValue and newValue of the
104      * generated PropertyChangeEvent are determined by whether
105      * or not the typed API in IPreferenceStore was called.
106      * If values are changed via setValue(name,type) the
107      * values in the PropertyChangedEvent will be of that type.
108      * If they are set using a non typed API (i.e. #setToDefault
109      * or using the OSGI Preferences) the values will be unconverted
110      * Strings.
111      * </p>
112      * <p>
113      * A listener will be called in the same Thread
114      * that it is invoked in. Any Thread dependant listeners (such as
115      * those who update an SWT widget) will need to update in the
116      * correct Thread. In the case of an SWT update you can update
117      * using Display#syncExec(Runnable) or Display#asyncExec(Runnable).
118      * </p>
119      * <p>
120      * Likewise any application that updates an IPreferenceStore
121      * from a Thread other than the UI Thread should be aware of
122      * any listeners that require an update in the UI Thread.
123      * </p>
124      *
125      * @param listener a property change listener
126      * @see org.eclipse.jface.util.PropertyChangeEvent
127      * @see #setToDefault(String)
128      * @see #setValue(String, boolean)
129      * @see #setValue(String, double)
130      * @see #setValue(String, float)
131      * @see #setValue(String, int)
132      * @see #setValue(String, long)
133      * @see #setValue(String, String)
134      */
135     public void addPropertyChangeListener(IPropertyChangeListener listener);
136
137     /**
138      * Returns whether the named preference is known to this preference
139      * store.
140      *
141      * @param name the name of the preference
142      * @return <code>true</code> if either a current value or a default
143      * value is known for the named preference, and <code>false</code> otherwise
144      */
145     public boolean contains(String name);
146
147     /**
148      * Fires a property change event corresponding to a change to the
149      * current value of the preference with the given name.
150      * <p>
151      * This method is provided on this interface to simplify the implementation
152      * of decorators. There is normally no need to call this method since
153      * <code>setValue</code> and <code>setToDefault</code> report such
154      * events in due course. Implementations should funnel all preference
155      * changes through this method.
156      * </p>
157      *
158      * @param name the name of the preference, to be used as the property
159      * in the event object
160      * @param oldValue the old value
161      * @param newValue the new value
162      */
163     public void firePropertyChangeEvent(String name, Object oldValue,
164             Object newValue);
165
166     /**
167      * Returns the current value of the boolean-valued preference with the
168      * given name.
169      * Returns the default-default value (<code>false</code>) if there
170      * is no preference with the given name, or if the current value
171      * cannot be treated as a boolean.
172      *
173      * @param name the name of the preference
174      * @return the boolean-valued preference
175      */
176     public boolean getBoolean(String name);
177
178     /**
179      * Returns the default value for the boolean-valued preference
180      * with the given name.
181      * Returns the default-default value (<code>false</code>) if there
182      * is no default preference with the given name, or if the default
183      * value cannot be treated as a boolean.
184      *
185      * @param name the name of the preference
186      * @return the default value of the named preference
187      */
188     public boolean getDefaultBoolean(String name);
189
190     /**
191      * Returns the default value for the double-valued preference
192      * with the given name.
193      * Returns the default-default value (<code>0.0</code>) if there
194      * is no default preference with the given name, or if the default
195      * value cannot be treated as a double.
196      *
197      * @param name the name of the preference
198      * @return the default value of the named preference
199      */
200     public double getDefaultDouble(String name);
201
202     /**
203      * Returns the default value for the float-valued preference
204      * with the given name.
205      * Returns the default-default value (<code>0.0f</code>) if there
206      * is no default preference with the given name, or if the default
207      * value cannot be treated as a float.
208      *
209      * @param name the name of the preference
210      * @return the default value of the named preference
211      */
212     public float getDefaultFloat(String name);
213
214     /**
215      * Returns the default value for the integer-valued preference
216      * with the given name.
217      * Returns the default-default value (<code>0</code>) if there
218      * is no default preference with the given name, or if the default
219      * value cannot be treated as an integer.
220      *
221      * @param name the name of the preference
222      * @return the default value of the named preference
223      */
224     public int getDefaultInt(String name);
225
226     /**
227      * Returns the default value for the long-valued preference
228      * with the given name.
229      * Returns the default-default value (<code>0L</code>) if there
230      * is no default preference with the given name, or if the default
231      * value cannot be treated as a long.
232      *
233      * @param name the name of the preference
234      * @return the default value of the named preference
235      */
236     public long getDefaultLong(String name);
237
238     /**
239      * Returns the default value for the string-valued preference
240      * with the given name.
241      * Returns the default-default value (the empty string <code>""</code>)
242      * is no default preference with the given name, or if the default
243      * value cannot be treated as a string.
244      *
245      * @param name the name of the preference
246      * @return the default value of the named preference
247      */
248     public String getDefaultString(String name);
249
250     /**
251      * Returns the current value of the double-valued preference with the
252      * given name.
253      * Returns the default-default value (<code>0.0</code>) if there
254      * is no preference with the given name, or if the current value
255      * cannot be treated as a double.
256      *
257      * @param name the name of the preference
258      * @return the double-valued preference
259      */
260     public double getDouble(String name);
261
262     /**
263      * Returns the current value of the float-valued preference with the
264      * given name.
265      * Returns the default-default value (<code>0.0f</code>) if there
266      * is no preference with the given name, or if the current value
267      * cannot be treated as a float.
268      *
269      * @param name the name of the preference
270      * @return the float-valued preference
271      */
272     public float getFloat(String name);
273
274     /**
275      * Returns the current value of the integer-valued preference with the
276      * given name.
277      * Returns the default-default value (<code>0</code>) if there
278      * is no preference with the given name, or if the current value
279      * cannot be treated as an integter.
280      *
281      * @param name the name of the preference
282      * @return the int-valued preference
283      */
284     public int getInt(String name);
285
286     /**
287      * Returns the current value of the long-valued preference with the
288      * given name.
289      * Returns the default-default value (<code>0L</code>) if there
290      * is no preference with the given name, or if the current value
291      * cannot be treated as a long.
292      *
293      * @param name the name of the preference
294      * @return the long-valued preference
295      */
296     public long getLong(String name);
297
298     /**
299      * Returns the current value of the string-valued preference with the
300      * given name.
301      * Returns the default-default value (the empty string <code>""</code>)
302      * if there is no preference with the given name, or if the current value
303      * cannot be treated as a string.
304      *
305      * @param name the name of the preference
306      * @return the string-valued preference
307      */
308     public String getString(String name);
309
310     /**
311      * Returns whether the current value of the preference with the given name
312      * has the default value.
313      *
314      * @param name the name of the preference
315      * @return <code>true</code> if the preference has a known default value
316      * and its current value is the same, and <code>false</code> otherwise
317      * (including the case where the preference is unknown to this store)
318      */
319     public boolean isDefault(String name);
320
321     /**
322      * Returns whether the current values in this property store
323      * require saving.
324      *
325      * @return <code>true</code> if at least one of values of
326      * the preferences known to this store has changed and
327      * requires saving, and <code>false</code> otherwise.
328      */
329     public boolean needsSaving();
330
331     /**
332      * Sets the current value of the preference with the given name to
333      * the given string value without sending a property change.
334      * <p>
335      * This method does not fire a property change event and
336      * should only be used for setting internal preferences
337      * that are not meant to be processed by listeners.
338      * Normal clients should instead call #setValue.
339      * </p>
340      *
341      * @param name the name of the preference
342      * @param value the new current value of the preference
343      */
344     public void putValue(String name, String value);
345
346     /**
347      * Removes the given listener from this preference store.
348      * Has no affect if the listener is not registered.
349      *
350      * @param listener a property change listener
351      */
352     public void removePropertyChangeListener(IPropertyChangeListener listener);
353
354     /**
355      * Sets the default value for the double-valued preference with the
356      * given name.
357      * <p>
358      * Note that the current value of the preference is affected if
359      * the preference's current value was its old default value, in which
360      * case it changes to the new default value. If the preference's current
361      * is different from its old default value, its current value is
362      * unaffected. No property change events are reported by changing default
363      * values.
364      * </p>
365      *
366      * @param name the name of the preference
367      * @param value the new default value for the preference
368      */
369     public void setDefault(String name, double value);
370
371     /**
372      * Sets the default value for the float-valued preference with the
373      * given name.
374      * <p>
375      * Note that the current value of the preference is affected if
376      * the preference's current value was its old default value, in which
377      * case it changes to the new default value. If the preference's current
378      * is different from its old default value, its current value is
379      * unaffected. No property change events are reported by changing default
380      * values.
381      * </p>
382      *
383      * @param name the name of the preference
384      * @param value the new default value for the preference
385      */
386     public void setDefault(String name, float value);
387
388     /**
389      * Sets the default value for the integer-valued preference with the
390      * given name.
391      * <p>
392      * Note that the current value of the preference is affected if
393      * the preference's current value was its old default value, in which
394      * case it changes to the new default value. If the preference's current
395      * is different from its old default value, its current value is
396      * unaffected. No property change events are reported by changing default
397      * values.
398      * </p>
399      *
400      * @param name the name of the preference
401      * @param value the new default value for the preference
402      */
403     public void setDefault(String name, int value);
404
405     /**
406      * Sets the default value for the long-valued preference with the
407      * given name.
408      * <p>
409      * Note that the current value of the preference is affected if
410      * the preference's current value was its old default value, in which
411      * case it changes to the new default value. If the preference's current
412      * is different from its old default value, its current value is
413      * unaffected. No property change events are reported by changing default
414      * values.
415      * </p>
416      *
417      * @param name the name of the preference
418      * @param value the new default value for the preference
419      */
420     public void setDefault(String name, long value);
421
422     /**
423      * Sets the default value for the string-valued preference with the
424      * given name.
425      * <p>
426      * Note that the current value of the preference is affected if
427      * the preference's current value was its old default value, in which
428      * case it changes to the new default value. If the preference's current
429      * is different from its old default value, its current value is
430      * unaffected. No property change events are reported by changing default
431      * values.
432      * </p>
433      *
434      * @param name the name of the preference
435      * @param defaultObject the new default value for the preference
436      */
437     public void setDefault(String name, String defaultObject);
438
439     /**
440      * Sets the default value for the boolean-valued preference with the
441      * given name.
442      * <p>
443      * Note that the current value of the preference is affected if
444      * the preference's current value was its old default value, in which
445      * case it changes to the new default value. If the preference's current
446      * is different from its old default value, its current value is
447      * unaffected. No property change events are reported by changing default
448      * values.
449      * </p>
450      *
451      * @param name the name of the preference
452      * @param value the new default value for the preference
453      */
454     public void setDefault(String name, boolean value);
455
456     /**
457      * Sets the current value of the preference with the given name back
458      * to its default value.
459      * <p>
460      * Note that the preferred way of re-initializing a preference to the
461      * appropriate default value is to call <code>setToDefault</code>.
462      * This is implemented by removing the named value from the store,
463      * thereby exposing the default value.
464      * </p>
465      *
466      * @param name the name of the preference
467      */
468     public void setToDefault(String name);
469
470     /**
471      * Sets the current value of the double-valued preference with the
472      * given name.
473      * <p>
474      * A property change event is reported if the current value of the
475      * preference actually changes from its previous value. In the event
476      * object, the property name is the name of the preference, and the
477      * old and new values are wrapped as objects.
478      * </p>
479      * <p>
480      * Note that the preferred way of re-initializing a preference to its
481      * default value is to call <code>setToDefault</code>.
482      * </p>
483      *
484      * @param name the name of the preference
485      * @param value the new current value of the preference
486      */
487     public void setValue(String name, double value);
488
489     /**
490      * Sets the current value of the float-valued preference with the
491      * given name.
492      * <p>
493      * A property change event is reported if the current value of the
494      * preference actually changes from its previous value. In the event
495      * object, the property name is the name of the preference, and the
496      * old and new values are wrapped as objects.
497      * </p>
498      * <p>
499      * Note that the preferred way of re-initializing a preference to its
500      * default value is to call <code>setToDefault</code>.
501      * </p>
502      *
503      * @param name the name of the preference
504      * @param value the new current value of the preference
505      */
506     public void setValue(String name, float value);
507
508     /**
509      * Sets the current value of the integer-valued preference with the
510      * given name.
511      * <p>
512      * A property change event is reported if the current value of the
513      * preference actually changes from its previous value. In the event
514      * object, the property name is the name of the preference, and the
515      * old and new values are wrapped as objects.
516      * </p>
517      * <p>
518      * Note that the preferred way of re-initializing a preference to its
519      * default value is to call <code>setToDefault</code>.
520      * </p>
521      *
522      * @param name the name of the preference
523      * @param value the new current value of the preference
524      */
525     public void setValue(String name, int value);
526
527     /**
528      * Sets the current value of the long-valued preference with the
529      * given name.
530      * <p>
531      * A property change event is reported if the current value of the
532      * preference actually changes from its previous value. In the event
533      * object, the property name is the name of the preference, and the
534      * old and new values are wrapped as objects.
535      * </p>
536      * <p>
537      * Note that the preferred way of re-initializing a preference to its
538      * default value is to call <code>setToDefault</code>.
539      * </p>
540      *
541      * @param name the name of the preference
542      * @param value the new current value of the preference
543      */
544     public void setValue(String name, long value);
545
546     /**
547      * Sets the current value of the string-valued preference with the
548      * given name.
549      * <p>
550      * A property change event is reported if the current value of the
551      * preference actually changes from its previous value. In the event
552      * object, the property name is the name of the preference, and the
553      * old and new values are wrapped as objects.
554      * </p>
555      * <p>
556      * Note that the preferred way of re-initializing a preference to its
557      * default value is to call <code>setToDefault</code>.
558      * </p>
559      *
560      * @param name the name of the preference
561      * @param value the new current value of the preference
562      */
563     public void setValue(String name, String value);
564
565     /**
566      * Sets the current value of the boolean-valued preference with the
567      * given name.
568      * <p>
569      * A property change event is reported if the current value of the
570      * preference actually changes from its previous value. In the event
571      * object, the property name is the name of the preference, and the
572      * old and new values are wrapped as objects.
573      * </p>
574      * <p>
575      * Note that the preferred way of re-initializing a preference to its
576      * default value is to call <code>setToDefault</code>.
577      * </p>
578      *
579      * @param name the name of the preference
580      * @param value the new current value of the preference
581      */
582     public void setValue(String name, boolean value);
583 }
584

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags