ServiceUI


1   /*
2    * @(#)ServiceUI.java   1.12 04/01/06
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.print;
9   
10  import java.awt.GraphicsConfiguration  ;
11  import java.awt.GraphicsEnvironment  ;
12  import java.awt.HeadlessException  ;
13  import java.awt.Dialog  ;
14  import java.awt.Frame  ;
15  import java.awt.Window  ;
16  import java.awt.KeyboardFocusManager  ;
17  import javax.print.attribute.Attribute  ;
18  import javax.print.attribute.AttributeSet  ;
19  import javax.print.attribute.PrintRequestAttributeSet  ;
20  import javax.print.attribute.standard.Destination  ;
21  import javax.print.attribute.standard.Fidelity  ;
22  
23  import sun.print.ServiceDialog;
24  import sun.print.SunAlternateMedia;
25  
26  /** This class is a collection of UI convenience methods which provide a
27   * graphical user dialog for browsing print services looked up through the Java
28   * Print Service API.
29   * <p>
30   * The dialogs follow a standard pattern of acting as a continue/cancel option
31   *for a user as well as allowing the user to select the print service to use
32   *and specify choices such as paper size and number of copies.
33   * <p>
34   * <p>
35   * The dialogs are designed to work with pluggable print services though the
36   * public APIs of those print services.
37   * <p>
38   * If a print service provides any vendor extensions these may be made
39   * accessible to the user through a vendor supplied tab panel Component.
40   * Such a vendor extension is encouraged to use Swing! and to support its
41   * accessibility APIs.
42   * The vendor extensions should return the settings as part of the
43   * AttributeSet.
44   * Applications which want to preserve the user settings should use those
45   * settings to specify the print job. 
46   * Note that this class is not referenced by any other part of the Java
47   * Print Service and may not be included in profiles which cannot depend
48   * on the presence of the AWT packages.
49   */
50  
51  public class ServiceUI {
52  
53  
54      /**
55       * Presents a dialog to the user for selecting a print service (printer).
56       * It is displayed at the location specified by the application and
57       * is modal.
58       * If the specification is invalid or would make the dialog not visible it
59       * will be displayed at a location determined by the implementation.
60       * The dialog blocks its calling thread and is application modal.
61       * <p>
62       * The dialog may include a tab panel with custom UI lazily obtained from
63       * the PrintService's ServiceUIFactory when the PrintService is browsed.
64       * The dialog will attempt to locate a MAIN_UIROLE first as a JComponent,
65       * then as a Panel. If there is no ServiceUIFactory or no matching role
66       * the custom tab will be empty or not visible.
67       * <p>
68       * The dialog returns the print service selected by the user if the user
69       * OK's the dialog and null if the user cancels the dialog.
70       * <p>
71       * An application must pass in an array of print services to browse.
72       * The array must be non-null and non-empty.
73       * Typically an application will pass in only PrintServices capable
74       * of printing a particular document flavor.
75       * <p>
76       * An application may pass in a PrintService to be initially displayed.
77       * A non-null parameter must be included in the array of browsable
78       * services.
79       * If this parameter is null a service is chosen by the implementation.
80       * <p>
81       * An application may optionally pass in the flavor to be printed.
82       * If this is non-null choices presented to the user can be better
83       * validated against those supported by the services.
84       * An application must pass in a PrintRequestAttributeSet for returning
85       * user choices.
86       * On calling the PrintRequestAttributeSet may be empty, or may contain
87       * application-specified values.
88       * <p>
89       * These are used to set the initial settings for the initially
90       * displayed print service. Values which are not supported by the print
91       * service are ignored. As the user browses print services, attributes
92       * and values are copied to the new display. If a user browses a
93       * print service which does not support a particular attribute-value, the
94       * default for that service is used as the new value to be copied.
95       * <p>
96       * If the user cancels the dialog, the returned attributes will not reflect
97       * any changes made by the user.
98       *
99       * A typical basic usage of this method may be : 
100      * <pre>
101      * PrintService[] services = PrintServiceLookup.lookupPrintServices(
102      *                            DocFlavor.INPUT_STREAM.JPEG, null);
103      * PrintRequestAttributeSet attributes = new HashPrintRequestAttributeSet();
104      * if (services.length > 0) {
105      *    PrintService service =  ServiceUI.printDialog(null, 50, 50,
106      *                                               services, services[0],
107      *                                               null,
108      *                                               attributes);
109      *    if (service != null) {
110      *     ... print ...
111      *    }
112      * }
113      * </pre>
114      * <p>
115 
116      * @param gc used to select screen. null means primary or default screen.
117      * @param x location of dialog including border in screen coordinates
118      * @param y location of dialog including border in screen coordinates
119      * @param services to be browsable, must be non-null.
120      * @param defaultService - initial PrintService to display.
121      * @param flavor - the flavor to be printed, or null.
122      * @param attributes on input is the initial application supplied
123      * preferences. This cannot be null but may be empty.
124      * On output the attributes reflect changes made by the user. 
125      * @return print service selected by the user, or null if the user
126      * cancelled the dialog.
127      * @throws HeadlessException if GraphicsEnvironment.isHeadless()
128      * returns true.
129      * @throws IllegalArgumentException if services is null or empty,
130      * or attributes is null, or the initial PrintService is not in the
131      * list of browsable services.
132      */
133     public static PrintService   printDialog(GraphicsConfiguration   gc,
134                                            int x, int y,
135                                            PrintService  [] services,
136                                            PrintService   defaultService,
137                                            DocFlavor   flavor,
138                                            PrintRequestAttributeSet   attributes) 
139     throws HeadlessException  
140     {
141         int defaultIndex = -1;
142 
143         if (GraphicsEnvironment.isHeadless()) {
144             throw new HeadlessException  ();
145         } else if ((services == null) || (services.length == 0)) {
146             throw new IllegalArgumentException  ("services must be non-null " +
147                                                "and non-empty");
148         } else if (attributes == null) {
149             throw new IllegalArgumentException  ("attributes must be non-null");
150         } 
151         
152         if (defaultService != null) {
153             for (int i = 0; i < services.length; i++) {
154                 if (services[i].equals(defaultService)) {
155                     defaultIndex = i;
156                     break;
157                 }
158             }
159             
160             if (defaultIndex < 0) {
161                 throw new IllegalArgumentException  ("services must contain " +
162                                                    "defaultService");
163             }
164         } else {
165             defaultIndex = 0;
166         }
167 
168     boolean newFrame = false;
169     Window   owner = 
170         KeyboardFocusManager.getCurrentKeyboardFocusManager().
171         getActiveWindow();
172 
173     if (!(owner instanceof Dialog   || owner instanceof Frame  )) {
174         owner = new Frame  ();
175         newFrame = true;
176     }
177 
178     ServiceDialog dialog;
179     if (owner instanceof Frame  ) {
180         dialog = new ServiceDialog(gc, x, y, 
181                        services, defaultIndex,
182                        flavor, attributes, 
183                        (Frame  )owner);
184     } else {
185         dialog = new ServiceDialog(gc, x, y, 
186                        services, defaultIndex,
187                        flavor, attributes, 
188                        (Dialog  )owner);
189     }
190         dialog.show();
191 
192         if (dialog.getStatus() == ServiceDialog.APPROVE) {
193             PrintRequestAttributeSet   newas = dialog.getAttributes();
194             Class   dstCategory = Destination  .class;
195             Class   amCategory = SunAlternateMedia.class;
196             Class   fdCategory = Fidelity  .class;
197 
198             if (attributes.containsKey(dstCategory) &&
199                 !newas.containsKey(dstCategory))
200             {
201                 attributes.remove(dstCategory);
202             }
203 
204             if (attributes.containsKey(amCategory) &&
205                 !newas.containsKey(amCategory))
206             {
207                 attributes.remove(amCategory);
208             }
209 
210             attributes.addAll(newas);
211 
212             Fidelity   fd = (Fidelity  )attributes.get(fdCategory);
213             if (fd != null) {
214                 if (fd == Fidelity.FIDELITY_TRUE) {
215                     removeUnsupportedAttributes(dialog.getPrintService(),
216                                                 flavor, attributes);
217                 }
218             }
219         }
220           
221     if (newFrame) {
222         owner.dispose();
223     }
224 
225     return dialog.getPrintService();
226     }
227 
228     /**
229      * POSSIBLE FUTURE API: This method may be used down the road if we
230      * decide to allow developers to explicitly display a "page setup" dialog.
231      * Currently we use that functionality internally for the AWT print model.
232      */
233     /*
234     public static void pageDialog(GraphicsConfiguration gc,
235                                   int x, int y,
236                                   PrintService service,
237                                   DocFlavor flavor,
238                                   PrintRequestAttributeSet attributes)
239         throws HeadlessException
240     {
241         if (GraphicsEnvironment.isHeadless()) {
242             throw new HeadlessException();
243         } else if (service == null) {
244             throw new IllegalArgumentException("service must be non-null");
245         } else if (attributes == null) {
246             throw new IllegalArgumentException("attributes must be non-null");
247         }
248 
249         ServiceDialog dialog = new ServiceDialog(gc, x, y, service,
250                                                  flavor, attributes);
251         dialog.show();
252 
253         if (dialog.getStatus() == ServiceDialog.APPROVE) {
254             PrintRequestAttributeSet newas = dialog.getAttributes();
255             Class amCategory = SunAlternateMedia.class;
256 
257             if (attributes.containsKey(amCategory) &&
258                 !newas.containsKey(amCategory))
259             {
260                 attributes.remove(amCategory);
261             }
262 
263             attributes.addAll(newas.values());
264         }
265 
266     dialog.getOwner().dispose();
267     }
268     */
269 
270     /**
271      * Removes any attributes from the given AttributeSet that are 
272      * unsupported by the given PrintService/DocFlavor combination.
273      */
274     private static void removeUnsupportedAttributes(PrintService   ps,
275                                                     DocFlavor   flavor,
276                                                     AttributeSet   aset)
277     {
278         AttributeSet   asUnsupported = ps.getUnsupportedAttributes(flavor,
279                                                                  aset);
280 
281         if (asUnsupported != null) {
282         Attribute  [] usAttrs = asUnsupported.toArray();
283 
284             for (int i=0; i<usAttrs.length; i++) {
285                 Class   category = usAttrs[i].getCategory();
286 
287                 if (ps.isAttributeCategorySupported(category)) {
288                     Attribute   attr = 
289                         (Attribute  )ps.getDefaultAttributeValue(category);
290 
291                     if (attr != null) {
292                         aset.add(attr);
293                     } else {
294                         aset.remove(category);
295                     }
296                 } else {
297                     aset.remove(category);
298                 }
299             }
300         }
301     }
302 }
303
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags