1 /*
2 * Copyright (c) 2000, 2013, 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 /**
29 * Services may optionally provide UIs which allow different styles
30 * of interaction in different roles.
31 * One role may be end-user browsing and setting of print options.
32 * Another role may be administering the print service.
33 * <p>
34 * Although the Print Service API does not presently provide standardised
35 * support for administering a print service, monitoring of the print
36 * service is possible and a UI may provide for private update mechanisms.
37 * <p>
38 * The basic design intent is to allow applications to lazily locate and
39 * initialize services only when needed without any API dependencies
40 * except in an environment in which they are used.
41 * <p>
42 * Swing UIs are preferred as they provide a more consistent {@literal L&F}
43 * and can support accessibility APIs.
44 * <p>
45 * Example usage:
46 * <pre>
47 * ServiceUIFactory factory = printService.getServiceUIFactory();
48 * if (factory != null) {
49 * JComponent swingui = (JComponent)factory.getUI(
50 * ServiceUIFactory.MAIN_UIROLE,
51 * ServiceUIFactory.JCOMPONENT_UI);
52 * if (swingui != null) {
53 * tabbedpane.add("Custom UI", swingui);
54 * }
55 * }
56 * </pre>
57 */
58
59 public abstract class ServiceUIFactory {
60
61 /**
62 * Denotes a UI implemented as a Swing component.
63 * The value of the String is the fully qualified classname :
64 * "javax.swing.JComponent".
65 */
66 public static final String JCOMPONENT_UI = "javax.swing.JComponent";
67
68 /**
69 * Denotes a UI implemented as an AWT panel.
70 * The value of the String is the fully qualified classname :
71 * "java.awt.Panel"
72 */
73 public static final String PANEL_UI = "java.awt.Panel";
74
75 /**
76 * Denotes a UI implemented as an AWT dialog.
77 * The value of the String is the fully qualified classname :
78 * "java.awt.Dialog"
79 */
80 public static final String DIALOG_UI = "java.awt.Dialog";
81
82 /**
83 * Denotes a UI implemented as a Swing dialog.
84 * The value of the String is the fully qualified classname :
85 * "javax.swing.JDialog"
86 */
87 public static final String JDIALOG_UI = "javax.swing.JDialog";
88
89 /**
90 * Denotes a UI which performs an informative "About" role.
91 */
92 public static final int ABOUT_UIROLE = 1;
93
94 /**
95 * Denotes a UI which performs an administrative role.
96 */
97 public static final int ADMIN_UIROLE = 2;
98
99 /**
100 * Denotes a UI which performs the normal end user role.
101 */
102 public static final int MAIN_UIROLE = 3;
103
104 /**
105 * Not a valid role but role id's greater than this may be used
106 * for private roles supported by a service. Knowledge of the
107 * function performed by this role is required to make proper use
108 * of it.
109 */
110 public static final int RESERVED_UIROLE = 99;
111 /**
112 * Get a UI object which may be cast to the requested UI type
113 * by the application and used in its user interface.
114 *
115 * @param role requested. Must be one of the standard roles or
116 * a private role supported by this factory.
117 * @param ui type in which the role is requested.
118 * @return the UI role or null if the requested UI role is not available
119 * from this factory
120 * @throws IllegalArgumentException if the role or ui is neither
121 * one of the standard ones, nor a private one
122 * supported by the factory.
123 */
124 public abstract Object getUI(int role, String ui) ;
125
126 /**
127 * Given a UI role obtained from this factory obtain the UI
128 * types available from this factory which implement this role.
129 * The returned Strings should refer to the static variables defined
130 * in this class so that applications can use equality of reference
131 * ("==").
132 * @param role to be looked up.
133 * @return the UI types supported by this class for the specified role,
134 * null if no UIs are available for the role.
135 * @throws IllegalArgumentException is the role is a non-standard
136 * role not supported by this factory.
137 */
138 public abstract String[] getUIClassNamesForRole(int role) ;
139
140
141
142 }