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 // if portion of dialog is not within the gc boundary
215 if (!gcBounds.contains(dlgBounds)) {
216
217 int dlgWidth = 0;
218 int dlgHeight = 0;
219
220 // if dialog bounds exceed window bounds, check if
221 // positioning the dialog by moving it (bounds.x + bounds.width) - dlgBound.width
222 // will result in moving it beyond the window bounds, then
223 // position it at window top-left
224 // so that dialog is entirely on-screen
225 if ((gcBounds.x + gcBounds.width - dlgBounds.width) > gcBounds.x) {
226 x = (gcBounds.x + gcBounds.width) - dlgBounds.width;
227 dlgWidth = dlgBounds.width;;
228 } else {
229 x = gcBounds.x;
230 dlgWidth = gcBounds.width;
231 }
232 if ((gcBounds.y + gcBounds.height - dlgBounds.height) > gcBounds.y) {
233 y = (gcBounds.y + gcBounds.height) - dlgBounds.height;
234 dlgHeight = dlgBounds.height;
235 } else {
236 y = gcBounds.y;
237 dlgHeight = gcBounds.height;
238 }
239 dialog.setBounds(x, y, dlgWidth, dlgHeight);
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 }