org.gvsig.gui.awt.text

Class RotatedTextUtils

java.lang.Object

org.gvsig.gui.awt.text.RotatedTextUtils

public class RotatedTextUtils
extends Object

A convenience class to easily draw rotated text which is positioned on a specific side of the rotation point (TOP, BOTTOM, LEFT or RIGHT). The text can be anchored by its central point or by the text corner.

The following diagrams illustrate the behaviour of each positioning and anchor point in relation to the rotation point:

 top center:         top corner:
        o                     o
       l                     l
      l                     l
     e                     e
    h                     h
      .                   . 
 
 
 right center:      right corner:
                          o 
                         l 
        o               l
       l               e
   .  l              .h 
     e
    h
 

The class provides 2 separate families of methods:

• draw methods, which rotate the graphics, draw the rotated text and restore the graphics transformation
• getPosition methods, which are used to get the position of the rotated text on an already rotated graphics (faster when drawing several rotated texts using the same rotation angle). Note that this family of methods deals with coordinates in 2 different coordinate spaces (the original, non-rotated space and the rotated space). The origin point coordinates has to be referred to the non-rotated space, while the returned position is referred to the rotated space.

Generally speaking the draw family of methods can be considered a simpler, higher level API, while the getPosition family is conceptually more complex but faster for some scenarios.

Example of draw method usage:

 // draw coordinates axis
 Graphics2D g = ...
 Point2D origin1 = new Point2D.Double(100, 200);
 int lenght = 100;
 g.drawLine((int)origin1.getX()-length, (int)origin1.getY(), (int)origin1.getX()+length, (int)origin1.getY());
 g.drawLine((int)origin1.getX(), (int)origin1.getY()-length, (int)origin1.getX(), (int)origin1.getY()+length);
 // draw the rotated text
 RotatedTextUtils.draw(origin1, g, "Hello world", angle, RotatedTextUtils.PLACEMENT_BOTTOM, RotatedTextUtils.ANCHOR_CORNER);
 

Example of getPosition method usage:

 // draw coordinates axis
 Graphics2D g = ...
 AffineTransform defaultAt = g.getTransform();
 Point2D origin1 = new Point2D.Double(100, 200);
 Point2D origin2 = new Point2D.Double(200, 200);
 int lenght = 100;
 g.drawLine((int)origin1.getX()-length, (int)origin1.getY(), (int)origin1.getX()+length, (int)origin1.getY());
 g.drawLine((int)origin1.getX(), (int)origin1.getY()-length, (int)origin1.getX(), (int)origin1.getY()+length);
 // draw the rotated text
 AffineTransform finalTransform = g.getTransform();
 finalTransform.rotate(angle);
 g.setTransform(finalTransform);
 TextLayout text = new TextLayout("Hello world", g.getFont(), g.getFontRenderContext());
 Point2D p = RotatedTextUtils.getPosition(origin1, angle, text, RotatedTextUtils.PLACEMENT_BOTTOM, RotatedTextUtils.ANCHOR_CORNER);
 text.draw(g, (float)p.getX(), (float)p.getY());
 // faster than RotatedTextUtils.draw if we are writing the same rotated text at different points
 p = RotatedTextUtils.getPosition(origin2, angle, text, RotatedTextUtils.PLACEMENT_BOTTOM, RotatedTextUtils.ANCHOR_CORNER);
 text.draw(g, (float)p.getX(), (float)p.getY());
 g.setTransform(defaultAt);
 

Field Summary

Fields

Modifier and Type	Field and Description
static int	ANCHOR_CENTER Anchor the center of the text on the rotation center.
static int	ANCHOR_CORNER Anchor a corner of the text on the rotation center.
static int	PLACEMENT_BOTTOM Place the text bellow the rotation point, meaning that no part of the text is over the rotation point.
static int	PLACEMENT_LEFT Place the text on the left of the rotation point, meaning that no part of the text is on the right the rotation point.
static int	PLACEMENT_RIGHT Place the text on the right of the rotation point, meaning that no part of the text is on the left the rotation point.
static int	PLACEMENT_TOP Place the text on the top of the rotation point, meaning that no part of the text is under the rotation point.

Constructor Summary

Constructors

Constructor and Description
RotatedTextUtils()

Method Summary

Modifier and Type	Method and Description
static void	draw(Point2D origin, Graphics2D g, String strText, double angle, int relativePosition, int anchor) Draws rotated text which is positioned on a specific side of the rotation point (TOP, BOTTOM, LEFT or RIGHT).
static void	drawRotated(Point2D location, Graphics2D g, String strText, double angle) Draws the provided text rotated by angle radians using location as rotation center without any positioning or anchoring adjustments.
static Point2D	getPosition(Point2D origin, TextLayout text, double angle, int relativePosition, int anchor) Gets the position in which the text should be drawn according to the provided origin point, angle, align and anchor.
static Point2D	getPositionBottomCenter(Point2D origin, TextLayout text, double angle) Gets the position in which the text should be drawn according to the provided origin point and angle, placing the text at the bottom of the point and using the center of the text as anchor.
static Point2D	getPositionBottomCorner(Point2D origin, TextLayout text, double angle) Gets the position in which the text should be drawn according to the provided origin point and angle, placing the text at the bottom of the point and using a corner of the text as anchor.
static Point2D	getPositionLeftCenter(Point2D origin, TextLayout text, double angle) Gets the position in which the text should be drawn according to the provided origin point and angle, placing the text at the left of the point and using the center of the text as anchor.
static Point2D	getPositionLeftCorner(Point2D origin, TextLayout text, double angle) Gets the position in which the text should be drawn according to the provided origin point and angle, placing the text at the left of the point and using a corner of the text as anchor.
static Point2D	getPositionRightCenter(Point2D origin, TextLayout text, double angle) Gets the position in which the text should be drawn according to the provided origin point and angle, placing the text at the right of the point and using the center of the text as anchor.
static Point2D	getPositionRightCorner(Point2D origin, TextLayout text, double angle) Gets the position in which the text should be drawn according to the provided origin point and angle, placing the text at the right of the point and using a corner of the text as anchor.
static Point2D	getPositionTopCenter(Point2D origin, TextLayout text, double angle) Gets the position in which the text should be drawn according to the provided origin point and angle, placing the text at the top of the point and using the center of the text as anchor.
static Point2D	getPositionTopCorner(Point2D origin, TextLayout text, double angle) Gets the position in which the text should be drawn according to the provided origin point and angle, placing the text at the top of the point and using a corner of the text as anchor.
static double	normalizeAngle(double angle) Normalizes an angle, in radians.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ANCHOR_CORNER

public static final int ANCHOR_CORNER

Anchor a corner of the text on the rotation center. In this way a corner (left or right) of the text string will be aligned with the rotation point. The corner (left or right) to anchor will be automatically selected depending on the rotation angle (choosing the corner which is closer to the rotation center)

See Also:

Constant Field Values

ANCHOR_CENTER

public static final int ANCHOR_CENTER

Anchor the center of the text on the rotation center. In this way the center of the text string will be aligned with the rotation point.

See Also:

Constant Field Values

PLACEMENT_TOP

public static final int PLACEMENT_TOP

Place the text on the top of the rotation point, meaning that no part of the text is under the rotation point.

See Also:

Constant Field Values

PLACEMENT_BOTTOM

public static final int PLACEMENT_BOTTOM

Place the text bellow the rotation point, meaning that no part of the text is over the rotation point.

See Also:

Constant Field Values

PLACEMENT_LEFT

public static final int PLACEMENT_LEFT

Place the text on the left of the rotation point, meaning that no part of the text is on the right the rotation point.

See Also:

Constant Field Values

PLACEMENT_RIGHT

public static final int PLACEMENT_RIGHT

Place the text on the right of the rotation point, meaning that no part of the text is on the left the rotation point.

See Also:

Constant Field Values

Constructor Detail

RotatedTextUtils

public RotatedTextUtils()

Method Detail

draw

public static void draw(Point2D origin,
                        Graphics2D g,
                        String strText,
                        double angle,
                        int relativePosition,
                        int anchor)

Draws rotated text which is positioned on a specific side of the rotation point (TOP, BOTTOM, LEFT or RIGHT). The text can be anchored by its central point or by the text corner.

Parameters:

origin - The rotation center point

g - The target Graphics2D

strText - The text to draw .Use the Graphics2D options (font, color, etc) to style the text before calling this method.

angle - The rotation angle, in radians. The angle should be comprised in the [0, 2*PI[ range, result is otherwise unexpected (a convenience method is provided to normalize it: normalizeAngle(double))

relativePosition - The position of the text compared with the origin point. See PLACEMENT_TOP, PLACEMENT_LEFT, PLACEMENT_RIGHT and 1.

anchor - Whether the center of the label should be aligned with the point (ANCHOR_CENTER) or a corner of the label should be used (ANCHOR_CORNER).

getPosition

public static Point2D getPosition(Point2D origin,
                                  TextLayout text,
                                  double angle,
                                  int relativePosition,
                                  int anchor)

Gets the position in which the text should be drawn according to the provided origin point, angle, align and anchor.

You may consider using the higher level draw methods (e.g. draw(Point2D, Graphics2D, String, double, int, int), #drawTopCenter(Point2D, Graphics2D, String, double), etc) if you are drawing a single label, as this method makes some assumptions for getting maximum performance when drawing several texts using the same rotation. In particular, this method assumes that the target Graphics2D has been rotated using the provided angle and the text has been laid out for this rotated target Graphics2D.

This method deals with coordinates in 2 different coordinate spaces (the original, non-rotated space and the rotated space). The origin point coordinates has to be referred to the non-rotated space, while the returned position is referred to the rotated space.

Parameters:

origin - The point used as the center of the rotation

text - The text to be positioned, which has to be prepared for a rotated graphics, matching the rotation angle

angle - The rotation angle, in radians. The angle should be comprised in the [0, 2*PI[ range, result is otherwise unexpected (a convenience method is provided to normalize it: normalizeAngle(double)

relativePosition - The position of the text compared with the origin point. See PLACEMENT_TOP, PLACEMENT_LEFT, PLACEMENT_RIGHT and 1.

anchor - Whether the center of the label should be aligned with the point (ANCHOR_CENTER) or a corner of the label should be used (ANCHOR_CORNER).

Returns:

The position in which the text should be drawn.

getPositionTopCorner

public static Point2D getPositionTopCorner(Point2D origin,
                                           TextLayout text,
                                           double angle)

Gets the position in which the text should be drawn according to the provided origin point and angle, placing the text at the top of the point and using a corner of the text as anchor.

This method deals with coordinates in 2 different coordinate spaces (the original, non-rotated space and the rotated space). The origin point coordinates has to be referred to the non-rotated space, while the returned position is referred to the rotated space.

Parameters:

origin - The center point of the rotation

text - The text to be drawn, created for the rotated Graphics2D

angle - The rotation angle, in radians. Angle is assumed to be normalized (see normalizeAngle(double))

Returns:

The position in which the text should be drawn, referenced to the rotated coordinate space

Throws:

NoninvertibleTransformException

See Also:

RotatedTextUtils#getPosition(Point2D, double, TextLayout, int, int)}, PLACEMENT_TOP, ANCHOR_CORNER

getPositionTopCenter

public static Point2D getPositionTopCenter(Point2D origin,
                                           TextLayout text,
                                           double angle)

Gets the position in which the text should be drawn according to the provided origin point and angle, placing the text at the top of the point and using the center of the text as anchor.

This method deals with coordinates in 2 different coordinate spaces (the original, non-rotated space and the rotated space). The origin point coordinates has to be referred to the non-rotated space, while the returned position is referred to the rotated space.

Parameters:

origin - The center point of the rotation

text - The text to be drawn, created for the rotated Graphics2D

angle - The rotation angle, in radians. Angle is assumed to be normalized (see normalizeAngle(double))

Returns:

The position in which the text should be drawn, referenced to the rotated coordinate space

Throws:

NoninvertibleTransformException

See Also:

RotatedTextUtils#getPosition(Point2D, double, TextLayout, int, int)}, PLACEMENT_TOP, ANCHOR_CENTER

getPositionRightCorner

public static Point2D getPositionRightCorner(Point2D origin,
                                             TextLayout text,
                                             double angle)

Gets the position in which the text should be drawn according to the provided origin point and angle, placing the text at the right of the point and using a corner of the text as anchor.

This method deals with coordinates in 2 different coordinate spaces (the original, non-rotated space and the rotated space). The origin point coordinates has to be referred to the non-rotated space, while the returned position is referred to the rotated space.

Parameters:

origin - The center point of the rotation

text - The text to be drawn, created for the rotated Graphics2D

angle - The rotation angle, in radians. Angle is assumed to be normalized (see normalizeAngle(double))

Returns:

The position in which the text should be drawn, referenced to the rotated coordinate space

Throws:

NoninvertibleTransformException

See Also:

RotatedTextUtils#getPosition(Point2D, double, TextLayout, int, int)}, PLACEMENT_RIGHT, ANCHOR_CORNER

getPositionRightCenter

public static Point2D getPositionRightCenter(Point2D origin,
                                             TextLayout text,
                                             double angle)

Gets the position in which the text should be drawn according to the provided origin point and angle, placing the text at the right of the point and using the center of the text as anchor.

This method deals with coordinates in 2 different coordinate spaces (the original, non-rotated space and the rotated space). The origin point coordinates has to be referred to the non-rotated space, while the returned position is referred to the rotated space.

Parameters:

origin - The center point of the rotation

text - The text to be drawn, created for the rotated Graphics2D

angle - The rotation angle, in radians. Angle is assumed to be normalized (see normalizeAngle(double))

Returns:

The position in which the text should be drawn, referenced to the rotated coordinate space

Throws:

NoninvertibleTransformException

See Also:

RotatedTextUtils#getPosition(Point2D, double, TextLayout, int, int)}, PLACEMENT_RIGHT, ANCHOR_CENTER

getPositionBottomCorner

public static Point2D getPositionBottomCorner(Point2D origin,
                                              TextLayout text,
                                              double angle)

Gets the position in which the text should be drawn according to the provided origin point and angle, placing the text at the bottom of the point and using a corner of the text as anchor.

This method deals with coordinates in 2 different coordinate spaces (the original, non-rotated space and the rotated space). The origin point coordinates has to be referred to the non-rotated space, while the returned position is referred to the rotated space.

Parameters:

origin - The center point of the rotation

text - The text to be drawn, created for the rotated Graphics2D

angle - The rotation angle, in radians. Angle is assumed to be normalized (see normalizeAngle(double))

Returns:

The position in which the text should be drawn, referenced to the rotated coordinate space

Throws:

NoninvertibleTransformException

See Also:

RotatedTextUtils#getPosition(Point2D, double, TextLayout, int, int)}, PLACEMENT_BOTTOM, ANCHOR_CORNER

getPositionBottomCenter

public static Point2D getPositionBottomCenter(Point2D origin,
                                              TextLayout text,
                                              double angle)

Gets the position in which the text should be drawn according to the provided origin point and angle, placing the text at the bottom of the point and using the center of the text as anchor.

This method deals with coordinates in 2 different coordinate spaces (the original, non-rotated space and the rotated space). The origin point coordinates has to be referred to the non-rotated space, while the returned position is referred to the rotated space.

Parameters:

origin - The center point of the rotation

text - The text to be drawn, created for the rotated Graphics2D

angle - The rotation angle, in radians. Angle is assumed to be normalized (see normalizeAngle(double))

Returns:

The position in which the text should be drawn, referenced to the rotated coordinate space

Throws:

NoninvertibleTransformException

See Also:

RotatedTextUtils#getPosition(Point2D, double, TextLayout, int, int)}, PLACEMENT_BOTTOM, ANCHOR_CENTER

getPositionLeftCorner

public static Point2D getPositionLeftCorner(Point2D origin,
                                            TextLayout text,
                                            double angle)

Gets the position in which the text should be drawn according to the provided origin point and angle, placing the text at the left of the point and using a corner of the text as anchor.

This method deals with coordinates in 2 different coordinate spaces (the original, non-rotated space and the rotated space). The origin point coordinates has to be referred to the non-rotated space, while the returned position is referred to the rotated space.

Parameters:

origin - The center point of the rotation

text - The text to be drawn, created for the rotated Graphics2D

angle - The rotation angle, in radians. Angle is assumed to be normalized (see normalizeAngle(double))

Returns:

The position in which the text should be drawn, referenced to the rotated coordinate space

Throws:

NoninvertibleTransformException

See Also:

RotatedTextUtils#getPosition(Point2D, double, TextLayout, int, int)}, PLACEMENT_LEFT, ANCHOR_CORNER

getPositionLeftCenter

public static Point2D getPositionLeftCenter(Point2D origin,
                                            TextLayout text,
                                            double angle)

Gets the position in which the text should be drawn according to the provided origin point and angle, placing the text at the left of the point and using the center of the text as anchor.

This method deals with coordinates in 2 different coordinate spaces (the original, non-rotated space and the rotated space). The origin point coordinates has to be referred to the non-rotated space, while the returned position is referred to the rotated space.

Parameters:

origin - The center point of the rotation

text - The text to be drawn, created for the rotated Graphics2D

angle - The rotation angle, in radians. Angle is assumed to be normalized (see normalizeAngle(double))

Returns:

The position in which the text should be drawn, referenced to the rotated coordinate space

Throws:

NoninvertibleTransformException

See Also:

RotatedTextUtils#getPosition(Point2D, double, TextLayout, int, int)}, PLACEMENT_LEFT, ANCHOR_CENTER

drawRotated

public static void drawRotated(Point2D location,
                               Graphics2D g,
                               String strText,
                               double angle)

Draws the provided text rotated by angle radians using location as rotation center without any positioning or anchoring adjustments. Use the Graphics2D options (font, color, etc) to style the text before calling this method.

Parameters:

location - The rotation center

g - The Graphics2D on which the text should be drawn

strText - The text to be drawn

angle - The rotation angle, in radians

normalizeAngle

public static double normalizeAngle(double angle)

Normalizes an angle, in radians. A normalized angle is an angle contained in the range [0, 2*PI[.

Parameters:

angle - The angle to normalize, in radians

Returns:

Normalized angled, in radians