/*
* 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.Dimension;
import java.util.Locale;
import javax.xml.transform.Result;
import org.apache.fop.accessibility.StructureTreeEventHandler;
import org.apache.fop.fonts.FontInfo;
/**
* Interface used to paint whole documents layouted by Apache FOP.
* <p>
* Call sequence:
* <p>
* <pre>
* startDocument()
* [setDocumentLocale()]
* startDocumentHeader()
* [handleExtension()]*
* endDocumentHeader()
* [
* startPageSequence()
* [
* startPage()
* startPageHeader()
* [handleExtension()]*
* endPageHeader()
* startPageContent()
* (#box)+
* endPageContent()
* startPageTrailer()
* (addTarget())*
* endPageTrailer()
* endPage()
* ]*
* endPageSequence()
* ]*
* startDocumentTrailer()
* [handleExtension()]*
* endDocumentTrailer()
* endDocument()
*
* #box:
* startBox() (#pageContent)+ endBox() |
* startViewport() (#pageContext)+ endViewport()
*
* #pageContent:
* (
* setFont() |
* drawText() |
* drawRect() |
* drawImage() |
* TODO etc. etc. |
* handleExtensionObject()
* )
* </pre>
*/
public interface IFDocumentHandler {
/**
* Returns the associated intermediate format context object.
* @return the context object
*/
IFContext getContext();
/**
* 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);
/**
* Returns the font set to work with.
* @return the font info object
*/
FontInfo getFontInfo();
/**
* Sets the default font set (with no custom configuration).
* @param fontInfo the font info object to populate
*/
void setDefaultFontInfo(FontInfo fontInfo);
/**
* Returns the configurator for this document handler, if any.
* @return the configurator or null if there's no configurator
*/
IFDocumentHandlerConfigurator getConfigurator();
/**
* @return the structure tree builder
*/
StructureTreeEventHandler getStructureTreeEventHandler();
/**
* Returns a document navigation handler if this feature is supported.
* @return the document navigation handler or null if not supported
*/
IFDocumentNavigationHandler getDocumentNavigationHandler();
/**
* 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;
/**
* @param locale Locale of the document.
*/
void setDocumentLocale(Locale locale);
/**
* Indicates the start of the document header. This method is called right after the
* {@link #startDocument()} method. Extensions sent to this painter between
* {@link #startDocumentHeader()} and {@link #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
* {@link #startDocumentTrailer()} and {@link #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
* {@link #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 pageMasterName the name of the simple-page-master that generated this page
* @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, String pageMasterName, 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. The method returns an {@link IFPainter} interface
* which is used to paint the page contents.
* @throws IFException if an error occurs while handling this event
* @return the IFPainter for the page content
*/
IFPainter startPageContent() throws IFException;
/**
* Indicates the end of the page content. Calls to the {@link IFPainter} returned by the
* respective {@link #startPageContent()} method are illegal.
* @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;
/**
* 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;
}