Save This Page
Home » openjdk-7 » java » awt » print » [javadoc | source]
    1   /*
    2    * Copyright 1997-2006 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.AWTError;
   29   import java.awt.HeadlessException;
   30   import java.util.Enumeration;
   31   
   32   import javax.print.DocFlavor;
   33   import javax.print.PrintService;
   34   import javax.print.PrintServiceLookup;
   35   import javax.print.StreamPrintServiceFactory;
   36   import javax.print.attribute.PrintRequestAttributeSet;
   37   import javax.print.attribute.standard.Media;
   38   import javax.print.attribute.standard.MediaPrintableArea;
   39   import javax.print.attribute.standard.MediaSize;
   40   import javax.print.attribute.standard.MediaSizeName;
   41   import javax.print.attribute.standard.OrientationRequested;
   42   
   43   import sun.security.action.GetPropertyAction;
   44   
   45   /**
   46    * The <code>PrinterJob</code> class is the principal class that controls
   47    * printing. An application calls methods in this class to set up a job,
   48    * optionally to invoke a print dialog with the user, and then to print
   49    * the pages of the job.
   50    */
   51   public abstract class PrinterJob {
   52   
   53    /* Public Class Methods */
   54   
   55       /**
   56        * Creates and returns a <code>PrinterJob</code> which is initially
   57        * associated with the default printer.
   58        * If no printers are available on the system, a PrinterJob will still
   59        * be returned from this method, but <code>getPrintService()</code>
   60        * will return <code>null</code>, and calling
   61        * {@link #print() print} with this <code>PrinterJob</code> might
   62        * generate an exception.  Applications that need to determine if
   63        * there are suitable printers before creating a <code>PrinterJob</code>
   64        * should ensure that the array returned from
   65        * {@link #lookupPrintServices() lookupPrintServices} is not empty.
   66        * @return a new <code>PrinterJob</code>.
   67        *
   68        * @throws  SecurityException if a security manager exists and its
   69        *          {@link java.lang.SecurityManager#checkPrintJobAccess}
   70        *          method disallows this thread from creating a print job request
   71        */
   72       public static PrinterJob getPrinterJob() {
   73           SecurityManager security = System.getSecurityManager();
   74           if (security != null) {
   75               security.checkPrintJobAccess();
   76           }
   77           return (PrinterJob) java.security.AccessController.doPrivileged(
   78               new java.security.PrivilegedAction() {
   79               public Object run() {
   80                   String nm = System.getProperty("java.awt.printerjob", null);
   81                   try {
   82                       return (PrinterJob)Class.forName(nm).newInstance();
   83                   } catch (ClassNotFoundException e) {
   84                       throw new AWTError("PrinterJob not found: " + nm);
   85                   } catch (InstantiationException e) {
   86                    throw new AWTError("Could not instantiate PrinterJob: " + nm);
   87                   } catch (IllegalAccessException e) {
   88                       throw new AWTError("Could not access PrinterJob: " + nm);
   89                   }
   90               }
   91           });
   92       }
   93   
   94       /**
   95        * A convenience method which looks up 2D print services.
   96        * Services returned from this method may be installed on
   97        * <code>PrinterJob</code>s which support print services.
   98        * Calling this method is equivalent to calling
   99        * {@link javax.print.PrintServiceLookup#lookupPrintServices(
  100        * DocFlavor, AttributeSet)
  101        * <code>PrintServiceLookup.lookupPrintServices()</code>}
  102        * and specifying a Pageable DocFlavor.
  103        * @return a possibly empty array of 2D print services.
  104        * @since     1.4
  105        */
  106       public static PrintService[] lookupPrintServices() {
  107           return PrintServiceLookup.
  108               lookupPrintServices(DocFlavor.SERVICE_FORMATTED.PAGEABLE, null);
  109       }
  110   
  111   
  112       /**
  113        * A convenience method which locates factories for stream print
  114        * services which can image 2D graphics.
  115        * Sample usage :
  116        * <pre>
  117        * FileOutputStream outstream;
  118        * StreamPrintService psPrinter;
  119        * String psMimeType = "application/postscript";
  120        *
  121        * StreamPrintServiceFactory[] factories =
  122        *     PrinterJob.lookupStreamPrintServices(psMimeType);
  123        * if (factories.length > 0) {
  124        *     try {
  125        *         outstream = new File("out.ps");
  126        *         psPrinter =  factories[0].getPrintService(fos);
  127        *         // psPrinter can now be set as the service on a PrinterJob
  128        *     } catch (FileNotFoundException e) {
  129        *     }
  130        * }
  131        * </pre>
  132        * Services returned from this method may be installed on
  133        * <code>PrinterJob</code> instances which support print services.
  134        * Calling this method is equivalent to calling
  135        * {@link javax.print.StreamPrintServiceFactory#lookupStreamPrintServiceFactories(DocFlavor, String)
  136        * <code>StreamPrintServiceFactory.lookupStreamPrintServiceFactories()
  137        * </code>} and specifying a Pageable DocFlavor.
  138        *
  139        * @param mimeType the required output format, or null to mean any format.
  140        * @return a possibly empty array of 2D stream print service factories.
  141        * @since     1.4
  142        */
  143       public static StreamPrintServiceFactory[]
  144           lookupStreamPrintServices(String mimeType) {
  145           return StreamPrintServiceFactory.lookupStreamPrintServiceFactories(
  146                                          DocFlavor.SERVICE_FORMATTED.PAGEABLE,
  147                                          mimeType);
  148       }
  149   
  150   
  151    /* Public Methods */
  152   
  153       /**
  154        * A <code>PrinterJob</code> object should be created using the
  155        * static {@link #getPrinterJob() <code>getPrinterJob</code>} method.
  156        */
  157       public PrinterJob() {
  158       }
  159   
  160       /**
  161        * Returns the service (printer) for this printer job.
  162        * Implementations of this class which do not support print services
  163        * may return null.  null will also be returned if no printers are
  164        * available.
  165        * @return the service for this printer job.
  166        * @see #setPrintService(PrintService)
  167        * @see #getPrinterJob()
  168        * @since     1.4
  169        */
  170       public PrintService getPrintService() {
  171           return null;
  172       }
  173   
  174       /**
  175        * Associate this PrinterJob with a new PrintService.
  176        * This method is overridden by subclasses which support
  177        * specifying a Print Service.
  178        *
  179        * Throws <code>PrinterException</code> if the specified service
  180        * cannot support the <code>Pageable</code> and
  181        * <code>Printable</code> interfaces necessary to support 2D printing.
  182        * @param service a print service that supports 2D printing
  183        * @exception PrinterException if the specified service does not support
  184        * 2D printing, or this PrinterJob class does not support
  185        * setting a 2D print service, or the specified service is
  186        * otherwise not a valid print service.
  187        * @see #getPrintService
  188        * @since     1.4
  189        */
  190       public void setPrintService(PrintService service)
  191           throws PrinterException {
  192               throw new PrinterException(
  193                            "Setting a service is not supported on this class");
  194       }
  195   
  196       /**
  197        * Calls <code>painter</code> to render the pages.  The pages in the
  198        * document to be printed by this
  199        * <code>PrinterJob</code> are rendered by the {@link Printable}
  200        * object, <code>painter</code>.  The {@link PageFormat} for each page
  201        * is the default page format.
  202        * @param painter the <code>Printable</code> that renders each page of
  203        * the document.
  204        */
  205       public abstract void setPrintable(Printable painter);
  206   
  207       /**
  208        * Calls <code>painter</code> to render the pages in the specified
  209        * <code>format</code>.  The pages in the document to be printed by
  210        * this <code>PrinterJob</code> are rendered by the
  211        * <code>Printable</code> object, <code>painter</code>. The
  212        * <code>PageFormat</code> of each page is <code>format</code>.
  213        * @param painter the <code>Printable</code> called to render
  214        *          each page of the document
  215        * @param format the size and orientation of each page to
  216        *                   be printed
  217        */
  218       public abstract void setPrintable(Printable painter, PageFormat format);
  219   
  220       /**
  221        * Queries <code>document</code> for the number of pages and
  222        * the <code>PageFormat</code> and <code>Printable</code> for each
  223        * page held in the <code>Pageable</code> instance,
  224        * <code>document</code>.
  225        * @param document the pages to be printed. It can not be
  226        * <code>null</code>.
  227        * @exception NullPointerException the <code>Pageable</code> passed in
  228        * was <code>null</code>.
  229        * @see PageFormat
  230        * @see Printable
  231        */
  232       public abstract void setPageable(Pageable document)
  233           throws NullPointerException;
  234   
  235       /**
  236        * Presents a dialog to the user for changing the properties of
  237        * the print job.
  238        * This method will display a native dialog if a native print
  239        * service is selected, and user choice of printers will be restricted
  240        * to these native print services.
  241        * To present the cross platform print dialog for all services,
  242        * including native ones instead use
  243        * <code>printDialog(PrintRequestAttributeSet)</code>.
  244        * <p>
  245        * PrinterJob implementations which can use PrintService's will update
  246        * the PrintService for this PrinterJob to reflect the new service
  247        * selected by the user.
  248        * @return <code>true</code> if the user does not cancel the dialog;
  249        * <code>false</code> otherwise.
  250        * @exception HeadlessException if GraphicsEnvironment.isHeadless()
  251        * returns true.
  252        * @see java.awt.GraphicsEnvironment#isHeadless
  253        */
  254       public abstract boolean printDialog() throws HeadlessException;
  255   
  256       /**
  257        * A convenience method which displays a cross-platform print dialog
  258        * for all services which are capable of printing 2D graphics using the
  259        * <code>Pageable</code> interface. The selected printer when the
  260        * dialog is initially displayed will reflect the print service currently
  261        * attached to this print job.
  262        * If the user changes the print service, the PrinterJob will be
  263        * updated to reflect this, unless the user cancels the dialog.
  264        * As well as allowing the user to select the destination printer,
  265        * the user can also select values of various print request attributes.
  266        * <p>
  267        * The attributes parameter on input will reflect the applications
  268        * required initial selections in the user dialog. Attributes not
  269        * specified display using the default for the service. On return it
  270        * will reflect the user's choices. Selections may be updated by
  271        * the implementation to be consistent with the supported values
  272        * for the currently selected print service.
  273        * <p>
  274        * As the user scrolls to a new print service selection, the values
  275        * copied are based on the settings for the previous service, together
  276        * with any user changes. The values are not based on the original
  277        * settings supplied by the client.
  278        * <p>
  279        * With the exception of selected printer, the PrinterJob state is
  280        * not updated to reflect the user's changes.
  281        * For the selections to affect a printer job, the attributes must
  282        * be specified in the call to the
  283        * <code>print(PrintRequestAttributeSet)</code> method. If using
  284        * the Pageable interface, clients which intend to use media selected
  285        * by the user must create a PageFormat derived from the user's
  286        * selections.
  287        * If the user cancels the dialog, the attributes will not reflect
  288        * any changes made by the user.
  289        * @param attributes on input is application supplied attributes,
  290        * on output the contents are updated to reflect user choices.
  291        * This parameter may not be null.
  292        * @return <code>true</code> if the user does not cancel the dialog;
  293        * <code>false</code> otherwise.
  294        * @exception HeadlessException if GraphicsEnvironment.isHeadless()
  295        * returns true.
  296        * @exception NullPointerException if <code>attributes</code> parameter
  297        * is null.
  298        * @see java.awt.GraphicsEnvironment#isHeadless
  299        * @since     1.4
  300        *
  301        */
  302       public boolean printDialog(PrintRequestAttributeSet attributes)
  303           throws HeadlessException {
  304   
  305           if (attributes == null) {
  306               throw new NullPointerException("attributes");
  307           }
  308           return printDialog();
  309       }
  310   
  311       /**
  312        * Displays a dialog that allows modification of a
  313        * <code>PageFormat</code> instance.
  314        * The <code>page</code> argument is used to initialize controls
  315        * in the page setup dialog.
  316        * If the user cancels the dialog then this method returns the
  317        * original <code>page</code> object unmodified.
  318        * If the user okays the dialog then this method returns a new
  319        * <code>PageFormat</code> object with the indicated changes.
  320        * In either case, the original <code>page</code> object is
  321        * not modified.
  322        * @param page the default <code>PageFormat</code> presented to the
  323        *                  user for modification
  324        * @return    the original <code>page</code> object if the dialog
  325        *            is cancelled; a new <code>PageFormat</code> object
  326        *            containing the format indicated by the user if the
  327        *            dialog is acknowledged.
  328        * @exception HeadlessException if GraphicsEnvironment.isHeadless()
  329        * returns true.
  330        * @see java.awt.GraphicsEnvironment#isHeadless
  331        * @since     1.2
  332        */
  333       public abstract PageFormat pageDialog(PageFormat page)
  334           throws HeadlessException;
  335   
  336       /**
  337        * A convenience method which displays a cross-platform page setup dialog.
  338        * The choices available will reflect the print service currently
  339        * set on this PrinterJob.
  340        * <p>
  341        * The attributes parameter on input will reflect the client's
  342        * required initial selections in the user dialog. Attributes which are
  343        * not specified display using the default for the service. On return it
  344        * will reflect the user's choices. Selections may be updated by
  345        * the implementation to be consistent with the supported values
  346        * for the currently selected print service.
  347        * <p>
  348        * The return value will be a PageFormat equivalent to the
  349        * selections in the PrintRequestAttributeSet.
  350        * If the user cancels the dialog, the attributes will not reflect
  351        * any changes made by the user, and the return value will be null.
  352        * @param attributes on input is application supplied attributes,
  353        * on output the contents are updated to reflect user choices.
  354        * This parameter may not be null.
  355        * @return a page format if the user does not cancel the dialog;
  356        * <code>null</code> otherwise.
  357        * @exception HeadlessException if GraphicsEnvironment.isHeadless()
  358        * returns true.
  359        * @exception NullPointerException if <code>attributes</code> parameter
  360        * is null.
  361        * @see java.awt.GraphicsEnvironment#isHeadless
  362        * @since     1.4
  363        *
  364        */
  365       public PageFormat pageDialog(PrintRequestAttributeSet attributes)
  366           throws HeadlessException {
  367   
  368           if (attributes == null) {
  369               throw new NullPointerException("attributes");
  370           }
  371           return pageDialog(defaultPage());
  372       }
  373   
  374       /**
  375        * Clones the <code>PageFormat</code> argument and alters the
  376        * clone to describe a default page size and orientation.
  377        * @param page the <code>PageFormat</code> to be cloned and altered
  378        * @return clone of <code>page</code>, altered to describe a default
  379        *                      <code>PageFormat</code>.
  380        */
  381       public abstract PageFormat defaultPage(PageFormat page);
  382   
  383       /**
  384        * Creates a new <code>PageFormat</code> instance and
  385        * sets it to a default size and orientation.
  386        * @return a <code>PageFormat</code> set to a default size and
  387        *          orientation.
  388        */
  389       public PageFormat defaultPage() {
  390           return defaultPage(new PageFormat());
  391       }
  392   
  393       /**
  394        * Calculates a <code>PageFormat</code> with values consistent with those
  395        * supported by the current <code>PrintService</code> for this job
  396        * (ie the value returned by <code>getPrintService()</code>) and media,
  397        * printable area and orientation contained in <code>attributes</code>.
  398        * <p>
  399        * Calling this method does not update the job.
  400        * It is useful for clients that have a set of attributes obtained from
  401        * <code>printDialog(PrintRequestAttributeSet attributes)</code>
  402        * and need a PageFormat to print a Pageable object.
  403        * @param attributes a set of printing attributes, for example obtained
  404        * from calling printDialog. If <code>attributes</code> is null a default
  405        * PageFormat is returned.
  406        * @return a <code>PageFormat</code> whose settings conform with
  407        * those of the current service and the specified attributes.
  408        * @since 1.6
  409        */
  410       public PageFormat getPageFormat(PrintRequestAttributeSet attributes) {
  411   
  412           PrintService service = getPrintService();
  413           PageFormat pf = defaultPage();
  414   
  415           if (service == null || attributes == null) {
  416               return pf;
  417           }
  418   
  419           Media media = (Media)attributes.get(Media.class);
  420           MediaPrintableArea mpa =
  421               (MediaPrintableArea)attributes.get(MediaPrintableArea.class);
  422           OrientationRequested orientReq =
  423              (OrientationRequested)attributes.get(OrientationRequested.class);
  424   
  425           if (media == null && mpa == null && orientReq == null) {
  426              return pf;
  427           }
  428           Paper paper = pf.getPaper();
  429   
  430           /* If there's a media but no media printable area, we can try
  431            * to retrieve the default value for mpa and use that.
  432            */
  433           if (mpa == null && media != null &&
  434               service.isAttributeCategorySupported(MediaPrintableArea.class)) {
  435               Object mpaVals =
  436                   service.getSupportedAttributeValues(MediaPrintableArea.class,
  437                                                       null, attributes);
  438               if (mpaVals instanceof MediaPrintableArea[] &&
  439                   ((MediaPrintableArea[])mpaVals).length > 0) {
  440                   mpa = ((MediaPrintableArea[])mpaVals)[0];
  441               }
  442           }
  443   
  444           if (media != null &&
  445               service.isAttributeValueSupported(media, null, attributes)) {
  446               if (media instanceof MediaSizeName) {
  447                   MediaSizeName msn = (MediaSizeName)media;
  448                   MediaSize msz = MediaSize.getMediaSizeForName(msn);
  449                   if (msz != null) {
  450                       double inch = 72.0;
  451                       double paperWid = msz.getX(MediaSize.INCH) * inch;
  452                       double paperHgt = msz.getY(MediaSize.INCH) * inch;
  453                       paper.setSize(paperWid, paperHgt);
  454                       if (mpa == null) {
  455                           paper.setImageableArea(inch, inch,
  456                                                  paperWid-2*inch,
  457                                                  paperHgt-2*inch);
  458                       }
  459                   }
  460               }
  461           }
  462   
  463           if (mpa != null &&
  464               service.isAttributeValueSupported(mpa, null, attributes)) {
  465               float [] printableArea =
  466                   mpa.getPrintableArea(MediaPrintableArea.INCH);
  467               for (int i=0; i < printableArea.length; i++) {
  468                   printableArea[i] = printableArea[i]*72.0f;
  469               }
  470               paper.setImageableArea(printableArea[0], printableArea[1],
  471                                      printableArea[2], printableArea[3]);
  472           }
  473   
  474           if (orientReq != null &&
  475               service.isAttributeValueSupported(orientReq, null, attributes)) {
  476               int orient;
  477               if (orientReq.equals(OrientationRequested.REVERSE_LANDSCAPE)) {
  478                   orient = PageFormat.REVERSE_LANDSCAPE;
  479               } else if (orientReq.equals(OrientationRequested.LANDSCAPE)) {
  480                   orient = PageFormat.LANDSCAPE;
  481               } else {
  482                   orient = PageFormat.PORTRAIT;
  483               }
  484               pf.setOrientation(orient);
  485           }
  486   
  487           pf.setPaper(paper);
  488           pf = validatePage(pf);
  489           return pf;
  490       }
  491   
  492       /**
  493        * Returns the clone of <code>page</code> with its settings
  494        * adjusted to be compatible with the current printer of this
  495        * <code>PrinterJob</code>.  For example, the returned
  496        * <code>PageFormat</code> could have its imageable area
  497        * adjusted to fit within the physical area of the paper that
  498        * is used by the current printer.
  499        * @param page the <code>PageFormat</code> that is cloned and
  500        *          whose settings are changed to be compatible with
  501        *          the current printer
  502        * @return a <code>PageFormat</code> that is cloned from
  503        *          <code>page</code> and whose settings are changed
  504        *          to conform with this <code>PrinterJob</code>.
  505        */
  506       public abstract PageFormat validatePage(PageFormat page);
  507   
  508       /**
  509        * Prints a set of pages.
  510        * @exception PrinterException an error in the print system
  511        *            caused the job to be aborted.
  512        * @see Book
  513        * @see Pageable
  514        * @see Printable
  515        */
  516       public abstract void print() throws PrinterException;
  517   
  518      /**
  519        * Prints a set of pages using the settings in the attribute
  520        * set. The default implementation ignores the attribute set.
  521        * <p>
  522        * Note that some attributes may be set directly on the PrinterJob
  523        * by equivalent method calls, (for example), copies:
  524        * <code>setcopies(int)</code>, job name: <code>setJobName(String)</code>
  525        * and specifying media size and orientation though the
  526        * <code>PageFormat</code> object.
  527        * <p>
  528        * If a supported attribute-value is specified in this attribute set,
  529        * it will take precedence over the API settings for this print()
  530        * operation only.
  531        * The following behaviour is specified for PageFormat:
  532        * If a client uses the Printable interface, then the
  533        * <code>attributes</code> parameter to this method is examined
  534        * for attributes which specify media (by size), orientation, and
  535        * imageable area, and those are used to construct a new PageFormat
  536        * which is passed to the Printable object's print() method.
  537        * See {@link Printable} for an explanation of the required
  538        * behaviour of a Printable to ensure optimal printing via PrinterJob.
  539        * For clients of the Pageable interface, the PageFormat will always
  540        * be as supplied by that interface, on a per page basis.
  541        * <p>
  542        * These behaviours allow an application to directly pass the
  543        * user settings returned from
  544        * <code>printDialog(PrintRequestAttributeSet attributes</code> to
  545        * this print() method.
  546        * <p>
  547        *
  548        * @param attributes a set of attributes for the job
  549        * @exception PrinterException an error in the print system
  550        *            caused the job to be aborted.
  551        * @see Book
  552        * @see Pageable
  553        * @see Printable
  554        * @since 1.4
  555        */
  556       public void print(PrintRequestAttributeSet attributes)
  557           throws PrinterException {
  558           print();
  559       }
  560   
  561       /**
  562        * Sets the number of copies to be printed.
  563        * @param copies the number of copies to be printed
  564        * @see #getCopies
  565        */
  566       public abstract void setCopies(int copies);
  567   
  568       /**
  569        * Gets the number of copies to be printed.
  570        * @return the number of copies to be printed.
  571        * @see #setCopies
  572        */
  573       public abstract int getCopies();
  574   
  575       /**
  576        * Gets the name of the printing user.
  577        * @return the name of the printing user
  578        */
  579       public abstract String getUserName();
  580   
  581       /**
  582        * Sets the name of the document to be printed.
  583        * The document name can not be <code>null</code>.
  584        * @param jobName the name of the document to be printed
  585        * @see #getJobName
  586        */
  587       public abstract void setJobName(String jobName);
  588   
  589       /**
  590        * Gets the name of the document to be printed.
  591        * @return the name of the document to be printed.
  592        * @see #setJobName
  593        */
  594       public abstract String getJobName();
  595   
  596       /**
  597        * Cancels a print job that is in progress.  If
  598        * {@link #print() print} has been called but has not
  599        * returned then this method signals
  600        * that the job should be cancelled at the next
  601        * chance. If there is no print job in progress then
  602        * this call does nothing.
  603        */
  604       public abstract void cancel();
  605   
  606       /**
  607        * Returns <code>true</code> if a print job is
  608        * in progress, but is going to be cancelled
  609        * at the next opportunity; otherwise returns
  610        * <code>false</code>.
  611        * @return <code>true</code> if the job in progress
  612        * is going to be cancelled; <code>false</code> otherwise.
  613        */
  614       public abstract boolean isCancelled();
  615   
  616   }

Save This Page
Home » openjdk-7 » java » awt » print » [javadoc | source]