1. /*
  2. * @(#)GlyphVector.java 1.21 00/02/02
  3. *
  4. * Copyright 1998-2000 Sun Microsystems, Inc. All Rights Reserved.
  5. *
  6. * This software is the proprietary information of Sun Microsystems, Inc.
  7. * Use is subject to license terms.
  8. *
  9. */
  10. /*
  11. * @author Charlton Innovations, Inc.
  12. */
  13. package java.awt.font;
  14. import java.awt.Graphics2D;
  15. import java.awt.Font;
  16. import java.awt.Polygon; // remind - need a floating point version
  17. import java.awt.geom.Point2D;
  18. import java.awt.geom.Rectangle2D;
  19. import java.awt.geom.AffineTransform;
  20. import java.awt.Shape;
  21. import java.awt.font.GlyphMetrics;
  22. import java.awt.font.GlyphJustificationInfo;
  23. /**
  24. * A <code>GlyphVector</code> object is a collection of glyphs
  25. * containing geometric information for the placement of each glyph
  26. * in a transformed coordinate space which corresponds to the
  27. * device on which the <code>GlyphVector</code> is ultimately
  28. * displayed.
  29. * <p>
  30. * The <code>GlyphVector</code> does not attempt any interpretation of
  31. * the sequence of glyphs it contains. Relationships between adjacent
  32. * glyphs in sequence are solely used to determine the placement of
  33. * the glyphs in the visual coordinate space.
  34. * <p>
  35. * Instances of <code>GlyphVector</code> are created by a {@link Font}.
  36. * <p>
  37. * In a text processing application that can cache intermediate
  38. * representations of text, creation and subsequent caching of a
  39. * <code>GlyphVector</code> for use during rendering is the fastest
  40. * method to present the visual representation of characters to a user.
  41. * <p>
  42. * A <code>GlyphVector</code> is associated with exactly one
  43. * <code>Font</code>, and can provide data useful only in relation to
  44. * this <code>Font</code>. In addition, metrics obtained from a
  45. * <code>GlyphVector</code> are not generally geometrically scaleable
  46. * since the pixelization and spacing are dependent on grid-fitting
  47. * algorithms within a <code>Font</code>. To facilitate accurate
  48. * measurement of a <code>GlyphVector</code> and its component
  49. * glyphs, you must specify a scaling transform, anti-alias mode, and
  50. * fractional metrics mode when creating the <code>GlyphVector</code>.
  51. * These characteristics can be derived from the destination device.
  52. * <p>
  53. * For each glyph in the <code>GlyphVector</code>, you can obtain:
  54. * <ul>
  55. * <li>the position of the glyph
  56. * <li>the transform associated with the glyph
  57. * <li>the metrics of the glyph in the context of the
  58. * <code>GlyphVector</code>. The metrics of the glyph may be
  59. * different under different transforms, application specified
  60. * rendering hints, and the specific instance of the glyph within
  61. * the <code>GlyphVector</code>.
  62. * </ul>
  63. * <p>
  64. * Altering the data used to create the <code>GlyphVector</code> does not
  65. * alter the state of the <code>GlyphVector</code>.
  66. * <p>
  67. * Methods are provided to create new <code>GlyphVector</code>
  68. * objects which are the result of editing operations on the
  69. * <code>GlyphVector</code>, such as glyph insertion and deletion. These
  70. * methods are most appropriate for applications that are forming
  71. * combinations such as ligatures from existing glyphs or are breaking
  72. * such combinations into their component parts for visual presentation.
  73. * <p>
  74. * Methods are provided to create new <code>GlyphVector</code>
  75. * objects that are the result of specifying new positions for the glyphs
  76. * within the <code>GlyphVector</code>. These methods are most
  77. * appropriate for applications that are performing justification
  78. * operations for the presentation of the glyphs.
  79. * <p>
  80. * Methods are provided to return both the visual and logical bounds
  81. * of the entire <code>GlyphVector</code> or of individual glyphs within
  82. * the <code>GlyphVector</code>.
  83. * <p>
  84. * Methods are provided to return a {@link Shape} for the
  85. * <code>GlyphVector</code>, and for individual glyphs within the
  86. * <code>GlyphVector</code>.
  87. * @see Font
  88. * @see GlyphMetrics
  89. * @see TextLayout
  90. * @version 19 Mar 1998
  91. * @author Charlton Innovations, Inc.
  92. */
  93. public abstract class GlyphVector implements Cloneable {
  94. // methods associated with creation-time state
  95. /**
  96. * Returns the <code>Font</code> associated with this
  97. * <code>GlyphVector</code>.
  98. * @returns <code>Font</code> used to create this
  99. * <code>GlyphVector</code>.
  100. * @see Font
  101. */
  102. public abstract Font getFont();
  103. /**
  104. * Returns the {@link FontRenderContext} associated with this
  105. * <code>GlyphVector</code>.
  106. * @return <code>FontRenderContext</code> used to create this
  107. * <code>GlyphVector</code>.
  108. * @see FontRenderContext
  109. * @see Font
  110. */
  111. public abstract FontRenderContext getFontRenderContext();
  112. // methods associated with the GlyphVector as a whole
  113. /**
  114. * Assigns default positions to each glyph in this
  115. * <code>GlyphVector</code>. No shaping, reordering, or contextual
  116. * substitution is performed.
  117. */
  118. public abstract void performDefaultLayout();
  119. /**
  120. * Returns the number of glyphs in this <code>GlyphVector</code>.
  121. * This information is used to create arrays that are to be
  122. * filled with results of other information retrieval
  123. * operations.
  124. * @return number of glyphs in this <code>GlyphVector</code>.
  125. */
  126. public abstract int getNumGlyphs();
  127. /**
  128. * Returns the glyphcode of the specified glyph.
  129. * This return value is meaningless to anything other
  130. * than a <code>Font</code> object and can be used to ask the
  131. * <code>Font</code> object about the existence of ligatures and
  132. * other context sensitive information.
  133. * @param glyphIndex the index into this <code>GlyphVector</code>
  134. * that corresponds to the glyph from which to retrieve the
  135. * glyphcode.
  136. * @return the glyphcode of the glyph corresponding the the specified
  137. * <code>glyphIndex</code>.
  138. * @throws IndexOutOfBoundsException if <code>glyphIndex</code>
  139. * is less than 0 or greater than or equal to the
  140. * number of glyphs in this <code>GlyphVector</code>
  141. */
  142. public abstract int getGlyphCode(int glyphIndex);
  143. /**
  144. * Returns an array of glyphcodes for the specified glyphs.
  145. * The contents of this return value are meaningless to anything other
  146. * than a <code>Font</code> and can be used to ask the
  147. * <code>Font</code> about the existence of ligatures and other
  148. * context sensitive information. This method is used
  149. * for convenience and performance when processing glyphcodes.
  150. * If no array is passed in, an array is created.
  151. * @param beginGlyphIndex the index into this
  152. * <code>GlyphVector</code> at which to start retrieving glyphcodes
  153. * for the corresponding glyphs
  154. * @param numEntries the number of glyphs to retrieve
  155. * @param codeReturn the array that receives the glyphcodes and is
  156. * then returned
  157. * @return an array of glyphcodes for the specified glyphs.
  158. * @throws IllegalArgumentException if <code>numEntries</code> is
  159. * less than 0
  160. * @throws IndexOutOfBoundsException if <code>beginGlyphIndex</code>
  161. * is less than 0
  162. * @throws IndexOutOfBoundsException if the sum of
  163. * <code>beginGlyphIndex</code> and <code>numEntries</code> is
  164. * greater than the number of glyphs in this
  165. * <code>GlyphVector</code>
  166. */
  167. public abstract int[] getGlyphCodes(int beginGlyphIndex, int numEntries,
  168. int[] codeReturn);
  169. // methods associated with the GlyphVector as a whole,
  170. // after layout.
  171. /**
  172. * Returns the logical bounds of this <code>GlyphVector</code>.
  173. * This method is used when positioning this <code>GlyphVector</code>
  174. * in relation to visually adjacent <code>GlyphVector</code> objects.
  175. * @return a {@link Rectangle2D} that is the logical bounds of this
  176. * <code>GlyphVector</code>.
  177. */
  178. public abstract Rectangle2D getLogicalBounds();
  179. /**
  180. * Returns the visual bounds of this <code>GlyphVector</code>
  181. * The visual bounds is the tightest rectangle enclosing all
  182. * non-background pixels in the rendered representation of this
  183. * <code>GlyphVector</code>.
  184. * @return a <code>Rectangle2D</code> that is the tightest bounds
  185. * of this <code>GlyphVector</code>.
  186. */
  187. public abstract Rectangle2D getVisualBounds();
  188. /**
  189. * Returns a <code>Shape</code> whose interior corresponds to the
  190. * visual representation of this <code>GlyphVector</code>.
  191. * @return a <code>Shape</code> that is the outline of this
  192. * <code>GlyphVector</code>.
  193. */
  194. public abstract Shape getOutline();
  195. /**
  196. * Returns a <code>Shape</code> whose interior corresponds to the
  197. * visual representation of this <code>GlyphVector</code>, offset
  198. * to x, y.
  199. * @param x, y the coordinates of the location of the outline
  200. * <code>Shape</code>
  201. * @return a <code>Shape</code> that is the outline of this
  202. * <code>GlyphVector</code>, offset to the specified
  203. * coordinates.
  204. */
  205. public abstract Shape getOutline(float x, float y);
  206. /**
  207. * Returns a <code>Shape</code> whose interior corresponds to the
  208. * visual representation of the specified glyph
  209. * within this <code>GlyphVector</code>.
  210. * @param glyphIndex the index into this <code>GlyphVector</code>
  211. * @return a <code>Shape</code> that is the outline of the glyph
  212. * at the specified <code>glyphIndex</code> of this
  213. * <code>GlyphVector</code>.
  214. * @throws IndexOutOfBoundsException if <code>glyphIndex</code>
  215. * is less than 0 or greater than or equal to the number
  216. * of glyphs in this <code>GlyphVector</code>
  217. */
  218. public abstract Shape getGlyphOutline(int glyphIndex);
  219. /**
  220. * Returns the position of the specified glyph within this
  221. * <code>GlyphVector</code>.
  222. * This position corresponds to the leading edge of the baseline for
  223. * the glyph.
  224. * If <code>glyphIndex</code> equals the number of of glyphs in
  225. * this <code>GlyphVector</code>, this method gets the position after
  226. * the last glyph and this position is used to define the advance of
  227. * the entire <code>GlyphVector</code>.
  228. * @param glyphIndex the index into this <code>GlyphVector</code>
  229. * @return a {@link Point2D} object that is the position of the glyph
  230. * at the specified <code>glyphIndex</code>.
  231. * @throws IndexOutOfBoundsException if <code>glyphIndex</code>
  232. * is less than 0 or greater than the number of glyphs
  233. * in this <code>GlyphVector</code>
  234. */
  235. public abstract Point2D getGlyphPosition(int glyphIndex);
  236. /**
  237. * Sets the position of the specified glyph within this
  238. * <code>GlyphVector</code>.
  239. * This position corresponds to the leading edge of the baseline for
  240. * the glyph.
  241. * If <code>glyphIndex</code> equals the number of of glyphs in
  242. * this <code>GlyphVector</code>, this method sets the position after
  243. * the last glyph and this position is used to define the advance of
  244. * the entire <code>GlyphVector</code>.
  245. * @param glyphIndex the index into this <code>GlyphVector</code>
  246. * @param newPos the <code>Point2D</code> at which to position the
  247. * glyph at the specified <code>glyphIndex</code>
  248. * @throws IndexOutOfBoundsException if <code>glyphIndex</code>
  249. * is less than 0 or greater than the number of glyphs
  250. * in this <code>GlyphVector</code>
  251. */
  252. public abstract void setGlyphPosition(int glyphIndex, Point2D newPos);
  253. /**
  254. * Gets the transform of the specified glyph within this
  255. * <code>GlyphVector</code>. The transform is relative to the
  256. * glyph position. If no special transform has been applied,
  257. * <code>null</code> can be returned. Such a transform would
  258. * be an identity transform.
  259. * @param glyphIndex the index into this <code>GlyphVector</code>
  260. * @return an {@link AffineTransform} that is the transform of
  261. * the glyph at the specified <code>glyphIndex</code>.
  262. * @throws IndexOutOfBoundsException if <code>glyphIndex</code>
  263. * is less than 0 or greater than or equal to the number
  264. * of glyphs in this <code>GlyphVector</code>
  265. */
  266. public abstract AffineTransform getGlyphTransform(int glyphIndex);
  267. /**
  268. * Sets the transform of the specified glyph within this
  269. * <code>GlyphVector</code>. The transform is relative to the glyph
  270. * position. A <code>null</code> argument for <code>newTX</code>
  271. * indicates that no special transform is applied for the specified
  272. * glyph.
  273. * This method can be used to rotate, mirror, translate and scale the
  274. * glyph. Adding a transform can result in signifant performance changes.
  275. * @param glyphIndex the index into this <code>GlyphVector</code>
  276. * @param newTx the specified transform that the transform of the
  277. * glyph at the specified <code>glyphIndex</code> is set to
  278. * @throws IndexOutOfBoundsException if <code>glyphIndex</code>
  279. * is less than 0 or greater than or equal to the number
  280. * of glyphs in this <code>GlyphVector</code>
  281. */
  282. public abstract void setGlyphTransform(int glyphIndex, AffineTransform newTX);
  283. /**
  284. * Returns an array of glyph positions for the specified glyphs.
  285. * The position of each glyph corresponds to the leading edge of the
  286. * baseline for that glyph. This method is used for convenience and
  287. * performance when processing glyph positions.
  288. * If no array is passed in, a new array is created.
  289. * Even numbered array entries beginning with position zero are the X
  290. * coordinates of the glyph numbered beginGlyphIndex + position/2.
  291. * Odd numbered array entries beginning with position one are the Y
  292. * coordinates of the glyph numbered beginGlyphIndex + (position-1)/2.
  293. * If <code>beginGlyphIndex</code> equals the number of of glyphs in
  294. * this <code>GlyphVector</code>, this method gets the position after
  295. * the last glyph and this position is used to define the advance of
  296. * the entire <code>GlyphVector</code>.
  297. * @param beginGlyphIndex the index at which to begin retrieving
  298. * glyph positions
  299. * @param numEntries the number of glyphs to retrieve
  300. * @param positionReturn the array that receives the glyph positions
  301. * and is then returned.
  302. * @return an array of glyph positions specified by
  303. * <code>beginGlyphIndex</code> and <code>numEntries</code>.
  304. * @throws IllegalArgumentException if <code>numEntries</code> is
  305. * less than 0
  306. * @throws IndexOutOfBoundsException if <code>beginGlyphIndex</code>
  307. * is less than 0
  308. * @throws IndexOutOfBoundsException if the sum of
  309. * <code>beginGlyphIndex</code> and <code>numEntries</code>
  310. * is greater than the number of glyphs in this
  311. * <code>GlyphVector</code> plus one
  312. */
  313. public abstract float[] getGlyphPositions(int beginGlyphIndex, int numEntries,
  314. float[] positionReturn);
  315. /**
  316. * Returns the logical bounds of the specified glyph within this
  317. * <code>GlyphVector</code>.
  318. * These logical bounds have a total of four edges, with two edges
  319. * parallel to the baseline under the glyph's transform and the other two
  320. * edges are shared with adjacent glyphs if they are present. This
  321. * method is useful for hit-testing of the specified glyph,
  322. * positioning of a caret at the leading or trailing edge of a glyph,
  323. * and for drawing a highlight region around the specified glyph.
  324. * @param glyphIndex the index into this <code>GlyphVector</code>
  325. * that corresponds to the glyph from which to retrieve its logical
  326. * bounds
  327. * @return a <code>Shape</code> that is the logical bounds of the
  328. * glyph at the specified <code>glyphIndex</code>.
  329. * @throws IndexOutOfBoundsException if <code>glyphIndex</code>
  330. * is less than 0 or greater than or equal to the number
  331. * of glyphs in this <code>GlyphVector</code>
  332. * @see #getGlyphVisualBounds
  333. */
  334. public abstract Shape getGlyphLogicalBounds(int glyphIndex);
  335. /**
  336. * Returns the visual bounds of the specified glyph within the
  337. * <code>GlyphVector</code>.
  338. * These visual bounds have a total of four edges, representing the
  339. * tightest polygon enclosing non-background pixels in the rendered
  340. * representation of the glyph whose edges are parallel to the edges
  341. * of the logical bounds. Useful for hit-testing of the specified glyph.
  342. * @param glyphIndex the index into this <code>GlyphVector</code>
  343. * that corresponds to the glyph from which to retrieve its visual
  344. * bounds
  345. * @return a <code>Shape</code> that is the visual bounds of the
  346. * glyph at the specified <code>glyphIndex</code>.
  347. * @throws IndexOutOfBoundsException if <code>glyphIndex</code>
  348. * is less than 0 or greater than or equal to the number
  349. * of glyphs in this <code>GlyphVector</code>
  350. * @see #getGlyphLogicalBounds
  351. */
  352. public abstract Shape getGlyphVisualBounds(int glyphIndex);
  353. /**
  354. * Returns the metrics of the glyph at the specified index into
  355. * this <code>GlyphVector</code>.
  356. * @param glyphIndex the index into this <code>GlyphVector</code>
  357. * that corresponds to the glyph from which to retrieve its metrics
  358. * @return a {@link GlyphMetrics} object that represents the
  359. * metrics of the glyph at the specified <code>glyphIndex</code>
  360. * into this <code>GlyphVector</code>.
  361. * @throws IndexOutOfBoundsException if <code>glyphIndex</code>
  362. * is less than 0 or greater than or equal to the number
  363. * of glyphs in this <code>GlyphVector</code>
  364. */
  365. public abstract GlyphMetrics getGlyphMetrics(int glyphIndex);
  366. /**
  367. * Returns the justification information for the glyph at
  368. * the specified index into this <code>GlyphVector</code>.
  369. * @param glyphIndex the index into this <code>GlyphVector</code>
  370. * that corresponds to the glyph from which to retrieve its
  371. * justification properties
  372. * @return a {@link GlyphJustificationInfo} object that
  373. * represents the justification properties of the glyph at the
  374. * specified <code>glyphIndex</code> into this
  375. * <code>GlyphVector</code>.
  376. * @throws IndexOutOfBoundsException if <code>glyphIndex</code>
  377. * is less than 0 or greater than or equal to the number
  378. * of glyphs in this <code>GlyphVector</code>
  379. */
  380. public abstract GlyphJustificationInfo getGlyphJustificationInfo(int glyphIndex);
  381. // general utility methods
  382. /**
  383. * Tests if the specified <code>GlyphVector</code> exactly
  384. * equals this <code>GlyphVector</code>.
  385. * @param set the specified <code>GlyphVector</code> to test
  386. * @return <code>true</code> if the specified
  387. * <code>GlyphVector</code> equals this <code>GlyphVector</code>
  388. * <code>false</code> otherwise.
  389. */
  390. public abstract boolean equals(GlyphVector set);
  391. }