1 /* 2 * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.awt.print; 27 28 import java.awt.Graphics; 29 30 31 /** 32 * The <code>Printable</code> interface is implemented 33 * by the <code>print</code> methods of the current 34 * page painter, which is called by the printing 35 * system to render a page. When building a 36 * {@link Pageable}, pairs of {@link PageFormat} 37 * instances and instances that implement 38 * this interface are used to describe each page. The 39 * instance implementing <code>Printable</code> is called to 40 * print the page's graphics. 41 * <p> 42 * A <code>Printable(..)</code> may be set on a <code>PrinterJob</code>. 43 * When the client subsequently initiates printing by calling 44 * <code>PrinterJob.print(..)</code> control 45 * <p> 46 * is handed to the printing system until all pages have been printed. 47 * It does this by calling <code>Printable.print(..)</code> until 48 * all pages in the document have been printed. 49 * In using the <code>Printable</code> interface the printing 50 * commits to image the contents of a page whenever 51 * requested by the printing system. 52 * <p> 53 * The parameters to <code>Printable.print(..)</code> include a 54 * <code>PageFormat</code> which describes the printable area of 55 * the page, needed for calculating the contents that will fit the 56 * page, and the page index, which specifies the zero-based print 57 * stream index of the requested page. 58 * <p> 59 * For correct printing behaviour, the following points should be 60 * observed: 61 * <ul> 62 * <li> The printing system may request a page index more than once. 63 * On each occasion equal PageFormat parameters will be supplied. 64 * 65 * <li>The printing system will call <code>Printable.print(..)</code> 66 * with page indexes which increase monotonically, although as noted above, 67 * the <code>Printable</code> should expect multiple calls for a page index 68 * and that page indexes may be skipped, when page ranges are specified 69 * by the client, or by a user through a print dialog. 70 * 71 * <li>If multiple collated copies of a document are requested, and the 72 * printer cannot natively support this, then the document may be imaged 73 * multiple times. Printing will start each copy from the lowest print 74 * stream page index page. 75 * 76 * <li>With the exception of re-imaging an entire document for multiple 77 * collated copies, the increasing page index order means that when 78 * page N is requested if a client needs to calculate page break position, 79 * it may safely discard any state related to pages < N, and make current 80 * that for page N. "State" usually is just the calculated position in the 81 * document that corresponds to the start of the page. 82 * 83 * <li>When called by the printing system the <code>Printable</code> must 84 * inspect and honour the supplied PageFormat parameter as well as the 85 * page index. The format of the page to be drawn is specified by the 86 * supplied PageFormat. The size, orientation and imageable area of the page 87 * is therefore already determined and rendering must be within this 88 * imageable area. 89 * This is key to correct printing behaviour, and it has the 90 * implication that the client has the responsibility of tracking 91 * what content belongs on the specified page. 92 * 93 * <li>When the <code>Printable</code> is obtained from a client-supplied 94 * <code>Pageable</code> then the client may provide different PageFormats 95 * for each page index. Calculations of page breaks must account for this. 96 * </ul> 97 * <p> 98 * @see java.awt.print.Pageable 99 * @see java.awt.print.PageFormat 100 * @see java.awt.print.PrinterJob 101 */ 102 public interface Printable { 103 104 /** 105 * Returned from {@link #print(Graphics, PageFormat, int)} 106 * to signify that the requested page was rendered. 107 */ 108 int PAGE_EXISTS = 0; 109 110 /** 111 * Returned from <code>print</code> to signify that the 112 * <code>pageIndex</code> is too large and that the requested page 113 * does not exist. 114 */ 115 int NO_SUCH_PAGE = 1; 116 117 /** 118 * Prints the page at the specified index into the specified 119 * {@link Graphics} context in the specified 120 * format. A <code>PrinterJob</code> calls the 121 * <code>Printable</code> interface to request that a page be 122 * rendered into the context specified by 123 * <code>graphics</code>. The format of the page to be drawn is 124 * specified by <code>pageFormat</code>. The zero based index 125 * of the requested page is specified by <code>pageIndex</code>. 126 * If the requested page does not exist then this method returns 127 * NO_SUCH_PAGE; otherwise PAGE_EXISTS is returned. 128 * The <code>Graphics</code> class or subclass implements the 129 * {@link PrinterGraphics} interface to provide additional 130 * information. If the <code>Printable</code> object 131 * aborts the print job then it throws a {@link PrinterException}. 132 * @param graphics the context into which the page is drawn 133 * @param pageFormat the size and orientation of the page being drawn 134 * @param pageIndex the zero based index of the page to be drawn 135 * @return PAGE_EXISTS if the page is rendered successfully 136 * or NO_SUCH_PAGE if <code>pageIndex</code> specifies a 137 * non-existent page. 138 * @exception java.awt.print.PrinterException 139 * thrown when the print job is terminated. 140 */ 141 int print(Graphics graphics, PageFormat pageFormat, int pageIndex) 142 throws PrinterException; 143 144 }