2362N/A * Copyright (c) 1997, 2005, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * The <code>Printable</code> interface is implemented 0N/A * by the <code>print</code> methods of the current 0N/A * page painter, which is called by the printing 0N/A * system to render a page. When building a 0N/A * {@link Pageable}, pairs of {@link PageFormat} 0N/A * instances and instances that implement 0N/A * this interface are used to describe each page. The 0N/A * instance implementing <code>Printable</code> is called to 0N/A * print the page's graphics. 0N/A * A <code>Printable(..)</code> may be set on a <code>PrinterJob</code>. 0N/A * When the client subsequently initiates printing by calling 0N/A * <code>PrinterJob.print(..)</code> control 0N/A * is handed to the printing system until all pages have been printed. 0N/A * It does this by calling <code>Printable.print(..)</code> until 0N/A * all pages in the document have been printed. 0N/A * In using the <code>Printable</code> interface the printing 0N/A * commits to image the contents of a page whenever 0N/A * requested by the printing system. 0N/A * The parameters to <code>Printable.print(..)</code> include a 0N/A * <code>PageFormat</code> which describes the printable area of 0N/A * the page, needed for calculating the contents that will fit the 0N/A * page, and the page index, which specifies the zero-based print 0N/A * stream index of the requested page. 0N/A * For correct printing behaviour, the following points should be 0N/A * <li> The printing system may request a page index more than once. 0N/A * On each occasion equal PageFormat parameters will be supplied. 0N/A * <li>The printing system will call <code>Printable.print(..)</code> 0N/A * with page indexes which increase monotonically, although as noted above, 0N/A * the <code>Printable</code> should expect multiple calls for a page index 0N/A * and that page indexes may be skipped, when page ranges are specified 0N/A * by the client, or by a user through a print dialog. 0N/A * <li>If multiple collated copies of a document are requested, and the 0N/A * printer cannot natively support this, then the document may be imaged 0N/A * multiple times. Printing will start each copy from the lowest print 0N/A * stream page index page. 0N/A * <li>With the exception of re-imaging an entire document for multiple 0N/A * collated copies, the increasing page index order means that when 0N/A * page N is requested if a client needs to calculate page break position, 0N/A * it may safely discard any state related to pages < N, and make current 0N/A * that for page N. "State" usually is just the calculated position in the 0N/A * document that corresponds to the start of the page. 0N/A * <li>When called by the printing system the <code>Printable</code> must 0N/A * inspect and honour the supplied PageFormat parameter as well as the 0N/A * page index. The format of the page to be drawn is specified by the 0N/A * supplied PageFormat. The size, orientation and imageable area of the page 0N/A * is therefore already determined and rendering must be within this 0N/A * This is key to correct printing behaviour, and it has the 0N/A * implication that the client has the responsibility of tracking 0N/A * what content belongs on the specified page. 0N/A * <li>When the <code>Printable</code> is obtained from a client-supplied 0N/A * <code>Pageable</code> then the client may provide different PageFormats 0N/A * for each page index. Calculations of page breaks must account for this. 0N/A * @see java.awt.print.Pageable 0N/A * @see java.awt.print.PageFormat 0N/A * @see java.awt.print.PrinterJob 0N/A * Returned from {@link #print(Graphics, PageFormat, int)} 0N/A * to signify that the requested page was rendered. 0N/A * Returned from <code>print</code> to signify that the 0N/A * <code>pageIndex</code> is too large and that the requested page 0N/A * Prints the page at the specified index into the specified 0N/A * {@link Graphics} context in the specified 0N/A * format. A <code>PrinterJob</code> calls the 0N/A * <code>Printable</code> interface to request that a page be 0N/A * rendered into the context specified by 0N/A * <code>graphics</code>. The format of the page to be drawn is 0N/A * specified by <code>pageFormat</code>. The zero based index 0N/A * of the requested page is specified by <code>pageIndex</code>. 0N/A * If the requested page does not exist then this method returns 0N/A * NO_SUCH_PAGE; otherwise PAGE_EXISTS is returned. 0N/A * The <code>Graphics</code> class or subclass implements the 0N/A * {@link PrinterGraphics} interface to provide additional 0N/A * information. If the <code>Printable</code> object 0N/A * aborts the print job then it throws a {@link PrinterException}. 0N/A * @param graphics the context into which the page is drawn 0N/A * @param pageFormat the size and orientation of the page being drawn 0N/A * @param pageIndex the zero based index of the page to be drawn 0N/A * @return PAGE_EXISTS if the page is rendered successfully 0N/A * or NO_SUCH_PAGE if <code>pageIndex</code> specifies a 0N/A * non-existent page. 0N/A * @exception java.awt.print.PrinterException 0N/A * thrown when the print job is terminated.