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