layoutbox.java

Java生成PDF Java生成PDF Java生成PDF

// $Id: LayoutBox.java,v 1.6 2003/11/04 17:16:01 mike Exp $

package org.faceless.pdf;

import java.util.*;
import java.text.*;

/**
 * <p>
 * A <code>LayoutBox</code> is a box for laying out text, which allows a great
 * deal more control over positioning than the standard
 * {@link PDFPage#drawText drawText} method.
 * </p><p>
 * 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 {@link PDFPage#drawLayoutBox PDFPage.drawLayoutBox} method. At its simplest, the
 * following will create a single line of Text on the page.
 * </p>
 * <pre>
 *   PDFStyle style = new PDFStyle();
 *   style.setFont(new StandardFont(StandardFont.HELVETICA), 12);
 *   style.setFillColor(Color.black);
 * 
 *   <b>LayoutBox box = new LayoutBox(page.getWidth()-100);</b>
 *   <b>box.addText("Hello, World", style, Locale.getDefault());</b>
 *   <b>page.drawLayoutBox(box, 50, page.getHeight()-50);</b>
 * </pre>
 * <p>
 * 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:
 * </p>
 * <pre>
 *   PDFStyle style = new PDFStyle();
 *   style.setFont(new StandardFont(StandardFont.HELVETICA), 12);
 *   style.setFillColor(Color.black);
 * 
 *   LayoutBox box = new LayoutBox(page.getWidth()-100);
 *   <b>LayoutBox.Box imagebox = box.addBoxLeft(100,100, PDFStyle.TEXTALIGN_BASELINE);</b>
 *   imagebox.setImage(myimage);
 *   box.addText("Hello, World", style, Locale.getDefault());
 *
 *   page.drawLayoutBox(box, 50, page.getHeight()-50);
 * </pre>
 * <p>
 * Images can also be drawn inline with the {@link #addBoxInline addBoxInline} method, or to
 * the right with the {@link #addBoxRight addBoxRight} method.
 * </p>
 *
 * @since 1.2
 * @version $Id: LayoutBox.java,v 1.6 2003/11/04 17:16:01 mike Exp $
 */
public class LayoutBox extends PeeredObject
{
    /**
     * A flag indicating that the Box created by {@link #addBoxLeft} or {@link #addBoxRight}
     * does not require either a left or right margin to line up against.
     */
     public static final int CLEAR_NONE=0;

    /**
     * A flag indicating that the Box created by {@link #addBoxLeft} or {@link #addBoxRight}
     * should always be flat against the left margin - it should have no content to
     * its left.
     */
    public static final int CLEAR_LEFT=1;

    /**
     * A flag indicating that the Box created by {@link #addBoxLeft} or {@link #addBoxRight}
     * should always be flat against the right margin - it should have no content to
     * its right.
     */
    public static final int CLEAR_RIGHT=2;

    final org.faceless.pdf2.LayoutBox box;

    Object getPeer()
    {
        return box;
    }

    LayoutBox(org.faceless.pdf2.LayoutBox box)
    {
        this.box=box;
    }

    /**
     * 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.
     * @param width the width of the LayoutBox, in points
     */
    public LayoutBox(float width)
    {
	box = new org.faceless.pdf2.LayoutBox(width);
    }

    /**
     * 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 <code>addText</code> methods.
     *
     * @param width the width of the LayoutBox, in points
     * @param locale the overall locale of the LayoutBox
     * @since 1.2.10
     */
    public LayoutBox(float width, Locale locale)
    {
	box = new org.faceless.pdf2.LayoutBox(width, locale);
    }

    /**
     * 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 {@link #addText addText},
     * {@link #addTextNoBreak addTextNoBreak} or {@link #addLineBreak addLineBreak}
     *
     * @param style the default style of the LayoutBox
     * @see #getStyle
     */
    public void setStyle(PDFStyle style)
    {
	box.setStyle(style.style);
    }

    /** 
     * Add a line of text to the LayoutBox. The text may be broken into
     * smaller units to fit the line, in which case the {@link LayoutBox.Text#getNextTwin} method
     * can be used to traverse through them.
     * @param string the text to display
     * @param style the style in which to display the text
     * @param locale the locale of the text. With locales where this is unlikely
     * to make a difference, i.e. western european languages, this may be <code>null</code> 
     * @return a <code>Text</code> object representing this string.
     */
    public Text addText(String string, PDFStyle style, Locale locale)
    {
	return (Text)PeeredObject.getPeer(box.addText(string, style.style, locale));
    }

    /** 
     * Add a line of text to the LayoutBox. As for {@link #addText(String,PDFStyle,Locale)},
     * but the text is not ligaturized first, for speed. If it needs to be, run it
     * through the {@link PDFFont#ligaturize(char[],int,int,Locale)} method first.
     *
     * @param buf the buffer containing the text to add
     * @param off the offset of the start of the meaningful content of the buffer
     * @param len the length of the meaningful content of the buffer
     * @param style the style in which to display the text
     * @param locale the locale of the text. With locales where this is unlikely
     * to make a difference, i.e. western european languages, this may be <code>null</code> 
     * @since 1.2.1
     */
    public Text addText(char[] buf, int off, int len, PDFStyle style, Locale locale)
    {
	return (Text)PeeredObject.getPeer(box.addText(buf, off, len, style.style, 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.
     * @param string the text to display
     * @param style the style in which to display the text
     * @param locale the locale of the text. With locales where this is unlikely
     * to make a difference, i.e. western european languages, this may be <code>null</code> 
     * @return a <code>Text</code> object representing this string.
     */
    public Text addTextNoBreak(String string, PDFStyle style, Locale locale)
    {
	return (Text)PeeredObject.getPeer(box.addTextNoBreak(string, style.style, locale));
    }

    /** 
     * Add a line of text to the LayoutBox. As for {@link #addTextNoBreak(String,PDFStyle,Locale)},
     * but the text is not ligaturized first, for speed. If it needs to be, run it
     * through the {@link PDFFont#ligaturize(char[],int,int,Locale)} method first.
     *
     * @param buf the buffer containing the text to add
     * @param off the offset of the start of the meaningful content of the buffer
     * @param len the length of the meaningful content of the buffer
     * @param style the style in which to display the text
     * @param locale the locale of the text. With locales where this is unlikely
     * to make a difference, i.e. western european languages, this may be <code>null</code> 
     * @return a <code>Text</code> object representing this string.
     * @since 1.2.1
     */
    public Text addTextNoBreak(char[] buf, int off, int len, PDFStyle style, Locale locale)
    {
	return (Text)PeeredObject.getPeer(box.addTextNoBreak(buf, off, len, style.style, locale));
    }

    /**
     * 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 <tt>style.getFontLeading()</tt> points
     * @param style the style defining the font in which to add the linebreak
     */
    public void addLineBreak(PDFStyle style)
    {
	box.addLineBreak(style.style);
    }

    /**
     * Add a new Box which will be appear "inline" - i.e. positioned in the same way
     * as the text.
     * @param width the width of the rectangle
     * @param height the height of the rectangle
     * @param align how to align the text - one of {@link PDFStyle#TEXTALIGN_TOP},
     * {@link PDFStyle#TEXTALIGN_MIDDLE} or {@link PDFStyle#TEXTALIGN_BOTTOM}
     * @return a {@link LayoutBox.Box} representing this object
     */
    public Box addBoxInline(float width, float height, int align)
    {
	return (Box)PeeredObject.getPeer(box.addBoxInline(width,height,align));
    }

    /**
     * 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.
     * @param height the height of the box.
     * @since 1.2.1
     */
    public Box addBoxFullWidth(float height)
    {
	return (Box)PeeredObject.getPeer(box.addBoxFullWidth(height));
    }

    /**
     * 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 <tt>clearflags</tt>
     * @param width the width of the rectangle
     * @param height the height of the rectangle
     * @param clearflags logical-or of zero or more of {@link #CLEAR_LEFT} or {@link #CLEAR_RIGHT}
     * @return a {@link LayoutBox.Box} representing this object
     */
    public Box addBoxLeft(float width, float height, int clearflags)
    {
	return (Box)PeeredObject.getPeer(box.addBoxLeft(width,height,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 <tt>clearflags</tt>
     * @param width the width of the rectangle
     * @param height the height of the rectangle
     * @param clearflags logical-or of zero or more of {@link #CLEAR_LEFT} or {@link #CLEAR_RIGHT}
     * @return a {@link LayoutBox.Box} representing this object
     */
    public Box addBoxRight(float width, float height, int clearflags)
    {
	return (Box)PeeredObject.getPeer(box.addBoxRight(width,height,clearflags));
    }

    /**
     * <p>
     * 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, <code>{ 80, 100, 150 }</code>
     * 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.
     * </p><p>
     * 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 <code>{ 50 }</code>.
     * </p><p>
     * If there are no further tab stops available on the current line, the
     * cursor is moved to the start of the next line.
     * </p><p>
     * <b>Note</b> Tab stops only work with left-aligned text. Consequently, if the
     * alignment for the LayoutBox is anything other than <code>TEXTALIGN_LEFT</code>,
     * an exception is thrown.
     * </p>
     * @param stops an array of one or more floats defining the position of tab
     * stops in points from the left edge of the LayoutBox
     * @throws IllegalStateException if the LayoutBox is not left-aligned.
     * @return the cursor position in points from the left edge of the LayoutBox