com.lowagie.text.pdf

Class MultiColumnText

public class MultiColumnText extends Object implements Element

Formats content into one or more columns bounded by a rectangle. The columns may be simple rectangles or more complicated shapes. Add all of the columns before adding content. Column continuation is supported. A MultiColumnText object may be added to a document using Document.add.

Author: Steve Appling

Nested Class Summary
classMultiColumnText.ColumnDef
Inner class used to define a column
Field Summary
static floatAUTOMATIC
special constant for automatic calculation of height
ArrayListcolumnDefs
Array of ColumnDef objects used to define the columns
booleancolumnsRightToLeft
ColumnTextcolumnText
ColumnText object used to do all the real work.
intcurrentColumn
floatdesiredHeight
total desiredHeight of columns.
PdfDocumentdocument
floatnextY
booleanoverflow
true if all the text could not be written out due to height restriction
floatpageBottom
used to store the y position of the bottom of the page
booleansimple
true if all columns are simple (rectangular)
floattop
Top of the columns - y position on starting page.
floattotalHeight
total height of element written out so far
Constructor Summary
MultiColumnText()
Default constructor.
MultiColumnText(float height)
Construct a MultiColumnText container of the specified height.
MultiColumnText(float top, float height)
Construct a MultiColumnText container of the specified height starting at the specified Y position.
Method Summary
voidaddColumn(float[] left, float[] right)
Add a new column.
voidaddElement(Element element)
Add an element to be rendered in a column.
voidaddRegularColumns(float left, float right, float gutterWidth, int numColumns)
Add the specified number of evenly spaced rectangular columns.
voidaddSimpleColumn(float left, float right)
Add a simple rectangular column with specified left and right x position boundaries.
voidaddText(Phrase phrase)
Adds a Phrase to the current text array.
voidaddText(Chunk chunk)
Adds a Chunk to the current text array.
ArrayListgetChunks()
Returns null - not used
floatgetColumnBottom()
Calculates the appropriate y position for the bottom of the columns on this page.
intgetCurrentColumn()
Gets the current column.
floatgetHeight(float[] left, float[] right)
Figure out the height of a column from the border extents
booleanisContent()
booleanisNestable()
booleanisOverflow()
Indicates that all of the text did not fit in the specified height.
voidnewPage()
voidnextColumn()
Moves the text insertion point to the beginning of the next column, issuing a page break if needed.
booleanprocess(ElementListener listener)
Processes the element by adding it to an ElementListener.
voidresetCurrentColumn()
Resets the current column.
voidsetAlignment(int alignment)
Sets the default alignment
voidsetArabicOptions(int arabicOptions)
Sets the arabic shaping options.
voidsetColumnsRightToLeft(boolean direction)
Sets the direction of the columns.
voidsetRunDirection(int runDirection)
Sets the run direction.
voidsetSpaceCharRatio(float spaceCharRatio)
Sets the ratio between the extra word spacing and the extra character spacing when the text is fully justified.
booleanshiftCurrentColumn()
Shifts the current column.
inttype()
Gets the type of the text element.
voiduseColumnParams(ColumnText sourceColumn)
Copy the parameters from the specified ColumnText to use when rendering.
floatwrite(PdfContentByte canvas, PdfDocument document, float documentY)
Write out the columns.

Field Detail

AUTOMATIC

public static final float AUTOMATIC
special constant for automatic calculation of height

columnDefs

private ArrayList columnDefs
Array of ColumnDef objects used to define the columns

columnsRightToLeft

private boolean columnsRightToLeft

columnText

private ColumnText columnText
ColumnText object used to do all the real work. This same object is used for all columns

currentColumn

private int currentColumn

desiredHeight

private float desiredHeight
total desiredHeight of columns. If AUTOMATIC, this means fill pages until done. This may be larger than one page

document

private PdfDocument document

nextY

private float nextY

overflow

private boolean overflow
true if all the text could not be written out due to height restriction

pageBottom

private float pageBottom
used to store the y position of the bottom of the page

simple

private boolean simple
true if all columns are simple (rectangular)

top

private float top
Top of the columns - y position on starting page. If AUTOMATIC, it means current y position when added to document

totalHeight

private float totalHeight
total height of element written out so far

Constructor Detail

MultiColumnText

public MultiColumnText()
Default constructor. Sets height to AUTOMATIC. Columns will repeat on each page as necessary to accommodate content length.

MultiColumnText

public MultiColumnText(float height)
Construct a MultiColumnText container of the specified height. If height is AUTOMATIC, fill complete pages until done. If a specific height is used, it may span one or more pages.

Parameters: height

MultiColumnText

public MultiColumnText(float top, float height)
Construct a MultiColumnText container of the specified height starting at the specified Y position.

Parameters: height top

Method Detail

addColumn

public void addColumn(float[] left, float[] right)
Add a new column. The parameters are limits for each column wall in the format of a sequence of points (x1,y1,x2,y2,...).

Parameters: left limits for left column right limits for right column

addElement

public void addElement(Element element)
Add an element to be rendered in a column. Note that you can only add a Phrase or a Chunk if the columns are not all simple. This is an underlying restriction in ColumnText

Parameters: element element to add

Throws: DocumentException if element can't be added

addRegularColumns

public void addRegularColumns(float left, float right, float gutterWidth, int numColumns)
Add the specified number of evenly spaced rectangular columns. Columns will be separated by the specified gutterWidth.

Parameters: left left boundary of first column right right boundary of last column gutterWidth width of gutter spacing between columns numColumns number of columns to add

addSimpleColumn

public void addSimpleColumn(float left, float right)
Add a simple rectangular column with specified left and right x position boundaries.

Parameters: left left boundary right right boundary

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

Since: 2.1.5

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

Since: 2.1.5

getChunks

public ArrayList getChunks()
Returns null - not used

Returns: null

getColumnBottom

private float getColumnBottom()
Calculates the appropriate y position for the bottom of the columns on this page.

Returns: the y position of the bottom of the columns

getCurrentColumn

public int getCurrentColumn()
Gets the current column.

Returns: the current column

getHeight

private float getHeight(float[] left, float[] right)
Figure out the height of a column from the border extents

Parameters: left left border right right border

Returns: height

isContent

public boolean isContent()

Since: iText 2.0.8

See Also: isContent

isNestable

public boolean isNestable()

Since: iText 2.0.8

See Also: isNestable

isOverflow

public boolean isOverflow()
Indicates that all of the text did not fit in the specified height. Note that isOverflow will return false before the MultiColumnText object has been added to the document. It will always be false if the height is AUTOMATIC.

Returns: true if there is still space left in the column

newPage

private void newPage()

nextColumn

public void nextColumn()
Moves the text insertion point to the beginning of the next column, issuing a page break if needed.

Throws: DocumentException on error

process

public boolean process(ElementListener listener)
Processes the element by adding it to an ElementListener.

Parameters: listener an ElementListener

Returns: true if the element was processed successfully

resetCurrentColumn

public void resetCurrentColumn()
Resets the current column.

setAlignment

public void setAlignment(int alignment)
Sets the default alignment

Parameters: alignment the default 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

setColumnsRightToLeft

public void setColumnsRightToLeft(boolean direction)
Sets the direction of the columns.

Parameters: direction true = right2left; false = left2right

setRunDirection

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

Parameters: runDirection the run direction

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

shiftCurrentColumn

public boolean shiftCurrentColumn()
Shifts the current column.

Returns: true if the current column has changed

type

public int type()
Gets the type of the text element.

Returns: a type

useColumnParams

public void useColumnParams(ColumnText sourceColumn)
Copy the parameters from the specified ColumnText to use when rendering. Parameters like setArabicOptions must be set in this way.

Parameters: sourceColumn

write

public float write(PdfContentByte canvas, PdfDocument document, float documentY)
Write out the columns. After writing, use isOverflow to see if all text was written.

Parameters: canvas PdfContentByte to write with document document to write to (only used to get page limit info) documentY starting y position to begin writing at

Returns: the current height (y position) after writing the columns

Throws: DocumentException on error