bb.gui
Class GraphicsLabel

java.lang.Object
  extended by bb.gui.GraphicsLabel

public class GraphicsLabel
extends Object

Represents a text label in some graphical context (e.g. the label for a grid line).

This text label always has some associated "anchor point": a Point2D instance which defines a location in space. The text is located somewhere around the anchor point (e.g. below it, above it, etc; see the various factory methods of this class for some of the common possibilities).

In addition to the "anchor point", there is also always an associated "reference point", which is the term used by FontMetrics for the point which marks the start of the text's baseline.

Warning: the dimension's of each instance are only valid for the particular Graphics2D context it was constructed with.

Like typical Java GUI code, this class is not multithread safe: it expects to only be called by EventQueue's dispatch thread. This threading limitation is checked in every public method.

Author:
Brent Boyer

Nested Class Summary
static class GraphicsLabel.UnitTest
          See the Overview page of the project's javadocs for a general description of this unit test class.
 
Field Summary
private  Point2D anchorPoint
           
private  double ascent
           
private  double descent
           
private  double leading
           
private  Point2D referencePoint
           
private  String text
           
private  double width
           
 
Constructor Summary
GraphicsLabel(String text, Point2D anchorPoint, Point2D referencePoint, double ascent, double descent, double leading, double width)
          Constructor.
 
Method Summary
 Point2D getAnchorPoint()
          Returns the "anchor point", which is an arbitrary Point2D which is associated with this instance.
 double getAscent()
          Returns the ascent (as defined by LineMetrics) of this instance's text.
 double getBottom()
          Returns the y-coordinate of the bottom edge of the rectangle which bounds this instance's text.
 Rectangle2D.Double getBounds()
          Returns the rectangle which bounds this instance's text.
 double getDescent()
          Returns the descent (as defined by LineMetrics) of this instance's text.
 double getExtentAboveAnchorPoint()
          Returns the maximum distance which this instance's text vertically extends above the anchor point.
 double getExtentBelowAnchorPoint()
          Returns the maximum distance which this instance's text vertically extends below the anchor point.
 double getExtentToLeftOfAnchorPoint()
          Returns the maximum distance which this instance's text horizontally extends to the left of the anchor point.
 double getExtentToRightOfAnchorPoint()
          Returns the maximum distance which this instance's text horizontally extends to the right of the anchor point.
 double getHeight()
          Returns the height of this instance's text.
static double getHeight(String text, Graphics2D g2)
          Returns the height of the rectangle which bounds text.
 double getLeading()
          Returns the leading (as defined by LineMetrics) of this instance's text.
 double getLeft()
          Returns the x-coordinate of the left edge of the rectangle which bounds this instance's text.
 Point2D getReferencePoint()
          Is the term used by FontMetrics for the point which marks the start of text's baseline.
 double getRight()
          Returns the x-coordinate of the right edge of the rectangle which bounds this instance's text.
 String getText()
          Returns the text for this instance.
 double getTop()
          Returns the y-coordinate of the top edge of the rectangle which bounds this instance's text.
 double getWidth()
          Returns the width of this instance's text.
static double getWidth(String text, Graphics2D g2)
          Returns the width of the rectangle which bounds text.
private static GraphicsLabel make(String text, Point2D centerPoint, Point2D anchorPoint, Graphics2D g2)
          Fundamental factory method, called by many of the others.
static GraphicsLabel makeAbove(String text, Point2D anchorPoint, double margin, Graphics2D g2)
          Convenience factory method which returns a new GraphicsLabel instance which is above anchorPoint.
static GraphicsLabel makeBelow(String text, Point2D anchorPoint, double margin, Graphics2D g2)
          Convenience factory method which returns a new GraphicsLabel instance which is below anchorPoint.
static GraphicsLabel makeCenter(String text, Point2D anchorPoint, Graphics2D g2)
          Convenience factory method which returns a new GraphicsLabel instance which is centered on anchorPoint.
static GraphicsLabel makeLeft(String text, Point2D anchorPoint, double margin, Graphics2D g2)
          Convenience factory method which returns a new GraphicsLabel instance to the left of anchorPoint.
static GraphicsLabel makeOffsetCenter(String text, Point2D anchorPoint, double dx, double dy, Graphics2D g2)
          Convenience factory method which returns a new GraphicsLabel instance whose center is offset from anchorPoint.
static GraphicsLabel makeOffsetCorner(String text, Point2D anchorPoint, double dx, double dy, Graphics2D g2)
          Convenience factory method which returns a new GraphicsLabel instance whose corner is offset from anchorPoint.
static GraphicsLabel makeRight(String text, GraphicsLabel labelExisting, double margin, Graphics2D g2)
          Convenience factory method which returns a new GraphicsLabel instance to the right of labelExisting.
static GraphicsLabel makeRight(String text, Point2D anchorPoint, double margin, Graphics2D g2)
          Convenience factory method which returns a new GraphicsLabel instance to the right of anchorPoint.
 void paint(Graphics2D g2)
          Paints this instance's text onto g2.
 void paintBaseline(Graphics2D g2)
          Paints the baseline for this instance's text onto g2.
 void paintBounds(Graphics2D g2)
          Paints the rectangle which bounds this instance's text onto g2.
 GraphicsLabel shift(double dx, double dy)
          Returns shift(getText(), dx, dy).
 GraphicsLabel shift(String text, double dx, double dy)
          Returns a new GraphicsLabel which is the same as this instance except that the text field is changed to the text param and the referencePoint field is shifted by the deltas.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

text

private final String text

anchorPoint

private final Point2D anchorPoint

referencePoint

private final Point2D referencePoint

ascent

private final double ascent

descent

private final double descent

leading

private final double leading

width

private final double width
Constructor Detail

GraphicsLabel

public GraphicsLabel(String text,
                     Point2D anchorPoint,
                     Point2D referencePoint,
                     double ascent,
                     double descent,
                     double leading,
                     double width)
              throws IllegalArgumentException,
                     IllegalStateException
Constructor.

Throws:
IllegalArgumentException - if text == null; anchorPoint == null; referencePoint == null; any double arg is abnormal or negative
IllegalStateException - if calling thread is not EventQueue's dispatch thread
Method Detail

getWidth

public static double getWidth(String text,
                              Graphics2D g2)
                       throws IllegalArgumentException,
                              IllegalStateException
Returns the width of the rectangle which bounds text.

Throws:
IllegalArgumentException - if text == null; g2 == null
IllegalStateException - if calling thread is not EventQueue's dispatch thread

getHeight

public static double getHeight(String text,
                               Graphics2D g2)
                        throws IllegalArgumentException,
                               IllegalStateException
Returns the height of the rectangle which bounds text.

Throws:
IllegalArgumentException - if text == null; g2 == null
IllegalStateException - if calling thread is not EventQueue's dispatch thread

makeCenter

public static GraphicsLabel makeCenter(String text,
                                       Point2D anchorPoint,
                                       Graphics2D g2)
                                throws IllegalArgumentException,
                                       IllegalStateException
Convenience factory method which returns a new GraphicsLabel instance which is centered on anchorPoint. Specificly, the rectangle which bounds text has its center at anchorPoint.

Throws:
IllegalArgumentException - if text == null; anchorPoint == null; g2 == null
IllegalStateException - if calling thread is not EventQueue's dispatch thread

makeOffsetCenter

public static GraphicsLabel makeOffsetCenter(String text,
                                             Point2D anchorPoint,
                                             double dx,
                                             double dy,
                                             Graphics2D g2)
                                      throws IllegalArgumentException,
                                             IllegalStateException
Convenience factory method which returns a new GraphicsLabel instance whose center is offset from anchorPoint. Specificly, the rectangle which bounds text has its center located at a vector displacement of (dx, dy) from anchorPoint.

Throws:
IllegalArgumentException - if text == null; anchorPoint == null; dx or dy are not normal; g2 == null
IllegalStateException - if calling thread is not EventQueue's dispatch thread

makeOffsetCorner

public static GraphicsLabel makeOffsetCorner(String text,
                                             Point2D anchorPoint,
                                             double dx,
                                             double dy,
                                             Graphics2D g2)
                                      throws IllegalArgumentException,
                                             IllegalStateException
Convenience factory method which returns a new GraphicsLabel instance whose corner is offset from anchorPoint. Specificly, the rectangle which bounds text has its relevant corner located at a vector displacement of (dx, dy) from anchorPoint. The corner used is the top left if dx >= 0 and dy >= 0; the bottom left if dx >= 0 and dy < 0; the top right if dx < 0 and dy >= 0; the bottom right if dx < 0 and dy < 0.

Throws:
IllegalArgumentException - if text == null; anchorPoint == null; dx or dy are not normal; g2 == null
IllegalStateException - if calling thread is not EventQueue's dispatch thread

makeLeft

public static GraphicsLabel makeLeft(String text,
                                     Point2D anchorPoint,
                                     double margin,
                                     Graphics2D g2)
                              throws IllegalArgumentException,
                                     IllegalStateException
Convenience factory method which returns a new GraphicsLabel instance to the left of anchorPoint. Specificly, the rectangle which bounds text has its right edge a distance of margin from anchorPoint, and its top and bottom edges are vertically equidistant from anchorPoint.

Throws:
IllegalArgumentException - if text == null; anchorPoint == null; margin is abnormal or negative; g2 == null
IllegalStateException - if calling thread is not EventQueue's dispatch thread

makeRight

public static GraphicsLabel makeRight(String text,
                                      Point2D anchorPoint,
                                      double margin,
                                      Graphics2D g2)
                               throws IllegalArgumentException,
                                      IllegalStateException
Convenience factory method which returns a new GraphicsLabel instance to the right of anchorPoint. Specificly, the rectangle which bounds text has its left edge a distance of margin from anchorPoint, and its top and bottom edges are vertically equidistant from anchorPoint.

Throws:
IllegalArgumentException - if text == null; anchorPoint == null; margin is abnormal or negative; g2 == null
IllegalStateException - if calling thread is not EventQueue's dispatch thread

makeRight

public static GraphicsLabel makeRight(String text,
                                      GraphicsLabel labelExisting,
                                      double margin,
                                      Graphics2D g2)
                               throws IllegalArgumentException,
                                      IllegalStateException
Convenience factory method which returns a new GraphicsLabel instance to the right of labelExisting. Specificly, both instances have the same baseline, and the left edge of this new instance is a distance of margin from the right edge of labelExisting.

Note: the anchorPoint of the result is labelExisting's anchorPoint.

Throws:
IllegalArgumentException - if text == null; labelExisting == null; margin is abnormal or negative; g2 == null
IllegalStateException - if calling thread is not EventQueue's dispatch thread

makeAbove

public static GraphicsLabel makeAbove(String text,
                                      Point2D anchorPoint,
                                      double margin,
                                      Graphics2D g2)
                               throws IllegalArgumentException,
                                      IllegalStateException
Convenience factory method which returns a new GraphicsLabel instance which is above anchorPoint. Specificly, the rectangle which bounds text has its bottom edge a distance of margin from anchorPoint, and its left and right edges are horizontally equidistant from anchorPoint.

Throws:
IllegalArgumentException - if text == null; anchorPoint == null; margin is abnormal or negative; g2 == null
IllegalStateException - if calling thread is not EventQueue's dispatch thread

makeBelow

public static GraphicsLabel makeBelow(String text,
                                      Point2D anchorPoint,
                                      double margin,
                                      Graphics2D g2)
                               throws IllegalArgumentException,
                                      IllegalStateException
Convenience factory method which returns a new GraphicsLabel instance which is below anchorPoint. Specificly, the rectangle which bounds text has its top edge a distance of margin from anchorPoint, and its left and right edges are horizontally equidistant from anchorPoint.

Throws:
IllegalArgumentException - if text == null; anchorPoint == null; margin is abnormal or negative; g2 == null
IllegalStateException - if calling thread is not EventQueue's dispatch thread

make

private static GraphicsLabel make(String text,
                                  Point2D centerPoint,
                                  Point2D anchorPoint,
                                  Graphics2D g2)
                           throws IllegalArgumentException,
                                  IllegalStateException
Fundamental factory method, called by many of the others. Returns a new GraphicsLabel instance which is centered on centerPoint. Specificly, the rectangle which bounds text has its center at centerPoint. The location of anchorPoint is arbitrary, but it is the Point2D used as the anchorPoint of the result.

Throws:
IllegalArgumentException - if text == null; centerPoint == null; anchorPoint == null; g2 == null
IllegalStateException - if calling thread is not EventQueue's dispatch thread

shift

public GraphicsLabel shift(double dx,
                           double dy)
                    throws IllegalArgumentException,
                           IllegalStateException
Returns shift(getText(), dx, dy).

Throws:
IllegalStateException - if calling thread is not EventQueue's dispatch thread
IllegalArgumentException

shift

public GraphicsLabel shift(String text,
                           double dx,
                           double dy)
                    throws IllegalArgumentException,
                           IllegalStateException
Returns a new GraphicsLabel which is the same as this instance except that the text field is changed to the text param and the referencePoint field is shifted by the deltas. Specifically, the new x is the old x + dx, and the new y is the old y + dy.

Throws:
IllegalArgumentException - if text == null; dx or dy are not normal
IllegalStateException - if calling thread is not EventQueue's dispatch thread

getText

public String getText()
               throws IllegalStateException
Returns the text for this instance. Result is never null (but may be anything else, including an empty string or all whitespace).

Throws:
IllegalStateException - if calling thread is not EventQueue's dispatch thread

getAnchorPoint

public Point2D getAnchorPoint()
                       throws IllegalStateException
Returns the "anchor point", which is an arbitrary Point2D which is associated with this instance. Result is never null.

Throws:
IllegalStateException - if calling thread is not EventQueue's dispatch thread

getReferencePoint

public Point2D getReferencePoint()
                          throws IllegalStateException
Is the term used by FontMetrics for the point which marks the start of text's baseline. Result is never null.

Throws:
IllegalStateException - if calling thread is not EventQueue's dispatch thread

getAscent

public double getAscent()
                 throws IllegalStateException
Returns the ascent (as defined by LineMetrics) of this instance's text. Result is >= 0.

Throws:
IllegalStateException - if calling thread is not EventQueue's dispatch thread

getDescent

public double getDescent()
                  throws IllegalStateException
Returns the descent (as defined by LineMetrics) of this instance's text. Result is >= 0.

Throws:
IllegalStateException - if calling thread is not EventQueue's dispatch thread

getLeading

public double getLeading()
                  throws IllegalStateException
Returns the leading (as defined by LineMetrics) of this instance's text. Result is >= 0.

Throws:
IllegalStateException - if calling thread is not EventQueue's dispatch thread

getWidth

public double getWidth()
                throws IllegalStateException
Returns the width of this instance's text. Result is >= 0.

Throws:
IllegalStateException - if calling thread is not EventQueue's dispatch thread

getHeight

public double getHeight()
                 throws IllegalStateException
Returns the height of this instance's text. Here, the height is strictly the height of this label considered by itself, and is always calculated as the sum of the ascent + descent (i.e. the leading, that is the space between lines, is not considered). This differs from the height returned by, say, FontMetrics. Result is >= 0.

Throws:
IllegalStateException - if calling thread is not EventQueue's dispatch thread

getLeft

public double getLeft()
               throws IllegalStateException
Returns the x-coordinate of the left edge of the rectangle which bounds this instance's text.

Throws:
IllegalStateException - if calling thread is not EventQueue's dispatch thread

getRight

public double getRight()
                throws IllegalStateException
Returns the x-coordinate of the right edge of the rectangle which bounds this instance's text.

Throws:
IllegalStateException - if calling thread is not EventQueue's dispatch thread

getTop

public double getTop()
              throws IllegalStateException
Returns the y-coordinate of the top edge of the rectangle which bounds this instance's text.

Throws:
IllegalStateException - if calling thread is not EventQueue's dispatch thread

getBottom

public double getBottom()
                 throws IllegalStateException
Returns the y-coordinate of the bottom edge of the rectangle which bounds this instance's text.

Throws:
IllegalStateException - if calling thread is not EventQueue's dispatch thread

getBounds

public Rectangle2D.Double getBounds()
                             throws IllegalStateException
Returns the rectangle which bounds this instance's text.

Throws:
IllegalStateException - if calling thread is not EventQueue's dispatch thread

getExtentAboveAnchorPoint

public double getExtentAboveAnchorPoint()
                                 throws IllegalStateException
Returns the maximum distance which this instance's text vertically extends above the anchor point. By "above", it is meant as the user sees the screen (recall that the screen y-coordinate system, however, runs from top to bottom). Result will be negative if this instance's text never rises above the anchor point.

Throws:
IllegalStateException - if calling thread is not EventQueue's dispatch thread

getExtentBelowAnchorPoint

public double getExtentBelowAnchorPoint()
                                 throws IllegalStateException
Returns the maximum distance which this instance's text vertically extends below the anchor point. By "below", it is meant as the user sees the screen (recall that the screen y-coordinate system, however, runs from top to bottom). Result will be negative if this instance's text never falls below the anchor point.

Throws:
IllegalStateException - if calling thread is not EventQueue's dispatch thread

getExtentToLeftOfAnchorPoint

public double getExtentToLeftOfAnchorPoint()
                                    throws IllegalStateException
Returns the maximum distance which this instance's text horizontally extends to the left of the anchor point. By "left", it is meant as the user sees the screen. Result will be negative if this instance's text never goes left of the anchor point.

Throws:
IllegalStateException - if calling thread is not EventQueue's dispatch thread

getExtentToRightOfAnchorPoint

public double getExtentToRightOfAnchorPoint()
                                     throws IllegalStateException
Returns the maximum distance which this instance's text horizontally extends to the right of the anchor point. By "right", it is meant as the user sees the screen. Result will be negative if this instance's text never goes right of the anchor point.

Throws:
IllegalStateException - if calling thread is not EventQueue's dispatch thread

paint

public void paint(Graphics2D g2)
           throws IllegalArgumentException,
                  IllegalStateException
Paints this instance's text onto g2.

Throws:
IllegalArgumentException - if g2 == null
IllegalStateException - if calling thread is not EventQueue's dispatch thread

paintBaseline

public void paintBaseline(Graphics2D g2)
                   throws IllegalArgumentException,
                          IllegalStateException
Paints the baseline for this instance's text onto g2.

Throws:
IllegalArgumentException - if g2 == null
IllegalStateException - if calling thread is not EventQueue's dispatch thread

paintBounds

public void paintBounds(Graphics2D g2)
                 throws IllegalArgumentException,
                        IllegalStateException
Paints the rectangle which bounds this instance's text onto g2.

Throws:
IllegalArgumentException - if g2 == null
IllegalStateException - if calling thread is not EventQueue's dispatch thread