org.faceless.pdf2

Class LayoutBox

java.lang.Object

org.faceless.pdf2.LayoutBox

public final class LayoutBox
extends Object

A LayoutBox is a box for laying out text, which allows a great deal more control over positioning than the standard drawText method.

A LayoutBox has a fixed width but no predefined height. Text and "Boxes" can be added to the box, and when the box is complete it can be drawn onto a page using the PDFPage.drawLayoutBox method. At its simplest, the following will create a single line of Text on the page.

   PDFStyle style = new PDFStyle();
   style.setFont(new StandardFont(StandardFont.HELVETICA), 12);
   style.setFillColor(Color.black);

   LayoutBox box = new LayoutBox(page.getWidth()-100);
   box.addText("Hello, World", style, Locale.getDefault());
   page.drawLayoutBox(box, 50, page.getHeight()-50);
 

The LayoutBox class also allows "boxes" to be inserted into the flow, which can later be used to position images or similar items in the text. For example, the following code will produce an image in the top-left hand corner with text wrapping around it:

   PDFStyle style = new PDFStyle();
   style.setFont(new StandardFont(StandardFont.HELVETICA), 12);
   style.setFillColor(Color.black);

   LayoutBox box = new LayoutBox(page.getWidth()-100);
   LayoutBox.Box imagebox = box.addBoxLeft(100,100, PDFStyle.TEXTALIGN_BASELINE);
   imagebox.setImage(myimage);
   box.addText("Hello, World", style, Locale.getDefault());

   page.drawLayoutBox(box, 50, page.getHeight()-50);
 

Images can also be drawn inline with the addBoxInline method, or to the right with the addBoxRight method.

Since:

1.2

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	LayoutBox.Box A class representing a Box, several of which make up the visible content of a LayoutBox.
class	LayoutBox.Text The Text class is a subclass of LayoutBox.Box which is specifically for displaying Text.

Field Summary

Fields

Modifier and Type	Field and Description
static int	CLEAR_LEFT A flag indicating that the Box created by addBoxLeft(float, float, int) or addBoxRight(float, float, int) should always be flat against the left margin - it should have no content to its left.
static int	CLEAR_NONE A flag indicating that the Box created by addBoxLeft(float, float, int) or addBoxRight(float, float, int) does not require either a left or right margin to line up against.
static int	CLEAR_RIGHT A flag indicating that the Box created by addBoxLeft(float, float, int) or addBoxRight(float, float, int) should always be flat against the right margin - it should have no content to its right.

Constructor Summary

Constructors

Constructor and Description
LayoutBox(float width) Create a new LayoutBox of the specified width.
LayoutBox(float width, Locale locale) Create a new LayoutBox of the specified width, and with the specified Locale as the parent locale of the LayoutBox.

Method Summary

Modifier and Type	Method and Description
LayoutBox.Box	addBoxFullWidth(float height) Add a new box that takes the full width of the LayoutBox, less the width of any left or right floating boxes.
LayoutBox.Box	addBoxInline(float width, float height, int align) Add a new Box which will be appear "inline" - ie. positioned in the same way as the text.
LayoutBox.Box	addBoxLeft(float width, float height, int clearflags) Add a new Box which will float at the left of the LayoutBox.
LayoutBox.Box	addBoxRight(float width, float height, int clearflags) Add a new Box which will float at the right of the LayoutBox.
void	addLineBreak(PDFStyle style) Add a line-break in the specified style.
float	addTab(float[] stops) Add a horizontal tab to the LayoutBox.
LayoutBox.Text	addText(char[] buf, int off, int len, PDFStyle style, Locale locale) Add a line of text to the LayoutBox.
LayoutBox.Text	addText(String string, PDFStyle style, Locale locale) Add a line of text to the LayoutBox.
LayoutBox.Text	addTextNoBreak(char[] buf, int off, int len, PDFStyle style, Locale locale) Add a line of text to the LayoutBox.
LayoutBox.Text	addTextNoBreak(String string, PDFStyle style, Locale locale) Add a line of text to the LayoutBox.
void	beginTag(String tag, Map<String,Object> atts) Open a structural tag on this LayoutBox.
void	endTag() Close a structural tag on this LayoutBox.
void	flush() Flush the flowbox.
LayoutBox.Box[]	getBoxes() Return the list of boxes which make up the LayoutBox.
float	getHeight() Return the height in points of the LayoutBox.
int	getNumberOfLines() Return the number of lines in the LayoutBox.
PDFStyle	getStyle() Return the style of the LayoutBox, as set by setStyle(org.faceless.pdf2.PDFStyle)
boolean	isEmpty() Return true if the LayoutBox is empty, false if it's not
boolean	isFlushed() Return true if the LayoutBox has been flushed - ie. if there are any items of text that are still to be positioned.
void	setStyle(PDFStyle style) Set the default style of the box.
void	setWordBreaksAllowed(boolean breaks) Set whether word breaks are allowed between items added to the LayoutBox.
LayoutBox	splitAt(float splitpos) Split a LayoutBox into two boxes at the specified height.

Methods inherited from class java.lang.Object

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

Field Detail

CLEAR_NONE

public static final int CLEAR_NONE

A flag indicating that the Box created by addBoxLeft(float, float, int) or addBoxRight(float, float, int) does not require either a left or right margin to line up against.

See Also:

Constant Field Values

CLEAR_LEFT

public static final int CLEAR_LEFT

A flag indicating that the Box created by addBoxLeft(float, float, int) or addBoxRight(float, float, int) should always be flat against the left margin - it should have no content to its left.

See Also:

Constant Field Values

CLEAR_RIGHT

public static final int CLEAR_RIGHT

A flag indicating that the Box created by addBoxLeft(float, float, int) or addBoxRight(float, float, int) should always be flat against the right margin - it should have no content to its right.

See Also:

Constant Field Values

Constructor Detail

LayoutBox

public LayoutBox(float width)

Create a new LayoutBox of the specified width. Note that if you're working with bidirectional text, you should use the other constructor and pass in a Locale.

Parameters:

width - the width of the LayoutBox, in points

LayoutBox

public LayoutBox(float width,
                 Locale locale)

Create a new LayoutBox of the specified width, and with the specified Locale as the parent locale of the LayoutBox. This is necessary in order to correctly order items on a line during bidirectional text processing. The Locale specified here is the overall locale of the LayoutBox, it may be overridden on a phrase-by-phrase basis by specifying the locale in the addText methods.

Parameters:

width - the width of the LayoutBox, in points

locale - the overall locale of the LayoutBox

Since:

1.2.10

Method Detail

setStyle

public void setStyle(PDFStyle style)

Set the default style of the box. This is used to determine the alignment of the text in the box - left, centered, right or justified. It should be set immediately after the box is created, or at least before the first line is positioned. If it is not called, the default style of the box is the style used in the first call to addText, addTextNoBreak or addLineBreak

Parameters:

style - the default style of the LayoutBox

See Also:

getStyle()

addText

public LayoutBox.Text addText(String string,
                              PDFStyle style,
                              Locale locale)

Add a line of text to the LayoutBox. The text may be broken into smaller units to fit the line, in which case the LayoutBox.Text.getNextTwin() method can be used to traverse through them.

Since 2.0 the text may contain newline (\n) characters, which act in the normal way (prior to 2.0 it was necessary to call the addLineBreak(org.faceless.pdf2.PDFStyle) method). Tab (\t) characters are not recognised however - to insert a horizontal tab into the text, you need to call the addTab(float[]) method, as this is the only way for the system to know how wide each tab is to be.

Parameters:

string - the text to display.

style - the style in which to display the text

locale - the locale of the text. With locales where this is unlikely to make a difference, ie. western european languages, this may be null

Returns:

a Text object representing this string.

addText

public LayoutBox.Text addText(char[] buf,
                              int off,
                              int len,
                              PDFStyle style,
                              Locale locale)

Add a line of text to the LayoutBox. Identical to addText(String,PDFStyle,Locale),

Parameters:

buf - the buffer containing the text to add

off - the offset of the start of the meaningful content of the buffer

len - the length of the meaningful content of the buffer

style - the style in which to display the text

locale - the locale of the text. With locales where this is unlikely to make a difference, ie. western european languages, this may be null

Since:

1.2.1

setWordBreaksAllowed

public void setWordBreaksAllowed(boolean breaks)

Set whether word breaks are allowed between items added to the LayoutBox. By default word breaks are allowed at appropriate locations in any text added via addText(), and between any two calls to addText() or addTextNoBreak().

This method can be called to turn off those word-breaking opportunities, and is required to suppress breaks between subsequent calls to addTextNoBreak().

Parameters:

breaks - whether to allow word breaks - the default value is true

Since:

2.11.4

See Also:

PDFStyle.setLineBreakBehaviour(int)

addTextNoBreak

public LayoutBox.Text addTextNoBreak(String string,
                                     PDFStyle style,
                                     Locale locale)

Add a line of text to the LayoutBox. The text will not be broken into smaller units to fit the line, but will appear as one line. It is the callers responsibilty to ensure the text will actually fit on the line. Including newline or tab characters in the text passed to this method will cause warnings to be displayed.

Parameters:

string - the text to display

style - the style in which to display the text

locale - the locale of the text. With locales where this is unlikely to make a difference, ie. western european languages, this may be null

Returns:

a Text object representing this string.

addTextNoBreak

public LayoutBox.Text addTextNoBreak(char[] buf,
                                     int off,
                                     int len,
                                     PDFStyle style,
                                     Locale locale)

Add a line of text to the LayoutBox. Identical to addTextNoBreak(String,PDFStyle,Locale),

Parameters:

buf - the buffer containing the text to add

off - the offset of the start of the meaningful content of the buffer

len - the length of the meaningful content of the buffer

style - the style in which to display the text

locale - the locale of the text. With locales where this is unlikely to make a difference, ie. western european languages, this may be null

Returns:

a Text object representing this string.

Since:

1.2.1

addTab

public float addTab(float[] stops)

Add a horizontal tab to the LayoutBox. Tabs are specified as an array of floats which represent the position (in points) of the tab stop from the left of the box. For instance, { 80, 100, 150 } would cause the first cursor to move right to 80, 100 or 150 points from the left of the LayoutBox, depending on how far in it already was.

If the cursor is past the last entry in the array, then tab stops are assumed to continue over the same width to the right of the box. The width of these stops is the same as the last specified width - so in the example above, tab stops 200, 250, 300, 350 and so on are implied. This means that for the simplest case - a tab stop every 50 points - all you need to do is specify an array with a single float of { 50 }.

If there are no further tab stops available on the current line, the cursor is moved to the start of the next line.

Note Tab stops only work with left-aligned text. Consequently, if the alignment for the LayoutBox is anything other than TEXTALIGN_LEFT, an exception is thrown.

Parameters:

stops - an array of one or more floats defining the position of tab stops in points from the left edge of the LayoutBox

Returns:

the cursor position in points from the left edge of the LayoutBox

Throws:

IllegalStateException - if the LayoutBox is not left-aligned.

Since:

1.2.10

addLineBreak

public void addLineBreak(PDFStyle style)

Add a line-break in the specified style. Line Breaks reset the cursor to the left (or right, for RTL text) side of the LayoutBox, and move the cursor down the page by style.getFontLeading() points

Parameters:

style - the style defining the font in which to add the linebreak

addBoxInline

public LayoutBox.Box addBoxInline(float width,
                                  float height,
                                  int align)

Add a new Box which will be appear "inline" - ie. positioned in the same way as the text.

Parameters:

width - the width of the rectangle

height - the height of the rectangle

align - how to align the text - one of PDFStyle.TEXTALIGN_TOP, PDFStyle.TEXTALIGN_MIDDLE or PDFStyle.TEXTALIGN_BOTTOM

Returns:

a LayoutBox.Box representing this object

addBoxFullWidth

public LayoutBox.Box addBoxFullWidth(float height)

Add a new box that takes the full width of the LayoutBox, less the width of any left or right floating boxes. Use this method for reserving a block in the middle of the paragraph for other content.

Parameters:

height - the height of the box.

Since:

1.2.1

addBoxLeft

public LayoutBox.Box addBoxLeft(float width,
                                float height,
                                int clearflags)

Add a new Box which will float at the left of the LayoutBox. Content which follows this rectangle will appear either to the right or below it, depending on the value of clearflags

Parameters:

width - the width of the rectangle

height - the height of the rectangle

clearflags - logical-or of zero or more of CLEAR_LEFT or CLEAR_RIGHT

Returns:

a LayoutBox.Box representing this object

addBoxRight

public LayoutBox.Box addBoxRight(float width,
                                 float height,
                                 int clearflags)

Add a new Box which will float at the right of the LayoutBox. Content which follows this rectangle will appear either to the left or below it, depending on the value of clearflags

Parameters:

width - the width of the rectangle

height - the height of the rectangle

clearflags - logical-or of zero or more of CLEAR_LEFT or CLEAR_RIGHT

Returns:

a LayoutBox.Box representing this object

beginTag

public void beginTag(String tag,
                     Map<String,Object> atts)

Open a structural tag on this LayoutBox. This call must be matched by a later call to endTag() See the PDFCanvas version of this method for the full documnentation.

Since:

2.11.9

See Also:

PDFCanvas.beginTag(java.lang.String, java.util.Map<java.lang.String, java.lang.Object>)

endTag

public void endTag()

Close a structural tag on this LayoutBox. This call must match an earlier call to beginTag() See the PDFCanvas version of this method for the full documnentation.

Since:

2.11.9

See Also:

PDFCanvas.beginTag(java.lang.String, java.util.Map<java.lang.String, java.lang.Object>)

isEmpty

public boolean isEmpty()

Return true if the LayoutBox is empty, false if it's not

getHeight

public float getHeight()

Return the height in points of the LayoutBox. The box should be flushed first by calling the flush() method, otherwise there is a very good chance the last line of text hasn't been positioned (and won't be included in the returned value).

Returns:

the height of the LayoutBox in points.

isFlushed

public boolean isFlushed()

Return true if the LayoutBox has been flushed - ie. if there are any items of text that are still to be positioned. A LayoutBox should be flushed before the getBoxes() or the getHeight() methods are called.

See Also:

flush()

flush

public void flush()

Flush the flowbox. Flushing causes any items which have not yet been positioned (specifically any text on the last incomplete line of the LayoutBox) to be positioned.

See Also:

isFlushed()

getBoxes

public LayoutBox.Box[] getBoxes()

Return the list of boxes which make up the LayoutBox. Unless the LayoutBox has been flushed, some of these items may not have a position specified.

Returns:

a list of LayoutBox.Box objects which make up the visible contents of the LayoutBox.

See Also:

isFlushed(), flush()

getStyle

public PDFStyle getStyle()

Return the style of the LayoutBox, as set by setStyle(org.faceless.pdf2.PDFStyle)

splitAt

public LayoutBox splitAt(float splitpos)

Split a LayoutBox into two boxes at the specified height. The current box is shortened and a new box returned containing all the content below the requested row.

Returns:

a new LayoutBox containing all the data below the requested row.

Since:

1.2.1

getNumberOfLines

public int getNumberOfLines()

Return the number of lines in the LayoutBox. Blank lines are not included in the total. The LayoutBox should be flushed before calling this method to ensure the correct result.

Since:

1.2.1