1 /* 2 * Copyright (c) 2000, 2014, 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 * 135 * @param gc used to select screen. null means primary or default screen. 136 * @param x location of dialog including border in screen coordinates 137 * @param y location of dialog including border in screen coordinates 138 * @param services to be browsable, must be non-null. 139 * @param defaultService - initial PrintService to display. 140 * @param flavor - the flavor to be printed, or null. 141 * @param attributes on input is the initial application supplied 142 * preferences. This cannot be null but may be empty. 143 * On output the attributes reflect changes made by the user. 144 * @return print service selected by the user, or null if the user 145 * cancelled the dialog. 146 * @throws HeadlessException if GraphicsEnvironment.isHeadless() 147 * returns true. 148 * @throws IllegalArgumentException if services is null or empty, 149 * or attributes is null, or the initial PrintService is not in the 150 * list of browsable services. 151 */ 152 @SuppressWarnings("deprecation") 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<? extends Attribute> 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 }