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