View Javadoc
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 &lt; 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 }