gnu.jpdf
Class BoundingBox

java.lang.Object
  java.awt.geom.RectangularShape
      java.awt.geom.Rectangle2D
          java.awt.Rectangle
              gnu.jpdf.BoundingBox

All Implemented Interfaces:

java.awt.Shape, java.io.Serializable, java.lang.Cloneable

public class BoundingBox
extends java.awt.Rectangle

This class simplifies the placement of Strings within a canvas area where the placement of objects is absolute

A BoundingBox is just a Rectangle that knows how to find the coordinates for a String based on the desired alignment and FontMetrics. For each new String, a new child BoundingBox is made that can be subtracted from the original box so new Strings can be added

One of the more helpful features of this class is the string wrap feature of getStringBounds. The box returned by that method will contain an array of strings that have been broken down to fit the box. The box's coordinates and size will reflect the size of the entire group of strings if it is laid out as expected. Using the returned box and iterating through the array of strings from top to bottom, getting new bounding boxes for each one (with upper left alignment and no padding) will result in the correct string wrap.

Note that you will need to have Xvfb running on a Unix server to use this class

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class java.awt.geom.Rectangle2D

java.awt.geom.Rectangle2D.Double, java.awt.geom.Rectangle2D.Float

Field Summary

static int	HORIZ_ALIGN_CENTER Used to align a String horizontally in the center of the box
static int	HORIZ_ALIGN_LEFT Used to align a String to the left in the box
static int	HORIZ_ALIGN_RIGHT Used to aling a String to the right in a box
static int	LINE_SPACING_PERCENTAGE Percent f line height to space lines
static int	SUBTRACT_FROM_BOTTOM Used to subtract a child from a box, *leaving* the bottom portion
static int	SUBTRACT_FROM_LEFT Used to subtract a child from a box, *leaving* the left portion
static int	SUBTRACT_FROM_RIGHT Used to subtract a child from a box, *leaving" the right portion
static int	SUBTRACT_FROM_TOP Used to subtract a child from a box, *leaving* the top portion
static int	VERT_ALIGN_BOTTOM Used to align a String at the bottom of the box
static int	VERT_ALIGN_CENTER Used to a align a String centered vertically
static int	VERT_ALIGN_TOP Used to align a String at the top of the box

Fields inherited from class java.awt.Rectangle

height, width, x, y

Fields inherited from class java.awt.geom.Rectangle2D

OUT_BOTTOM, OUT_LEFT, OUT_RIGHT, OUT_TOP

Constructor Summary

BoundingBox(java.awt.Point p, java.awt.Dimension d)
Creates a new BoundingBox instance.

Method Summary

void	add(BoundingBox child) Make the specified box this box's child.
boolean	boxExists() Returns false if for any reason this box has negative dimensions
void	drawChoppedString(java.awt.Graphics g, java.awt.FontMetrics fm, int padding, int hAlign) Take the first line of the string (if it is wrapped, otherwise just take the whole string) and chop the end of it off to make it fit in the box.
void	drawWrappedString(java.awt.Graphics g, java.awt.FontMetrics fm, int padding, int hAlign) This method is called after getting the box by calling getStringBounds on the parent.
void	drawWrappedStringTruncate(java.awt.Graphics g, java.awt.FontMetrics fm, int padding, int hAlign) Draws lines from the wrapped string until there is no more room and then stops.
java.awt.Point	getAbsoluteLocation() Get the absolute upper left location point for this box
java.awt.Point	getDrawingPoint() Gets the drawing point to use in Graphics drawing methods.
java.lang.String	getFullString() Returns the full string associated with a call to getStringBounds
BoundingBox	getParent() Get this box's parent box
java.lang.String[]	getStringArray() Get the wrapped strings if this box was from a call to getStringBounds, otherwise this method returns null
BoundingBox	getStringBounds(java.lang.String string, int hAlign, int vAlign, java.awt.FontMetrics fm, int padding) Gets the location of a String after it is adjusted for alignment within this box.
BoundingBox	getStringBounds(java.lang.String string, int hAlign, int vAlign, java.awt.FontMetrics fm, int padding, boolean enforce) Gets the location of a String after it is adjusted for alignment within this box.
boolean	hasParent() Returns true if this box has a parent.
static void	main(java.lang.String[] args) For testing
void	setAbsoluteLocation(java.awt.Point point) Set the absolute upper left world location point for this box
void	setFullString(java.lang.String string) Sets the full string associated with getStringBounds
void	setParent(BoundingBox parent) Make the specified box this box's parent
void	setStringArray(java.lang.String[] strArray) Set the value of the string array
BoundingBox	subtract(BoundingBox child, int subtractFrom) Removes the child box from this parent box.

Methods inherited from class java.awt.Rectangle

add, add, add, contains, contains, contains, contains, createIntersection, createUnion, equals, getBounds, getBounds2D, getHeight, getLocation, getSize, getWidth, getX, getY, grow, inside, intersection, intersects, isEmpty, move, outcode, reshape, resize, setBounds, setBounds, setLocation, setLocation, setRect, setSize, setSize, toString, translate, union

Methods inherited from class java.awt.geom.Rectangle2D

add, add, add, contains, contains, getPathIterator, getPathIterator, hashCode, intersect, intersects, intersectsLine, intersectsLine, outcode, setFrame, setRect, union

Methods inherited from class java.awt.geom.RectangularShape

clone, contains, contains, getCenterX, getCenterY, getFrame, getMaxX, getMaxY, getMinX, getMinY, intersects, setFrame, setFrame, setFrameFromCenter, setFrameFromCenter, setFrameFromDiagonal, setFrameFromDiagonal

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.awt.Shape

contains, contains, contains, contains, getPathIterator, getPathIterator, intersects, intersects

Field Detail

LINE_SPACING_PERCENTAGE

public static final int LINE_SPACING_PERCENTAGE

Percent f line height to space lines

See Also:

Constant Field Values

VERT_ALIGN_CENTER

public static final int VERT_ALIGN_CENTER

Used to a align a String centered vertically

See Also:

Constant Field Values

VERT_ALIGN_TOP

public static final int VERT_ALIGN_TOP

Used to align a String at the top of the box

See Also:

Constant Field Values

VERT_ALIGN_BOTTOM

public static final int VERT_ALIGN_BOTTOM

Used to align a String at the bottom of the box

See Also:

Constant Field Values

HORIZ_ALIGN_CENTER

public static final int HORIZ_ALIGN_CENTER

Used to align a String horizontally in the center of the box

See Also:

Constant Field Values

HORIZ_ALIGN_LEFT

public static final int HORIZ_ALIGN_LEFT

Used to align a String to the left in the box

See Also:

Constant Field Values

HORIZ_ALIGN_RIGHT

public static final int HORIZ_ALIGN_RIGHT

Used to aling a String to the right in a box

See Also:

Constant Field Values

SUBTRACT_FROM_TOP

public static final int SUBTRACT_FROM_TOP

Used to subtract a child from a box, *leaving* the top portion

See Also:

Constant Field Values

SUBTRACT_FROM_BOTTOM

public static final int SUBTRACT_FROM_BOTTOM

Used to subtract a child from a box, *leaving* the bottom portion

See Also:

Constant Field Values

SUBTRACT_FROM_LEFT

public static final int SUBTRACT_FROM_LEFT

Used to subtract a child from a box, *leaving* the left portion

See Also:

Constant Field Values

SUBTRACT_FROM_RIGHT

public static final int SUBTRACT_FROM_RIGHT

Used to subtract a child from a box, *leaving" the right portion

See Also:

Constant Field Values

Constructor Detail

BoundingBox

public BoundingBox(java.awt.Point p,
                   java.awt.Dimension d)

Creates a new BoundingBox instance.

Parameters:

p - a Point, upper left coords

d - a Dimension, used to determine height and width

Method Detail

hasParent

public boolean hasParent()

Returns true if this box has a parent. The 'world', or enclosing canvas is not considered a parent

Returns:

a boolean value

getParent

public BoundingBox getParent()

Get this box's parent box

Returns:

a BoundingBox value

add

public void add(BoundingBox child)

Make the specified box this box's child. Equivalent to child.setParent(parent) where the specified 'parent' is this instance

Parameters:

child - a BoundingBox, any box that can fit inside this one. The results of calling getAbsoluteLocation() on the child will be altered after this to take into account the child's new location in the 'world'

setParent

public void setParent(BoundingBox parent)

Make the specified box this box's parent

Parameters:

parent - a BoundingBox value

getStringArray

public java.lang.String[] getStringArray()

Get the wrapped strings if this box was from a call to getStringBounds, otherwise this method returns null

Returns:

a String[] array of strings, top to bottom in layout

setStringArray

public void setStringArray(java.lang.String[] strArray)

Set the value of the string array

Parameters:

strArray - a String array

setAbsoluteLocation

public void setAbsoluteLocation(java.awt.Point point)

Set the absolute upper left world location point for this box

Parameters:

point - a Point value

boxExists

public boolean boxExists()

Returns false if for any reason this box has negative dimensions

getAbsoluteLocation

public java.awt.Point getAbsoluteLocation()

Get the absolute upper left location point for this box

Returns:

a Point value

getFullString

public java.lang.String getFullString()

Returns the full string associated with a call to getStringBounds

setFullString

public void setFullString(java.lang.String string)

Sets the full string associated with getStringBounds

Parameters:

string - a String

getStringBounds

public BoundingBox getStringBounds(java.lang.String string,
                                   int hAlign,
                                   int vAlign,
                                   java.awt.FontMetrics fm,
                                   int padding,
                                   boolean enforce)
                            throws java.lang.IllegalArgumentException,
                                   StringTooLongException

Gets the location of a String after it is adjusted for alignment within this box. The point's coordinates are either within this box or within the enclosing area.

Parameters:

string - a String, the String to be placed

hAlign - an int, HORIZ_ALIGN_CENTER, HORIZ_ALIGN_LEFT, HORIX_ALIGN_RIGHT

vAlign - an int, VERT_ALIGN_CENTER, VERT_ALIGN_TOP, VERT_ALIGN_BOTTOM

fm - a FontMetrics object for this String

padding - an int, the padding around the String

enforce - a boolean, if true the method will throw an exception when the string is too big, if not true it will break the string down and overrun the bottom of the box. If the box is too small for even one word, the exception will be thrown

Returns:

a Point, the coords to use in drawString()

Throws:

IllegalArgumentException - if the args are invalid

StringTooLongException - if the string won't fit and enforce is set to true. The exception can still be thrown if enforce is false, but only in cases such as the box having no height or width

java.lang.IllegalArgumentException

StringTooLongException

See Also:

HORIZ_ALIGN_LEFT, HORIZ_ALIGN_CENTER, HORIZ_ALIGN_RIGHT, VERT_ALIGN_TOP, VERT_ALIGN_CENTER, VERT_ALIGN_BOTTOM

getStringBounds

public BoundingBox getStringBounds(java.lang.String string,
                                   int hAlign,
                                   int vAlign,
                                   java.awt.FontMetrics fm,
                                   int padding)
                            throws StringTooLongException,
                                   java.lang.IllegalArgumentException

Gets the location of a String after it is adjusted for alignment within this box. The point's coordinates are either within this box or within the enclosing area.

By default, this method enforces string length and throws the exception if it is too long

Parameters:

string - a String, the String to be placed

hAlign - an int, HORIZ_ALIGN_CENTER, HORIZ_ALIGN_LEFT, HORIX_ALIGN_RIGHT

vAlign - an int, VERT_ALIGN_CENTER, VERT_ALIGN_TOP, VERT_ALIGN_BOTTOM

fm - a FontMetrics object for this String

padding - an int, the padding around the String

Returns:

a Point, the coords to use in drawString()

Throws:

IllegalArgumentException - if the args are invalid

StringTooLongException - if the string won't fit

StringTooLongException

java.lang.IllegalArgumentException

drawWrappedString

public void drawWrappedString(java.awt.Graphics g,
                              java.awt.FontMetrics fm,
                              int padding,
                              int hAlign)
                       throws java.lang.IllegalArgumentException,
                              StringTooLongException

This method is called after getting the box by calling getStringBounds on the parent. Wraps the string at word boundaries and draws it to the specified Graphics context. Make sure padding is the same as specified for the getStringBounds call, or you may get an unexpected StringTooLongException

Parameters:

g - the Graphics object

fm - the FontMetrics to use for sizing

padding - an int, the padding around the strings

hAlign - the int horizontal alignment

Throws:

IllegalArgumentException - if the args are invalid

StringTooLongException - if the string won't fit this will only happen if the fm or padding has been changed since getStringBounds was called succesfully

java.lang.IllegalArgumentException

StringTooLongException

drawWrappedStringTruncate

public void drawWrappedStringTruncate(java.awt.Graphics g,
                                      java.awt.FontMetrics fm,
                                      int padding,
                                      int hAlign)

Draws lines from the wrapped string until there is no more room and then stops. If there is no string or the box is too small for anything to be drawn, does nothing

Parameters:

g - the Graphics object to draw to

fm - the FontMetrics object to use for string sizing

padding - the int amount of padding around the string

hAlign - the int horizontal alignment

drawChoppedString

public void drawChoppedString(java.awt.Graphics g,
                              java.awt.FontMetrics fm,
                              int padding,
                              int hAlign)

Take the first line of the string (if it is wrapped, otherwise just take the whole string) and chop the end of it off to make it fit in the box. If the box is smaller than one letter, draw nothing

Parameters:

g - the Graphics object to draw to

fm - the FontMetrics object to use for string sizing

padding - the int amount of padding around the string

hAlign - the int horizontal alignment

subtract

public BoundingBox subtract(BoundingBox child,
                            int subtractFrom)

Removes the child box from this parent box. The child must have this object as its parent or the method does nothing. The BoundingBox returned will be cut by an area equal to the child area plus the horizontal or vertical strip in which it sits, depending on the 'subtractFrom' value passed in

Parameters:

child - a BoundingBox value

subtractFrom - an int, SUBTRACT_FROM_LEFT, SUBTRACT_FROM_RIGHT, SUBTRACT_FROM_TOP, SUBTRACT_FROM_BOTTOM

Returns:

a BoundingBox value

See Also:

SUBTRACT_FROM_LEFT, SUBTRACT_FROM_RIGHT, SUBTRACT_FROM_TOP, SUBTRACT_FROM_BOTTOM

getDrawingPoint

public java.awt.Point getDrawingPoint()

Gets the drawing point to use in Graphics drawing methods. After getting a new BoundingBox with getStringBounds(), calling this method will give you an absolute point, accounting for alignment and padding, etc, from which to start drawing the String

If getStringBounds was not called (this is a parent box), the upper left coordinates will be returned (this.getLocation())

Returns:

a Point

main

public static void main(java.lang.String[] args)

For testing

Parameters:

args - a String[] value