1 /*
   2  * Copyright (c) 2000, 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 javax.print;
  27 
  28 import java.awt.GraphicsConfiguration;
  29 import java.awt.GraphicsDevice;
  30 import java.awt.GraphicsEnvironment;
  31 import java.awt.HeadlessException;
  32 import java.awt.Dialog;
  33 import java.awt.Frame;
  34 import java.awt.Point;
  35 import java.awt.Rectangle;
  36 import java.awt.Window;
  37 import java.awt.KeyboardFocusManager;
  38 import javax.print.attribute.Attribute;
  39 import javax.print.attribute.AttributeSet;
  40 import javax.print.attribute.PrintRequestAttributeSet;
  41 import javax.print.attribute.standard.Destination;
  42 import javax.print.attribute.standard.Fidelity;
  43 
  44 import sun.print.ServiceDialog;
  45 import sun.print.SunAlternateMedia;
  46 
  47 /** This class is a collection of UI convenience methods which provide a
  48  * graphical user dialog for browsing print services looked up through the Java
  49  * Print Service API.
  50  * <p>
  51  * The dialogs follow a standard pattern of acting as a continue/cancel option
  52  *for a user as well as allowing the user to select the print service to use
  53  *and specify choices such as paper size and number of copies.
  54  * <p>
  55  * The dialogs are designed to work with pluggable print services though the
  56  * public APIs of those print services.
  57  * <p>
  58  * If a print service provides any vendor extensions these may be made
  59  * accessible to the user through a vendor supplied tab panel Component.
  60  * Such a vendor extension is encouraged to use Swing! and to support its
  61  * accessibility APIs.
  62  * The vendor extensions should return the settings as part of the
  63  * AttributeSet.
  64  * Applications which want to preserve the user settings should use those
  65  * settings to specify the print job.
  66  * Note that this class is not referenced by any other part of the Java
  67  * Print Service and may not be included in profiles which cannot depend
  68  * on the presence of the AWT packages.
  69  */
  70 
  71 public class ServiceUI {
  72 
  73 
  74     /**
  75      * Presents a dialog to the user for selecting a print service (printer).
  76      * It is displayed at the location specified by the application and
  77      * is modal.
  78      * If the specification is invalid or would make the dialog not visible it
  79      * will be displayed at a location determined by the implementation.
  80      * The dialog blocks its calling thread and is application modal.
  81      * <p>
  82      * The dialog may include a tab panel with custom UI lazily obtained from
  83      * the PrintService's ServiceUIFactory when the PrintService is browsed.
  84      * The dialog will attempt to locate a MAIN_UIROLE first as a JComponent,
  85      * then as a Panel. If there is no ServiceUIFactory or no matching role
  86      * the custom tab will be empty or not visible.
  87      * <p>
  88      * The dialog returns the print service selected by the user if the user
  89      * OK's the dialog and null if the user cancels the dialog.
  90      * <p>
  91      * An application must pass in an array of print services to browse.
  92      * The array must be non-null and non-empty.
  93      * Typically an application will pass in only PrintServices capable
  94      * of printing a particular document flavor.
  95      * <p>
  96      * An application may pass in a PrintService to be initially displayed.
  97      * A non-null parameter must be included in the array of browsable
  98      * services.
  99      * If this parameter is null a service is chosen by the implementation.
 100      * <p>
 101      * An application may optionally pass in the flavor to be printed.
 102      * If this is non-null choices presented to the user can be better
 103      * validated against those supported by the services.
 104      * An application must pass in a PrintRequestAttributeSet for returning
 105      * user choices.
 106      * On calling the PrintRequestAttributeSet may be empty, or may contain
 107      * application-specified values.
 108      * <p>
 109      * These are used to set the initial settings for the initially
 110      * displayed print service. Values which are not supported by the print
 111      * service are ignored. As the user browses print services, attributes
 112      * and values are copied to the new display. If a user browses a
 113      * print service which does not support a particular attribute-value, the
 114      * default for that service is used as the new value to be copied.
 115      * <p>
 116      * If the user cancels the dialog, the returned attributes will not reflect
 117      * any changes made by the user.
 118      *
 119      * A typical basic usage of this method may be :
 120      * <pre>{@code
 121      * PrintService[] services = PrintServiceLookup.lookupPrintServices(
 122      *                            DocFlavor.INPUT_STREAM.JPEG, null);
 123      * PrintRequestAttributeSet attributes = new HashPrintRequestAttributeSet();
 124      * if (services.length > 0) {
 125      *    PrintService service =  ServiceUI.printDialog(null, 50, 50,
 126      *                                               services, services[0],
 127      *                                               null,
 128      *                                               attributes);
 129      *    if (service != null) {
 130      *     ... print ...
 131      *    }
 132      * }
 133      * }</pre>
 134      * <p>
 135 
 136      * @param gc used to select screen. null means primary or default screen.
 137      * @param x location of dialog including border in screen coordinates
 138      * @param y location of dialog including border in screen coordinates
 139      * @param services to be browsable, must be non-null.
 140      * @param defaultService - initial PrintService to display.
 141      * @param flavor - the flavor to be printed, or null.
 142      * @param attributes on input is the initial application supplied
 143      * preferences. This cannot be null but may be empty.
 144      * On output the attributes reflect changes made by the user.
 145      * @return print service selected by the user, or null if the user
 146      * cancelled the dialog.
 147      * @throws HeadlessException if GraphicsEnvironment.isHeadless()
 148      * returns true.
 149      * @throws IllegalArgumentException if services is null or empty,
 150      * or attributes is null, or the initial PrintService is not in the
 151      * list of browsable services.
 152      */
 153     public static PrintService printDialog(GraphicsConfiguration gc,
 154                                            int x, int y,
 155                                            PrintService[] services,
 156                                            PrintService defaultService,
 157                                            DocFlavor flavor,
 158                                            PrintRequestAttributeSet attributes)
 159         throws HeadlessException
 160     {
 161         int defaultIndex = -1;
 162 
 163         if (GraphicsEnvironment.isHeadless()) {
 164             throw new HeadlessException();
 165         } else if ((services == null) || (services.length == 0)) {
 166             throw new IllegalArgumentException("services must be non-null " +
 167                                                "and non-empty");
 168         } else if (attributes == null) {
 169             throw new IllegalArgumentException("attributes must be non-null");
 170         }
 171 
 172         if (defaultService != null) {
 173             for (int i = 0; i < services.length; i++) {
 174                 if (services[i].equals(defaultService)) {
 175                     defaultIndex = i;
 176                     break;
 177                 }
 178             }
 179 
 180             if (defaultIndex < 0) {
 181                 throw new IllegalArgumentException("services must contain " +
 182                                                    "defaultService");
 183             }
 184         } else {
 185             defaultIndex = 0;
 186         }
 187 
 188         // For now we set owner to null. In the future, it may be passed
 189         // as an argument.
 190         Window owner = null;
 191 
 192         Rectangle gcBounds = (gc == null) ?  GraphicsEnvironment.
 193             getLocalGraphicsEnvironment().getDefaultScreenDevice().
 194             getDefaultConfiguration().getBounds() : gc.getBounds();
 195 
 196         ServiceDialog dialog;
 197         if (owner instanceof Frame) {
 198             dialog = new ServiceDialog(gc,
 199                                        x + gcBounds.x,
 200                                        y + gcBounds.y,
 201                                        services, defaultIndex,
 202                                        flavor, attributes,
 203                                        (Frame)owner);
 204         } else {
 205             dialog = new ServiceDialog(gc,
 206                                        x + gcBounds.x,
 207                                        y + gcBounds.y,
 208                                        services, defaultIndex,
 209                                        flavor, attributes,
 210                                        (Dialog)owner);
 211         }
 212         Rectangle dlgBounds = dialog.getBounds();
 213 
 214         // get union of all GC bounds
 215         GraphicsEnvironment ge = GraphicsEnvironment.getLocalGraphicsEnvironment();
 216         GraphicsDevice[] gs = ge.getScreenDevices();
 217         for (int j=0; j<gs.length; j++) {
 218             gcBounds =
 219                 gcBounds.union(gs[j].getDefaultConfiguration().getBounds());
 220         }
 221 
 222         // if portion of dialog is not within the gc boundary
 223         if (!gcBounds.contains(dlgBounds)) {
 224             // put in the center relative to parent frame/dialog
 225             dialog.setLocationRelativeTo(owner);
 226         }
 227         dialog.show();
 228 
 229         if (dialog.getStatus() == ServiceDialog.APPROVE) {
 230             PrintRequestAttributeSet newas = dialog.getAttributes();
 231             Class dstCategory = Destination.class;
 232             Class amCategory = SunAlternateMedia.class;
 233             Class fdCategory = Fidelity.class;
 234 
 235             if (attributes.containsKey(dstCategory) &&
 236                 !newas.containsKey(dstCategory))
 237             {
 238                 attributes.remove(dstCategory);
 239             }
 240 
 241             if (attributes.containsKey(amCategory) &&
 242                 !newas.containsKey(amCategory))
 243             {
 244                 attributes.remove(amCategory);
 245             }
 246 
 247             attributes.addAll(newas);
 248 
 249             Fidelity fd = (Fidelity)attributes.get(fdCategory);
 250             if (fd != null) {
 251                 if (fd == Fidelity.FIDELITY_TRUE) {
 252                     removeUnsupportedAttributes(dialog.getPrintService(),
 253                                                 flavor, attributes);
 254                 }
 255             }
 256         }
 257 
 258         return dialog.getPrintService();
 259     }
 260 
 261     /**
 262      * POSSIBLE FUTURE API: This method may be used down the road if we
 263      * decide to allow developers to explicitly display a "page setup" dialog.
 264      * Currently we use that functionality internally for the AWT print model.
 265      */
 266     /*
 267     public static void pageDialog(GraphicsConfiguration gc,
 268                                   int x, int y,
 269                                   PrintService service,
 270                                   DocFlavor flavor,
 271                                   PrintRequestAttributeSet attributes)
 272         throws HeadlessException
 273     {
 274         if (GraphicsEnvironment.isHeadless()) {
 275             throw new HeadlessException();
 276         } else if (service == null) {
 277             throw new IllegalArgumentException("service must be non-null");
 278         } else if (attributes == null) {
 279             throw new IllegalArgumentException("attributes must be non-null");
 280         }
 281 
 282         ServiceDialog dialog = new ServiceDialog(gc, x, y, service,
 283                                                  flavor, attributes);
 284         dialog.show();
 285 
 286         if (dialog.getStatus() == ServiceDialog.APPROVE) {
 287             PrintRequestAttributeSet newas = dialog.getAttributes();
 288             Class amCategory = SunAlternateMedia.class;
 289 
 290             if (attributes.containsKey(amCategory) &&
 291                 !newas.containsKey(amCategory))
 292             {
 293                 attributes.remove(amCategory);
 294             }
 295 
 296             attributes.addAll(newas.values());
 297         }
 298 
 299         dialog.getOwner().dispose();
 300     }
 301     */
 302 
 303     /**
 304      * Removes any attributes from the given AttributeSet that are
 305      * unsupported by the given PrintService/DocFlavor combination.
 306      */
 307     private static void removeUnsupportedAttributes(PrintService ps,
 308                                                     DocFlavor flavor,
 309                                                     AttributeSet aset)
 310     {
 311         AttributeSet asUnsupported = ps.getUnsupportedAttributes(flavor,
 312                                                                  aset);
 313 
 314         if (asUnsupported != null) {
 315             Attribute[] usAttrs = asUnsupported.toArray();
 316 
 317             for (int i=0; i<usAttrs.length; i++) {
 318                 Class category = usAttrs[i].getCategory();
 319 
 320                 if (ps.isAttributeCategorySupported(category)) {
 321                     Attribute attr =
 322                         (Attribute)ps.getDefaultAttributeValue(category);
 323 
 324                     if (attr != null) {
 325                         aset.add(attr);
 326                     } else {
 327                         aset.remove(category);
 328                     }
 329                 } else {
 330                     aset.remove(category);
 331                 }
 332             }
 333         }
 334     }
 335 }