PreferenceConverter


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 java.util.Arrays  ;
14  import java.util.StringTokenizer  ;
15  
16  import org.eclipse.jface.resource.JFaceResources;
17  import org.eclipse.jface.resource.StringConverter;
18  import org.eclipse.swt.SWTException;
19  import org.eclipse.swt.graphics.FontData;
20  import org.eclipse.swt.graphics.Point;
21  import org.eclipse.swt.graphics.RGB;
22  import org.eclipse.swt.graphics.Rectangle;
23  import org.eclipse.swt.widgets.Display;
24  
25  /**
26   * A utility class for dealing with preferences whose values are
27   * common SWT objects (color, points, rectangles, and font data).
28   * The static methods on this class handle the conversion between
29   * the SWT objects and their string representations.
30   * <p>
31   * Usage:
32   * <pre>
33   * IPreferenceStore store = ...;
34   * PreferenceConverter.setValue(store, "bg", new RGB(127,127,127));
35   * ...
36   * RBG bgColor = PreferenceConverter.getValue(store, "bg");
37   * </pre>
38   * </p>
39   * <p>
40   * This class contains static methods and fields only and cannot 
41   * be instantiated.
42   * </p>
43   * Note: touching this class has the side effect of creating a display (static initializer).
44   */
45  public class PreferenceConverter {
46  
47      /**
48       * The default-default value for point preferences
49       * (the origin, <code>(0,0)</code>).
50       */
51      public static final Point POINT_DEFAULT_DEFAULT = new Point(0, 0);
52  
53      /**
54       * The default-default value for rectangle preferences
55       * (the empty rectangle <code>(0,0,0,0)</code>).
56       */
57      public static final Rectangle RECTANGLE_DEFAULT_DEFAULT = new Rectangle(0,
58              0, 0, 0);
59  
60      /**
61       * The default-default value for color preferences 
62       * (black, <code>RGB(0,0,0)</code>).
63       */
64      public static final RGB COLOR_DEFAULT_DEFAULT = new RGB(0, 0, 0);
65  
66      private static final String   ENTRY_SEPARATOR = ";"; //$NON-NLS-1$
67  
68      /**
69       * The default-default value for <code>FontData[]</code> preferences.
70       */
71      public static final FontData[] FONTDATA_ARRAY_DEFAULT_DEFAULT;
72  
73      /**
74       * The default-default value for <code>FontData</code> preferences.
75       */
76      public static final FontData FONTDATA_DEFAULT_DEFAULT;
77      static {
78          Display display = Display.getCurrent();
79          if (display == null) {
80              display = Display.getDefault ();
81          }
82          
83          FONTDATA_ARRAY_DEFAULT_DEFAULT = display.getSystemFont().getFontData();
84          /**
85           * The default-default value for <code>FontData</code> preferences.
86           * This is left in for compatibility purposes. It is recommended that
87           * FONTDATA_ARRAY_DEFAULT_DEFAULT is actually used.
88           */
89  
90          FONTDATA_DEFAULT_DEFAULT = FONTDATA_ARRAY_DEFAULT_DEFAULT[0];
91      }
92  
93      /* (non-Javadoc)
94       * private constructor to prevent instantiation.
95       */
96      private PreferenceConverter() {
97          //no-op
98      }
99  
100     /**
101      * Helper method to construct a color from the given string.
102      * @param value the indentifier for the color
103      * @return RGB
104      */
105     private static RGB basicGetColor(String   value) {
106 
107         if (IPreferenceStore.STRING_DEFAULT_DEFAULT.equals(value)) {
108             return COLOR_DEFAULT_DEFAULT;
109         }
110 
111         RGB color = StringConverter.asRGB(value, null);
112         if (color == null) {
113             return COLOR_DEFAULT_DEFAULT;
114         }
115         return color;
116     }
117 
118     /**
119      * Helper method to construct a <code>FontData</code> from the given string.
120      * String is in the form FontData;FontData; in order that
121      * multiple FontDatas can be defined.
122      * @param value the identifier for the font
123      * @return FontData[]
124      * 
125      * @since 3.0
126      */
127     public static FontData[] basicGetFontData(String   value) {
128         if (IPreferenceStore.STRING_DEFAULT_DEFAULT.equals(value)) {
129             return FONTDATA_ARRAY_DEFAULT_DEFAULT;
130         }
131 
132         //Read in all of them to get the value
133         StringTokenizer   tokenizer = new StringTokenizer  (value, ENTRY_SEPARATOR);
134         int numTokens = tokenizer.countTokens();
135         FontData[] fontData = new FontData[numTokens];
136 
137         for (int i = 0; i < numTokens; i++) {
138             try {
139                 fontData[i] = new FontData(tokenizer.nextToken());
140             } catch (SWTException error) {
141                 return FONTDATA_ARRAY_DEFAULT_DEFAULT;
142             } catch (IllegalArgumentException   error) {
143                 return FONTDATA_ARRAY_DEFAULT_DEFAULT;
144             }
145         }
146         return fontData;
147     }
148 
149     /**
150      * Reads the supplied string and returns its corresponding
151      * FontData. If it cannot be read then the default FontData
152      * will be returned.
153      * 
154      * @param fontDataValue the string value for the font data  
155      * @return the font data
156      */
157     public static FontData[] readFontData(String   fontDataValue) {
158         return basicGetFontData(fontDataValue);
159     }
160 
161     /**
162      * Helper method to construct a point from the given string.
163      * @param value
164      * @return Point
165      */
166     private static Point basicGetPoint(String   value) {
167         Point dp = new Point(POINT_DEFAULT_DEFAULT.x, POINT_DEFAULT_DEFAULT.y);
168         if (IPreferenceStore.STRING_DEFAULT_DEFAULT.equals(value)) {
169             return dp;
170         }
171         return StringConverter.asPoint(value, dp);
172     }
173 
174     /**
175      *  Helper method to construct a rectangle from the given string.
176      * @param value
177      * @return Rectangle
178      */
179     private static Rectangle basicGetRectangle(String   value) {
180         // We can't just return RECTANGLE_DEFAULT_DEFAULT because
181         // a rectangle object doesn't have value semantik.
182         Rectangle dr = new Rectangle(RECTANGLE_DEFAULT_DEFAULT.x,
183                 RECTANGLE_DEFAULT_DEFAULT.y, RECTANGLE_DEFAULT_DEFAULT.width,
184                 RECTANGLE_DEFAULT_DEFAULT.height);
185 
186         if (IPreferenceStore.STRING_DEFAULT_DEFAULT.equals(value)) {
187             return dr;
188         }
189         return StringConverter.asRectangle(value, dr);
190     }
191 
192     /**
193      * Returns the current value of the color-valued preference with the
194      * given name in the given preference store.
195      * Returns the default-default value (<code>COLOR_DEFAULT_DEFAULT</code>) 
196      * if there is no preference with the given name, or if the current value 
197      * cannot be treated as a color.
198      *
199      * @param store the preference store
200      * @param name the name of the preference
201      * @return the color-valued preference
202      */
203     public static RGB getColor(IPreferenceStore store, String   name) {
204         return basicGetColor(store.getString(name));
205     }
206 
207     /**
208      * Returns the default value for the color-valued preference
209      * with the given name in the given preference store.
210      * Returns the default-default value (<code>COLOR_DEFAULT_DEFAULT</code>) 
211      * is no default preference with the given name, or if the default 
212      * value cannot be treated as a color.
213      *
214      * @param store the preference store
215      * @param name the name of the preference
216      * @return the default value of the preference
217      */
218     public static RGB getDefaultColor(IPreferenceStore store, String   name) {
219         return basicGetColor(store.getDefaultString(name));
220     }
221 
222     /**
223      * Returns the default value array for the font-valued preference
224      * with the given name in the given preference store.
225      * Returns the default-default value (<code>FONTDATA_ARRAY_DEFAULT_DEFAULT</code>) 
226      * is no default preference with the given name, or if the default 
227      * value cannot be treated as font data.
228      *
229      * @param store the preference store
230      * @param name the name of the preference
231      * @return the default value of the preference
232      */
233     public static FontData[] getDefaultFontDataArray(IPreferenceStore store,
234             String   name) {
235         return basicGetFontData(store.getDefaultString(name));
236     }
237 
238     /**
239      * Returns a single default value for the font-valued preference
240      * with the given name in the given preference store.
241      * Returns the default-default value (<code>FONTDATA_DEFAULT_DEFAULT</code>) 
242      * is no default preference with the given name, or if the default 
243      * value cannot be treated as font data.
244      * This method is provided for backwards compatibility. It is
245      * recommended that <code>getDefaultFontDataArray</code> is
246      * used instead.
247      *
248      * @param store the preference store
249      * @param name the name of the preference
250      * @return the default value of the preference
251      */
252     public static FontData getDefaultFontData(IPreferenceStore store,
253             String   name) {
254         return getDefaultFontDataArray(store, name)[0];
255     }
256 
257     /**
258      * Returns the default value for the point-valued preference
259      * with the given name in the given preference store.
260      * Returns the default-default value (<code>POINT_DEFAULT_DEFAULT</code>) 
261      * is no default preference with the given name, or if the default 
262      * value cannot be treated as a point.
263      *
264      * @param store the preference store
265      * @param name the name of the preference
266      * @return the default value of the preference
267      */
268     public static Point getDefaultPoint(IPreferenceStore store, String   name) {
269         return basicGetPoint(store.getDefaultString(name));
270     }
271 
272     /**
273      * Returns the default value for the rectangle-valued preference
274      * with the given name in the given preference store.
275      * Returns the default-default value (<code>RECTANGLE_DEFAULT_DEFAULT</code>) 
276      * is no default preference with the given name, or if the default 
277      * value cannot be treated as a rectangle.
278      *
279      * @param store the preference store
280      * @param name the name of the preference
281      * @return the default value of the preference
282      */
283     public static Rectangle getDefaultRectangle(IPreferenceStore store,
284             String   name) {
285         return basicGetRectangle(store.getDefaultString(name));
286     }
287 
288     /**
289      * Returns the current value of the font-valued preference with the
290      * given name in the given preference store.
291      * Returns the default-default value (<code>FONTDATA_ARRAY_DEFAULT_DEFAULT</code>) 
292      * if there is no preference with the given name, or if the current value 
293      * cannot be treated as font data.
294      *
295      * @param store the preference store
296      * @param name the name of the preference
297      * @return the font-valued preference
298      */
299     public static FontData[] getFontDataArray(IPreferenceStore store,
300             String   name) {
301         return basicGetFontData(store.getString(name));
302     }
303 
304     /**
305      * Returns the current value of the first entry of the
306      * font-valued preference with the
307      * given name in the given preference store.
308      * Returns the default-default value (<code>FONTDATA_ARRAY_DEFAULT_DEFAULT</code>) 
309      * if there is no preference with the given name, or if the current value 
310      * cannot be treated as font data.
311      * This API is provided for backwards compatibility. It is
312      * recommended that <code>getFontDataArray</code> is used instead.
313      *
314      * @param store the preference store
315      * @param name the name of the preference
316      * @return the font-valued preference
317      */
318     public static FontData getFontData(IPreferenceStore store, String   name) {
319         return getFontDataArray(store, name)[0];
320     }
321 
322     /**
323      * Returns the current value of the point-valued preference with the
324      * given name in the given preference store.
325      * Returns the default-default value (<code>POINT_DEFAULT_DEFAULT</code>) 
326      * if there is no preference with the given name, or if the current value 
327      * cannot be treated as a point.
328      *
329      * @param store the preference store
330      * @param name the name of the preference
331      * @return the point-valued preference
332      */
333     public static Point getPoint(IPreferenceStore store, String   name) {
334         return basicGetPoint(store.getString(name));
335     }
336 
337     /**
338      * Returns the current value of the rectangle-valued preference with the
339      * given name in the given preference store.
340      * Returns the default-default value (<code>RECTANGLE_DEFAULT_DEFAULT</code>) 
341      * if there is no preference with the given name, or if the current value 
342      * cannot be treated as a rectangle.
343      *
344      * @param store the preference store
345      * @param name the name of the preference
346      * @return the rectangle-valued preference
347      */
348     public static Rectangle getRectangle(IPreferenceStore store, String   name) {
349         return basicGetRectangle(store.getString(name));
350     }
351 
352     /**
353      * Sets the default value of the preference with the given name
354      * in the given preference store. As FontDatas are stored as 
355      * arrays this method is only provided for backwards compatibility.
356      * Use <code>setDefault(IPreferenceStore, String, FontData[])</code>
357      * instead.
358      *
359      * @param store the preference store
360      * @param name the name of the preference
361      * @param value the new default value of the preference
362      */
363     public static void setDefault(IPreferenceStore store, String   name,
364             FontData value) {
365         FontData[] fontDatas = new FontData[1];
366         fontDatas[0] = value;
367         setDefault(store, name, fontDatas);
368     }
369 
370     /**
371      * Sets the default value of the preference with the given name
372      * in the given preference store.
373      *
374      * @param store the preference store
375      * @param name the name of the preference
376      * @param value the new default value of the preference
377      */
378     public static void setDefault(IPreferenceStore store, String   name,
379             FontData[] value) {
380         store.setDefault(name, getStoredRepresentation(value));
381     }
382 
383     /**
384      * Sets the default value of the preference with the given name
385      * in the given preference store.
386      *
387      * @param store the preference store
388      * @param name the name of the preference
389      * @param value the new default value of the preference
390      */
391     public static void setDefault(IPreferenceStore store, String   name,
392             Point value) {
393         store.setDefault(name, StringConverter.asString(value));
394     }
395 
396     /**
397      * Sets the default value of the preference with the given name
398      * in the given preference store.
399      *
400      * @param store the preference store
401      * @param name the name of the preference
402      * @param value the new default value of the preference
403      */
404     public static void setDefault(IPreferenceStore store, String   name,
405             Rectangle value) {
406         store.setDefault(name, StringConverter.asString(value));
407     }
408 
409     /**
410      * Sets the default value of the preference with the given name
411      * in the given preference store.
412      *
413      * @param store the preference store
414      * @param name the name of the preference
415      * @param value the new default value of the preference
416      */
417     public static void setDefault(IPreferenceStore store, String   name, RGB value) {
418         store.setDefault(name, StringConverter.asString(value));
419     }
420 
421     /**
422      * Sets the current value of the preference with the given name
423      * in the given preference store. 
424      * <p>
425      * Included for backwards compatibility.  This method is equivalent to
426      * </code>setValue(store, name, new FontData[]{value})</code>.
427      * </p>
428      * 
429      * @param store the preference store
430      * @param name the name of the preference
431      * @param value the new current value of the preference
432      */
433     public static void setValue(IPreferenceStore store, String   name,
434             FontData value) {
435         setValue(store, name, new FontData[] { value });
436     }
437 
438     /**
439      * Sets the current value of the preference with the given name
440      * in the given preference store. This method also sets the corresponding
441      * key in the JFace font registry to the value and fires a 
442      * property change event to listeners on the preference store.
443      * 
444      * <p>
445      * Note that this API does not update any other settings that may
446      * be dependant upon it. Only the value in the preference store 
447      * and in the font registry is updated.
448      * </p> 
449      * @param store the preference store
450      * @param name the name of the preference
451      * @param value the new current value of the preference
452      * 
453      * @see #putValue(IPreferenceStore, String, FontData[])
454      */
455     public static void setValue(IPreferenceStore store, String   name,
456             FontData[] value) {
457         FontData[] oldValue = getFontDataArray(store, name);
458         // see if the font has changed
459         if (!Arrays.equals(oldValue, value)) {
460             store.putValue(name, getStoredRepresentation(value));
461             JFaceResources.getFontRegistry().put(name, value);
462             store.firePropertyChangeEvent(name, oldValue, value);
463         }
464     }
465 
466     /**
467      * Sets the current value of the preference with the given name
468      * in the given preference store. This method does not update
469      * the font registry or fire a property change event.
470      * 
471      * @param store the preference store
472      * @param name the name of the preference
473      * @param value the new current value of the preference
474      * 
475      * @see PreferenceConverter#setValue(IPreferenceStore, String, FontData[])
476      */
477     public static void putValue(IPreferenceStore store, String   name,
478             FontData[] value) {
479         FontData[] oldValue = getFontDataArray(store, name);
480         // see if the font has changed
481         if (!Arrays.equals(oldValue, value)) {
482             store.putValue(name, getStoredRepresentation(value));
483         }
484     }
485 
486     /**
487      * Returns the stored representation of the given array of FontData objects.
488      * The stored representation has the form FontData;FontData;
489      * Only includes the non-null entries.
490      * 
491      * @param fontData the array of FontData objects
492      * @return the stored representation of the FontData objects
493      * @since 3.0
494      */
495     public static String   getStoredRepresentation(FontData[] fontData) {
496         StringBuffer   buffer = new StringBuffer  ();
497         for (int i = 0; i < fontData.length; i++) {
498             if (fontData[i] != null) {
499                 buffer.append(fontData[i].toString());
500                 buffer.append(ENTRY_SEPARATOR);
501             }
502         }
503         return buffer.toString();
504     }
505 
506     /**
507      * Sets the current value of the preference with the given name
508      * in the given preference store.
509      *
510      * @param store the preference store
511      * @param name the name of the preference
512      * @param value the new current value of the preference
513      */
514     public static void setValue(IPreferenceStore store, String   name, Point value) {
515         Point oldValue = getPoint(store, name);
516         if (oldValue == null || !oldValue.equals(value)) {
517             store.putValue(name, StringConverter.asString(value));
518             store.firePropertyChangeEvent(name, oldValue, value);
519         }
520     }
521 
522     /**
523      * Sets the current value of the preference with the given name
524      * in the given preference store.
525      *
526      * @param store the preference store
527      * @param name the name of the preference
528      * @param value the new current value of the preference
529      */
530     public static void setValue(IPreferenceStore store, String   name,
531             Rectangle value) {
532         Rectangle oldValue = getRectangle(store, name);
533         if (oldValue == null || !oldValue.equals(value)) {
534             store.putValue(name, StringConverter.asString(value));
535             store.firePropertyChangeEvent(name, oldValue, value);
536         }
537     }
538 
539     /**
540      * Sets the current value of the preference with the given name
541      * in the given preference store.
542      *
543      * @param store the preference store
544      * @param name the name of the preference
545      * @param value the new current value of the preference
546      */
547     public static void setValue(IPreferenceStore store, String   name, RGB value) {
548         RGB oldValue = getColor(store, name);
549         if (oldValue == null || !oldValue.equals(value)) {
550             store.putValue(name, StringConverter.asString(value));
551             store.firePropertyChangeEvent(name, oldValue, value);
552         }
553     }
554 }
555
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags