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. /*

  12.  * @author Charlton Innovations, Inc.

  13.  */

  14. 

  15. package java.awt.font;

  16. 

  17. import java.awt.Graphics2D;

  18. import java.awt.Font;

  19. import java.awt.Polygon;        // remind - need a floating point version

  20. import java.awt.geom.Point2D;

  21. import java.awt.geom.Rectangle2D;

  22. import java.awt.geom.AffineTransform;

  23. import java.awt.Shape;

  24. import java.awt.font.GlyphMetrics;

  25. import java.awt.font.GlyphJustificationInfo;

  26. 

  27. /**

  28. *   A <code>GlyphVector</code> object is a collection of glyphs

  29. *   containing geometric information for the placement of each glyph 

  30. *   in a transformed coordinate space which corresponds to the

  31. *   device on which the <code>GlyphVector</code> is ultimately 

  32. *   displayed. 

  33. *   <p>

  34. *   The <code>GlyphVector</code> does not attempt any interpretation of

  35. *   the sequence of glyphs it contains.  Relationships between adjacent

  36. *   glyphs in sequence are solely used to determine the placement of

  37. *   the glyphs in the visual coordinate space.

  38. *   <p>

  39. *   Instances of <code>GlyphVector</code> are created by a {@link Font}.

  40. *   <p>

  41. *   In a text processing application that can cache intermediate

  42. *   representations of text, creation and subsequent caching of a 

  43. *   <code>GlyphVector</code> for use during rendering is the fastest

  44. *   method to present the visual representation of characters to a user.

  45. *   <p>

  46. *   A <code>GlyphVector</code> is associated with exactly one 

  47. *   <code>Font</code>, and can provide data useful only in relation to

  48. *   this <code>Font</code>.  In addition, metrics obtained from a

  49. *   <code>GlyphVector</code> are not generally geometrically scaleable

  50. *   since the pixelization and spacing are dependent on grid-fitting

  51. *   algorithms within a <code>Font</code>.  To facilitate accurate

  52. *   measurement of a <code>GlyphVector</code> and its component

  53. *   glyphs, you must specify a scaling transform, anti-alias mode, and

  54. *   fractional metrics mode when creating the <code>GlyphVector</code>.

  55. *   These characteristics can be derived from the destination device.

  56. *   <p>

  57. *   For each glyph in the <code>GlyphVector</code>, you can obtain:

  58. *   <ul>

  59. *   <li>the position of the glyph

  60. *   <li>the transform associated with the glyph

  61. *   <li>the metrics of the glyph in the context of the 

  62. *	   <code>GlyphVector</code>.  The metrics of the glyph may be

  63. *           different under different transforms, application specified

  64. *           rendering hints, and the specific instance of the glyph within

  65. *           the <code>GlyphVector</code>.

  66. *   </ul>

  67. *   <p>

  68. *   Altering the data used to create the <code>GlyphVector</code> does not

  69. *   alter the state of the <code>GlyphVector</code>.

  70. *   <p>

  71. *   Methods are provided to create new <code>GlyphVector</code>

  72. *   objects which are the result of editing operations on the

  73. *   <code>GlyphVector</code>, such as glyph insertion and deletion.  These

  74. *   methods are most appropriate for applications that are forming

  75. *   combinations such as ligatures from existing glyphs or are breaking

  76. *   such combinations into their component parts for visual presentation.

  77. *   <p>

  78. *   Methods are provided to create new <code>GlyphVector</code>

  79. *   objects that are the result of specifying new positions for the glyphs

  80. *   within the <code>GlyphVector</code>.  These methods are most

  81. *   appropriate for applications that are performing justification

  82. *   operations for the presentation of the glyphs.

  83. *   <p>

  84. *   Methods are provided to return both the visual and logical bounds

  85. *   of the entire <code>GlyphVector</code> or of individual glyphs within

  86. *   the <code>GlyphVector</code>.

  87. *   <p>

  88. *   Methods are provided to return a {@link Shape} for the 

  89. *   <code>GlyphVector</code>, and for individual glyphs within the

  90. *   <code>GlyphVector</code>.

  91. *   @see Font

  92. *   @see GlyphMetrics

  93. *   @see TextLayout

  94. *   @version 19 Mar 1998

  95. *   @author Charlton Innovations, Inc.

  96. */

  97. 

  98. public abstract class GlyphVector implements Cloneable {

  99. 

  100. 

  101.     // methods associated with creation-time state

  102.     /**

  103.     *   Returns the <code>Font</code> associated with this 

  104.     *   <code>GlyphVector</code>.

  105.     *   @returns <code>Font</code> used to create this 

  106.     *   <code>GlyphVector</code>.

  107.     *   @see Font

  108.     */

  109.     public abstract Font getFont();

  110. 

  111.     /**

  112.     *   Returns the {@link FontRenderContext} associated with this

  113.     *   <code>GlyphVector</code>.

  114.     *   @return <code>FontRenderContext</code> used to create this

  115.     *   <code>GlyphVector</code>.

  116.     *   @see FontRenderContext

  117.     *   @see Font

  118.     */

  119.     public abstract FontRenderContext getFontRenderContext();

  120. 

  121.     // methods associated with the GlyphVector as a whole

  122. 

  123.     /**

  124.     *   Assigns default positions to each glyph in this 

  125.     *   <code>GlyphVector</code>.  No shaping, reordering, or contextual

  126.     *   substitution is performed.

  127.     */

  128.     public abstract void performDefaultLayout();

  129. 

  130.     /**

  131.     *   Returns the number of glyphs in this <code>GlyphVector</code>.

  132.     *   This information is used to create arrays that are to be

  133.     *   filled with results of other information retrieval

  134.     *   operations.

  135.     *   @return number of glyphs in this <code>GlyphVector</code>.

  136.     */

  137.     public abstract int getNumGlyphs();

  138. 

  139.     /**

  140.     *   Returns the glyphcode of the specified glyph.

  141.     *   This return value is meaningless to anything other

  142.     *   than a <code>Font</code> object and can be used to ask the 

  143.     *   <code>Font</code> object about the existence of ligatures and

  144.     *   other context sensitive information.

  145.     *   @param glyphIndex the index into this <code>GlyphVector</code>

  146.     *   that corresponds to the glyph from which to retrieve the 

  147.     *   glyphcode.

  148.     *   @return the glyphcode of the glyph corresponding the the specified

  149.     *   <code>glyphIndex</code>.

  150.     *   @throws IndexOutOfBoundsException if <code>glyphIndex</code>

  151.     *           is less than 0 or greater than or equal to the 

  152.     *           number of glyphs in this <code>GlyphVector</code>

  153.     */

  154.     public abstract int getGlyphCode(int glyphIndex);

  155. 

  156.     /**

  157.     *   Returns an array of glyphcodes for the specified glyphs.

  158.     *   The contents of this return value are meaningless to anything other

  159.     *   than a <code>Font</code> and can be used to ask the 

  160.     *   <code>Font</code> about the existence of ligatures and other

  161.     *   context sensitive information.  This method is used

  162.     *   for convenience and performance when processing glyphcodes.

  163.     *   If no array is passed in, an array is created.

  164.     *   @param beginGlyphIndex the index into this

  165.     *   <code>GlyphVector</code> at which to start retrieving glyphcodes

  166.     *   for the corresponding glyphs

  167.     *   @param numEntries the number of glyphs to retrieve

  168.     *   @param codeReturn the array that receives the glyphcodes and is

  169.     *		then returned

  170.     *   @return an array of glyphcodes for the specified glyphs.

  171.     *   @throws IllegalArgumentException if <code>numEntries</code> is 

  172.     *           less than 0

  173.     *   @throws IndexOutOfBoundsException if <code>beginGlyphIndex</code> 

  174.     *           is less than 0

  175.     *   @throws IndexOutOfBoundsException if the sum of 

  176.     *           <code>beginGlyphIndex</code> and <code>numEntries</code> is 

  177.     *           greater than the number of glyphs in this

  178.     *           <code>GlyphVector</code>

  179.     */

  180.     public abstract int[] getGlyphCodes(int beginGlyphIndex, int numEntries,

  181.                                         int[] codeReturn);

  182. 

  183.     // methods associated with the GlyphVector as a whole,

  184.     // after layout.

  185.     /**

  186.     *   Returns the logical bounds of this <code>GlyphVector</code>.

  187.     *   This method is used when positioning this <code>GlyphVector</code> 

  188.     *   in relation to visually adjacent <code>GlyphVector</code> objects.

  189.     *   @return a {@link Rectangle2D} that is the logical bounds of this

  190.     *   <code>GlyphVector</code>.

  191.     */

  192.     public abstract Rectangle2D getLogicalBounds();

  193. 

  194.     /**

  195.     *   Returns the visual bounds of this <code>GlyphVector</code>

  196.     *   The visual bounds is the tightest rectangle enclosing all

  197.     *   non-background pixels in the rendered representation of this

  198.     *   <code>GlyphVector</code>.

  199.     *   @return a <code>Rectangle2D</code> that is the tightest bounds

  200.     *   of this <code>GlyphVector</code>.

  201.     */

  202.     public abstract Rectangle2D getVisualBounds();

  203. 

  204.     /**

  205.     *   Returns a <code>Shape</code> whose interior corresponds to the

  206.     *   visual representation of this <code>GlyphVector</code>.

  207.     *   @return a <code>Shape</code> that is the outline of this

  208.     *   <code>GlyphVector</code>.

  209.     */

  210.     public abstract Shape getOutline();

  211. 

  212.     /**

  213.     *   Returns a <code>Shape</code> whose interior corresponds to the

  214.     *   visual representation of this <code>GlyphVector</code>, offset

  215.     *   to x, y.

  216.     *   @param x, y the coordinates of the location of the outline

  217.     *		<code>Shape</code>

  218.     *   @return a <code>Shape</code> that is the outline of this

  219.     *           <code>GlyphVector</code>, offset to the specified 

  220.     *		coordinates.

  221.     */

  222.     public abstract Shape getOutline(float x, float y);

  223. 

  224.     /**

  225.     *   Returns a <code>Shape</code> whose interior corresponds to the

  226.     *   visual representation of the specified glyph

  227.     *   within this <code>GlyphVector</code>.

  228.     *   @param glyphIndex the index into this <code>GlyphVector</code>

  229.     *   @return a <code>Shape</code> that is the outline of the glyph

  230.     *		at the specified <code>glyphIndex</code> of this

  231.     *		<code>GlyphVector</code>.

  232.     *   @throws IndexOutOfBoundsException if <code>glyphIndex</code>

  233.     *           is less than 0 or greater than or equal to the number

  234.     *           of glyphs in this <code>GlyphVector</code>

  235.     */

  236.     public abstract Shape getGlyphOutline(int glyphIndex);

  237. 

  238.     /**

  239.     *   Returns the position of the specified glyph within this

  240.     *   <code>GlyphVector</code>.

  241.     *   This position corresponds to the leading edge of the baseline for

  242.     *   the glyph.

  243.     *   If <code>glyphIndex</code> equals the number of of glyphs in 

  244.     *   this <code>GlyphVector</code>, this method gets the position after

  245.     *   the last glyph and this position is used to define the advance of 

  246.     *   the entire <code>GlyphVector</code>.

  247.     *   @param glyphIndex the index into this <code>GlyphVector</code>

  248.     *   @return a {@link Point2D} object that is the position of the glyph

  249.     *		at the specified <code>glyphIndex</code>.

  250.     *   @throws IndexOutOfBoundsException if <code>glyphIndex</code>

  251.     *           is less than 0 or greater than the number of glyphs

  252.     *           in this <code>GlyphVector</code>

  253.     */

  254.     public abstract Point2D getGlyphPosition(int glyphIndex);

  255. 

  256.     /**

  257.     *   Sets the position of the specified glyph within this

  258.     *   <code>GlyphVector</code>.

  259.     *   This position corresponds to the leading edge of the baseline for

  260.     *   the glyph.

  261.     *   If <code>glyphIndex</code> equals the number of of glyphs in 

  262.     *   this <code>GlyphVector</code>, this method sets the position after

  263.     *   the last glyph and this position is used to define the advance of 

  264.     *   the entire <code>GlyphVector</code>.

  265.     *   @param glyphIndex the index into this <code>GlyphVector</code>

  266.     *   @param newPos the <code>Point2D</code> at which to position the

  267.     *		glyph at the specified <code>glyphIndex</code>

  268.     *   @throws IndexOutOfBoundsException if <code>glyphIndex</code>

  269.     *           is less than 0 or greater than the number of glyphs

  270.     *           in this <code>GlyphVector</code>

  271.     */

  272.     public abstract void setGlyphPosition(int glyphIndex, Point2D newPos);

  273. 

  274.     /**

  275.     *   Gets the transform of the specified glyph within this

  276.     *   <code>GlyphVector</code>.  The transform is relative to the

  277.     *   glyph position.  If no special transform has been applied, 

  278.     *   <code>null</code> can be returned.  Such a transform would 

  279.     *   be an identity transform.

  280.     *   @param glyphIndex the index into this <code>GlyphVector</code>

  281.     *   @return an {@link AffineTransform} that is the transform of

  282.     *		the glyph at the specified <code>glyphIndex</code>.

  283.     *   @throws IndexOutOfBoundsException if <code>glyphIndex</code>

  284.     *           is less than 0 or greater than or equal to the number 

  285.     *           of glyphs in this <code>GlyphVector</code>

  286.     */

  287.     public abstract AffineTransform getGlyphTransform(int glyphIndex);

  288. 

  289.     /**

  290.     *   Sets the transform of the specified glyph within this

  291.     *   <code>GlyphVector</code>.  The transform is relative to the glyph

  292.     *   position.  A <code>null</code> argument for <code>newTX</code>

  293.     *   indicates that no special transform is applied for the specified

  294.     *   glyph.

  295.     *   This method can be used to rotate, mirror, translate and scale the

  296.     *   glyph.  Adding a transform can result in signifant performance changes.

  297.     *   @param glyphIndex the index into this <code>GlyphVector</code>

  298.     *   @param newTx the specified transform that the transform of the

  299.     *		glyph at the specified <code>glyphIndex</code> is set to

  300.     *   @throws IndexOutOfBoundsException if <code>glyphIndex</code>

  301.     *           is less than 0 or greater than or equal to the number 

  302.     *           of glyphs in this <code>GlyphVector</code>

  303.     */

  304.     public abstract void setGlyphTransform(int glyphIndex, AffineTransform newTX);

  305. 

  306.     /**

  307.     *   Returns an array of glyph positions for the specified glyphs.

  308.     *   The position of each glyph corresponds to the leading edge of the

  309.     *   baseline for that glyph.  This method is used for convenience and

  310.     *   performance when processing glyph positions.

  311.     *   If no array is passed in, a new array is created.

  312.     *   Even numbered array entries beginning with position zero are the X

  313.     *   coordinates of the glyph numbered beginGlyphIndex + position/2.  

  314.     *   Odd numbered array entries beginning with position one are the Y

  315.     *   coordinates of the glyph numbered beginGlyphIndex + (position-1)/2.

  316.     *   If <code>beginGlyphIndex</code> equals the number of of glyphs in 

  317.     *   this <code>GlyphVector</code>, this method gets the position after

  318.     *   the last glyph and this position is used to define the advance of 

  319.     *   the entire <code>GlyphVector</code>.

  320.     *   @param beginGlyphIndex the index at which to begin retrieving

  321.     *        glyph positions

  322.     *   @param numEntries the number of glyphs to retrieve

  323.     *   @param positionReturn the array that receives the glyph positions

  324.     *     and is then returned.

  325.     *   @return an array of glyph positions specified by

  326.     *		<code>beginGlyphIndex</code> and <code>numEntries</code>.

  327.     *   @throws IllegalArgumentException if <code>numEntries</code> is

  328.     *           less than 0

  329.     *   @throws IndexOutOfBoundsException if <code>beginGlyphIndex</code>

  330.     *           is less than 0

  331.     *   @throws IndexOutOfBoundsException if the sum of 

  332.     *           <code>beginGlyphIndex</code> and <code>numEntries</code> 

  333.     *           is greater than the number of glyphs in this 

  334.     *           <code>GlyphVector</code> plus one

  335.     */

  336.     public abstract float[] getGlyphPositions(int beginGlyphIndex, int numEntries,

  337.                                               float[] positionReturn);

  338. 

  339.     /**

  340.     *   Returns the logical bounds of the specified glyph within this

  341.     *   <code>GlyphVector</code>.

  342.     *   These logical bounds have a total of four edges, with two edges

  343.     *   parallel to the baseline under the glyph's transform and the other two

  344.     *   edges are shared with adjacent glyphs if they are present.  This

  345.     *   method is useful for hit-testing of the specified glyph,

  346.     *   positioning of a caret at the leading or trailing edge of a glyph,

  347.     *   and for drawing a highlight region around the specified glyph.

  348.     *   @param glyphIndex the index into this <code>GlyphVector</code>

  349.     *   that corresponds to the glyph from which to retrieve its logical

  350.     *   bounds

  351.     *   @return  a <code>Shape</code> that is the logical bounds of the

  352.     *	glyph at the specified <code>glyphIndex</code>.

  353.     *   @throws IndexOutOfBoundsException if <code>glyphIndex</code>

  354.     *           is less than 0 or greater than or equal to the number 

  355.     *           of glyphs in this <code>GlyphVector</code>

  356.     *   @see #getGlyphVisualBounds

  357.     */

  358.     public abstract Shape getGlyphLogicalBounds(int glyphIndex);

  359. 

  360.     /**

  361.     *   Returns the visual bounds of the specified glyph within the

  362.     * 	<code>GlyphVector</code>.

  363.     *   These visual bounds have a total of four edges, representing the

  364.     *   tightest polygon enclosing non-background pixels in the rendered

  365.     *   representation of the glyph whose edges are parallel to the edges

  366.     *   of the logical bounds.  Useful for hit-testing of the specified glyph.

  367.     *	@param glyphIndex the index into this <code>GlyphVector</code>

  368.     *   that corresponds to the glyph from which to retrieve its visual

  369.     *   bounds

  370.     *	@return a <code>Shape</code> that is the visual bounds of the

  371.     * 	glyph at the specified <code>glyphIndex</code>.

  372.     *   @throws IndexOutOfBoundsException if <code>glyphIndex</code>

  373.     *           is less than 0 or greater than or equal to the number 

  374.     *           of glyphs in this <code>GlyphVector</code>

  375.     *   @see #getGlyphLogicalBounds

  376.     */

  377.     public abstract Shape getGlyphVisualBounds(int glyphIndex);

  378. 

  379.    /**	

  380.     *   Returns the metrics of the glyph at the specified index into

  381.     *	this <code>GlyphVector</code>.

  382.     *	@param glyphIndex the index into this <code>GlyphVector</code>

  383.     *   that corresponds to the glyph from which to retrieve its metrics

  384.     *	@return a {@link GlyphMetrics} object that represents the

  385.     *	metrics of the glyph at the specified <code>glyphIndex</code> 

  386.     *	into this <code>GlyphVector</code>.

  387.     *   @throws IndexOutOfBoundsException if <code>glyphIndex</code>

  388.     *           is less than 0 or greater than or equal to the number 

  389.     *           of glyphs in this <code>GlyphVector</code>

  390.     */

  391.     public abstract GlyphMetrics getGlyphMetrics(int glyphIndex);

  392. 

  393.    /**

  394.     *   Returns the justification information for the glyph at

  395.     *   the specified index into this <code>GlyphVector</code>.

  396.     * 	@param glyphIndex the index into this <code>GlyphVector</code>

  397.     *	that corresponds to the glyph from which to retrieve its 

  398.     *	justification properties

  399.     *	@return a {@link GlyphJustificationInfo} object that

  400.     *	represents the justification properties of the glyph at the

  401.     *	specified <code>glyphIndex</code> into this

  402.     *	<code>GlyphVector</code>.

  403.     *   @throws IndexOutOfBoundsException if <code>glyphIndex</code>

  404.     *           is less than 0 or greater than or equal to the number 

  405.     *           of glyphs in this <code>GlyphVector</code>

  406.     */

  407.     public abstract GlyphJustificationInfo getGlyphJustificationInfo(int glyphIndex);

  408.     // general utility methods

  409.     /**

  410.     *   Tests if the specified <code>GlyphVector</code> exactly

  411.     *	equals this <code>GlyphVector</code>.

  412.     *	@param set the specified <code>GlyphVector</code> to test

  413.     *	@return <code>true</code> if the specified

  414.     *	<code>GlyphVector</code> equals this <code>GlyphVector</code>

  415.     *	<code>false</code> otherwise.

  416.     */

  417.     public abstract boolean equals(GlyphVector set);

  418. }