/*
 * 
 * Copyright  1990-2006 Sun Microsystems, Inc. All Rights Reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
 * 
 * This program 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. 
 * 
 * This program 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 at /legal/license.txt). 
 * 
 * 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 or visit www.sun.com if you need additional
 * information or have any questions. 
 */

package javax.microedition.media.control;


/**
 * <code>GUIControl</code> extends <code>Control</code> and is defined
 * for controls that provide GUI functionalities.
 * <p>
 * <code>Control</code>s that support a GUI component
 * should implement this interface.
 */
public interface GUIControl extends javax.microedition.media.Control {

    /**
     * This defines a mode on how the GUI is displayed.
     * It is used in conjunction with 
     * <a href="#initDisplayMode(int, java.lang.Object)">
     * <code>initDisplayMode</code></a>.
     * <p>
     * When <code>USE_GUI_PRIMITIVE</code> is specified for
     * <code>initDisplayMode</code>, a GUI primitive will be
     * returned.  This object is where the GUI
     * of this control will be displayed. 
     * It can be used
     * in conjunction with other GUI objects, and conforms
     * to the GUI behaviors as specified by
     * the platform.
     * <p> 
     * For a given platform, the object returned
     * must implement or extend from the appropriate GUI primitive
     * of the platform.  For platforms that support only AWT such as 
     * some CDC implementations, the object must
     * extend from <code>java.awt.Component</code>; for MIDP 
     * implementations with only LCDUI support, it must extend from
     * <code>javax.microedition.lcdui.Item</code>.
     * <p>
     * In these cases, the <code>arg</code> argument must be 
     * <code>null</code> or a <code>String</code> that specifies
     * the fully-qualified classname of the GUI primitive.
     * <p>
     * On some platforms that support multiple types of GUI primitives,
     * the <code>arg</code> argument must be used to arbitrate among the
     * options.  The <code>arg</code> argument must be a
     * <code>String</code> that specifies the fully-qualified
     * classname of the GUI primitive to be returned by the method.
     * <p>
     * For example, a platform that supports both AWT and LCDUI
     * must use either <code>"java.awt.Component"</code> or
     * <code>"javax.microedition.lcdui.Item"</code> as the
     * <code>arg</code> argument.  The object returned will be
     * of either type according to what's specified.
     * <p>
     * Here are some sample usage scenarios:
     * <p>
     * For CDC implementations with only AWT support: 
     * <pre>
     * <code>
     *   try {
     *       Player p = Manager.createPlayer("http://abc.mpg");
     *       p.realize();
     *       GUIControl gc;
     *       if ((gc = (GUIControl)p.getControl("GUIControl")) != null)
     *           add((Component)gc.initDisplayMode(GUIControl.USE_GUI_PRIMITIVE, null));
     *       p.start();
     *   } catch (MediaException pe) {
     *   } catch (IOException ioe) {
     *   }
     * </code>
     * </pre>
     * <p>
     * For MIDP implementations with only LCDUI support:
     * <pre>
     * <code>
     *   try {
     *       Player p = Manager.createPlayer("http://abc.mpg");
     *       p.realize();
     *       GUIControl gc;
     *       if ((gc = (GUIControl)p.getControl("GUIControl")) != null) {
     *           Form form = new Form("My GUI");
     *           form.append((Item)gc.initDisplayMode(GUIControl.USE_GUI_PRIMITIVE, null));
     *           Display.getDisplay().setCurrent(form);
     *       }
     *       p.start();
     *   } catch (MediaException pe) {
     *   } catch (IOException ioe) {
     *   }
     * </code>
     * </pre>
     * <p>
     * For implementations with both AWT and LCDUI support: 
     * <pre>
     * <code>
     *   try {
     *       Player p = Manager.createPlayer("http://abc.mpg");
     *       p.realize();
     *       GUIControl gc;
     *       if ((gc = (GUIControl)p.getControl("GUIControl")) != null)
     *           add((Component)gc.initDisplayMode(GUIControl.USE_GUI_PRIMITIVE,
     *                                   "java.awt.Component");
     *       p.start();
     *   } catch (MediaException pe) {
     *   } catch (IOException ioe) {
     *   }
     * </code>
     * </pre>
     * <p>
     * Value 0 is assigned to <code>USE_GUI_PRIMITIVE</code>.
     */
    int USE_GUI_PRIMITIVE = 0;

    /**
     * Initialize the mode on how the GUI is displayed.
     *
     * @param mode The mode that determines how the GUI is
     * displayed.  <code>GUIControl</code> defines only
     * one mode:
     * <a href="#USE_GUI_PRIMITIVE"><code>USE_GUI_PRIMITIVE</code></a>.
     * Subclasses of this may introduce more modes.
     *
     * @param arg The exact semantics of this argument is
     * specified in the respective mode definitions.
     *
     * @return The exact semantics and type of the object returned
     * are specified in the respective mode definitions.
     * 
     * @exception IllegalStateException Thrown if 
     * <code>initDisplayMode</code> is called again after it has 
     * previously been called successfully.
     *
     * @exception IllegalArgumentException Thrown if
     * the <code>mode</code> or <code>arg</code> 
     * argument is invalid.   <code>mode</code> must be
     * defined by GUIControl or its subclasses; or a custom mode
     * supported by this implementation.
     * <code>arg</code> must conform to the 
     * constraints defined by the 
     * respective mode definitions.
     * Refer to the mode definitions for the required type
     * of <code>arg</code>.
     */
    Object initDisplayMode(int mode, Object arg);
}
