--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/javax/print/ServiceUI.java Sat Dec 01 00:00:00 2007 +0000
@@ -0,0 +1,336 @@
+/*
+ * Copyright 2000-2005 Sun Microsystems, Inc. All Rights Reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Sun designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Sun in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+ * CA 95054 USA or visit www.sun.com if you need additional information or
+ * have any questions.
+ */
+
+package javax.print;
+
+import java.awt.GraphicsConfiguration;
+import java.awt.GraphicsDevice;
+import java.awt.GraphicsEnvironment;
+import java.awt.HeadlessException;
+import java.awt.Dialog;
+import java.awt.Frame;
+import java.awt.Point;
+import java.awt.Rectangle;
+import java.awt.Window;
+import java.awt.KeyboardFocusManager;
+import javax.print.attribute.Attribute;
+import javax.print.attribute.AttributeSet;
+import javax.print.attribute.PrintRequestAttributeSet;
+import javax.print.attribute.standard.Destination;
+import javax.print.attribute.standard.Fidelity;
+
+import sun.print.ServiceDialog;
+import sun.print.SunAlternateMedia;
+
+/** This class is a collection of UI convenience methods which provide a
+ * graphical user dialog for browsing print services looked up through the Java
+ * Print Service API.
+ * <p>
+ * The dialogs follow a standard pattern of acting as a continue/cancel option
+ *for a user as well as allowing the user to select the print service to use
+ *and specify choices such as paper size and number of copies.
+ * <p>
+ * <p>
+ * The dialogs are designed to work with pluggable print services though the
+ * public APIs of those print services.
+ * <p>
+ * If a print service provides any vendor extensions these may be made
+ * accessible to the user through a vendor supplied tab panel Component.
+ * Such a vendor extension is encouraged to use Swing! and to support its
+ * accessibility APIs.
+ * The vendor extensions should return the settings as part of the
+ * AttributeSet.
+ * Applications which want to preserve the user settings should use those
+ * settings to specify the print job.
+ * Note that this class is not referenced by any other part of the Java
+ * Print Service and may not be included in profiles which cannot depend
+ * on the presence of the AWT packages.
+ */
+
+public class ServiceUI {
+
+
+ /**
+ * Presents a dialog to the user for selecting a print service (printer).
+ * It is displayed at the location specified by the application and
+ * is modal.
+ * If the specification is invalid or would make the dialog not visible it
+ * will be displayed at a location determined by the implementation.
+ * The dialog blocks its calling thread and is application modal.
+ * <p>
+ * The dialog may include a tab panel with custom UI lazily obtained from
+ * the PrintService's ServiceUIFactory when the PrintService is browsed.
+ * The dialog will attempt to locate a MAIN_UIROLE first as a JComponent,
+ * then as a Panel. If there is no ServiceUIFactory or no matching role
+ * the custom tab will be empty or not visible.
+ * <p>
+ * The dialog returns the print service selected by the user if the user
+ * OK's the dialog and null if the user cancels the dialog.
+ * <p>
+ * An application must pass in an array of print services to browse.
+ * The array must be non-null and non-empty.
+ * Typically an application will pass in only PrintServices capable
+ * of printing a particular document flavor.
+ * <p>
+ * An application may pass in a PrintService to be initially displayed.
+ * A non-null parameter must be included in the array of browsable
+ * services.
+ * If this parameter is null a service is chosen by the implementation.
+ * <p>
+ * An application may optionally pass in the flavor to be printed.
+ * If this is non-null choices presented to the user can be better
+ * validated against those supported by the services.
+ * An application must pass in a PrintRequestAttributeSet for returning
+ * user choices.
+ * On calling the PrintRequestAttributeSet may be empty, or may contain
+ * application-specified values.
+ * <p>
+ * These are used to set the initial settings for the initially
+ * displayed print service. Values which are not supported by the print
+ * service are ignored. As the user browses print services, attributes
+ * and values are copied to the new display. If a user browses a
+ * print service which does not support a particular attribute-value, the
+ * default for that service is used as the new value to be copied.
+ * <p>
+ * If the user cancels the dialog, the returned attributes will not reflect
+ * any changes made by the user.
+ *
+ * A typical basic usage of this method may be :
+ * <pre>
+ * PrintService[] services = PrintServiceLookup.lookupPrintServices(
+ * DocFlavor.INPUT_STREAM.JPEG, null);
+ * PrintRequestAttributeSet attributes = new HashPrintRequestAttributeSet();
+ * if (services.length > 0) {
+ * PrintService service = ServiceUI.printDialog(null, 50, 50,
+ * services, services[0],
+ * null,
+ * attributes);
+ * if (service != null) {
+ * ... print ...
+ * }
+ * }
+ * </pre>
+ * <p>
+
+ * @param gc used to select screen. null means primary or default screen.
+ * @param x location of dialog including border in screen coordinates
+ * @param y location of dialog including border in screen coordinates
+ * @param services to be browsable, must be non-null.
+ * @param defaultService - initial PrintService to display.
+ * @param flavor - the flavor to be printed, or null.
+ * @param attributes on input is the initial application supplied
+ * preferences. This cannot be null but may be empty.
+ * On output the attributes reflect changes made by the user.
+ * @return print service selected by the user, or null if the user
+ * cancelled the dialog.
+ * @throws HeadlessException if GraphicsEnvironment.isHeadless()
+ * returns true.
+ * @throws IllegalArgumentException if services is null or empty,
+ * or attributes is null, or the initial PrintService is not in the
+ * list of browsable services.
+ */
+ public static PrintService printDialog(GraphicsConfiguration gc,
+ int x, int y,
+ PrintService[] services,
+ PrintService defaultService,
+ DocFlavor flavor,
+ PrintRequestAttributeSet attributes)
+ throws HeadlessException
+ {
+ int defaultIndex = -1;
+
+ if (GraphicsEnvironment.isHeadless()) {
+ throw new HeadlessException();
+ } else if ((services == null) || (services.length == 0)) {
+ throw new IllegalArgumentException("services must be non-null " +
+ "and non-empty");
+ } else if (attributes == null) {
+ throw new IllegalArgumentException("attributes must be non-null");
+ }
+
+ if (defaultService != null) {
+ for (int i = 0; i < services.length; i++) {
+ if (services[i].equals(defaultService)) {
+ defaultIndex = i;
+ break;
+ }
+ }
+
+ if (defaultIndex < 0) {
+ throw new IllegalArgumentException("services must contain " +
+ "defaultService");
+ }
+ } else {
+ defaultIndex = 0;
+ }
+
+ // For now we set owner to null. In the future, it may be passed
+ // as an argument.
+ Window owner = null;
+
+ Rectangle gcBounds = (gc == null) ? GraphicsEnvironment.
+ getLocalGraphicsEnvironment().getDefaultScreenDevice().
+ getDefaultConfiguration().getBounds() : gc.getBounds();
+
+ ServiceDialog dialog;
+ if (owner instanceof Frame) {
+ dialog = new ServiceDialog(gc,
+ x + gcBounds.x,
+ y + gcBounds.y,
+ services, defaultIndex,
+ flavor, attributes,
+ (Frame)owner);
+ } else {
+ dialog = new ServiceDialog(gc,
+ x + gcBounds.x,
+ y + gcBounds.y,
+ services, defaultIndex,
+ flavor, attributes,
+ (Dialog)owner);
+ }
+ Rectangle dlgBounds = dialog.getBounds();
+
+ // get union of all GC bounds
+ GraphicsEnvironment ge = GraphicsEnvironment.getLocalGraphicsEnvironment();
+ GraphicsDevice[] gs = ge.getScreenDevices();
+ for (int j=0; j<gs.length; j++) {
+ gcBounds =
+ gcBounds.union(gs[j].getDefaultConfiguration().getBounds());
+ }
+
+ // if portion of dialog is not within the gc boundary
+ if (!gcBounds.contains(dlgBounds)) {
+ // put in the center relative to parent frame/dialog
+ dialog.setLocationRelativeTo(owner);
+ }
+ dialog.show();
+
+ if (dialog.getStatus() == ServiceDialog.APPROVE) {
+ PrintRequestAttributeSet newas = dialog.getAttributes();
+ Class dstCategory = Destination.class;
+ Class amCategory = SunAlternateMedia.class;
+ Class fdCategory = Fidelity.class;
+
+ if (attributes.containsKey(dstCategory) &&
+ !newas.containsKey(dstCategory))
+ {
+ attributes.remove(dstCategory);
+ }
+
+ if (attributes.containsKey(amCategory) &&
+ !newas.containsKey(amCategory))
+ {
+ attributes.remove(amCategory);
+ }
+
+ attributes.addAll(newas);
+
+ Fidelity fd = (Fidelity)attributes.get(fdCategory);
+ if (fd != null) {
+ if (fd == Fidelity.FIDELITY_TRUE) {
+ removeUnsupportedAttributes(dialog.getPrintService(),
+ flavor, attributes);
+ }
+ }
+ }
+
+ return dialog.getPrintService();
+ }
+
+ /**
+ * POSSIBLE FUTURE API: This method may be used down the road if we
+ * decide to allow developers to explicitly display a "page setup" dialog.
+ * Currently we use that functionality internally for the AWT print model.
+ */
+ /*
+ public static void pageDialog(GraphicsConfiguration gc,
+ int x, int y,
+ PrintService service,
+ DocFlavor flavor,
+ PrintRequestAttributeSet attributes)
+ throws HeadlessException
+ {
+ if (GraphicsEnvironment.isHeadless()) {
+ throw new HeadlessException();
+ } else if (service == null) {
+ throw new IllegalArgumentException("service must be non-null");
+ } else if (attributes == null) {
+ throw new IllegalArgumentException("attributes must be non-null");
+ }
+
+ ServiceDialog dialog = new ServiceDialog(gc, x, y, service,
+ flavor, attributes);
+ dialog.show();
+
+ if (dialog.getStatus() == ServiceDialog.APPROVE) {
+ PrintRequestAttributeSet newas = dialog.getAttributes();
+ Class amCategory = SunAlternateMedia.class;
+
+ if (attributes.containsKey(amCategory) &&
+ !newas.containsKey(amCategory))
+ {
+ attributes.remove(amCategory);
+ }
+
+ attributes.addAll(newas.values());
+ }
+
+ dialog.getOwner().dispose();
+ }
+ */
+
+ /**
+ * Removes any attributes from the given AttributeSet that are
+ * unsupported by the given PrintService/DocFlavor combination.
+ */
+ private static void removeUnsupportedAttributes(PrintService ps,
+ DocFlavor flavor,
+ AttributeSet aset)
+ {
+ AttributeSet asUnsupported = ps.getUnsupportedAttributes(flavor,
+ aset);
+
+ if (asUnsupported != null) {
+ Attribute[] usAttrs = asUnsupported.toArray();
+
+ for (int i=0; i<usAttrs.length; i++) {
+ Class category = usAttrs[i].getCategory();
+
+ if (ps.isAttributeCategorySupported(category)) {
+ Attribute attr =
+ (Attribute)ps.getDefaultAttributeValue(category);
+
+ if (attr != null) {
+ aset.add(attr);
+ } else {
+ aset.remove(category);
+ }
+ } else {
+ aset.remove(category);
+ }
+ }
+ }
+ }
+}