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   param);
101 }
102
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags