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 }