fop/fop-core/src/main/java/org/apache/fop/render/intermediate/IFPainter.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/* $Id$ */

package org.apache.fop.render.intermediate;

import java.awt.Color;
import java.awt.Dimension;
import java.awt.Paint;
import java.awt.Point;
import java.awt.Rectangle;
import java.awt.geom.AffineTransform;

import org.w3c.dom.Document;

import org.apache.fop.traits.BorderProps;
import org.apache.fop.traits.RuleStyle;

/**
 * Interface used to paint whole documents layouted by Apache FOP.
 * <p>
 * Call sequence:
 * <p>
 * <pre>
 * startDocument()
 *   startDocumentHeader()
 *   [handleExtension()]*
 *   endDocumentHeader()
 *   [
 *   startPageSequence()
 *     [
 *     startPage()
 *       startPageHeader()
 *         [handleExtension()]*
 *       endPageHeader()
 *       startPageContent()
 *         (#pageContent)+
 *       endPageContent()
 *       startPageTrailer()
 *         (addTarget())*
 *       endPageTrailer()
 *     endPage()
 *     ]*
 *   endPageSequence()
 *   ]*
 *   startDocumentTrailer()
 *   [handleExtension()]*
 *   endDocumentTrailer()
 * endDocument()
 *
 * #box:
 * startBox()
 * (#pageContent)+
 * endBox()
 *
 * #pageContent:
 * (
 *   setFont() |
 *   drawText() |
 *   drawRect() |
 *   drawImage() |
 *   TODO etc. etc. |
 *   handleExtensionObject()
 * )
 * </pre>
 */
public interface IFPainter {

    /**
     * Starts a new viewport, establishing a new coordinate system. A viewport has a size and
     * can optionally be clipped. Corresponds to SVG's svg element.
     * @param transform the transformation matrix establishing the new coordinate system
     * @param size the size of the viewport
     * @param clipRect the clipping rectangle (may be null)
     * @throws IFException if an error occurs while handling this element
     */
    void startViewport(AffineTransform transform, Dimension size, Rectangle clipRect)
        throws IFException;

    /**
     * Starts a new viewport, establishing a new coordinate system. A viewport has a size and
     * can optionally be clipped. Corresponds to SVG's svg element.
     * @param transforms a series of transformation matrices establishing the new coordinate system
     * @param size the size of the viewport
     * @param clipRect the clipping rectangle (may be null)
     * @throws IFException if an error occurs while handling this element
     */
    void startViewport(AffineTransform[] transforms, Dimension size, Rectangle clipRect)
        throws IFException;
    //For transform, Batik's org.apache.batik.parser.TransformListHandler/Parser can be used

    /**
     * Ends the current viewport and restores the previous coordinate system.
     * @throws IFException if an error occurs while handling this element
     */
    void endViewport() throws IFException;

    /**
     * Starts a new group of graphical elements. Corresponds to SVG's g element.
     * @param transforms a series of transformation matrices establishing the new coordinate system
     * @param layer an optional layer label (or null if none)
     * @throws IFException if an error occurs while handling this element
     */
    void startGroup(AffineTransform[] transforms, String layer) throws IFException;

    /**
     * Starts a new group of graphical elements. Corresponds to SVG's g element.
     * @param transform the transformation matrix establishing the new coordinate system
     * @param layer an optional layer label (or null if none)
     * @throws IFException if an error occurs while handling this element
     */
    void startGroup(AffineTransform transform, String layer) throws IFException;

    /**
     * Ends the current group and restores the previous coordinate system (and layer).
     * @throws IFException if an error occurs while handling this element
     */
    void endGroup() throws IFException;

    /**
     * Updates the current font.
     * @param family the font family (or null if there's no change)
     * @param style the font style (or null if there's no change)
     * @param weight the font weight (or null if there's no change)
     * @param variant the font variant (or null if there's no change)
     * @param size the font size (or null if there's no change)
     * @param color the text color (or null if there's no change)
     * @throws IFException if an error occurs while handling this event
     */
    void setFont(String family, String style, Integer weight, String variant, Integer size,
            Color color) throws IFException;

    /**
     * Draws text. The initial coordinates (x and y) point to the starting point at the normal
     * baseline of the font. The parameters letterSpacing, wordSpacing and the array dx are
     * optional and can be used to influence character positioning (for example, for kerning).
     * @param x X-coordinate of the starting point of the text
     * @param y Y-coordinate of the starting point of the text
     * @param letterSpacing additional spacing between characters (may be 0)
     * @param wordSpacing additional spacing between words (may be 0)
     * @param dp an array of 4-tuples, expressing [X,Y] placment
     * adjustments and [X,Y] advancement adjustments, in that order (may be null); if
     * not null, then adjustments.length must be the same as text.length()
     * @param text the text
     * @throws IFException if an error occurs while handling this event
     */
    void drawText(int x, int y, int letterSpacing, int wordSpacing,
            int[][] dp, String text) throws IFException;

    /**
     * Restricts the current clipping region with the given rectangle.
     * @param rect the rectangle's coordinates and extent
     * @throws IFException if an error occurs while handling this event
     */
    void clipRect(Rectangle rect) throws IFException;
    //TODO clipRect() shall be considered temporary until verified with SVG and PCL


    /**
     * Restricts the current clipping region to the inner border.
     * @param rect the rectangle's coordinates and extent
     * @param bpsBefore the border segment on the before-side (top)
     * @param bpsAfter the border segment on the after-side (bottom)
     * @param bpsStart the border segment on the start-side (left)
     * @param bpsEnd the border segment on the end-side (right)
     * @throws IFException if an error occurs while handling this event
     */
    void clipBackground(Rectangle rect,
            BorderProps bpsBefore, BorderProps bpsAfter,
            BorderProps bpsStart, BorderProps bpsEnd) throws IFException;


    /**
     * TODO Painter-specific rounded borders logic required background drawing to be
     * made optional.  A future refactoring of the rounded borders code should aim to make
     * the need for this abstraction obsolete
     * @param bpsBefore the before border
     * @param bpsAfter the after border
     * @param bpsStart the start border
     * @param bpsEnd the end border
     * @return true if and only if background drawing is required
     */
    boolean isBackgroundRequired(BorderProps bpsBefore, BorderProps bpsAfter,
            BorderProps bpsStart, BorderProps bpsEnd);

    /**
     * Fills a rectangular area.
     * @param rect the rectangle's coordinates and extent
     * @param fill the fill paint
     * @throws IFException if an error occurs while handling this event
     */
    void fillRect(Rectangle rect, Paint fill) throws IFException;

    /**
     * Draws a border rectangle. The border segments are specified through {@link BorderProps}
     * instances.
     * @param rect the rectangle's coordinates and extent
     * @param top the border segment on the top edge
     * @param bottom the border segment on the bottom edge
     * @param left the border segment on the left edge
     * @param right the border segment on the right edge
     * @param innerBackgroundColor the color of the inner background
     * @throws IFException if an error occurs while handling this event
     */
    void drawBorderRect(Rectangle rect,
            BorderProps top, BorderProps bottom,
            BorderProps left, BorderProps right, Color innerBackgroundColor) throws IFException;

    /**
     * Draws a line. NOTE: Currently, only horizontal lines are implemented!
     * @param start the start point of the line
     * @param end the end point of the line
     * @param width the line width
     * @param color the line color
     * @param style the line style (using the Constants.EN_* constants for the rule-style property)
     * @throws IFException if an error occurs while handling this event
     */
    void drawLine(Point start, Point end, int width, Color color, RuleStyle style)
            throws IFException;

    /**
     * Draws an image identified by a URI inside a given rectangle. This is the equivalent to
     * an fo:external-graphic in XSL-FO.
     * @param uri the image's URI
     * @param rect the rectangle in which the image shall be painted
     * @throws IFException if an error occurs while handling this event
     */
    void drawImage(String uri, Rectangle rect) throws IFException;

    /**
     * Draws an image (represented by a DOM document) inside a given rectangle. This is the
     * equivalent to an fo:instream-foreign-object in XSL-FO.
     * @param doc the DOM document containing the foreign object
     * @param rect the rectangle in which the image shall be painted
     * @throws IFException if an error occurs while handling this event
     */
    void drawImage(Document doc, Rectangle rect) throws IFException;
    //Note: For now, all foreign objects are handled as DOM documents. At the moment, all known
    //implementations use a DOM anyway, so optimizing this to work with SAX wouldn't result in
    //any performance benefits. The IFRenderer itself has a DOM anyway. Only the IFParser could
    //potentially profit if there's an image handler that can efficiently deal with the foreign
    //object without building a DOM.

    //etc. etc.

}