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
    Modifier and Type | Class and Description
    --- | ---
    `private class` | `MultiColumnText.ColumnDef` Inner class used to define a column

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `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
    Modifier and Type | Method and Description
    --- | ---
    `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