/* * @(#)TextPaintable.java 2.6.0 7 June 2007 * * Copyright 2007 * 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 edu.neu.ccs.*; 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.5, the class was refactored to be consistent with * the new Paintable interface and * the new AbstractPaintable class. * *

In 2.4.0, the default anchor locator was changed from * TextAnchor.LEFT_BASELINE to * TextAnchor.LEFT_ASCENTLINE. The rationale for * this change is to allow text with the default anchor locator * and default anchor position of (0, 0) to be visible in a * panel or window whose upper left corner is also (0, 0). In * practice, a user is likely to want to set the anchor locator * and anchor position explicitly but this new default makes it * easier to do quick testing.

* *

In 2.4.0, several constructors were added that permit the * anchor locator and anchor position to be set without * specifying other parameters.

* *

In 2.4.0, this class was also updated to be consistent with * refinements to the Paintable interface.

* *

In 2.6.0, changed getOriginalCenter() to return * a point equal to the anchor position unless the caller has set * a specific default original position.

* *

In 2.6.0, changed setAnchorPostion by calling a * new method shiftAnchorPostion. This method makes * an adjustment to the internal mutator so that the net effect is * visually the same as if the shift had been applied by calling * the move method on the mutated paintable.

* *

In 2.6.0, removed final designations on methods to allow for * overrides.

* * @author Richard Rasala * @version 2.6.0 * @since 2.3 * @see MultiLineTextPaintable */ 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.

* * */ public TextPaintable() { this(null, null, null, null, null, 0, 0); } /** *

The constructor that creates a TextPaintable with * the given string * and with the defaults set as described in the default constructor.

* * @param string the string to display * @see #TextPaintable() */ public TextPaintable(String string) { this(string, null, null, null, null, 0, 0); } /** *

The constructor that creates a TextPaintable with * the given string and anchor position * and with the defaults set as described in the default constructor.

* * @param string the string to display * @param anchorX the anchor x-coordinate * @param anchorY the anchor y-coordinate * @see #TextPaintable() */ public TextPaintable(String string, float anchorX, float anchorY) { this(string, null, null, null, null, anchorX, anchorY); } /** *

The constructor that creates a TextPaintable with * the given string, anchor locator, and anchor position * and with the defaults set as described in the default constructor.

* * @param string the string to display * @param locator the locator for the anchor position * @param anchorX the anchor x-coordinate * @param anchorY the anchor y-coordinate * @see #TextPaintable() */ public TextPaintable( String string, TextAnchor.Locator locator, float anchorX, float anchorY) { this(string, null, null, null, locator, anchorX, anchorY); } /** *

The constructor that creates a TextPaintable with * the given string and font * and with the defaults set as described in the default constructor.

* * @param string the string to display * @param font the font to use to display the string * @see #TextPaintable() */ 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 anchor position * and with the defaults set as described in the default constructor.

* * @param string the string to display * @param font the font to use to display the string * @param anchorX the anchor x-coordinate * @param anchorY the anchor y-coordinate * @see #TextPaintable() */ public TextPaintable(String string, Font font, float anchorX, float anchorY) { this(string, font, null, null, null, anchorX, anchorY); } /** *

The constructor that creates a TextPaintable with * the given string, font, anchor locator, and anchor position * and with the defaults set as described in the default constructor.

* * @param string the string to display * @param font the font to use to display the string * @param locator the locator for the anchor position * @param anchorX the anchor x-coordinate * @param anchorY the anchor y-coordinate * @see #TextPaintable() */ public TextPaintable( String string, Font font, TextAnchor.Locator locator, float anchorX, float anchorY) { this(string, font, null, null, locator, anchorX, anchorY); } /** *

The constructor that creates a TextPaintable with * the given string, font, and fill paint * and with the defaults set as described in the default constructor.

* * @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 #TextPaintable() */ 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 anchor position * and with the defaults set as described in the default constructor.

* * @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 anchorX the anchor x-coordinate * @param anchorY the anchor y-coordinate * @see #TextPaintable() */ public TextPaintable( String string, Font font, Paint fillpaint, float anchorX, float anchorY) { this(string, font, fillpaint, null, null, anchorX, anchorY); } /** *

The constructor that creates a TextPaintable with * the given string, font, fill paint, anchor locator, and anchor position * and with the defaults set as described in the default constructor.

* * @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 locator the locator for the anchor position * @param anchorX the anchor x-coordinate * @param anchorY the anchor y-coordinate * @see #TextPaintable() */ public TextPaintable( String string, Font font, Paint fillpaint, TextAnchor.Locator locator, float anchorX, float anchorY) { this(string, font, fillpaint, null, locator, anchorX, anchorY); } /** *

The constructor that creates a TextPaintable with * the given string, font, fill paint, and bounds strategy * and with the defaults set as described in the default constructor.

* * @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 #TextPaintable() */ 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 * position * and with the defaults set as described in the default constructor.

* * @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 anchorX the anchor x-coordinate * @param anchorY the anchor y-coordinate * @see #TextPaintable() */ public TextPaintable( String string, Font font, Paint fillpaint, TextBounds.Strategy strategy, float anchorX, float anchorY) { this(string, font, fillpaint, strategy, null, anchorX, anchorY); } /** *

The constructor that creates a TextPaintable with * the given string, font, fill paint, bounds strategy, and anchor * locator * and with the defaults set as described in the default constructor.

* * @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 #TextPaintable() */ 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 as in the default constructor:

* * * * @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 #TextPaintable() */ 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 using information * from this object but without the use of the mutator transform.

* *

Does nothing if the encapsulated text string has zero length * or the graphics context is null.

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

Returns the actual bounds of the original paintable or * null if the paintable is effectively empty.

*/ public XRect getActualBounds2D() { if (string.length() == 0) return null; return strategy.getBounds2D(this); } /** *

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

* *

If the user has set a default original position then that * is returned. Otherwise, we define the original center to be * the anchor position. This will usually not be the geometric * center.

* * @return a copy of the center of the original paint region */ public XPoint2D getOriginalCenter() { XPoint2D center = getDefaultOriginalCenter(); if (center != null) return center; return new XPoint2D(anchorX, anchorY); } /** *

Tests if a point specified by coordinates is inside the * original paintable without mutation.

* * @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 * original paintable */ public boolean originalContains(double x, double y) { if (string.length() == 0) return false; if (!possiblyContains(x, y)) return false; return getOutline().contains(x, y); } /** *

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 original * 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 */ public XRect getStringBounds() { if (string.length() == 0) return new XRect(anchorX, anchorY, 0, 0); return locator.getBounds2D(string, font, anchorX, anchorY); } /** *

Returns a copy of the 2-dimensional bounds of the original * 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 */ public XRect getTightBounds() { if (string.length() == 0) return new XRect(anchorX, anchorY, 0, 0); // find absolute bounds XRect area = new XRect(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 XRect(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 */ public XRect getLooseBounds() { XRect area = getStringBounds(); return area.createUnionRect(getTightBounds()); } /** *

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())); } /** *

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

* *

Fires property change: SET_ANCHOR_LOCATOR.

* * @param locator the locator for the anchor position */ public void setAnchorLocator(TextAnchor.Locator locator) { if (locator == null) locator = TextAnchor.LEFT_ASCENTLINE; 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 */ public 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 */ public void setAnchorPosition(float anchorX, float anchorY) { float dx = anchorX - this.anchorX; float dy = anchorY - this.anchorY; shiftAnchorPosition(dx, dy); } /** *

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 */ public void setAnchorPosition(float[] position) { if ((position == null) || (position.length != 2)) return; setAnchorPosition(position[0], position[1]); } /** *

Shift the anchor position by the given dx and dy.

* *

Fires property change: SET_ANCHOR_POSITION.

* * @param dx the shift in the anchor x position * @param dy the shift in the anchor y position */ public void shiftAnchorPosition(float dx, float dy) { if ((dx == 0) && (dy == 0)) return; anchorX += dx; anchorY += dy; addPreMutation (TransformFactory.translate(-dx, -dy)); addPostMutation(TransformFactory.translate( dx, dy)); firePropertyChange(SET_ANCHOR_POSITION, null, null); } /** * Returns a copy of the anchor position for this TextPaintable * as an array float[2]. * * @return the anchor position */ public 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 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 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 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 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 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 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 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 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 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); } }