Package org.faceless.pdf2

Class LayoutBox

  • public final class LayoutBox
extends java.lang.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 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.

    • Constructor Summary

      Constructors 
      Constructor Description
      LayoutBox​(float width)
      Create a new LayoutBox of the specified width.
      LayoutBox​(float width, java.util.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 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, java.util.Locale locale)
      Add a line of text to the LayoutBox.
      LayoutBox.Text addText​(java.lang.String string, PDFStyle style, java.util.Locale locale)
      Add a line of text to the LayoutBox.
      LayoutBox.Text addTextNoBreak​(char[] buf, int off, int len, PDFStyle style, java.util.Locale locale)
      Add a line of text to the LayoutBox.
      LayoutBox.Text addTextNoBreak​(java.lang.String string, PDFStyle style, java.util.Locale locale)
      Add a line of text to the LayoutBox.
      void beginTag​(java.lang.String tag, java.util.Map<java.lang.String,​java.lang.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

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

    • 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,
                 java.util.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​(java.lang.String string,
                              PDFStyle style,
                              java.util.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,
                              java.util.Locale locale)
        Add a line of text to the LayoutBox. Identical to addText(String,PDFStyle,Locale),
        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
        See Also:
        PDFStyle.setLineBreakBehaviour(int)

      • addTextNoBreak

        public LayoutBox.Text addTextNoBreak​(java.lang.String string,
                                     PDFStyle style,
                                     java.util.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,
                                     java.util.Locale locale)
        Add a line of text to the LayoutBox. Identical to addTextNoBreak(String,PDFStyle,Locale),
        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:
        java.lang.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

      • 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

      • 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()

      • 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