Java tutorial
/******************************************************************************* * Copyright (c) 2000, 2015 IBM Corporation and others. * * This program and the accompanying materials * are made available under the terms of the Eclipse Public License 2.0 * which accompanies this distribution, and is available at * https://www.eclipse.org/legal/epl-2.0/ * * SPDX-License-Identifier: EPL-2.0 * * Contributors: * IBM Corporation - initial API and implementation *******************************************************************************/ package org.eclipse.jface.preference; import java.util.Arrays; import java.util.StringTokenizer; import org.eclipse.jface.resource.JFaceResources; import org.eclipse.jface.resource.StringConverter; import org.eclipse.swt.SWTException; import org.eclipse.swt.graphics.FontData; import org.eclipse.swt.graphics.Point; import org.eclipse.swt.graphics.RGB; import org.eclipse.swt.graphics.Rectangle; import org.eclipse.swt.widgets.Display; /** * A utility class for dealing with preferences whose values are common SWT * objects (color, points, rectangles, and font data). The static methods on * this class handle the conversion between the SWT objects and their string * representations. * <p> * Usage: * </p> * * <pre> * IPreferenceStore store = ...; * PreferenceConverter.setValue(store, "bg", new RGB(127,127,127)); * ... * RBG bgColor = PreferenceConverter.getValue(store, "bg"); * </pre> * <p> * This class contains static methods and fields only and cannot be * instantiated. * </p> * Note: touching this class has the side effect of creating a display (static * initializer). * * @noinstantiate This class is not intended to be instantiated by clients. */ public class PreferenceConverter { /** * The default-default value for point preferences * (the origin, <code>(0,0)</code>). */ public static final Point POINT_DEFAULT_DEFAULT = new Point(0, 0); /** * The default-default value for rectangle preferences * (the empty rectangle <code>(0,0,0,0)</code>). */ public static final Rectangle RECTANGLE_DEFAULT_DEFAULT = new Rectangle(0, 0, 0, 0); /** * The default-default value for color preferences * (black, <code>RGB(0,0,0)</code>). */ public static final RGB COLOR_DEFAULT_DEFAULT = new RGB(0, 0, 0); private static final String ENTRY_SEPARATOR = ";"; //$NON-NLS-1$ /** * The default-default value for <code>FontData[]</code> preferences. * Read-only. * * @deprecated this is not thread-safe and may contain invalid data at * startup. Call {@link #getFontDataArrayDefaultDefault()} from * the UI thread instead. */ @Deprecated public static FontData[] FONTDATA_ARRAY_DEFAULT_DEFAULT; /** * The default-default value for <code>FontData</code> preferences. * Read-only. * * @deprecated this is not thread-safe and may contain invalid data at * startup. Call {@link #getFontDataArrayDefaultDefault()}} from * the UI thread instead. */ @Deprecated public static FontData FONTDATA_DEFAULT_DEFAULT; private static FontData[] fontDataArrayDefaultDefault; static { Display display = Display.getDefault(); display.asyncExec(() -> { // Ensure that the deprecated FONTDATA_DEFAULT_DEFAULT and // FONTDATA_ARRAY_DEFAULT values // are initialized as soon as possible FONTDATA_ARRAY_DEFAULT_DEFAULT = getFontDataArrayDefaultDefault(); FONTDATA_DEFAULT_DEFAULT = getFontDataArrayDefaultDefault()[0]; }); } /** * private constructor to prevent instantiation. */ private PreferenceConverter() { //no-op } /** * Helper method to construct a color from the given string. * @param value the indentifier for the color * @return RGB */ private static RGB basicGetColor(String value) { if (IPreferenceStore.STRING_DEFAULT_DEFAULT.equals(value)) { return COLOR_DEFAULT_DEFAULT; } RGB color = StringConverter.asRGB(value, null); if (color == null) { return COLOR_DEFAULT_DEFAULT; } return color; } /** * Helper method to construct a <code>FontData</code> from the given string. * String is in the form FontData;FontData; in order that * multiple FontDatas can be defined. * @param value the identifier for the font * @return FontData[] * * @since 3.0 */ public static FontData[] basicGetFontData(String value) { FontData[] defaultResult = getFontDataArrayDefaultDefault(); if (IPreferenceStore.STRING_DEFAULT_DEFAULT.equals(value)) { return defaultResult; } //Read in all of them to get the value StringTokenizer tokenizer = new StringTokenizer(value, ENTRY_SEPARATOR); int numTokens = tokenizer.countTokens(); FontData[] fontData = new FontData[numTokens]; for (int i = 0; i < numTokens; i++) { try { fontData[i] = new FontData(tokenizer.nextToken()); } catch (SWTException | IllegalArgumentException error) { return defaultResult; } } return fontData; } /** * Reads the supplied string and returns its corresponding * FontData. If it cannot be read then the default FontData * will be returned. * * @param fontDataValue the string value for the font data * @return the font data */ public static FontData[] readFontData(String fontDataValue) { return basicGetFontData(fontDataValue); } /** * Helper method to construct a point from the given string. * @param value * @return Point */ private static Point basicGetPoint(String value) { Point dp = new Point(POINT_DEFAULT_DEFAULT.x, POINT_DEFAULT_DEFAULT.y); if (IPreferenceStore.STRING_DEFAULT_DEFAULT.equals(value)) { return dp; } return StringConverter.asPoint(value, dp); } /** * Helper method to construct a rectangle from the given string. * @param value * @return Rectangle */ private static Rectangle basicGetRectangle(String value) { // We can't just return RECTANGLE_DEFAULT_DEFAULT because // a rectangle object doesn't have value semantik. Rectangle dr = new Rectangle(RECTANGLE_DEFAULT_DEFAULT.x, RECTANGLE_DEFAULT_DEFAULT.y, RECTANGLE_DEFAULT_DEFAULT.width, RECTANGLE_DEFAULT_DEFAULT.height); if (IPreferenceStore.STRING_DEFAULT_DEFAULT.equals(value)) { return dr; } return StringConverter.asRectangle(value, dr); } /** * Returns the current value of the color-valued preference with the * given name in the given preference store. * Returns the default-default value (<code>COLOR_DEFAULT_DEFAULT</code>) * if there is no preference with the given name, or if the current value * cannot be treated as a color. * * @param store the preference store * @param name the name of the preference * @return the color-valued preference */ public static RGB getColor(IPreferenceStore store, String name) { return basicGetColor(store.getString(name)); } /** * Returns the default value for the color-valued preference * with the given name in the given preference store. * Returns the default-default value (<code>COLOR_DEFAULT_DEFAULT</code>) * is no default preference with the given name, or if the default * value cannot be treated as a color. * * @param store the preference store * @param name the name of the preference * @return the default value of the preference */ public static RGB getDefaultColor(IPreferenceStore store, String name) { return basicGetColor(store.getDefaultString(name)); } /** * Returns the default value array for the font-valued preference * with the given name in the given preference store. * Returns the default-default value (<code>FONTDATA_ARRAY_DEFAULT_DEFAULT</code>) * is no default preference with the given name, or if the default * value cannot be treated as font data. * * @param store the preference store * @param name the name of the preference * @return the default value of the preference */ public static FontData[] getDefaultFontDataArray(IPreferenceStore store, String name) { return basicGetFontData(store.getDefaultString(name)); } /** * Returns a single default value for the font-valued preference * with the given name in the given preference store. * Returns the default-default value (<code>FONTDATA_DEFAULT_DEFAULT</code>) * is no default preference with the given name, or if the default * value cannot be treated as font data. * This method is provided for backwards compatibility. It is * recommended that <code>getDefaultFontDataArray</code> is * used instead. * * @param store the preference store * @param name the name of the preference * @return the default value of the preference */ public static FontData getDefaultFontData(IPreferenceStore store, String name) { return getDefaultFontDataArray(store, name)[0]; } /** * Returns the default value for the point-valued preference * with the given name in the given preference store. * Returns the default-default value (<code>POINT_DEFAULT_DEFAULT</code>) * is no default preference with the given name, or if the default * value cannot be treated as a point. * * @param store the preference store * @param name the name of the preference * @return the default value of the preference */ public static Point getDefaultPoint(IPreferenceStore store, String name) { return basicGetPoint(store.getDefaultString(name)); } /** * Returns the default value for the rectangle-valued preference * with the given name in the given preference store. * Returns the default-default value (<code>RECTANGLE_DEFAULT_DEFAULT</code>) * is no default preference with the given name, or if the default * value cannot be treated as a rectangle. * * @param store the preference store * @param name the name of the preference * @return the default value of the preference */ public static Rectangle getDefaultRectangle(IPreferenceStore store, String name) { return basicGetRectangle(store.getDefaultString(name)); } /** * Returns the current value of the font-valued preference with the * given name in the given preference store. * Returns the default-default value (<code>FONTDATA_ARRAY_DEFAULT_DEFAULT</code>) * if there is no preference with the given name, or if the current value * cannot be treated as font data. * * @param store the preference store * @param name the name of the preference * @return the font-valued preference */ public static FontData[] getFontDataArray(IPreferenceStore store, String name) { return basicGetFontData(store.getString(name)); } /** * The default-default value for <code>FontData[]</code> preferences. Must * be called from the UI thread. * * @return the default-default value for <code>FontData[]</code> * preferences. * @since 3.12 */ public static FontData[] getFontDataArrayDefaultDefault() { Display display = Display.getCurrent(); if (fontDataArrayDefaultDefault == null) { fontDataArrayDefaultDefault = display.getSystemFont().getFontData(); } return fontDataArrayDefaultDefault; } /** * Returns the current value of the first entry of the * font-valued preference with the * given name in the given preference store. * Returns the default-default value (<code>FONTDATA_ARRAY_DEFAULT_DEFAULT</code>) * if there is no preference with the given name, or if the current value * cannot be treated as font data. * This API is provided for backwards compatibility. It is * recommended that <code>getFontDataArray</code> is used instead. * * @param store the preference store * @param name the name of the preference * @return the font-valued preference */ public static FontData getFontData(IPreferenceStore store, String name) { return getFontDataArray(store, name)[0]; } /** * Returns the current value of the point-valued preference with the * given name in the given preference store. * Returns the default-default value (<code>POINT_DEFAULT_DEFAULT</code>) * if there is no preference with the given name, or if the current value * cannot be treated as a point. * * @param store the preference store * @param name the name of the preference * @return the point-valued preference */ public static Point getPoint(IPreferenceStore store, String name) { return basicGetPoint(store.getString(name)); } /** * Returns the current value of the rectangle-valued preference with the * given name in the given preference store. * Returns the default-default value (<code>RECTANGLE_DEFAULT_DEFAULT</code>) * if there is no preference with the given name, or if the current value * cannot be treated as a rectangle. * * @param store the preference store * @param name the name of the preference * @return the rectangle-valued preference */ public static Rectangle getRectangle(IPreferenceStore store, String name) { return basicGetRectangle(store.getString(name)); } /** * Sets the default value of the preference with the given name * in the given preference store. As FontDatas are stored as * arrays this method is only provided for backwards compatibility. * Use <code>setDefault(IPreferenceStore, String, FontData[])</code> * instead. * * @param store the preference store * @param name the name of the preference * @param value the new default value of the preference */ public static void setDefault(IPreferenceStore store, String name, FontData value) { FontData[] fontDatas = new FontData[1]; fontDatas[0] = value; setDefault(store, name, fontDatas); } /** * Sets the default value of the preference with the given name * in the given preference store. * * @param store the preference store * @param name the name of the preference * @param value the new default value of the preference */ public static void setDefault(IPreferenceStore store, String name, FontData[] value) { store.setDefault(name, getStoredRepresentation(value)); } /** * Sets the default value of the preference with the given name * in the given preference store. * * @param store the preference store * @param name the name of the preference * @param value the new default value of the preference */ public static void setDefault(IPreferenceStore store, String name, Point value) { store.setDefault(name, StringConverter.asString(value)); } /** * Sets the default value of the preference with the given name * in the given preference store. * * @param store the preference store * @param name the name of the preference * @param value the new default value of the preference */ public static void setDefault(IPreferenceStore store, String name, Rectangle value) { store.setDefault(name, StringConverter.asString(value)); } /** * Sets the default value of the preference with the given name * in the given preference store. * * @param store the preference store * @param name the name of the preference * @param value the new default value of the preference */ public static void setDefault(IPreferenceStore store, String name, RGB value) { store.setDefault(name, StringConverter.asString(value)); } /** * Sets the current value of the preference with the given name in the given * preference store. * <p> * Included for backwards compatibility. This method is equivalent to * <code>setValue(store, name, new FontData[]{value})</code>. * </p> * * @param store the preference store * @param name the name of the preference * @param value the new current value of the preference */ public static void setValue(IPreferenceStore store, String name, FontData value) { setValue(store, name, new FontData[] { value }); } /** * Sets the current value of the preference with the given name * in the given preference store. This method also sets the corresponding * key in the JFace font registry to the value and fires a * property change event to listeners on the preference store. * * <p> * Note that this API does not update any other settings that may * be dependant upon it. Only the value in the preference store * and in the font registry is updated. * </p> * @param store the preference store * @param name the name of the preference * @param value the new current value of the preference * * @see #putValue(IPreferenceStore, String, FontData[]) */ public static void setValue(IPreferenceStore store, String name, FontData[] value) { FontData[] oldValue = getFontDataArray(store, name); // see if the font has changed if (!Arrays.equals(oldValue, value)) { store.putValue(name, getStoredRepresentation(value)); JFaceResources.getFontRegistry().put(name, value); store.firePropertyChangeEvent(name, oldValue, value); } } /** * Sets the current value of the preference with the given name * in the given preference store. This method does not update * the font registry or fire a property change event. * * @param store the preference store * @param name the name of the preference * @param value the new current value of the preference * * @see PreferenceConverter#setValue(IPreferenceStore, String, FontData[]) */ public static void putValue(IPreferenceStore store, String name, FontData[] value) { FontData[] oldValue = getFontDataArray(store, name); // see if the font has changed if (!Arrays.equals(oldValue, value)) { store.putValue(name, getStoredRepresentation(value)); } } /** * Returns the stored representation of the given array of FontData objects. * The stored representation has the form FontData;FontData; * Only includes the non-null entries. * * @param fontData the array of FontData objects * @return the stored representation of the FontData objects * @since 3.0 */ public static String getStoredRepresentation(FontData[] fontData) { StringBuilder buffer = new StringBuilder(); for (FontData element : fontData) { if (element != null) { buffer.append(element.toString()); buffer.append(ENTRY_SEPARATOR); } } return buffer.toString(); } /** * Sets the current value of the preference with the given name * in the given preference store. * * @param store the preference store * @param name the name of the preference * @param value the new current value of the preference */ public static void setValue(IPreferenceStore store, String name, Point value) { Point oldValue = getPoint(store, name); if (oldValue == null || !oldValue.equals(value)) { store.putValue(name, StringConverter.asString(value)); store.firePropertyChangeEvent(name, oldValue, value); } } /** * Sets the current value of the preference with the given name * in the given preference store. * * @param store the preference store * @param name the name of the preference * @param value the new current value of the preference */ public static void setValue(IPreferenceStore store, String name, Rectangle value) { Rectangle oldValue = getRectangle(store, name); if (oldValue == null || !oldValue.equals(value)) { store.putValue(name, StringConverter.asString(value)); store.firePropertyChangeEvent(name, oldValue, value); } } /** * Sets the current value of the preference with the given name * in the given preference store. * * @param store the preference store * @param name the name of the preference * @param value the new current value of the preference */ public static void setValue(IPreferenceStore store, String name, RGB value) { RGB oldValue = getColor(store, name); if (oldValue == null || !oldValue.equals(value)) { store.putValue(name, StringConverter.asString(value)); store.firePropertyChangeEvent(name, oldValue, value); } } }