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

    All Methods Instance Methods Concrete Methods
    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. As for `addText(String,PDFStyle,Locale)`, but the text is not ligaturized first, for speed. If it needs to be, run it through the `PDFFont.ligaturize(char[],int,int,Locale)` method first.
      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

    - #### 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. As for `addTextNoBreak(String,PDFStyle,Locale)`, but the text is not ligaturized first, for speed. If it needs to be, run it through the `PDFFont.ligaturize(char[],int,int,Locale)` method first.
      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

Copyright © 2001-2015 Big Faceless Organization