001 /*
002 * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 /*
027 * (C) Copyright Taligent, Inc. 1996 - 1997, All Rights Reserved
028 * (C) Copyright IBM Corp. 1996 - 1998, All Rights Reserved
029 *
030 * The original version of this source code and documentation is
031 * copyrighted and owned by Taligent, Inc., a wholly-owned subsidiary
032 * of IBM. These materials are provided under terms of a License
033 * Agreement between Taligent and Sun. This technology is protected
034 * by multiple US and International patents.
035 *
036 * This notice and attribution to Taligent may not be removed.
037 * Taligent is a registered trademark of Taligent, Inc.
038 *
039 */
040
041 package java.awt.font;
042
043 import java.awt.geom.Rectangle2D;
044
045 /**
046 * The <code>GlyphMetrics</code> class represents infomation for a
047 * single glyph. A glyph is the visual representation of one or more
048 * characters. Many different glyphs can be used to represent a single
049 * character or combination of characters. <code>GlyphMetrics</code>
050 * instances are produced by {@link java.awt.Font Font} and are applicable
051 * to a specific glyph in a particular <code>Font</code>.
052 * <p>
053 * Glyphs are either STANDARD, LIGATURE, COMBINING, or COMPONENT.
054 * <ul>
055 * <li>STANDARD glyphs are commonly used to represent single characters.
056 * <li>LIGATURE glyphs are used to represent sequences of characters.
057 * <li>COMPONENT glyphs in a {@link GlyphVector} do not correspond to a
058 * particular character in a text model. Instead, COMPONENT glyphs are
059 * added for typographical reasons, such as Arabic justification.
060 * <li>COMBINING glyphs embellish STANDARD or LIGATURE glyphs, such
061 * as accent marks. Carets do not appear before COMBINING glyphs.
062 * </ul>
063 * <p>
064 * Other metrics available through <code>GlyphMetrics</code> are the
065 * components of the advance, the visual bounds, and the left and right
066 * side bearings.
067 * <p>
068 * Glyphs for a rotated font, or obtained from a <code>GlyphVector</code>
069 * which has applied a rotation to the glyph, can have advances that
070 * contain both X and Y components. Usually the advance only has one
071 * component.
072 * <p>
073 * The advance of a glyph is the distance from the glyph's origin to the
074 * origin of the next glyph along the baseline, which is either vertical
075 * or horizontal. Note that, in a <code>GlyphVector</code>,
076 * the distance from a glyph to its following glyph might not be the
077 * glyph's advance, because of kerning or other positioning adjustments.
078 * <p>
079 * The bounds is the smallest rectangle that completely contains the
080 * outline of the glyph. The bounds rectangle is relative to the
081 * glyph's origin. The left-side bearing is the distance from the glyph
082 * origin to the left of its bounds rectangle. If the left-side bearing is
083 * negative, part of the glyph is drawn to the left of its origin. The
084 * right-side bearing is the distance from the right side of the bounds
085 * rectangle to the next glyph origin (the origin plus the advance). If
086 * negative, part of the glyph is drawn to the right of the next glyph's
087 * origin. Note that the bounds does not necessarily enclose all the pixels
088 * affected when rendering the glyph, because of rasterization and pixel
089 * adjustment effects.
090 * <p>
091 * Although instances of <code>GlyphMetrics</code> can be directly
092 * constructed, they are almost always obtained from a
093 * <code>GlyphVector</code>. Once constructed, <code>GlyphMetrics</code>
094 * objects are immutable.
095 * <p>
096 * <strong>Example</strong>:<p>
097 * Querying a <code>Font</code> for glyph information
098 * <blockquote><pre>
099 * Font font = ...;
100 * int glyphIndex = ...;
101 * GlyphMetrics metrics = GlyphVector.getGlyphMetrics(glyphIndex);
102 * int isStandard = metrics.isStandard();
103 * float glyphAdvance = metrics.getAdvance();
104 * </pre></blockquote>
105 * @see java.awt.Font
106 * @see GlyphVector
107 */
108
109 public final class GlyphMetrics {
110 /**
111 * Indicates whether the metrics are for a horizontal or vertical baseline.
112 */
113 private boolean horizontal;
114
115 /**
116 * The x-component of the advance.
117 */
118 private float advanceX;
119
120 /**
121 * The y-component of the advance.
122 */
123 private float advanceY;
124
125 /**
126 * The bounds of the associated glyph.
127 */
128 private Rectangle2D.Float bounds;
129
130 /**
131 * Additional information about the glyph encoded as a byte.
132 */
133 private byte glyphType;
134
135 /**
136 * Indicates a glyph that represents a single standard
137 * character.
138 */
139 public static final byte STANDARD = 0;
140
141 /**
142 * Indicates a glyph that represents multiple characters
143 * as a ligature, for example 'fi' or 'ffi'. It is followed by
144 * filler glyphs for the remaining characters. Filler and combining
145 * glyphs can be intermixed to control positioning of accent marks
146 * on the logically preceeding ligature.
147 */
148 public static final byte LIGATURE = 1;
149
150 /**
151 * Indicates a glyph that represents a combining character,
152 * such as an umlaut. There is no caret position between this glyph
153 * and the preceeding glyph.
154 */
155 public static final byte COMBINING = 2;
156
157 /**
158 * Indicates a glyph with no corresponding character in the
159 * backing store. The glyph is associated with the character
160 * represented by the logicaly preceeding non-component glyph. This
161 * is used for kashida justification or other visual modifications to
162 * existing glyphs. There is no caret position between this glyph
163 * and the preceeding glyph.
164 */
165 public static final byte COMPONENT = 3;
166
167 /**
168 * Indicates a glyph with no visual representation. It can
169 * be added to the other code values to indicate an invisible glyph.
170 */
171 public static final byte WHITESPACE = 4;
172
173 /**
174 * Constructs a <code>GlyphMetrics</code> object.
175 * @param advance the advance width of the glyph
176 * @param bounds the black box bounds of the glyph
177 * @param glyphType the type of the glyph
178 */
179 public GlyphMetrics(float advance, Rectangle2D bounds,
180 byte glyphType) {
181 this .horizontal = true;
182 this .advanceX = advance;
183 this .advanceY = 0;
184 this .bounds = new Rectangle2D.Float();
185 this .bounds.setRect(bounds);
186 this .glyphType = glyphType;
187 }
188
189 /**
190 * Constructs a <code>GlyphMetrics</code> object.
191 * @param horizontal if true, metrics are for a horizontal baseline,
192 * otherwise they are for a vertical baseline
193 * @param advanceX the X-component of the glyph's advance
194 * @param advanceY the Y-component of the glyph's advance
195 * @param bounds the visual bounds of the glyph
196 * @param glyphType the type of the glyph
197 * @since 1.4
198 */
199 public GlyphMetrics(boolean horizontal, float advanceX,
200 float advanceY, Rectangle2D bounds, byte glyphType) {
201
202 this .horizontal = horizontal;
203 this .advanceX = advanceX;
204 this .advanceY = advanceY;
205 this .bounds = new Rectangle2D.Float();
206 this .bounds.setRect(bounds);
207 this .glyphType = glyphType;
208 }
209
210 /**
211 * Returns the advance of the glyph along the baseline (either
212 * horizontal or vertical).
213 * @return the advance of the glyph
214 */
215 public float getAdvance() {
216 return horizontal ? advanceX : advanceY;
217 }
218
219 /**
220 * Returns the x-component of the advance of the glyph.
221 * @return the x-component of the advance of the glyph
222 * @since 1.4
223 */
224 public float getAdvanceX() {
225 return advanceX;
226 }
227
228 /**
229 * Returns the y-component of the advance of the glyph.
230 * @return the y-component of the advance of the glyph
231 * @since 1.4
232 */
233 public float getAdvanceY() {
234 return advanceY;
235 }
236
237 /**
238 * Returns the bounds of the glyph. This is the bounding box of the glyph outline.
239 * Because of rasterization and pixel alignment effects, it does not necessarily
240 * enclose the pixels that are affected when rendering the glyph.
241 * @return a {@link Rectangle2D} that is the bounds of the glyph.
242 */
243 public Rectangle2D getBounds2D() {
244 return new Rectangle2D.Float(bounds.x, bounds.y, bounds.width,
245 bounds.height);
246 }
247
248 /**
249 * Returns the left (top) side bearing of the glyph.
250 * <p>
251 * This is the distance from 0, 0 to the left (top) of the glyph
252 * bounds. If the bounds of the glyph is to the left of (above) the
253 * origin, the LSB is negative.
254 * @return the left side bearing of the glyph.
255 */
256 public float getLSB() {
257 return horizontal ? bounds.x : bounds.y;
258 }
259
260 /**
261 * Returns the right (bottom) side bearing of the glyph.
262 * <p>
263 * This is the distance from the right (bottom) of the glyph bounds to
264 * the advance. If the bounds of the glyph is to the right of (below)
265 * the advance, the RSB is negative.
266 * @return the right side bearing of the glyph.
267 */
268 public float getRSB() {
269 return horizontal ? advanceX - bounds.x - bounds.width
270 : advanceY - bounds.y - bounds.height;
271 }
272
273 /**
274 * Returns the raw glyph type code.
275 * @return the raw glyph type code.
276 */
277 public int getType() {
278 return glyphType;
279 }
280
281 /**
282 * Returns <code>true</code> if this is a standard glyph.
283 * @return <code>true</code> if this is a standard glyph;
284 * <code>false</code> otherwise.
285 */
286 public boolean isStandard() {
287 return (glyphType & 0x3) == STANDARD;
288 }
289
290 /**
291 * Returns <code>true</code> if this is a ligature glyph.
292 * @return <code>true</code> if this is a ligature glyph;
293 * <code>false</code> otherwise.
294 */
295 public boolean isLigature() {
296 return (glyphType & 0x3) == LIGATURE;
297 }
298
299 /**
300 * Returns <code>true</code> if this is a combining glyph.
301 * @return <code>true</code> if this is a combining glyph;
302 * <code>false</code> otherwise.
303 */
304 public boolean isCombining() {
305 return (glyphType & 0x3) == COMBINING;
306 }
307
308 /**
309 * Returns <code>true</code> if this is a component glyph.
310 * @return <code>true</code> if this is a component glyph;
311 * <code>false</code> otherwise.
312 */
313 public boolean isComponent() {
314 return (glyphType & 0x3) == COMPONENT;
315 }
316
317 /**
318 * Returns <code>true</code> if this is a whitespace glyph.
319 * @return <code>true</code> if this is a whitespace glyph;
320 * <code>false</code> otherwise.
321 */
322 public boolean isWhitespace() {
323 return (glyphType & 0x4) == WHITESPACE;
324 }
325 }
|