KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > imageio > IIOParamController


1 /*
2  * @(#)IIOParamController.java 1.12 03/12/19
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.imageio;
9
10 /**
11  * An interface to be implemented by objects that can determine the
12  * settings of an <code>IIOParam</code> object, either by putting up a
13  * GUI to obtain values from a user, or by other means. This
14  * interface merely specifies a generic <code>activate</code> method
15  * that invokes the controller, without regard for how the controller
16  * obtains values (<i>i.e.</i>, whether the controller puts up a GUI
17  * or merely computes a set of values is irrelevant to this
18  * interface).
19  *
20  * <p> Within the <code>activate</code> method, a controller obtains
21  * initial values by querying the <code>IIOParam</code> object's
22  * <code>get</code> methods, modifies values by whatever means, then
23  * invokes the <code>IIOParam</code> object's <code>set</code> methods
24  * to modify the appropriate settings. Normally, these
25  * <code>set</code> methods will be invoked all at once at a final
26  * commit in order that a cancel operation not disturb existing
27  * values. In general, applications may expect that when the
28  * <code>activate</code> method returns <code>true</code>, the
29  * <code>IIOParam</code> object is ready for use in a read or write
30  * operation.
31  *
32  * <p> Vendors may choose to provide GUIs for the
33  * <code>IIOParam</code> subclasses they define for a particular
34  * plug-in. These can be set up as default controllers in the
35  * corresponding <code>IIOParam</code> subclasses.
36  *
37  * <p> Applications may override any default GUIs and provide their
38  * own controllers embedded in their own framework. All that is
39  * required is that the<code>activate</code> method behave modally
40  * (not returning until either cancelled or committed), though it need
41  * not put up an explicitly modal dialog. Such a non-modal GUI
42  * component would be coded roughly as follows:
43  *
44  * <br>
45  * <pre>
46  * class MyGUI extends SomeComponent implements IIOParamController {
47  *
48  * public MyGUI() {
49  * // ...
50  * setEnabled(false);
51  * }
52  *
53  * public boolean activate(IIOParam param) {
54  * // disable other components if desired
55  * setEnabled(true);
56  * // go to sleep until either cancelled or committed
57  * boolean ret = false;
58  * if (!cancelled) {
59  * // set values on param
60  * ret = true;
61  * }
62  * setEnabled(false);
63  * // enable any components disabled above
64  * return ret;
65  * }
66  * </pre>
67  *
68  * <p> Alternatively, an algorithmic process such as a database lookup
69  * or the parsing of a command line could be used as a controller, in
70  * which case the <code>activate</code> method would simply look up or
71  * compute the settings, call the <code>IIOParam.setXXX</code>
72  * methods, and return <code>true</code>.
73  *
74  * @see IIOParam#setController
75  * @see IIOParam#getController
76  * @see IIOParam#getDefaultController
77  * @see IIOParam#hasController
78  * @see IIOParam#activateController
79  *
80  * @version 0.5
81  */

82 public interface IIOParamController {
83
84     /**
85      * Activates the controller. If <code>true</code> is returned,
86      * all settings in the <code>IIOParam</code> object should be
87      * ready for use in a read or write operation. If
88      * <code>false</code> is returned, no settings in the
89      * <code>IIOParam</code> object will be disturbed (<i>i.e.</i>,
90      * the user canceled the operation).
91      *
92      * @param param the <code>IIOParam</code> object to be modified.
93      *
94      * @return <code>true</code> if the <code>IIOParam</code> has been
95      * modified, <code>false</code> otherwise.
96      *
97      * @exception IllegalArgumentException if <code>param</code> is
98      * <code>null</code> or is not an instance of the correct class.
99      */

100     boolean activate(IIOParam JavaDoc param);
101 }
102
Popular Tags