001: /*******************************************************************************
002: * Copyright (c) 2004, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jface.resource;
011:
012: import org.eclipse.swt.graphics.Device;
013: import org.eclipse.swt.graphics.Font;
014: import org.eclipse.swt.graphics.FontData;
015: import org.eclipse.swt.widgets.Display;
016:
017: /**
018: * Lightweight descriptor for a font. Creates the described font on demand.
019: * Subclasses can implement different ways of describing a font. These objects
020: * will be compared, so hashCode(...) and equals(...) must return something
021: * meaningful.
022: *
023: * @since 3.1
024: */
025: public abstract class FontDescriptor extends DeviceResourceDescriptor {
026:
027: /**
028: * Creates a FontDescriptor that describes an existing font. The resulting
029: * descriptor depends on the Font. Disposing the Font while the descriptor
030: * is still in use may throw a graphic disposed exception.
031: *
032: * @since 3.1
033: *
034: * @deprecated use {@link FontDescriptor#createFrom(Font)}
035: *
036: * @param font a font to describe
037: * @param originalDevice must be the same Device that was passed into
038: * the font's constructor when it was first created.
039: * @return a newly created FontDescriptor.
040: */
041: public static FontDescriptor createFrom(Font font,
042: Device originalDevice) {
043: return new ArrayFontDescriptor(font);
044: }
045:
046: /**
047: * Creates a FontDescriptor that describes an existing font. The resulting
048: * descriptor depends on the original Font, and disposing the original Font
049: * while the descriptor is still in use may cause SWT to throw a graphic
050: * disposed exception.
051: *
052: * @since 3.1
053: *
054: * @param font font to create
055: * @return a newly created FontDescriptor that describes the given font
056: */
057: public static FontDescriptor createFrom(Font font) {
058: return new ArrayFontDescriptor(font);
059: }
060:
061: /**
062: * Creates a new FontDescriptor given the an array of FontData that describes
063: * the font.
064: *
065: * @since 3.1
066: *
067: * @param data an array of FontData that describes the font (will be passed into
068: * the Font's constructor)
069: * @return a FontDescriptor that describes the given font
070: */
071: public static FontDescriptor createFrom(FontData[] data) {
072: return new ArrayFontDescriptor(data);
073: }
074:
075: /**
076: * Creates a new FontDescriptor given the associated FontData
077: *
078: * @param data FontData describing the font to create
079: * @return a newly created FontDescriptor
080: */
081: public static FontDescriptor createFrom(FontData data) {
082: return new ArrayFontDescriptor(new FontData[] { data });
083: }
084:
085: /**
086: * Creates a new FontDescriptor given an OS-specific font name, height, and style.
087: *
088: * @see Font#Font(org.eclipse.swt.graphics.Device, java.lang.String, int, int)
089: *
090: * @param name os-specific font name
091: * @param height height (pixels)
092: * @param style a bitwise combination of NORMAL, BOLD, ITALIC
093: * @return a new FontDescriptor
094: */
095: public static FontDescriptor createFrom(String name, int height,
096: int style) {
097: return createFrom(new FontData(name, height, style));
098: }
099:
100: /**
101: * Returns the set of FontData associated with this font. Modifying the elements
102: * in the returned array has no effect on the original FontDescriptor.
103: *
104: * @return the set of FontData associated with this font
105: * @since 3.3
106: */
107: public FontData[] getFontData() {
108: Font tempFont = createFont(Display.getCurrent());
109: FontData[] result = tempFont.getFontData();
110: destroyFont(tempFont);
111: return result;
112: }
113:
114: /**
115: * Returns an array of FontData containing copies of the FontData
116: * from the original.
117: *
118: * @param original array to copy
119: * @return a deep copy of the original array
120: * @since 3.3
121: */
122: public static FontData[] copy(FontData[] original) {
123: FontData[] result = new FontData[original.length];
124: for (int i = 0; i < original.length; i++) {
125: FontData next = original[i];
126:
127: result[i] = copy(next);
128: }
129:
130: return result;
131: }
132:
133: /**
134: * Returns a copy of the original FontData
135: *
136: * @param next FontData to copy
137: * @return a copy of the given FontData
138: * @since 3.3
139: */
140: public static FontData copy(FontData next) {
141: FontData result = new FontData(next.getName(),
142: next.getHeight(), next.getStyle());
143: result.setLocale(next.getLocale());
144: return result;
145: }
146:
147: /**
148: * Returns a FontDescriptor that is equivalent to the reciever, but uses
149: * the given style bits.
150: *
151: * <p>Does not modify the reciever.</p>
152: *
153: * @param style a bitwise combination of SWT.NORMAL, SWT.ITALIC and SWT.BOLD
154: * @return a new FontDescriptor with the given style
155: *
156: * @since 3.3
157: */
158: public final FontDescriptor setStyle(int style) {
159: FontData[] data = getFontData();
160:
161: for (int i = 0; i < data.length; i++) {
162: FontData next = data[i];
163:
164: next.setStyle(style);
165: }
166:
167: // Optimization: avoid holding onto extra instances by returning the reciever if
168: // if it is exactly the same as the result
169: FontDescriptor result = new ArrayFontDescriptor(data);
170: if (result.equals(this )) {
171: return this ;
172: }
173:
174: return result;
175: }
176:
177: /**
178: * <p>Returns a FontDescriptor that is equivalent to the reciever, but
179: * has the given style bits, in addition to any styles the reciever already has.</p>
180: *
181: * <p>Does not modify the reciever.</p>
182: *
183: * @param style a bitwise combination of SWT.NORMAL, SWT.ITALIC and SWT.BOLD
184: * @return a new FontDescriptor with the given additional style bits
185: * @since 3.3
186: */
187: public final FontDescriptor withStyle(int style) {
188: FontData[] data = getFontData();
189:
190: for (int i = 0; i < data.length; i++) {
191: FontData next = data[i];
192:
193: next.setStyle(next.getStyle() | style);
194: }
195:
196: // Optimization: avoid allocating extra instances by returning the reciever if
197: // if it is exactly the same as the result
198: FontDescriptor result = new ArrayFontDescriptor(data);
199: if (result.equals(this )) {
200: return this ;
201: }
202:
203: return result;
204: }
205:
206: /**
207: * <p>Returns a new FontDescriptor that is equivalent to the reciever, but
208: * has the given height.</p>
209: *
210: * <p>Does not modify the reciever.</p>
211: *
212: * @param height a height, in points
213: * @return a new FontDescriptor with the height, in points
214: * @since 3.3
215: */
216: public final FontDescriptor setHeight(int height) {
217: FontData[] data = getFontData();
218:
219: for (int i = 0; i < data.length; i++) {
220: FontData next = data[i];
221:
222: next.setHeight(height);
223: }
224:
225: // Optimization: avoid holding onto extra instances by returning the reciever if
226: // if it is exactly the same as the result
227: FontDescriptor result = new ArrayFontDescriptor(data);
228: if (result.equals(this )) {
229: return this ;
230: }
231:
232: return result;
233: }
234:
235: /**
236: * <p>Returns a FontDescriptor that is equivalent to the reciever, but whose height
237: * is larger by the given number of points.</p>
238: *
239: * <p>Does not modify the reciever.</p>
240: *
241: * @param heightDelta a change in height, in points. Negative values will return smaller
242: * fonts.
243: * @return a FontDescriptor whose height differs from the reciever by the given number
244: * of points.
245: * @since 3.3
246: */
247: public final FontDescriptor increaseHeight(int heightDelta) {
248: if (heightDelta == 0) {
249: return this ;
250: }
251: FontData[] data = getFontData();
252:
253: for (int i = 0; i < data.length; i++) {
254: FontData next = data[i];
255:
256: next.setHeight(next.getHeight() + heightDelta);
257: }
258:
259: return new ArrayFontDescriptor(data);
260: }
261:
262: /**
263: * Creates the Font described by this descriptor.
264: *
265: * @since 3.1
266: *
267: * @param device device on which to allocate the font
268: * @return a newly allocated Font (never null)
269: * @throws DeviceResourceException if unable to allocate the Font
270: */
271: public abstract Font createFont(Device device)
272: throws DeviceResourceException;
273:
274: /**
275: * Deallocates anything that was allocated by createFont, given a font
276: * that was allocated by an equal FontDescriptor.
277: *
278: * @since 3.1
279: *
280: * @param previouslyCreatedFont previously allocated font
281: */
282: public abstract void destroyFont(Font previouslyCreatedFont);
283:
284: /* (non-Javadoc)
285: * @see org.eclipse.jface.resource.DeviceResourceDescriptor#create(org.eclipse.swt.graphics.Device)
286: */
287: public final Object createResource(Device device)
288: throws DeviceResourceException {
289: return createFont(device);
290: }
291:
292: /* (non-Javadoc)
293: * @see org.eclipse.jface.resource.DeviceResourceDescriptor#destroy(java.lang.Object)
294: */
295: public final void destroyResource(Object previouslyCreatedObject) {
296: destroyFont((Font) previouslyCreatedObject);
297: }
298: }
|