1 /*
2 * Copyright 2000 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package javax.imageio;
27
28 /**
29 * An interface to be implemented by objects that can determine the
30 * settings of an <code>IIOParam</code> object, either by putting up a
31 * GUI to obtain values from a user, or by other means. This
32 * interface merely specifies a generic <code>activate</code> method
33 * that invokes the controller, without regard for how the controller
34 * obtains values (<i>i.e.</i>, whether the controller puts up a GUI
35 * or merely computes a set of values is irrelevant to this
36 * interface).
37 *
38 * <p> Within the <code>activate</code> method, a controller obtains
39 * initial values by querying the <code>IIOParam</code> object's
40 * <code>get</code> methods, modifies values by whatever means, then
41 * invokes the <code>IIOParam</code> object's <code>set</code> methods
42 * to modify the appropriate settings. Normally, these
43 * <code>set</code> methods will be invoked all at once at a final
44 * commit in order that a cancel operation not disturb existing
45 * values. In general, applications may expect that when the
46 * <code>activate</code> method returns <code>true</code>, the
47 * <code>IIOParam</code> object is ready for use in a read or write
48 * operation.
49 *
50 * <p> Vendors may choose to provide GUIs for the
51 * <code>IIOParam</code> subclasses they define for a particular
52 * plug-in. These can be set up as default controllers in the
53 * corresponding <code>IIOParam</code> subclasses.
54 *
55 * <p> Applications may override any default GUIs and provide their
56 * own controllers embedded in their own framework. All that is
57 * required is that the<code>activate</code> method behave modally
58 * (not returning until either cancelled or committed), though it need
59 * not put up an explicitly modal dialog. Such a non-modal GUI
60 * component would be coded roughly as follows:
61 *
62 * <br>
63 * <pre>
64 * class MyGUI extends SomeComponent implements IIOParamController {
65 *
66 * public MyGUI() {
67 * // ...
68 * setEnabled(false);
69 * }
70 *
71 * public boolean activate(IIOParam param) {
72 * // disable other components if desired
73 * setEnabled(true);
74 * // go to sleep until either cancelled or committed
75 * boolean ret = false;
76 * if (!cancelled) {
77 * // set values on param
78 * ret = true;
79 * }
80 * setEnabled(false);
81 * // enable any components disabled above
82 * return ret;
83 * }
84 * </pre>
85 *
86 * <p> Alternatively, an algorithmic process such as a database lookup
87 * or the parsing of a command line could be used as a controller, in
88 * which case the <code>activate</code> method would simply look up or
89 * compute the settings, call the <code>IIOParam.setXXX</code>
90 * methods, and return <code>true</code>.
91 *
92 * @see IIOParam#setController
93 * @see IIOParam#getController
94 * @see IIOParam#getDefaultController
95 * @see IIOParam#hasController
96 * @see IIOParam#activateController
97 *
98 */
99 public interface IIOParamController {
100
101 /**
102 * Activates the controller. If <code>true</code> is returned,
103 * all settings in the <code>IIOParam</code> object should be
104 * ready for use in a read or write operation. If
105 * <code>false</code> is returned, no settings in the
106 * <code>IIOParam</code> object will be disturbed (<i>i.e.</i>,
107 * the user canceled the operation).
108 *
109 * @param param the <code>IIOParam</code> object to be modified.
110 *
111 * @return <code>true</code> if the <code>IIOParam</code> has been
112 * modified, <code>false</code> otherwise.
113 *
114 * @exception IllegalArgumentException if <code>param</code> is
115 * <code>null</code> or is not an instance of the correct class.
116 */
117 boolean activate(IIOParam param);
118 }
Save This Page