1 /*
   2  * Copyright (c) 2000, 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.imageio;
  27 
  28 /**
  29  * An interface to be implemented by objects that can determine the
  30  * settings of an {@code IIOParam} 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} 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} method, a controller obtains
  39  * initial values by querying the {@code IIOParam} object's
  40  * {@code get} methods, modifies values by whatever means, then
  41  * invokes the {@code IIOParam} object's {@code set} methods
  42  * to modify the appropriate settings.  Normally, these
  43  * {@code set} 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} method returns {@code true}, the
  47  * {@code IIOParam} 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} subclasses they define for a particular
  52  * plug-in.  These can be set up as default controllers in the
  53  * corresponding {@code IIOParam} 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} 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} method would simply look up or
  89  * compute the settings, call the {@code IIOParam.setXXX}
  90  * methods, and return {@code true}.
  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} is returned,
 103      * all settings in the {@code IIOParam} object should be
 104      * ready for use in a read or write operation.  If
 105      * {@code false} is returned, no settings in the
 106      * {@code IIOParam} object will be disturbed (<i>i.e.</i>,
 107      * the user canceled the operation).
 108      *
 109      * @param param the {@code IIOParam} object to be modified.
 110      *
 111      * @return {@code true} if the {@code IIOParam} has been
 112      * modified, {@code false} otherwise.
 113      *
 114      * @exception IllegalArgumentException if {@code param} is
 115      * {@code null} or is not an instance of the correct class.
 116      */
 117     boolean activate(IIOParam param);
 118 }