com.lowagie.text.pdf

## Class MultiColumnText

- java.lang.Object
- - com.lowagie.text.pdf.MultiColumnText

All Implemented Interfaces:
  Element

    public class MultiColumnText
    extends java.lang.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

Nested Classes
`private class` `MultiColumnText.ColumnDef` Inner class used to define a column

### Field Summary

Fields
`static float` `AUTOMATIC` special constant for automatic calculation of height
`private java.util.ArrayList` `columnDefs` Array of `ColumnDef` objects used to define the columns
`private boolean` `columnsRightToLeft`
`private ColumnText` `columnText` ColumnText object used to do all the real work.
`private int` `currentColumn`
`private float` `desiredHeight` total desiredHeight of columns.
`private PdfDocument` `document`
`private float` `nextY`
`private boolean` `overflow` true if all the text could not be written out due to height restriction
`private boolean` `simple` true if all columns are simple (rectangular)
`private float` `top` Top of the columns - y position on starting page.
`private float` `totalHeight` total height of element written out so far

### Fields inherited from interface com.lowagie.text.Element

`ALIGN_BASELINE, ALIGN_BOTTOM, ALIGN_CENTER, ALIGN_JUSTIFIED, ALIGN_JUSTIFIED_ALL, ALIGN_LEFT, ALIGN_MIDDLE, ALIGN_RIGHT, ALIGN_TOP, ALIGN_UNDEFINED, ANCHOR, ANNOTATION, AUTHOR, CCITT_BLACKIS1, CCITT_ENCODEDBYTEALIGN, CCITT_ENDOFBLOCK, CCITT_ENDOFLINE, CCITTG3_1D, CCITTG3_2D, CCITTG4, CELL, CHAPTER, CHUNK, CREATIONDATE, CREATOR, HEADER, IMGRAW, IMGTEMPLATE, JBIG2, JPEG, JPEG2000, KEYWORDS, LIST, LISTITEM, MARKED, MULTI_COLUMN_TEXT, PARAGRAPH, PHRASE, PRODUCER, PTABLE, RECTANGLE, ROW, SECTION, SUBJECT, TABLE, TITLE, YMARK`

### Constructor Summary

Constructors
Constructor and Description
`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

Methods
`void` `addColumn(float[] left, float[] right)` Add a new column.
`void` `addElement(Element element)` Add an element to be rendered in a column.
`void` `addRegularColumns(float left, float right, float gutterWidth, int numColumns)` Add the specified number of evenly spaced rectangular columns.
`void` `addSimpleColumn(float left, float right)` Add a simple rectangular column with specified left and right x position boundaries.
`void` `addText(Chunk chunk)` Adds a `Chunk` to the current text array.
`void` `addText(Phrase phrase)` Adds a `Phrase` to the current text array.
`java.util.ArrayList` `getChunks()` Returns null - not used
`private float` `getColumnBottom()` Calculates the appropriate y position for the bottom of the columns on this page.
`int` `getCurrentColumn()` Gets the current column.
`private float` `getHeight(float[] left, float[] right)` Figure out the height of a column from the border extents
`boolean` `isContent()` Checks if this element is a content object.
`boolean` `isNestable()` Checks if this element is nestable.
`boolean` `isOverflow()` Indicates that all of the text did not fit in the specified height.
`private void` `newPage()`
`void` `nextColumn()` Moves the text insertion point to the beginning of the next column, issuing a page break if needed.
`boolean` `process(ElementListener listener)` Processes the element by adding it to an `ElementListener`.
`void` `resetCurrentColumn()` Resets the current column.
`void` `setAlignment(int alignment)` Sets the default alignment
`void` `setArabicOptions(int arabicOptions)` Sets the arabic shaping options.
`void` `setColumnsRightToLeft(boolean direction)` Sets the direction of the columns.
`void` `setRunDirection(int runDirection)` Sets the run direction.
`void` `setSpaceCharRatio(float spaceCharRatio)` Sets the ratio between the extra word spacing and the extra character spacing when the text is fully justified.
`boolean` `shiftCurrentColumn()` Shifts the current column.
`int` `type()` Gets the type of the text element.
`void` `useColumnParams(ColumnText sourceColumn)` Copy the parameters from the specified ColumnText to use when rendering.
`float` `write(PdfContentByte canvas, PdfDocument document, float documentY)` Write out the columns.

### Methods inherited from class java.lang.Object

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

### Methods inherited from interface com.lowagie.text.Element

`toString`

### Field Detail

#### AUTOMATIC

    public static final float AUTOMATIC

special constant for automatic calculation of height

See Also:
  Constant Field Values

#### desiredHeight

    private float desiredHeight

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

#### totalHeight

    private float totalHeight

total height of element written out so far

#### overflow

    private boolean overflow

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

#### top

    private float top

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

#### columnText

    private ColumnText columnText

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

#### columnDefs

    private java.util.ArrayList columnDefs

Array of `ColumnDef` objects used to define the columns

#### simple

    private boolean simple

true if all columns are simple (rectangular)

#### currentColumn

    private int currentColumn

#### nextY

    private float nextY

#### columnsRightToLeft

    private boolean columnsRightToLeft

#### document

    private PdfDocument document

### 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

#### 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

#### 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` -

#### 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

#### 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

#### 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

#### 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

#### addElement

    public void addElement(Element element)
                    throws DocumentException

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

#### write

    public float write(PdfContentByte canvas,
              PdfDocument document,
              float documentY)
                throws DocumentException

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

#### newPage

    private void newPage()
                  throws DocumentException

Throws:
  `DocumentException`

#### 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

#### process

    public boolean process(ElementListener listener)

Processes the element by adding it to an `ElementListener`.

Specified by:
  `process` in interface `Element`
Parameters:
  `listener` - an `ElementListener`
Returns:
  `true` if the element was processed successfully

#### type

    public int type()

Gets the type of the text element.

Specified by:
  `type` in interface `Element`
Returns:
  a type

#### getChunks

    public java.util.ArrayList getChunks()

Returns null - not used

Specified by:
  `getChunks` in interface `Element`
Returns:
  null

#### isContent

    public boolean isContent()

Description copied from interface: `Element`
Checks if this element is a content object. If not, it's a metadata object.

Specified by:
  `isContent` in interface `Element`
Returns:
  true if this is a 'content' element; false if this is a 'metadata' element
Since:
  iText 2.0.8
See Also:
  `Element.isContent()`

#### isNestable

    public boolean isNestable()

Description copied from interface: `Element`
Checks if this element is nestable.

Specified by:
  `isNestable` in interface `Element`
Returns:
  true if this element can be nested inside other elements.
Since:
  iText 2.0.8
See Also:
  `Element.isNestable()`

#### 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

#### nextColumn

    public void nextColumn()
                    throws DocumentException

Moves the text insertion point to the beginning of the next column, issuing a page break if needed.

Throws:
  `DocumentException` - on error

#### getCurrentColumn

    public int getCurrentColumn()

Gets the current column.

Returns:
  the current column

#### resetCurrentColumn

    public void resetCurrentColumn()

Resets the current column.

#### shiftCurrentColumn

    public boolean shiftCurrentColumn()

Shifts the current column.

Returns:
  true if the current column has changed

#### setColumnsRightToLeft

    public void setColumnsRightToLeft(boolean direction)

Sets the direction of the columns.

Parameters:
  `direction` - true = right2left; false = left2right

#### 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

#### setRunDirection

    public void setRunDirection(int runDirection)

Sets the run direction.

Parameters:
  `runDirection` - the run direction

#### 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

#### setAlignment

    public void setAlignment(int alignment)

Sets the default alignment

Parameters:
  `alignment` - the default alignment