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 }