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 public static PrintService printDialog(GraphicsConfiguration gc, 153 int x, int y, 154 PrintService[] services, 155 PrintService defaultService, 156 DocFlavor flavor, 157 PrintRequestAttributeSet attributes) 158 throws HeadlessException 159 { 160 int defaultIndex = -1; 161 162 if (GraphicsEnvironment.isHeadless()) { 163 throw new HeadlessException(); 164 } else if ((services == null) || (services.length == 0)) { 165 throw new IllegalArgumentException("services must be non-null " + 166 "and non-empty"); 167 } else if (attributes == null) { 168 throw new IllegalArgumentException("attributes must be non-null"); 169 } 170 171 if (defaultService != null) { 172 for (int i = 0; i < services.length; i++) { 173 if (services[i].equals(defaultService)) { 174 defaultIndex = i; 175 break; 176 } 177 } 178 179 if (defaultIndex < 0) { 180 throw new IllegalArgumentException("services must contain " + 181 "defaultService"); 182 } 183 } else { 184 defaultIndex = 0; 185 } 186 187 // For now we set owner to null. In the future, it may be passed 188 // as an argument. 189 Window owner = null; 190 191 Rectangle gcBounds = (gc == null) ? GraphicsEnvironment. 192 getLocalGraphicsEnvironment().getDefaultScreenDevice(). 193 getDefaultConfiguration().getBounds() : gc.getBounds(); 194 195 ServiceDialog dialog; 196 if (owner instanceof Frame) { 197 dialog = new ServiceDialog(gc, 198 x + gcBounds.x, 199 y + gcBounds.y, 200 services, defaultIndex, 201 flavor, attributes, 202 (Frame)owner); 203 } else { 204 dialog = new ServiceDialog(gc, 205 x + gcBounds.x, 206 y + gcBounds.y, 207 services, defaultIndex, 208 flavor, attributes, 209 (Dialog)owner); 210 } 211 Rectangle dlgBounds = dialog.getBounds(); 212 213 // get union of all GC bounds 214 GraphicsEnvironment ge = GraphicsEnvironment.getLocalGraphicsEnvironment(); 215 GraphicsDevice[] gs = ge.getScreenDevices(); 216 for (int j=0; j<gs.length; j++) { 217 gcBounds = 218 gcBounds.union(gs[j].getDefaultConfiguration().getBounds()); 219 } 220 221 // if portion of dialog is not within the gc boundary 222 if (!gcBounds.contains(dlgBounds)) { 223 // put in the center relative to parent frame/dialog 224 dialog.setLocationRelativeTo(owner); 225 } 226 dialog.show(); 227 228 if (dialog.getStatus() == ServiceDialog.APPROVE) { 229 PrintRequestAttributeSet newas = dialog.getAttributes(); 230 Class<?> dstCategory = Destination.class; 231 Class<?> amCategory = SunAlternateMedia.class; 232 Class<?> fdCategory = Fidelity.class; 233 234 if (attributes.containsKey(dstCategory) && 235 !newas.containsKey(dstCategory)) 236 { 237 attributes.remove(dstCategory); 238 } 239 240 if (attributes.containsKey(amCategory) && 241 !newas.containsKey(amCategory)) 242 { 243 attributes.remove(amCategory); 244 } 245 246 attributes.addAll(newas); 247 248 Fidelity fd = (Fidelity)attributes.get(fdCategory); 249 if (fd != null) { 250 if (fd == Fidelity.FIDELITY_TRUE) { 251 removeUnsupportedAttributes(dialog.getPrintService(), 252 flavor, attributes); 253 } 254 } 255 } 256 257 return dialog.getPrintService(); 258 } 259 260 /** 261 * POSSIBLE FUTURE API: This method may be used down the road if we 262 * decide to allow developers to explicitly display a "page setup" dialog. 263 * Currently we use that functionality internally for the AWT print model. 264 */ 265 /* 266 public static void pageDialog(GraphicsConfiguration gc, 267 int x, int y, 268 PrintService service, 269 DocFlavor flavor, 270 PrintRequestAttributeSet attributes) 271 throws HeadlessException 272 { 273 if (GraphicsEnvironment.isHeadless()) { 274 throw new HeadlessException(); 275 } else if (service == null) { 276 throw new IllegalArgumentException("service must be non-null"); 277 } else if (attributes == null) { 278 throw new IllegalArgumentException("attributes must be non-null"); 279 } 280 281 ServiceDialog dialog = new ServiceDialog(gc, x, y, service, 282 flavor, attributes); 283 dialog.show(); 284 285 if (dialog.getStatus() == ServiceDialog.APPROVE) { 286 PrintRequestAttributeSet newas = dialog.getAttributes(); 287 Class amCategory = SunAlternateMedia.class; 288 289 if (attributes.containsKey(amCategory) && 290 !newas.containsKey(amCategory)) 291 { 292 attributes.remove(amCategory); 293 } 294 295 attributes.addAll(newas.values()); 296 } 297 298 dialog.getOwner().dispose(); 299 } 300 */ 301 302 /** 303 * Removes any attributes from the given AttributeSet that are 304 * unsupported by the given PrintService/DocFlavor combination. 305 */ 306 private static void removeUnsupportedAttributes(PrintService ps, 307 DocFlavor flavor, 308 AttributeSet aset) 309 { 310 AttributeSet asUnsupported = ps.getUnsupportedAttributes(flavor, 311 aset); 312 313 if (asUnsupported != null) { 314 Attribute[] usAttrs = asUnsupported.toArray(); 315 316 for (int i=0; i<usAttrs.length; i++) { 317 Class<? extends Attribute> category = usAttrs[i].getCategory(); 318 319 if (ps.isAttributeCategorySupported(category)) { 320 Attribute attr = 321 (Attribute)ps.getDefaultAttributeValue(category); 322 323 if (attr != null) { 324 aset.add(attr); 325 } else { 326 aset.remove(category); 327 } 328 } else { 329 aset.remove(category); 330 } 331 } 332 } 333 } 334 }