pdfannotation.java

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

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

package org.faceless.pdf;

import java.util.*;
import java.awt.Color;

/**
 * <p>
 * A PDFAnnotation allows the user to interact with the generated
 * PDF document, by adding / viewing rubber-stamps and popup notes
 * or following hyperlinks. A special class of annotation, called a
 * "Widget", is also used to display {@link Form} Fields on the page.
 * </p>
 * @version $Revision: 1.4 $
 * @since 1.1
 */
public class PDFAnnotation extends PeeredObject
{
    final org.faceless.pdf2.PDFAnnotation annot;

    Object getPeer()
    {
        return annot;
    }

    /**
     * Value for {@link #setEventAction} representing the event that occurs
     * when the annotation is clicked.
     * @since 1.1.23
     */
    public static final int EVENT_ONCLICK	=-1;

    /**
     * Value for {@link #setEventAction} representing the event that occurs
     * when the mouse pointer is moved over the annotation rectangle
     * @since 1.1.23
     */
    public static final int EVENT_ONMOUSEOVER   =0;

    /**
     * Value for {@link #setEventAction} representing the event that occurs
     * when the mouse pointer is moved out of the annotation rectangle
     * @since 1.1.23
     */
    public static final int EVENT_ONMOUSEOUT	=1;

    /**
     * Value for {@link #setEventAction} representing the event that occurs
     * when the mouse button is pressed over the annotation
     * @since 1.1.23
     */
    public static final int EVENT_ONMOUSEDOWN   =2;

    /**
     * Value for {@link #setEventAction} representing the event that occurs
     * when the mouse button is released over the annotation.
     * @since 1.1.23
     */
    public static final int EVENT_ONMOUSEUP	=3;

    /**
     * Value for {@link #setEventAction} representing the event that occurs
     * when the annotation gains focus.
     * Does not apply to buttons.
     * @since 1.1.23
     */
    public static final int EVENT_ONFOCUS	=4;

    /**
     * Value for {@link #setEventAction} representing the event that occurs
     * when the annotation loses focus.
     * Does not apply to buttons.
     * @since 1.1.23
     */
    public static final int EVENT_ONBLUR	=5;

    /**
     * Value for {@link #setEventAction} representing the event that occurs
     * when the annotation value changes.
     * Does not apply to buttons.
     * @since 1.1.23
     */
    public static final int EVENT_ONCHANGE	=6;

    /**
     * Value for {@link #setEventAction} representing the event that occurs
     * when a key is pressed and the annotation has focus.
     * Only applies to text boxes.
     * @since 1.1.23
     */
    public static final int EVENT_ONKEYPRESS	=7;

    /**
     * Value for {@link #setEventAction} representing the event that occurs
     * when a the contents of the annotation is being formatted for display.
     * Only applies to text boxes.
     * @since 1.1.23
     */
    public static final int EVENT_ONFORMAT	=8;

    /**
     * Value for {@link #setEventAction} representing the event that occurs
     * when <i>another</i> annotation changes - which makes this event a
     * little bit different to the others. You may set a JavaScript action
     * on this event which can recalculate the value of this field based on
     * the value of other fields (for example). Only applies to text boxes
     * @since 1.1.23
     */
    public static final int EVENT_ONOTHERCHANGE	=9;


    /**
     * A style of text annotation whose icon represents a "note" (the default).
     * The PDF spec doesn't define this any further. 
     */
    public static final int TEXT_NOTE = 0;

    /**
     * A style of text annotation whose icon represents "comment"
     * The PDF spec doesn't define this any further.
     */
    public static final int TEXT_COMMENT = 1;

    /**
     * A style of text annotation whose icon represents "help". The PDF
     * spec doesn't define this any further.
     */
    public static final int TEXT_HELP = 2;

    /**
     * A style of text annotation whose icon represents "insert". The PDF
     * spec doesn't define this any further.
     */
    public static final int TEXT_INSERT = 3;

    /**
     * A style of text annotation whose icon represents "key". The PDF
     * spec doesn't define this any further.
     */
    public static final int TEXT_KEY = 4;

    /**
     * A style of text annotation whose icon represents "new paragraph".
     * The PDF spec doesn't define this any further.
     */
    public static final int TEXT_NEWPARAGRAPH = 5;

    /**
     * A style of text annotation whose icon represents "paragraph".
     * The PDF spec doesn't define this any further.
     */
    public static final int TEXT_PARAGRAPH = 6;

    PDFAnnotation(org.faceless.pdf2.PDFAnnotation annot)
    {
	this.annot=annot;
    }

    /**
     * <p>
     * Return a new PDFAnnotation that performs the specified action
     * when clicked. This can be used to create an HTML-style hyperlink,
     * play a sound, or perform some other {@link PDFAction}. Although this
     * method can be called directly to mark a portion of the page as a
     * hyperlink, for text hyperlinks the {@link PDFPage#beginTextLink}
     * method is probably more convenient.
     * </p><p>
     * Remember to set the co-ordinates of the annotation using the
     * <code>setRectangle</code> method.
     * </p>
     * 
     * @param action the {@link PDFAction} to perform when the link is clicked
     * @param border whether to display a border around the link area
     */
    public static PDFAnnotation link(PDFAction action, boolean border)
    {
	org.faceless.pdf2.AnnotationLink link = new org.faceless.pdf2.AnnotationLink();
	link.setAction(action.action);
	if (border) {
	    org.faceless.pdf2.PDFStyle style = new org.faceless.pdf2.PDFStyle();
	    link.setStyle(style);
	}
	return new PDFAnnotation(link);
    }

    /**
     * Return a new PDFAnnotation that holds a text message. When the user clicks
     * on the annotation, a window pops up and displays the contents.
     * @param label the label to give of the popup window
     * @param contents The text to display in the window. May contain newline
     * characters for formatting.
     * @param open whether the window is open by default
     * @param type The visual appearance of the annotation when closed. May be
     * {@link #TEXT_NOTE}, {@link #TEXT_COMMENT}, {@link #TEXT_HELP},
     * {@link #TEXT_INSERT}, {@link #TEXT_KEY}, {@link #TEXT_NEWPARAGRAPH} or
     * {@link #TEXT_PARAGRAPH}
     */
    public static PDFAnnotation text(String label, String contents, boolean open, int type)
    {
	org.faceless.pdf2.AnnotationNote note = new org.faceless.pdf2.AnnotationNote();

	String newtype;
	if (type==TEXT_COMMENT) newtype = "Comment";
	else if (type==TEXT_HELP) newtype = "Help";
	else if (type==TEXT_INSERT) newtype = "Insert";
	else if (type==TEXT_KEY) newtype = "Key";
	else if (type==TEXT_NEWPARAGRAPH) newtype = "New Paragraph";
	else if (type==TEXT_PARAGRAPH) newtype = "Paragraph";
	else newtype = "Note";

	if (newtype!=null) {
	    note.setType(newtype, Color.yellow);
	}
	note.setOpen(open);
	note.setAuthor(label);
	note.setContents(contents);

	return new PDFAnnotation(note);
    }

    /**
     * Create a rubber-stamp annotation which can be added to the page.
     * Fourteen different rubber stamps are available - the parameter "type"
     * must be one of <code>Approved</code>, <code>AsIs</code>,
     * <code>Confidential</code>, <code>Departmental</code>, <code>Draft</code>,
     * <code>Experimental</code>, <code>Expired</code>, <code>Final</code>,
     * <code>ForComment</code>, <code>ForPublicRelease</code>,
     * <code>NotApproved</code>, <code>NotForPublicRelease</code>, <code>Sold</code>
     * or <code>TopSecret</code>. Any other value will result in an
     * <code>IllegalArgumengException</code> being thrown.
     * @param type the type of stamp - one of the values listed above
     * @throws IllegalArgumentException if the stamp type is unknown
     * @since 1.1.23
     */
    public static PDFAnnotation stamp(String type)
        throws IllegalArgumentException
    {
	org.faceless.pdf2.AnnotationStamp stamp = new org.faceless.pdf2.AnnotationStamp("stamp.stencil."+type, 1);
	return new PDFAnnotation(stamp);
    }

    /**
     * Set the rectangle for the annotation.
     * <ul>
     * <li>For <b>link</b> annotations, this is the rectangle that must be clicked
     * in to activate the action.</li>
     * <li>For <b>text</b> annotations, this is the rectangle describing the popup
     * window when it's opened. When it's closed, the icon is positioned at <i>x1,y1</i>.
     * </li>
     * </ul>
     * <p>
     * Note that all co-ordinates are in <b>absolute page co-ordinates</b>.
     * This means they are measured in points from the bottom-left hand
     * corner of the page, regardless of any calls to <code>rotate</code>,
     * <code>translate</code>, <code>scale</code> or <code>setCanvas</code>
     * that have been made. This restriction is part of the PDF specification.
     * </p>
     * @param x1 the X co-ordinate of the bottom-left corner of the rectangle
     * @param y1 the Y co-ordinate of the bottom-left corner of the rectangle
     * @param x2 the X co-ordinate of the top-right corner of the rectangle
     * @param y2 the Y co-ordinate of the top-right corner of the rectangle
     */
    public void setRectangle(float x1, float y1, float x2, float y2)
    {
	annot.setRectangle(x1,y1,x2,y2);
    }

    /**
     * Return the rectangle this annotation applies to on the page, or <tt>null</tt>
     * if no rectangle applies for this type of annotation.
     * @return the rectangle for this annotation, in the form of an array (<i>x1</i>, <i>y1</i>, <i>x2</i>, <i>y2</i>)
     * @since 1.1.12
     */
    public float[] getRectangle()
    {
	return annot.getRectangle();
    }

    /**
     * Get the type of annotation. Can be either "Link", "Text" or "Stamp:<i>type</i>"
     * (where <i>type</i> is the type of stamp, eg "Draft"), all of
     * which are supported by the PDF library, or one of various other annotation types
     * supported by the PDF specification but not this library.
     * @return the type of annotation
     * @since 1.1.12
     */
    public String getType()
    {
	return annot.getType();
    }

    /**
     * Return the page that this annotation is on, or <code>null</code>
     * if it a new annotation which has not yet been placed on a page
     * @since 1.1.23