1 /*
2 * Copyright 1997-2005 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package java.awt.print;
27
28 import java.awt.Graphics;
29
30 /**
31 * The <code>Printable</code> interface is implemented
32 * by the <code>print</code> methods of the current
33 * page painter, which is called by the printing
34 * system to render a page. When building a
35 * {@link Pageable}, pairs of {@link PageFormat}
36 * instances and instances that implement
37 * this interface are used to describe each page. The
38 * instance implementing <code>Printable</code> is called to
39 * print the page's graphics.
40 * <p>
41 * A <code>Printable(..)</code> may be set on a <code>PrinterJob</code>.
42 * When the client subsequently initiates printing by calling
43 * <code>PrinterJob.print(..)</code> control
44 * <p>
45 * is handed to the printing system until all pages have been printed.
46 * It does this by calling <code>Printable.print(..)</code> until
47 * all pages in the document have been printed.
48 * In using the <code>Printable</code> interface the printing
49 * commits to image the contents of a page whenever
50 * requested by the printing system.
51 * <p>
52 * The parameters to <code>Printable.print(..)</code> include a
53 * <code>PageFormat</code> which describes the printable area of
54 * the page, needed for calculating the contents that will fit the
55 * page, and the page index, which specifies the zero-based print
56 * stream index of the requested page.
57 * <p>
58 * For correct printing behaviour, the following points should be
59 * observed:
60 * <ul>
61 * <li> The printing system may request a page index more than once.
62 * On each occasion equal PageFormat parameters will be supplied.
63 *
64 * <li>The printing system will call <code>Printable.print(..)</code>
65 * with page indexes which increase monotonically, although as noted above,
66 * the <code>Printable</code> should expect multiple calls for a page index
67 * and that page indexes may be skipped, when page ranges are specified
68 * by the client, or by a user through a print dialog.
69 *
70 * <li>If multiple collated copies of a document are requested, and the
71 * printer cannot natively support this, then the document may be imaged
72 * multiple times. Printing will start each copy from the lowest print
73 * stream page index page.
74 *
75 * <li>With the exception of re-imaging an entire document for multiple
76 * collated copies, the increasing page index order means that when
77 * page N is requested if a client needs to calculate page break position,
78 * it may safely discard any state related to pages < N, and make current
79 * that for page N. "State" usually is just the calculated position in the
80 * document that corresponds to the start of the page.
81 *
82 * <li>When called by the printing system the <code>Printable</code> must
83 * inspect and honour the supplied PageFormat parameter as well as the
84 * page index. The format of the page to be drawn is specified by the
85 * supplied PageFormat. The size, orientation and imageable area of the page
86 * is therefore already determined and rendering must be within this
87 * imageable area.
88 * This is key to correct printing behaviour, and it has the
89 * implication that the client has the responsibility of tracking
90 * what content belongs on the specified page.
91 *
92 * <li>When the <code>Printable</code> is obtained from a client-supplied
93 * <code>Pageable</code> then the client may provide different PageFormats
94 * for each page index. Calculations of page breaks must account for this.
95 * </ul>
96 * <p>
97 * @see java.awt.print.Pageable
98 * @see java.awt.print.PageFormat
99 * @see java.awt.print.PrinterJob
100 */
101 public interface Printable {
102
103 /**
104 * Returned from {@link #print(Graphics, PageFormat, int)}
105 * to signify that the requested page was rendered.
106 */
107 int PAGE_EXISTS = 0;
108
109 /**
110 * Returned from <code>print</code> to signify that the
111 * <code>pageIndex</code> is too large and that the requested page
112 * does not exist.
113 */
114 int NO_SUCH_PAGE = 1;
115
116 /**
117 * Prints the page at the specified index into the specified
118 * {@link Graphics} context in the specified
119 * format. A <code>PrinterJob</code> calls the
120 * <code>Printable</code> interface to request that a page be
121 * rendered into the context specified by
122 * <code>graphics</code>. The format of the page to be drawn is
123 * specified by <code>pageFormat</code>. The zero based index
124 * of the requested page is specified by <code>pageIndex</code>.
125 * If the requested page does not exist then this method returns
126 * NO_SUCH_PAGE; otherwise PAGE_EXISTS is returned.
127 * The <code>Graphics</code> class or subclass implements the
128 * {@link PrinterGraphics} interface to provide additional
129 * information. If the <code>Printable</code> object
130 * aborts the print job then it throws a {@link PrinterException}.
131 * @param graphics the context into which the page is drawn
132 * @param pageFormat the size and orientation of the page being drawn
133 * @param pageIndex the zero based index of the page to be drawn
134 * @return PAGE_EXISTS if the page is rendered successfully
135 * or NO_SUCH_PAGE if <code>pageIndex</code> specifies a
136 * non-existent page.
137 * @exception java.awt.print.PrinterException
138 * thrown when the print job is terminated.
139 */
140 int print(Graphics graphics, PageFormat pageFormat, int pageIndex)
141 throws PrinterException;
142
143 }
Save This Page