com.lowagie.text.pdf

Class ColumnText

public class ColumnText extends Object

Formats text in a columnwise form. The text is bound on the left and on the right by a sequence of lines. This allows the column to have any shape, not only rectangular.

Several parameters can be set like the first paragraph line indent and extra space between paragraphs.

A call to the method go will return one of the following situations: the column ended or the text ended.

I the column ended, a new column definition can be loaded with the method setColumns and the method go can be called again.

If the text ended, more text can be loaded with addText and the method go can be called again.
The only limitation is that one or more complete paragraphs must be loaded each time.

Full bidirectional reordering is supported. If the run direction is PdfWriter.RUN_DIRECTION_RTL the meaning of the horizontal alignments and margins is mirrored.

Author: Paulo Soares (psoares@consiste.pt)

Field Summary
static intAR_COMPOSEDTASHKEEL
Compose the tashkeel in the ligatures.
static intAR_LIG
Do some extra double ligatures.
static intAR_NOVOWEL
Eliminate the arabic vowels
booleanadjustFirstLine
protected intalignment
The column alignment.
intarabicOptions
Holds value of property arabicOptions.
protected BidiLinebidiLine
The chunks that form the text.
protected PdfContentBytecanvas
The PdfContent where the text will be written to.
protected PdfContentByte[]canvases
protected booleancomposite
protected ColumnTextcompositeColumn
protected LinkedListcompositeElements
protected floatcurrentLeading
The leading for the current line.
protected floatdescender
static intDIGITS_AN2EN
Digit shaping option: Replace Arabic-Indic digits by European digits (U+0030...U+0039).
static intDIGITS_EN2AN
Digit shaping option: Replace European digits (U+0030...U+0039) by Arabic-Indic digits.
static intDIGITS_EN2AN_INIT_AL
Digit shaping option: Replace European digits (U+0030...U+0039) by Arabic-Indic digits if the most recent strongly directional character is an Arabic letter (its Bidi direction value is RIGHT_TO_LEFT_ARABIC).
static intDIGITS_EN2AN_INIT_LR
Digit shaping option: Replace European digits (U+0030...U+0039) by Arabic-Indic digits if the most recent strongly directional character is an Arabic letter (its Bidi direction value is RIGHT_TO_LEFT_ARABIC).
static intDIGIT_TYPE_AN
Digit type option: Use Arabic-Indic digits (U+0660...U+0669).
static intDIGIT_TYPE_AN_EXTENDED
Digit type option: Use Eastern (Extended) Arabic-Indic digits (U+06f0...U+06f9).
protected floatextraParagraphSpace
The extra space between paragraphs.
floatfilledWidth
Holds value of property filledWidth.
floatfirstLineY
booleanfirstLineYDone
protected floatfixedLeading
The fixed text leading.
protected floatfollowingIndent
The following paragraph lines indent.
static floatGLOBAL_SPACE_CHAR_RATIO
the space char ratio
protected floatindent
The first paragraph line indent.
booleanlastWasNewline
protected ArrayListleftWall
The left column bound.
protected floatleftX
intlinesWritten
Holds value of property linesWritten.
protected intlineStatus
The line status when trying to fit a line to a column.
protected intlistIdx
protected static intLINE_STATUS_NOLINE
The line cannot fit this column position.
protected static intLINE_STATUS_OFFLIMITS
The line is out the column limits.
protected static intLINE_STATUS_OK
The column is valid.
protected floatmaxY
Upper bound of the column.
protected floatminY
Lower bound of the column.
protected floatmultipliedLeading
The text leading that is multiplied by the biggest font size in the line.
static intNO_MORE_COLUMN
Signals that there is no more column.
static intNO_MORE_TEXT
Signals that there is no more text available.
protected booleanrectangularMode
protected floatrectangularWidth
The width of the line when the column is defined as a simple rectangle.
protected floatrightIndent
The right paragraph lines indent.
protected ArrayListrightWall
The right column bound.
protected floatrightX
protected intrunDirection
floatspaceCharRatio
Holds value of property spaceCharRatio.
booleansplittedRow
static intSTART_COLUMN
Initial value of the status.
booleanuseAscender
if true, first line height is adjusted so that the max ascender touches the top
protected PhrasewaitPhrase
protected floatyLine
The current y line location.
Constructor Summary
ColumnText(PdfContentByte canvas)
Creates a ColumnText.
Method Summary
voidaddElement(Element element)
Adds an element.
voidaddText(Phrase phrase)
Adds a Phrase to the current text array.
voidaddText(Chunk chunk)
Adds a Chunk to the current text array.
voidaddWaitingPhrase()
voidclearChunks()
Clears the chunk array.
protected ArrayListconvertColumn(float[] cLine)
Converts a sequence of lines representing one of the column bounds into an internal format.
static ColumnTextduplicate(ColumnText org)
Creates an independent duplicated of the instance org.
protected float[]findLimitsOneLine()
Finds the intersection between the yLine and the two column bounds.
protected floatfindLimitsPoint(ArrayList wall)
Finds the intersection between the yLine and the column.
protected float[]findLimitsTwoLines()
Finds the intersection between the yLine, the yLine-leadingand the two column bounds.
intgetAlignment()
Gets the alignment.
intgetArabicOptions()
Gets the arabic shaping options.
PdfContentBytegetCanvas()
Gets the canvas.
PdfContentByte[]getCanvases()
Gets the canvases.
floatgetDescender()
Gets the biggest descender value of the last line written.
floatgetExtraParagraphSpace()
Sets the extra space between paragraphs.
floatgetFilledWidth()
Gets the real width used by the largest line.
floatgetFollowingIndent()
Gets the following paragraph lines indent.
floatgetIndent()
Gets the first paragraph line indent.
floatgetLeading()
Gets the fixed leading.
intgetLinesWritten()
Gets the number of lines written.
floatgetMultipliedLeading()
Gets the variable leading.
floatgetRightIndent()
Gets the right paragraph lines indent.
intgetRunDirection()
Gets the run direction.
floatgetSpaceCharRatio()
Gets the space/character extra spacing ratio for fully justified text.
static floatgetWidth(Phrase phrase, int runDirection, int arabicOptions)
Gets the width that the line will occupy after writing.
static floatgetWidth(Phrase phrase)
Gets the width that the line will occupy after writing.
floatgetYLine()
Gets the yLine.
intgo()
Outputs the lines to the document.
intgo(boolean simulate)
Outputs the lines to the document.
protected intgoComposite(boolean simulate)
static booleanhasMoreText(int status)
Checks the status variable and looks if there's still some text.
booleanisAdjustFirstLine()
Gets the first line adjustment property.
booleanisUseAscender()
Checks if UseAscender is enabled/disabled.
ColumnTextsetACopy(ColumnText org)
Makes this instance an independent copy of org.
voidsetAdjustFirstLine(boolean adjustFirstLine)
Sets the first line adjustment.
voidsetAlignment(int alignment)
Sets the alignment.
voidsetArabicOptions(int arabicOptions)
Sets the arabic shaping options.
voidsetCanvas(PdfContentByte canvas)
Sets the canvas.
voidsetCanvases(PdfContentByte[] canvases)
Sets the canvases.
voidsetColumns(float[] leftLine, float[] rightLine)
Sets the columns bounds.
voidsetExtraParagraphSpace(float extraParagraphSpace)
Sets the extra space between paragraphs.
voidsetFilledWidth(float filledWidth)
Sets the real width used by the largest line.
voidsetFollowingIndent(float indent)
Sets the following paragraph lines indent.
voidsetIndent(float indent)
Sets the first paragraph line indent.
voidsetLeading(float leading)
Sets the leading to fixed.
voidsetLeading(float fixedLeading, float multipliedLeading)
Sets the leading fixed and variable.
voidsetRightIndent(float indent)
Sets the right paragraph lines indent.
voidsetRunDirection(int runDirection)
Sets the run direction.
voidsetSimpleColumn(Phrase phrase, float llx, float lly, float urx, float ury, float leading, int alignment)
Simplified method for rectangular columns.
voidsetSimpleColumn(float llx, float lly, float urx, float ury, float leading, int alignment)
Simplified method for rectangular columns.
voidsetSimpleColumn(float llx, float lly, float urx, float ury)
Simplified method for rectangular columns.
protected voidsetSimpleVars(ColumnText org)
voidsetSpaceCharRatio(float spaceCharRatio)
Sets the ratio between the extra word spacing and the extra character spacing when the text is fully justified.
voidsetText(Phrase phrase)
Replaces the current text array with this Phrase.
voidsetUseAscender(boolean useAscender)
Enables/Disables adjustment of first line height based on max ascender.
voidsetYLine(float yLine)
Sets the yLine.
static voidshowTextAligned(PdfContentByte canvas, int alignment, Phrase phrase, float x, float y, float rotation, int runDirection, int arabicOptions)
Shows a line of text.
static voidshowTextAligned(PdfContentByte canvas, int alignment, Phrase phrase, float x, float y, float rotation)
Shows a line of text.
voidupdateFilledWidth(float w)
Replaces the filledWidth if greater than the existing one.
booleanzeroHeightElement()
Checks if the element has a height of 0.

Field Detail

AR_COMPOSEDTASHKEEL

public static final int AR_COMPOSEDTASHKEEL
Compose the tashkeel in the ligatures.

AR_LIG

public static final int AR_LIG
Do some extra double ligatures.

AR_NOVOWEL

public static final int AR_NOVOWEL
Eliminate the arabic vowels

adjustFirstLine

private boolean adjustFirstLine

alignment

protected int alignment
The column alignment. Default is left alignment.

arabicOptions

private int arabicOptions
Holds value of property arabicOptions.

bidiLine

protected BidiLine bidiLine
The chunks that form the text.

canvas

protected PdfContentByte canvas
The PdfContent where the text will be written to.

canvases

protected PdfContentByte[] canvases

composite

protected boolean composite

compositeColumn

protected ColumnText compositeColumn

compositeElements

protected LinkedList compositeElements

currentLeading

protected float currentLeading
The leading for the current line.

descender

protected float descender

DIGITS_AN2EN

public static final int DIGITS_AN2EN
Digit shaping option: Replace Arabic-Indic digits by European digits (U+0030...U+0039).

DIGITS_EN2AN

public static final int DIGITS_EN2AN
Digit shaping option: Replace European digits (U+0030...U+0039) by Arabic-Indic digits.

DIGITS_EN2AN_INIT_AL

public static final int DIGITS_EN2AN_INIT_AL
Digit shaping option: Replace European digits (U+0030...U+0039) by Arabic-Indic digits if the most recent strongly directional character is an Arabic letter (its Bidi direction value is RIGHT_TO_LEFT_ARABIC). The initial state at the start of the text is assumed to be an Arabic, letter, so European digits at the start of the text will change. Compare to DIGITS_ALEN2AN_INT_LR.

DIGITS_EN2AN_INIT_LR

public static final int DIGITS_EN2AN_INIT_LR
Digit shaping option: Replace European digits (U+0030...U+0039) by Arabic-Indic digits if the most recent strongly directional character is an Arabic letter (its Bidi direction value is RIGHT_TO_LEFT_ARABIC). The initial state at the start of the text is assumed to be not an Arabic, letter, so European digits at the start of the text will not change. Compare to DIGITS_ALEN2AN_INIT_AL.

DIGIT_TYPE_AN

public static final int DIGIT_TYPE_AN
Digit type option: Use Arabic-Indic digits (U+0660...U+0669).

DIGIT_TYPE_AN_EXTENDED

public static final int DIGIT_TYPE_AN_EXTENDED
Digit type option: Use Eastern (Extended) Arabic-Indic digits (U+06f0...U+06f9).

extraParagraphSpace

protected float extraParagraphSpace
The extra space between paragraphs.

filledWidth

private float filledWidth
Holds value of property filledWidth.

firstLineY

private float firstLineY

firstLineYDone

private boolean firstLineYDone

fixedLeading

protected float fixedLeading
The fixed text leading.

followingIndent

protected float followingIndent
The following paragraph lines indent.

GLOBAL_SPACE_CHAR_RATIO

public static final float GLOBAL_SPACE_CHAR_RATIO
the space char ratio

indent

protected float indent
The first paragraph line indent.

lastWasNewline

private boolean lastWasNewline

leftWall

protected ArrayList leftWall
The left column bound.

leftX

protected float leftX

linesWritten

private int linesWritten
Holds value of property linesWritten.

lineStatus

protected int lineStatus
The line status when trying to fit a line to a column.

listIdx

protected int listIdx

LINE_STATUS_NOLINE

protected static final int LINE_STATUS_NOLINE
The line cannot fit this column position.

LINE_STATUS_OFFLIMITS

protected static final int LINE_STATUS_OFFLIMITS
The line is out the column limits.

LINE_STATUS_OK

protected static final int LINE_STATUS_OK
The column is valid.

maxY

protected float maxY
Upper bound of the column.

minY

protected float minY
Lower bound of the column.

multipliedLeading

protected float multipliedLeading
The text leading that is multiplied by the biggest font size in the line.

NO_MORE_COLUMN

public static final int NO_MORE_COLUMN
Signals that there is no more column.

NO_MORE_TEXT

public static final int NO_MORE_TEXT
Signals that there is no more text available.

rectangularMode

protected boolean rectangularMode

rectangularWidth

protected float rectangularWidth
The width of the line when the column is defined as a simple rectangle.

rightIndent

protected float rightIndent
The right paragraph lines indent.

rightWall

protected ArrayList rightWall
The right column bound.

rightX

protected float rightX

runDirection

protected int runDirection

spaceCharRatio

private float spaceCharRatio
Holds value of property spaceCharRatio.

splittedRow

private boolean splittedRow

START_COLUMN

public static final int START_COLUMN
Initial value of the status.

useAscender

private boolean useAscender
if true, first line height is adjusted so that the max ascender touches the top

waitPhrase

protected Phrase waitPhrase

yLine

protected float yLine
The current y line location. Text will be written at this line minus the leading.

Constructor Detail

ColumnText

public ColumnText(PdfContentByte canvas)
Creates a ColumnText.

Parameters: canvas the place where the text will be written to. Can be a template.

Method Detail

addElement

public void addElement(Element element)
Adds an element. Elements supported are Paragraph, List, PdfPTable, Image and Graphic.

It removes all the text placed with addText().

Parameters: element the Element

addText

public void addText(Phrase phrase)
Adds a Phrase to the current text array. Will not have any effect if addElement() was called before.

Parameters: phrase the text

addText

public void addText(Chunk chunk)
Adds a Chunk to the current text array. Will not have any effect if addElement() was called before.

Parameters: chunk the text

addWaitingPhrase

private void addWaitingPhrase()

clearChunks

public void clearChunks()
Clears the chunk array. A call to go() will always return NO_MORE_TEXT.

convertColumn

protected ArrayList convertColumn(float[] cLine)
Converts a sequence of lines representing one of the column bounds into an internal format.

Each array element will contain a float[4] representing the line x = ax + b.

Parameters: cLine the column array

Returns: the converted array

duplicate

public static ColumnText duplicate(ColumnText org)
Creates an independent duplicated of the instance org.

Parameters: org the original ColumnText

Returns: the duplicated

findLimitsOneLine

protected float[] findLimitsOneLine()
Finds the intersection between the yLine and the two column bounds. It will set the lineStatus appropriately.

Returns: a float[2]with the x coordinates of the intersection

findLimitsPoint

protected float findLimitsPoint(ArrayList wall)
Finds the intersection between the yLine and the column. It will set the lineStatus appropriately.

Parameters: wall the column to intersect

Returns: the x coordinate of the intersection

findLimitsTwoLines

protected float[] findLimitsTwoLines()
Finds the intersection between the yLine, the yLine-leadingand the two column bounds. It will set the lineStatus appropriately.

Returns: a float[4]with the x coordinates of the intersection

getAlignment

public int getAlignment()
Gets the alignment.

Returns: the alignment

getArabicOptions

public int getArabicOptions()
Gets the arabic shaping options.

Returns: the arabic shaping options

getCanvas

public PdfContentByte getCanvas()
Gets the canvas. If a set of four canvases exists, the TEXTCANVAS is returned.

Returns: a PdfContentByte.

getCanvases

public PdfContentByte[] getCanvases()
Gets the canvases.

Returns: an array of PdfContentByte

getDescender

public float getDescender()
Gets the biggest descender value of the last line written.

Returns: the biggest descender value of the last line written

getExtraParagraphSpace

public float getExtraParagraphSpace()
Sets the extra space between paragraphs.

Returns: the extra space between paragraphs

getFilledWidth

public float getFilledWidth()
Gets the real width used by the largest line.

Returns: the real width used by the largest line

getFollowingIndent

public float getFollowingIndent()
Gets the following paragraph lines indent.

Returns: the indent

getIndent

public float getIndent()
Gets the first paragraph line indent.

Returns: the indent

getLeading

public float getLeading()
Gets the fixed leading.

Returns: the leading

getLinesWritten

public int getLinesWritten()
Gets the number of lines written.

Returns: the number of lines written

getMultipliedLeading

public float getMultipliedLeading()
Gets the variable leading.

Returns: the leading

getRightIndent

public float getRightIndent()
Gets the right paragraph lines indent.

Returns: the indent

getRunDirection

public int getRunDirection()
Gets the run direction.

Returns: the run direction

getSpaceCharRatio

public float getSpaceCharRatio()
Gets the space/character extra spacing ratio for fully justified text.

Returns: the space/character extra spacing ratio

getWidth

public static float getWidth(Phrase phrase, int runDirection, int arabicOptions)
Gets the width that the line will occupy after writing. Only the width of the first line is returned.

Parameters: phrase the Phrase containing the line runDirection the run direction arabicOptions the options for the arabic shaping

Returns: the width of the line

getWidth

public static float getWidth(Phrase phrase)
Gets the width that the line will occupy after writing. Only the width of the first line is returned.

Parameters: phrase the Phrase containing the line

Returns: the width of the line

getYLine

public float getYLine()
Gets the yLine.

Returns: the yLine

go

public int go()
Outputs the lines to the document. It is equivalent to go(false).

Returns: returns the result of the operation. It can be NO_MORE_TEXT and/or NO_MORE_COLUMN

Throws: DocumentException on error

go

public int go(boolean simulate)
Outputs the lines to the document. The output can be simulated.

Parameters: simulate true to simulate the writing to the document

Returns: returns the result of the operation. It can be NO_MORE_TEXT and/or NO_MORE_COLUMN

Throws: DocumentException on error

goComposite

protected int goComposite(boolean simulate)

hasMoreText

public static boolean hasMoreText(int status)
Checks the status variable and looks if there's still some text.

isAdjustFirstLine

public boolean isAdjustFirstLine()
Gets the first line adjustment property.

Returns: the first line adjustment property.

isUseAscender

public boolean isUseAscender()
Checks if UseAscender is enabled/disabled.

Returns: true is the adjustment of the first line height is based on max ascender.

setACopy

public ColumnText setACopy(ColumnText org)
Makes this instance an independent copy of org.

Parameters: org the original ColumnText

Returns: itself

setAdjustFirstLine

public void setAdjustFirstLine(boolean adjustFirstLine)
Sets the first line adjustment. Some objects have properties, like spacing before, that behave differently if the object is the first to be written after go() or not. The first line adjustment is true by default but can be changed if several objects are to be placed one after the other in the same column calling go() several times.

Parameters: adjustFirstLine true to adjust the first line, false otherwise

setAlignment

public void setAlignment(int alignment)
Sets the alignment.

Parameters: alignment the alignment

setArabicOptions

public void setArabicOptions(int arabicOptions)
Sets the arabic shaping options. The option can be AR_NOVOWEL, AR_COMPOSEDTASHKEEL and AR_LIG.

Parameters: arabicOptions the arabic shaping options

setCanvas

public void setCanvas(PdfContentByte canvas)
Sets the canvas. If before a set of four canvases was set, it is being unset.

Parameters: canvas

setCanvases

public void setCanvases(PdfContentByte[] canvases)
Sets the canvases.

Parameters: canvases

setColumns

public void setColumns(float[] leftLine, float[] rightLine)
Sets the columns bounds. Each column bound is described by a float[] with the line points [x1,y1,x2,y2,...]. The array must have at least 4 elements.

Parameters: leftLine the left column bound rightLine the right column bound

setExtraParagraphSpace

public void setExtraParagraphSpace(float extraParagraphSpace)
Sets the extra space between paragraphs.

Parameters: extraParagraphSpace the extra space between paragraphs

setFilledWidth

public void setFilledWidth(float filledWidth)
Sets the real width used by the largest line. Only used to set it to zero to start another measurement.

Parameters: filledWidth the real width used by the largest line

setFollowingIndent

public void setFollowingIndent(float indent)
Sets the following paragraph lines indent.

Parameters: indent the indent

setIndent

public void setIndent(float indent)
Sets the first paragraph line indent.

Parameters: indent the indent

setLeading

public void setLeading(float leading)
Sets the leading to fixed.

Parameters: leading the leading

setLeading

public void setLeading(float fixedLeading, float multipliedLeading)
Sets the leading fixed and variable. The resultant leading will be fixedLeading+multipliedLeading*maxFontSize where maxFontSize is the size of the biggest font in the line.

Parameters: fixedLeading the fixed leading multipliedLeading the variable leading

setRightIndent

public void setRightIndent(float indent)
Sets the right paragraph lines indent.

Parameters: indent the indent

setRunDirection

public void setRunDirection(int runDirection)
Sets the run direction.

Parameters: runDirection the run direction

setSimpleColumn

public void setSimpleColumn(Phrase phrase, float llx, float lly, float urx, float ury, float leading, int alignment)
Simplified method for rectangular columns.

Parameters: phrase a Phrase llx the lower left x corner lly the lower left y corner urx the upper right x corner ury the upper right y corner leading the leading alignment the column alignment

setSimpleColumn

public void setSimpleColumn(float llx, float lly, float urx, float ury, float leading, int alignment)
Simplified method for rectangular columns.

Parameters: llx the lower left x corner lly the lower left y corner urx the upper right x corner ury the upper right y corner leading the leading alignment the column alignment

setSimpleColumn

public void setSimpleColumn(float llx, float lly, float urx, float ury)
Simplified method for rectangular columns.

Parameters: llx lly urx ury

setSimpleVars

protected void setSimpleVars(ColumnText org)

setSpaceCharRatio

public void setSpaceCharRatio(float spaceCharRatio)
Sets the ratio between the extra word spacing and the extra character spacing when the text is fully justified. Extra word spacing will grow spaceCharRatio times more than extra character spacing. If the ratio is PdfWriter.NO_SPACE_CHAR_RATIO then the extra character spacing will be zero.

Parameters: spaceCharRatio the ratio between the extra word spacing and the extra character spacing

setText

public void setText(Phrase phrase)
Replaces the current text array with this Phrase. Anything added previously with addElement() is lost.

Parameters: phrase the text

setUseAscender

public void setUseAscender(boolean useAscender)
Enables/Disables adjustment of first line height based on max ascender.

Parameters: useAscender enable adjustment if true

setYLine

public void setYLine(float yLine)
Sets the yLine. The line will be written to yLine-leading.

Parameters: yLine the yLine

showTextAligned

public static void showTextAligned(PdfContentByte canvas, int alignment, Phrase phrase, float x, float y, float rotation, int runDirection, int arabicOptions)
Shows a line of text. Only the first line is written.

Parameters: canvas where the text is to be written to alignment the alignment. It is not influenced by the run direction phrase the Phrase with the text x the x reference position y the y reference position rotation the rotation to be applied in degrees counterclockwise runDirection the run direction arabicOptions the options for the arabic shaping

showTextAligned

public static void showTextAligned(PdfContentByte canvas, int alignment, Phrase phrase, float x, float y, float rotation)
Shows a line of text. Only the first line is written.

Parameters: canvas where the text is to be written to alignment the alignment phrase the Phrase with the text x the x reference position y the y reference position rotation the rotation to be applied in degrees counterclockwise

updateFilledWidth

public void updateFilledWidth(float w)
Replaces the filledWidth if greater than the existing one.

Parameters: w the new filledWidth if greater than the existing one

zeroHeightElement

public boolean zeroHeightElement()
Checks if the element has a height of 0.

Returns: true or false

Since: 2.1.2