/*

 * Copyright 2000 Sun Microsystems, Inc.  All Rights Reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

package javax.imageio;

/**

 * An interface to be implemented by objects that can determine the

 * settings of an <code>IIOParam</code> object, either by putting up a

 * GUI to obtain values from a user, or by other means.  This

 * interface merely specifies a generic <code>activate</code> method

 * that invokes the controller, without regard for how the controller

 * obtains values (<i>i.e.</i>, whether the controller puts up a GUI

 * or merely computes a set of values is irrelevant to this

 * interface).

 *

 * <p> Within the <code>activate</code> method, a controller obtains

 * initial values by querying the <code>IIOParam</code> object's

 * <code>get</code> methods, modifies values by whatever means, then

 * invokes the <code>IIOParam</code> object's <code>set</code> methods

 * to modify the appropriate settings.  Normally, these

 * <code>set</code> methods will be invoked all at once at a final

 * commit in order that a cancel operation not disturb existing

 * values.  In general, applications may expect that when the

 * <code>activate</code> method returns <code>true</code>, the

 * <code>IIOParam</code> object is ready for use in a read or write

 * operation.

 *

 * <p> Vendors may choose to provide GUIs for the

 * <code>IIOParam</code> subclasses they define for a particular

 * plug-in.  These can be set up as default controllers in the

 * corresponding <code>IIOParam</code> subclasses.

 *

 * <p> Applications may override any default GUIs and provide their

 * own controllers embedded in their own framework.  All that is

 * required is that the<code>activate</code> method behave modally

 * (not returning until either cancelled or committed), though it need

 * not put up an explicitly modal dialog.  Such a non-modal GUI

 * component would be coded roughly as follows:

 *

 * <br>

 * <pre>

 * class MyGUI extends SomeComponent implements IIOParamController {

 *

 *    public MyGUI() {

 *        // ...

 *        setEnabled(false);

 *    }

 *

 *    public boolean activate(IIOParam param) {

 *        // disable other components if desired

 *        setEnabled(true);

 *        // go to sleep until either cancelled or committed

 *        boolean ret = false;

 *        if (!cancelled) {

 *            // set values on param

 *            ret = true;

 *        }

 *        setEnabled(false);

 *        // enable any components disabled above

 *        return ret;

 *    }

 * </pre>

 *

 * <p> Alternatively, an algorithmic process such as a database lookup

 * or the parsing of a command line could be used as a controller, in

 * which case the <code>activate</code> method would simply look up or

 * compute the settings, call the <code>IIOParam.setXXX</code>

 * methods, and return <code>true</code>.

 *

 * @see IIOParam#setController

 * @see IIOParam#getController

 * @see IIOParam#getDefaultController

 * @see IIOParam#hasController

 * @see IIOParam#activateController

 *

 */

public interface IIOParamController {

    /**

     * Activates the controller.  If <code>true</code> is returned,

     * all settings in the <code>IIOParam</code> object should be

     * ready for use in a read or write operation.  If

     * <code>false</code> is returned, no settings in the

     * <code>IIOParam</code> object will be disturbed (<i>i.e.</i>,

     * the user canceled the operation).

     *

     * @param param the <code>IIOParam</code> object to be modified.

     *

     * @return <code>true</code> if the <code>IIOParam</code> has been

     * modified, <code>false</code> otherwise.

     *

     * @exception IllegalArgumentException if <code>param</code> is

     * <code>null</code> or is not an instance of the correct class.

     */

    boolean activate(IIOParam param);

}