KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > awt > print > Printable


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