1. /*

  2.  * @(#)PrinterJob.java	1.23 00/02/02

  3.  *

  4.  * Copyright 1997-2000 Sun Microsystems, Inc. All Rights Reserved.

  5.  * 

  6.  * This software is the proprietary information of Sun Microsystems, Inc.  

  7.  * Use is subject to license terms.

  8.  * 

  9.  */

  10. 

  11. package java.awt.print;

  12. 

  13. import java.awt.AWTError;

  14. import java.util.Enumeration;

  15. 

  16. import sun.security.action.GetPropertyAction;

  17. 

  18. /**

  19.  * The <code>PrinterJob</code> class is the principal class that controls

  20.  * printing. An application calls methods in this class to set up a job,

  21.  * optionally to invoke a print dialog with the user, and then to print

  22.  * the pages of the job.

  23.  */

  24. public abstract class PrinterJob {

  25. 

  26. 

  27.  /* Public Class Methods */

  28. 

  29.     /**

  30.      * Creates and returns a <code>PrinterJob</code>.

  31.      * @return a new <code>PrinterJob</code>.

  32.      */

  33.     public static PrinterJob getPrinterJob() {

  34. 	SecurityManager security = System.getSecurityManager();

  35. 	if (security != null) {

  36. 	    security.checkPrintJobAccess();

  37. 	}

  38. 	return (PrinterJob) java.security.AccessController.doPrivileged(

  39. 	    new java.security.PrivilegedAction() {

  40. 	    public Object run() {

  41. 		String nm = System.getProperty("java.awt.printerjob", null);

  42. 		try {

  43. 		    return (PrinterJob)Class.forName(nm).newInstance();

  44. 		} catch (ClassNotFoundException e) {

  45. 		    throw new AWTError("PrinterJob not found: " + nm);

  46. 		} catch (InstantiationException e) {

  47. 		 throw new AWTError("Could not instantiate PrinterJob: " + nm);

  48. 		} catch (IllegalAccessException e) {

  49. 		    throw new AWTError("Could not access PrinterJob: " + nm);

  50. 		}

  51. 	    }

  52. 	});

  53.     }

  54. 

  55.  /* Public Methods */

  56. 

  57.     /**

  58.      * A <code>PrinterJob</code> object should be created using the

  59.      * static {@link #getPrinterJob() <code>getPrinterJob</code>} method.

  60.      */

  61.      public PrinterJob() {

  62.      }

  63. 

  64.     /**

  65.      * Calls <code>painter</code> to render the pages.  The pages in the

  66.      * document to be printed by this 

  67.      * <code>PrinterJob</code> are rendered by the {@link Printable}

  68.      * object, <code>painter</code>.  The {@link PageFormat} for each page

  69.      * is the default page format.

  70.      * @param painter the <code>Printable</code> that renders each page of

  71.      * the document.

  72.      */

  73.     public abstract void setPrintable(Printable painter);

  74. 

  75.     /**

  76.      * Calls <code>painter</code> to render the pages in the specified

  77.      * <code>format</code>.  The pages in the document to be printed by

  78.      * this <code>PrinterJob</code> are rendered by the

  79.      * <code>Printable</code> object, <code>painter</code>. The

  80.      * <code>PageFormat</code> of each page is <code>format</code>.

  81.      * @param painter the <code>Printable</code> called to render

  82.      *		each page of the document

  83.      * @param format the size and orientation of each page to

  84.      *                   be printed

  85.      */

  86.     public abstract void setPrintable(Printable painter, PageFormat format);

  87. 

  88.     /**

  89.      * Queries <code>document</code> for the number of pages and 

  90.      * the <code>PageFormat</code> and <code>Printable</code> for each

  91.      * page held in the <code>Pageable</code> instance,  

  92.      * <code>document</code>.

  93.      * @param document the pages to be printed. It can not be

  94.      * <code>null</code>.

  95.      * @exception NullPointerException the <code>Pageable</code> passed in

  96.      * was <code>null</code>.

  97.      * @see PageFormat

  98.      * @see Printable

  99.      */

  100.     public abstract void setPageable(Pageable document)

  101. 	throws NullPointerException;

  102. 

  103.     /**

  104.      * Presents a dialog to the user for changing the properties of

  105.      * the print job.

  106.      * @return <code>true</code> if the user does not cancel the dialog;

  107.      * <code>false</code> otherwise.

  108.      */

  109.     public abstract boolean printDialog();

  110. 

  111.     /**

  112.      * Displays a dialog that allows modification of a

  113.      * <code>PageFormat</code> instance.

  114.      * The <code>page</code> argument is used to initialize controls

  115.      * in the page setup dialog.

  116.      * If the user cancels the dialog then this method returns the

  117.      * original <code>page</code> object unmodified.

  118.      * If the user okays the dialog then this method returns a new

  119.      * <code>PageFormat</code> object with the indicated changes.

  120.      * In either case, the original <code>page</code> object is

  121.      * not modified.

  122.      * @param page the default <code>PageFormat</code> presented to the

  123.      *			user for modification

  124.      * @return    the original <code>page</code> object if the dialog

  125.      *            is cancelled; a new <code>PageFormat</code> object

  126.      *		  containing the format indicated by the user if the

  127.      *		  dialog is acknowledged.

  128.      * @since     1.2

  129.      */

  130.     public abstract PageFormat pageDialog(PageFormat page);

  131. 

  132.     /**

  133.      * Clones the <code>PageFormat</code> argument and alters the

  134.      * clone to describe a default page size and orientation.

  135.      * @param page the <code>PageFormat</code> to be cloned and altered

  136.      * @return clone of <code>page</code>, altered to describe a default

  137.      *                      <code>PageFormat</code>.

  138.      */

  139.     public abstract PageFormat defaultPage(PageFormat page);

  140. 

  141.     /**

  142.      * Creates a new <code>PageFormat</code> instance and

  143.      * sets it to a default size and orientation.

  144.      * @return a <code>PageFormat</code> set to a default size and

  145.      *		orientation.

  146.      */

  147.     public PageFormat defaultPage() {

  148.         return defaultPage(new PageFormat());

  149.     }

  150. 

  151.     /**

  152.      * Returns the clone of <code>page</code> with its settings

  153.      * adjusted to be compatible with the current printer of this

  154.      * <code>PrinterJob</code>.  For example, the returned 

  155.      * <code>PageFormat</code> could have its imageable area 

  156.      * adjusted to fit within the physical area of the paper that

  157.      * is used by the current printer.

  158.      * @param page the <code>PageFormat</code> that is cloned and 

  159.      *		whose settings are changed to be compatible with

  160.      *		the current printer

  161.      * @return a <code>PageFormat</code> that is cloned from

  162.      *		<code>page</code> and whose settings are changed 

  163.      *		to conform with this <code>PrinterJob</code>.

  164.      */

  165.     public abstract PageFormat validatePage(PageFormat page);

  166. 

  167.     /**

  168.      * Prints a set of pages.

  169.      * @exception PrinterException an error in the print system

  170.      *            caused the job to be aborted.

  171.      * @see Book

  172.      * @see Pageable

  173.      * @see Printable

  174.      */

  175.     public abstract void print() throws PrinterException;

  176. 

  177.     /**

  178.      * Sets the number of copies to be printed.

  179.      * @param copies the number of copies to be printed

  180.      */

  181.     public abstract void setCopies(int copies);

  182. 

  183.     /**

  184.      * Gets the number of copies to be printed.

  185.      * @return the number of copies to be printed.

  186.      */

  187.     public abstract int getCopies();

  188. 

  189.     /**

  190.      * Gets the name of the printing user.

  191.      * @return the name of the printing user

  192.      */

  193.     public abstract String getUserName();

  194. 

  195.     /**

  196.      * Sets the name of the document to be printed.

  197.      * The document name can not be <code>null</code>.

  198.      * @param jobName the name of the document to be printed

  199.      */

  200.     public abstract void setJobName(String jobName);

  201. 

  202.     /**

  203.      * Gets the name of the document to be printed.

  204.      * @return the name of the document to be printed.

  205.      */

  206.     public abstract String getJobName();

  207. 

  208.     /**

  209.      * Cancels a print job that is in progress.  If 

  210.      * {@link #print() print} has been called but has not 

  211.      * returned then this method signals

  212.      * that the job should be cancelled at the next

  213.      * chance. If there is no print job in progress then

  214.      * this call does nothing.

  215.      */

  216.     public abstract void cancel();

  217. 

  218.     /**

  219.      * Returns <code>true</code> if a print job is 

  220.      * in progress, but is going to be cancelled

  221.      * at the next opportunity; otherwise returns

  222.      * <code>false</code>.

  223.      * @return <code>true</code> if the job in progress

  224.      * is going to be cancelled; <code>false</code> otherwise.

  225.      */

  226.     public abstract boolean isCancelled();

  227. 

  228. }