/*
 * 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.Rectangle;
import java.awt.geom.AffineTransform;
import java.util.Map;

import javax.xml.transform.Result;

import org.w3c.dom.Document;

import org.apache.fop.apps.FOUserAgent;
import org.apache.fop.fonts.FontInfo;
import org.apache.fop.traits.BorderProps;

/**
 * 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 {

    /**
     * Set the user agent.
     * @param userAgent  The user agent
     */
    void setUserAgent(FOUserAgent userAgent);

    /**
     * Sets the JAXP Result object to receive the generated content.
     * @param result the JAXP Result object to receive the generated content
     * @throws IFException if an error occurs setting up the output
     */
    void setResult(Result result) throws IFException;

    /**
     * Sets the font set to work with.
     * @param fontInfo the font info object
     */
    void setFontInfo(FontInfo fontInfo);

    /**
     * Sets the default font set (with no custom configuration).
     */
    void setDefaultFontInfo();

    /**
     * Indicates whether the painter supports to handle the pages in mixed order rather than
     * ascending order.
     * @return true if out-of-order handling is supported
     */
    boolean supportsPagesOutOfOrder();

    /**
     * Returns the MIME type of the output format that is generated by this implementation.
     * @return the MIME type
     */
    String getMimeType();

    /**
     * Indicates the start of a document. This method may only be called once before any other
     * event method.
     * @throws IFException if an error occurs while handling this event
     */
    void startDocument() throws IFException;

    /**
     * Indicates the end of a document. This method may only be called once after the whole
     * document has been handled. Implementations can release resources (close streams). It is
     * an error to call any event method after this method.
     * @throws IFException if an error occurs while handling this event
     */
    void endDocument() throws IFException;

    /**
     * Indicates the start of the document header. This method is called right after the
     * {@code #startDocument()} method. Extensions sent to this painter between
     * {@code #startDocumentHeader()} and {@code #endDocumentHeader()} apply to the document as
     * a whole (like document metadata).
     * @throws IFException if an error occurs while handling this event
     */
    void startDocumentHeader() throws IFException;

    /**
     * Indicates the end of the document header. This method is called before the first
     * page sequence.
     * @throws IFException if an error occurs while handling this event
     */
    void endDocumentHeader() throws IFException;

    /**
     * Indicates the start of the document trailer. This method is called after the last
     * page sequence. Extensions sent to the painter between
     * {@code #startDocumentTrailer()} and {@code #endDocumentTrailer()} apply to the document as
     * a whole and is used for document-level content that is only known after all pages have
     * been rendered (like named destinations or the bookmark tree).
     * @throws IFException if an error occurs while handling this event
     */
    void startDocumentTrailer() throws IFException;

    /**
     * Indicates the end of the document trailer. This method is called right before the
     * {@code #endDocument()} method.
     * @throws IFException if an error occurs while handling this event
     */
    void endDocumentTrailer() throws IFException;

    /**
     * Indicates the start of a new page sequence.
     * @param id the page sequence's identifier (or null if none is available)
     * @throws IFException if an error occurs while handling this event
     */
    void startPageSequence(String id) throws IFException;
    /**
     * Indicates the end of a page sequence.
     * @throws IFException if an error occurs while handling this event
     */
    void endPageSequence() throws IFException;

    /**
     * Indicates the start of a new page.
     * @param index the index of the page (0-based)
     * @param name the page name (usually the formatted page number)
     * @param size the size of the page (equivalent to the MediaBox in PDF)
     * @throws IFException if an error occurs while handling this event
     */
    void startPage(int index, String name, Dimension size) throws IFException;

    /**
     * Indicates the end of a page
     * @throws IFException if an error occurs while handling this event
     */
    void endPage() throws IFException;

    /**
     * Indicates the start of the page header.
     * @throws IFException if an error occurs while handling this event
     */
    void startPageHeader() throws IFException;

    /**
     * Indicates the end of the page header.
     * @throws IFException if an error occurs while handling this event
     */
    void endPageHeader() throws IFException;

    /**
     * Indicates the start of the page content.
     * @throws IFException if an error occurs while handling this event
     */
    void startPageContent() throws IFException;

    /**
     * Indicates the end of the page content.
     * @throws IFException if an error occurs while handling this event
     */
    void endPageContent() throws IFException;

    /**
     * Indicates the start of the page trailer. The page trailer is used for writing down page
     * elements which are only know after handling the page itself (like PDF targets).
     * @throws IFException if an error occurs while handling this event
     */
    void startPageTrailer() throws IFException;

    /**
     * Indicates the end of the page trailer.
     * @throws IFException if an error occurs while handling this event
     */
    void endPageTrailer() throws IFException;

    void startViewport(AffineTransform transform, Dimension size, Rectangle clipRect) throws IFException;
    void startViewport(AffineTransform[] transforms, Dimension size, Rectangle clipRect) throws IFException;
    //For transform, Batik's org.apache.batik.parser.TransformListHandler/Parser can be used
    void endViewport() throws IFException;

    void startGroup(AffineTransform[] transforms) throws IFException;
    void startGroup(AffineTransform transform) throws IFException;
    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 arrays (dx and dy) are optional and can be used to achieve
     * effects like kerning.
     * @param x X-coordinate of the starting point of the text
     * @param y Y-coordinate of the starting point of the text
     * @param dx an array of adjustment values for each character in X-direction
     * @param dy an array of adjustment values for each character in Y-direction
     * @param text the text
     * @throws IFException if an error occurs while handling this event
     */
    void drawText(int x, int y, int[] dx, int[] dy, String text) throws IFException;

    /**
     * Draws a rectangle. Either fill or stroke has to be specified.
     * @param rect the rectangle's coordinates and extent
     * @param fill the fill paint (may be null)
     * @param stroke the stroke color (may be null)
     * @throws IFException if an error occurs while handling this event
     */
    void drawRect(Rectangle rect, Paint fill, Color stroke) throws IFException;

    /**
     * Draws a border rectangle. The border segments are specified through {@code BorderProps}
     * instances.
     * @param rect the rectangle's coordinates and extent
     * @param before the border segment on the before-side (top)
     * @param after the border segment on the after-side (bottom)
     * @param start the border segment on the start-side (left)
     * @param end the border segment on the end-side (right)
     * @throws IFException if an error occurs while handling this event
     */
    void drawBorderRect(Rectangle rect,
            BorderProps before, BorderProps after,
            BorderProps start, BorderProps end) 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
     * @param foreignAttributes a optional Map with foreign attributes (Map<QName,String>)
     * @throws IFException if an error occurs while handling this event
     */
    void drawImage(String uri, Rectangle rect, Map foreignAttributes) 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
     * @param foreignAttributes a optional Map with foreign attributes (Map<QName,String>)
     * @throws IFException if an error occurs while handling this event
     */
    void drawImage(Document doc, Rectangle rect, Map foreignAttributes)
                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.

    /**
     * Handles an extension object. This can be a DOM document or any arbitrary
     * object. If an implementation doesn't know how to handle a particular extension it is simply
     * ignored.
     * @param extension the extension object
     * @throws IFException if an error occurs while handling this event
     */
    void handleExtensionObject(Object extension) throws IFException;

    //TODO Prototype the following:
    //ContentHandler handleExtension() throws Exception
}