/* * @(#)TextPaintable.java 1.0 24 October 2004 * * Copyright 2004 * College of Computer and Information Science * Northeastern University * Boston, MA 02115 * * The Java Power Tools software may be used for educational * purposes as long as this copyright notice is retained intact * at the top of all source files. * * To discuss possible commercial use of this software, * contact Richard Rasala at Northeastern University, * College of Computer and Information Science, * 617-373-2462 or rasala@ccs.neu.edu. * * The Java Power Tools software has been designed and built * in collaboration with Viera Proulx and Jeff Raab. * * Should this software be modified, the words "Modified from * Original" must be included as a comment below this notice. * * All publication rights are retained. This software or its * documentation may not be published in any media either * in whole or in part without explicit permission. * * This software was created with support from Northeastern * University and from NSF grant DUE-9950829. */ package edu.neu.ccs.gui; import java.awt.*; import java.awt.geom.*; import javax.swing.*; import java.awt.font.*; /** *

A TextPaintable creates a Paintable * using a string, a font, and other related data.

* *

In 2.3.2, the method getBounds2D was modified to use the * default Bounds2D rectangle if that rectangle is non-null * before making any other tests or computations.

* * @author Richard Rasala * @version 2.3.2 * @since 2.3 */ public class TextPaintable extends AbstractPaintable { /** Bound property name for set string. */ public static final String SET_STRING = "set.string"; /** Bound property name for set font. */ public static final String SET_FONT = "set.font"; /** Bound property name for set fill paint. */ public static final String SET_FILL_PAINT = "set.fill.paint"; /** Bound property name for set anchor locator. */ public static final String SET_ANCHOR_LOCATOR = "set.anchor.locator"; /** Bound property name for set anchor position. */ public static final String SET_ANCHOR_POSITION = "set.anchor.position"; /** Bound property name for set bounds strategy. */ public static final String SET_BOUNDS_STRATEGY = "set.bounds.strategy"; /** * The standard font render context defined using the identity * transform, anti-aliasing on, and fractional-metrics off. */ public static final FontRenderContext standardFRC = new FontRenderContext(null, true, false); /** The text string. */ private String string = null; /** The font. */ private Font font = null; /** The fill paint. */ private Paint fillpaint = null; /** The text bounds strategy. */ private TextBounds.Strategy strategy = null; /** The text anchor locator. */ private TextAnchor.Locator locator = null; /** The x anchor position. */ private float anchorX = 0; /** The y anchor position. */ private float anchorY = 0; /** The TextLayout for bounds computation and text rendering. */ private TextLayout textLayout = null; /** *

The constructor that creates a TextPaintable with * all defaults.

* *

The default anchor position is (0, 0) which must be changed to * a more useful value by the caller.

* * @see #setString(String) * @see #setFont(Font) * @see #setFillPaint(Paint) * @see #setBoundsStrategy(TextBounds.Strategy) * @see #setAnchorLocator(TextAnchor.Locator) * @see #setAnchorPosition(float, float) * @see #setAnchorPosition(float[]) * @see #TextPaintable(String) * @see #TextPaintable(String, Font) * @see #TextPaintable(String, Font, Paint) * @see #TextPaintable(String, Font, Paint, TextBounds.Strategy) * @see #TextPaintable(String, Font, Paint, TextBounds.Strategy, TextAnchor.Locator) * @see #TextPaintable(String, Font, Paint, TextBounds.Strategy, TextAnchor.Locator, float, float) */ public TextPaintable() { this(null, null, null, null, null, 0, 0); } /** *

The constructor that creates a TextPaintable with * the given string.

* *

The default anchor position is (0, 0) which must be changed to * a more useful value by the caller.

* * @param string the string to display * @see #setString(String) * @see #setFont(Font) * @see #setFillPaint(Paint) * @see #setBoundsStrategy(TextBounds.Strategy) * @see #setAnchorLocator(TextAnchor.Locator) * @see #setAnchorPosition(float, float) * @see #setAnchorPosition(float[]) * @see #TextPaintable() * @see #TextPaintable(String, Font) * @see #TextPaintable(String, Font, Paint) * @see #TextPaintable(String, Font, Paint, TextBounds.Strategy) * @see #TextPaintable(String, Font, Paint, TextBounds.Strategy, TextAnchor.Locator) * @see #TextPaintable(String, Font, Paint, TextBounds.Strategy, TextAnchor.Locator, float, float) */ public TextPaintable(String string) { this(string, null, null, null, null, 0, 0); } /** *

The constructor that creates a TextPaintable with * the given string and font.

* *

The default anchor position is (0, 0) which must be changed to * a more useful value by the caller.

* * @param string the string to display * @param font the font to use to display the string * @see #setString(String) * @see #setFont(Font) * @see #setFillPaint(Paint) * @see #setBoundsStrategy(TextBounds.Strategy) * @see #setAnchorLocator(TextAnchor.Locator) * @see #setAnchorPosition(float, float) * @see #setAnchorPosition(float[]) * @see #TextPaintable() * @see #TextPaintable(String) * @see #TextPaintable(String, Font, Paint) * @see #TextPaintable(String, Font, Paint, TextBounds.Strategy) * @see #TextPaintable(String, Font, Paint, TextBounds.Strategy, TextAnchor.Locator) * @see #TextPaintable(String, Font, Paint, TextBounds.Strategy, TextAnchor.Locator, float, float) */ public TextPaintable(String string, Font font) { this(string, font, null, null, null, 0, 0); } /** *

The constructor that creates a TextPaintable with * the given string, font, and fill paint.

* *

The default anchor position is (0, 0) which must be changed to * a more useful value by the caller.

* * @param string the string to display * @param font the font to use to display the string * @param fillpaint the paint to use to fill the string * @see #setString(String) * @see #setFont(Font) * @see #setFillPaint(Paint) * @see #setBoundsStrategy(TextBounds.Strategy) * @see #setAnchorLocator(TextAnchor.Locator) * @see #setAnchorPosition(float, float) * @see #setAnchorPosition(float[]) * @see #TextPaintable() * @see #TextPaintable(String) * @see #TextPaintable(String, Font) * @see #TextPaintable(String, Font, Paint, TextBounds.Strategy) * @see #TextPaintable(String, Font, Paint, TextBounds.Strategy, TextAnchor.Locator) * @see #TextPaintable(String, Font, Paint, TextBounds.Strategy, TextAnchor.Locator, float, float) */ public TextPaintable(String string, Font font, Paint fillpaint) { this(string, font, fillpaint, null, null, 0, 0); } /** *

The constructor that creates a TextPaintable with * the given string, font, fill paint, and bounds strategy.

* *

The default anchor position is (0, 0) which must be changed to * a more useful value by the caller.

* * @param string the string to display * @param font the font to use to display the string * @param fillpaint the paint to use to fill the string * @param strategy the strategy to use to compute the paintable bounds * @see #setString(String) * @see #setFont(Font) * @see #setFillPaint(Paint) * @see #setBoundsStrategy(TextBounds.Strategy) * @see #setAnchorLocator(TextAnchor.Locator) * @see #setAnchorPosition(float, float) * @see #setAnchorPosition(float[]) * @see #TextPaintable() * @see #TextPaintable(String) * @see #TextPaintable(String, Font) * @see #TextPaintable(String, Font, Paint) * @see #TextPaintable(String, Font, Paint, TextBounds.Strategy, TextAnchor.Locator) * @see #TextPaintable(String, Font, Paint, TextBounds.Strategy, TextAnchor.Locator, float, float) */ public TextPaintable( String string, Font font, Paint fillpaint, TextBounds.Strategy strategy) { this(string, font, fillpaint, strategy, null, 0, 0); } /** *

The constructor that creates a TextPaintable with * the given string, font, fill paint, bounds strategy, and anchor * locator.

* *

The default anchor position is (0, 0) which must be changed to * a more useful value by the caller.

* * @param string the string to display * @param font the font to use to display the string * @param fillpaint the paint to use to fill the string * @param strategy the strategy to use to compute the paintable bounds * @param locator the locator for the anchor position * @see #setString(String) * @see #setFont(Font) * @see #setFillPaint(Paint) * @see #setBoundsStrategy(TextBounds.Strategy) * @see #setAnchorLocator(TextAnchor.Locator) * @see #setAnchorPosition(float, float) * @see #setAnchorPosition(float[]) * @see #TextPaintable() * @see #TextPaintable(String) * @see #TextPaintable(String, Font) * @see #TextPaintable(String, Font, Paint) * @see #TextPaintable(String, Font, Paint, TextBounds.Strategy) * @see #TextPaintable(String, Font, Paint, TextBounds.Strategy, TextAnchor.Locator, float, float) */ public TextPaintable( String string, Font font, Paint fillpaint, TextBounds.Strategy strategy, TextAnchor.Locator locator) { this(string, font, fillpaint, strategy, locator, 0, 0); } /** *

The constructor that creates a TextPaintable with * the given string, font, fill paint, bounds strategy, anchor locator, * and anchor position.

* *

Parameters that are null are set to the following * defaults:

* * * * @param string the string to display * @param font the font to use to display the string * @param fillpaint the paint to use to fill the string * @param strategy the strategy to use to compute the paintable bounds * @param locator the locator for the anchor position * @param anchorX the anchor x-coordinate * @param anchorY the anchor y-coordinate * @see #setString(String) * @see #setFont(Font) * @see #setFillPaint(Paint) * @see #setBoundsStrategy(TextBounds.Strategy) * @see #setAnchorLocator(TextAnchor.Locator) * @see #setAnchorPosition(float, float) * @see #setAnchorPosition(float[]) * @see #TextPaintable() * @see #TextPaintable(String) * @see #TextPaintable(String, Font) * @see #TextPaintable(String, Font, Paint) * @see #TextPaintable(String, Font, Paint, TextBounds.Strategy) * @see #TextPaintable(String, Font, Paint, TextBounds.Strategy, TextAnchor.Locator) */ public TextPaintable( String string, Font font, Paint fillpaint, TextBounds.Strategy strategy, TextAnchor.Locator locator, float anchorX, float anchorY) { // temporarily set internal string to a valid value // to avoid null pointer exception in setFont this.string = ""; setFont(font); setString(string); setFillPaint(fillpaint); setBoundsStrategy(strategy); setAnchorLocator(locator); setAnchorPosition(anchorX, anchorY); resetTextLayout(); } /** *

Paints onto a Graphics context g using information * from this object.

* *

Does nothing if the encapsulated text string has zero length.

* * @param g the graphics context on which to paint */ public final void paint(Graphics g) { if ((string.length() == 0) || (g == null) || !isVisible()) return; Graphics2D h = getPreparedGraphics2D(g); h.setFont(font); h.setPaint(fillpaint); textLayout.draw(h, getLeftX(), getBaseLineY()); } /** *

Returns the internal TextLayout that encapsulates * the text string and the font.

* *

If the encapsulated text string has zero length, then returns * null.

* * @return the internal TextLayout object */ public TextLayout getTextLayout() { return textLayout; } /** *

Returns a copy of the 2-dimensional bounds of the paint region * as computed using the getStringBounds method of the * Font class together with the anchor locator.

* *

In the vertical direction, these bounds extend from the ascent * line to the leading line. Thus, the height of these bounds do * not depend on the particular string being rendered.

* *

In the horizontal direction, these bounds extend from the left * edge of string being painted and will include allowances for both * leading and trailing white space. Unfortunately, however, if the * string has no leading and trailing whitespace, it is possible for * pixels to be painted outside of these bounds due to serifs or to * the slant of an italic font.

* *

If the encapsulated text string has zero length, then this method * returns a rectangle at the anchor position of zero width and height.

* * @return a copy of the 2-dimensional bounds of the paint region * @see #getTightBounds() * @see #getLooseBounds() * @see #getBounds2D() */ public final Rectangle2D getStringBounds() { if (string.length() == 0) return new Rectangle2D.Double(anchorX, anchorY, 0, 0); return locator.getBounds2D(string, font, anchorX, anchorY); } /** *

Returns a copy of the 2-dimensional bounds of the paint region * as computed using the getBounds method of the * TextLayout class together with the anchor locator.

* *

These bounds return a tight rectangle that includes all * pixel positions that may be modified when the string is painted. * The only exception to this rule is that anti-aliasing may cause * some pixels adjacent to this rectangle to be rendered also. There * is no Java code that is capable of testing for this effect.

* *

The height of these bounds will vary from string to string * depending on the height of the ascenders and descenders of the * particular characters in the particular string.

* *

These bounds do not include leading and trailing whitespace.

* *

Be aware that if you have set the logical left edge of the paint * area for a string to some value x then it is still possible * for pixels to the left of x to be modified during rendering * of the string due to the presence of serifs. The bounds returned * by this method will include adjustments for such effects and will * be as accurate as possible.

* *

If the encapsulated text string has zero length, then this method * returns a rectangle at the anchor position of zero width and height.

* * @return a copy of the tight bounds of the paint region * @see #getStringBounds() * @see #getLooseBounds() * @see #getBounds2D() */ public final Rectangle2D getTightBounds() { if (string.length() == 0) return new Rectangle2D.Double(anchorX, anchorY, 0, 0); // find absolute bounds Rectangle2D area = textLayout.getBounds(); float x = (float) area.getX(); float y = (float) area.getY(); float w = (float) area.getWidth(); float h = (float) area.getHeight(); // check for zero width or height if ((w <= 0) || (h <= 0)) return new Rectangle2D.Double(anchorX, anchorY, 0, 0); // get offset for string position float x0 = getLeftX(); float y0 = getBaseLineY(); // offset area area.setRect(x + x0, y + y0, w, h); return area; } /** *

Returns the smallest rectangle that contains the pair of rectangles * getStringBounds() and getTightBounds().

* *

These bounds return a loose rectangle that includes all * pixel positions that may be modified when the string is painted plus * allowances for additional horizontal and vertical white space.

* *

If the encapsulated text string has zero length, then this method * returns a rectangle at the anchor position of zero width and height.

* * @return a copy of the tight bounds of the paint region * @see #getStringBounds() * @see #getTightBounds() * @see #getBounds2D() */ public final Rectangle2D getLooseBounds() { Rectangle2D area = getStringBounds(); area.add(getTightBounds()); return area; } /** *

Returns the bounds of the paintable based on the default settings or on * more detailed computations.

* *

If the value of getDefaultBounds2D is non-null, * then this value is returned.

* *

Otherwise, if the encapsulated text string has zero length, then returns * a rectangle of zero width and height located at the anchor location.

* *

Otherwise, returns a copy of the 2-dimensional bounds of the paint * region affected by the paint method according to the * current bounds strategy.

* * @return a copy of the 2-dimensional bounds of the paint region * @see #getStringBounds() * @see #getTightBounds() * @see #getLooseBounds() */ public final Rectangle2D getBounds2D() { // get the default bounds Rectangle2D bounds = getDefaultBounds2D(); if (bounds != null) return bounds; // string has length 0 if (string.length() == 0) return new Rectangle2D.Double(anchorX, anchorY, 0, 0); // compute bounds return strategy.getBounds2D(this); } /** *

Returns a copy of the center of the paint region affected * by the paint method.

* *

The center is computed as the center of the base line.

* *

This method uses the anchor locator.

* * @return a copy of the center of the paint region */ public final Point2D getCenter() { if (string.length() == 0) return new Point2D.Double(anchorX, anchorY); return locator.getCenter(string, font, anchorX, anchorY); } /** *

Returns the Shape that represents the outline of * the rendered text string in its font at its location.

* *

Experimental tests show that the Shape returned * by this method is not 100% accurate. This is due to problems * in the getOutline method of the Java class * TextLayout.

* *

If the encapsulated text string has zero length, then returns * an empty Shape.

* * @return the Shape object */ public Shape getOutline() { return (string.length() == 0) ? new GeneralPath() : textLayout.getOutline (TransformFactory.translate(getLeftX(), getBaseLineY())); } /** *

Tests if a point specified by coordinates is inside the paintable.

* *

This method returns false if one or more of the following * conditions occurs:

* * * * @param x the x-coordinate of the point * @param y the y-coordinate of the point * @return whether or not a specified point is inside the paintable */ public boolean contains(double x, double y) { if (!possiblyContains(x, y)) return false; return getOutline().contains(x, y); } /** *

Sets the string for this TextPaintable.

* *

If the given string is null, it is set to * the zero length string.

* *

Does nothing if the string is equal to the current string.

* *

Fires property change: SET_STRING.

* * @param string the string to display * @see #getString() */ public final void setString(String string) { if (string == null) string = ""; if (string.equals(this.string)) return; this.string = string; resetTextLayout(); firePropertyChange(SET_STRING, null, null); } /** * Returns the string for this TextPaintable. * * @return the string to display * @see #setString(String) */ public final String getString() { return string; } /** *

Sets the font for this TextPaintable.

* *

If the given font is null then it is set to * getDefaultFont().

* *

Does nothing if the font is equal to the current font.

* *

Fires property change: SET_FONT.

* * @param font the font to use to display the string * @see #getFont() */ public final void setFont(Font font) { if (font == null) font = getDefaultFont(); if (font.equals(this.font)) return; removeAndAddForwardingListener(this.font, font); this.font = font; resetTextLayout(); firePropertyChange(SET_FONT, null, null); } /** * Returns the font for this TextPaintable. * * @return the font to use to display the string * @see #setFont(Font) */ public final Font getFont() { return font; } /** *

Sets the fill paint for this TextPaintable.

* *

If the given paint is null, it is set to * Color.black.

* *

Fires property change: SET_FILL_PAINT.

* * @param fillpaint the paint to use to fill the string * @see #getFillPaint() */ public final void setFillPaint(Paint fillpaint) { if (fillpaint == null) fillpaint = Color.black; if (fillpaint.equals(this.fillpaint)) return; removeAndAddForwardingListener(this.fillpaint, fillpaint); this.fillpaint = fillpaint; firePropertyChange(SET_FILL_PAINT, null, null); } /** * Returns the fill paint for this TextPaintable. * * @return the paint to use to fill the string * @see #setFillPaint(Paint) */ public final Paint getFillPaint() { return fillpaint; } /** *

Sets the bounds strategy for this TextPaintable.

* *

If the given strategy is null, it is set to * TextBounds.LOOSE.

* *

Fires property change: SET_BOUNDS_STRATEGY.

* * @param strategy the strategy to use to compute the paintable bounds * @see #getBoundsStrategy() */ public final void setBoundsStrategy(TextBounds.Strategy strategy) { if (strategy == null) strategy = TextBounds.LOOSE; if (strategy.equals(this.strategy)) return; this.strategy = strategy; firePropertyChange(SET_BOUNDS_STRATEGY, null, null); } /** * Returns the bounds strategy for this TextPaintable. * * @return the strategy to use to compute the paintable bounds * @see #setFillPaint(Paint) */ public final TextBounds.Strategy getBoundsStrategy() { return strategy; } /** *

Sets the TextAnchor.Locator for this * TextPaintable.

* *

The following constants are provided in the class * TextAnchor as possible options for the * TextAnchor.Locator parameter:

* * * *

If the given locator is null, it is set to * TextAnchor.LEFT_BASELINE.

* *

Fires property change: SET_ANCHOR_LOCATOR.

* * @param locator the locator for the anchor position * @see #getAnchorLocator() */ public final void setAnchorLocator(TextAnchor.Locator locator) { if (locator == null) locator = TextAnchor.LEFT_BASELINE; if (locator.equals(this.locator)) return; this.locator = locator; firePropertyChange(SET_ANCHOR_LOCATOR, null, null); } /** *

Returns the TextAnchor.Locator for this * TextPaintable.

* * @return the locator for the anchor position * @see #setAnchorLocator(TextAnchor.Locator) */ public final TextAnchor.Locator getAnchorLocator() { return locator; } /** *

Sets the anchor position for this TextPaintable.

* *

Fires property change: SET_ANCHOR_POSITION.

* * @param anchorX the anchor x-coordinate * @param anchorY the anchor y-coordinate * @see #setAnchorPosition(float[]) * @see #getAnchorPosition() */ public final void setAnchorPosition(float anchorX, float anchorY) { if ((anchorX == this.anchorX) && (anchorY == this.anchorY)) return; this.anchorX = anchorX; this.anchorY = anchorY; firePropertyChange(SET_ANCHOR_POSITION, null, null); } /** *

Sets the anchor position for this TextPaintable * using an array float[2].

* *

A null parameter is ignored.

* *

Fires property change: SET_ANCHOR_POSITION.

* * @param position the anchor position * @see #setAnchorPosition(float, float) * @see #getAnchorPosition() */ public final void setAnchorPosition(float[] position) { if ((position == null) || (position.length != 2)) return; setAnchorPosition(position[0], position[1]); } /** * Returns a copy of the anchor position for this TextPaintable * as an array float[2]. * * @return the anchor position * @see #setAnchorPosition(float, float) * @see #setAnchorPosition(float[]) */ public final float[] getAnchorPosition() { return new float[] { anchorX, anchorY }; } /** *

Returns the left x-coordinate of this TextPaintable.

* *

This method uses the anchor locator.

* * @return the left x-coordinate of this text paintable */ public final float getLeftX() { if (string.length() == 0) return anchorX; return locator.getLeftX(string, font, anchorX); } /** *

Returns the right x-coordinate of this TextPaintable.

* *

This method uses the anchor locator.

* * @return the right x-coordinate of this text paintable */ public final float getRightX() { if (string.length() == 0) return anchorX; return locator.getRightX(string, font, anchorX); } /** *

Returns the center x-coordinate of this TextPaintable.

* *

This method uses the anchor locator.

* * @return the center x-coordinate of this text paintable */ public final float getCenterX() { if (string.length() == 0) return anchorX; return locator.getCenterX(string, font, anchorX); } /** *

Returns the base line y-coordinate of this TextPaintable.

* *

This method uses the anchor locator.

* * @return the base line y-coordinate of this text paintable */ public final float getBaseLineY() { if (string.length() == 0) return anchorY; return locator.getBaseLineY(string, font, anchorY); } /** *

Returns the ascent line y-coordinate of this TextPaintable.

* *

This method uses the anchor locator.

* * @return the ascent line y-coordinate of this text paintable */ public final float getAscentLineY() { if (string.length() == 0) return anchorY; return locator.getAscentLineY(string, font, anchorY); } /** *

Returns the descent line y-coordinate of this TextPaintable.

* *

This method uses the anchor locator.

* * @return the descent line y-coordinate of this text paintable */ public final float getDescentLineY() { if (string.length() == 0) return anchorY; return locator.getDescentLineY(string, font, anchorY); } /** *

Returns the leading line y-coordinate of this TextPaintable.

* *

This methods uses the anchor locator.

* * @return the leading line y-coordinate of this text paintable */ public final float getLeadingLineY() { if (string.length() == 0) return anchorY; return locator.getLeadingLineY(string, font, anchorY); } /** *

Returns the width of the area that will be occupied by this * TextPaintable.

* *

This method uses the method getBounds2D. * * @return the width of this text paintable */ public final float getWidth() { return (float) getBounds2D().getWidth(); } /** *

Returns the height of the area that will be occupied by this * TextPaintable.

* *

This method uses the method getBounds2D. * * @return the height of this text paintable */ public final float getHeight() { return (float) getBounds2D().getHeight(); } /** *

Returns the default font for a JLabel in the * current UI settings. This font is used in constructing a * TextPaintable if the user does not specify a * font.

* * @return the current JLabel default font */ public static Font getDefaultFont() { JLabel label = new JLabel(); return label.getFont(); } /** * Resets the text layout on string or font change. */ private void resetTextLayout() { textLayout = (string.length() == 0) ? null : new TextLayout(string, font, standardFRC); } }