001: /*
002: *
003: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
004: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
005: *
006: * This program is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU General Public License version
008: * 2 only, as published by the Free Software Foundation.
009: *
010: * This program is distributed in the hope that it will be useful, but
011: * WITHOUT ANY WARRANTY; without even the implied warranty of
012: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
013: * General Public License version 2 for more details (a copy is
014: * included at /legal/license.txt).
015: *
016: * You should have received a copy of the GNU General Public License
017: * version 2 along with this work; if not, write to the Free Software
018: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
019: * 02110-1301 USA
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
022: * Clara, CA 95054 or visit www.sun.com if you need additional
023: * information or have any questions.
024: */
025:
026: package javax.microedition.media.control;
027:
028: /**
029: * <code>GUIControl</code> extends <code>Control</code> and is defined
030: * for controls that provide GUI functionalities.
031: * <p>
032: * <code>Control</code>s that support a GUI component
033: * should implement this interface.
034: */
035: public interface GUIControl extends javax.microedition.media.Control {
036:
037: /**
038: * This defines a mode on how the GUI is displayed.
039: * It is used in conjunction with
040: * <a href="#initDisplayMode(int, java.lang.Object)">
041: * <code>initDisplayMode</code></a>.
042: * <p>
043: * When <code>USE_GUI_PRIMITIVE</code> is specified for
044: * <code>initDisplayMode</code>, a GUI primitive will be
045: * returned. This object is where the GUI
046: * of this control will be displayed.
047: * It can be used
048: * in conjunction with other GUI objects, and conforms
049: * to the GUI behaviors as specified by
050: * the platform.
051: * <p>
052: * For a given platform, the object returned
053: * must implement or extend from the appropriate GUI primitive
054: * of the platform. For platforms that support only AWT such as
055: * some CDC implementations, the object must
056: * extend from <code>java.awt.Component</code>; for MIDP
057: * implementations with only LCDUI support, it must extend from
058: * <code>javax.microedition.lcdui.Item</code>.
059: * <p>
060: * In these cases, the <code>arg</code> argument must be
061: * <code>null</code> or a <code>String</code> that specifies
062: * the fully-qualified classname of the GUI primitive.
063: * <p>
064: * On some platforms that support multiple types of GUI primitives,
065: * the <code>arg</code> argument must be used to arbitrate among the
066: * options. The <code>arg</code> argument must be a
067: * <code>String</code> that specifies the fully-qualified
068: * classname of the GUI primitive to be returned by the method.
069: * <p>
070: * For example, a platform that supports both AWT and LCDUI
071: * must use either <code>"java.awt.Component"</code> or
072: * <code>"javax.microedition.lcdui.Item"</code> as the
073: * <code>arg</code> argument. The object returned will be
074: * of either type according to what's specified.
075: * <p>
076: * Here are some sample usage scenarios:
077: * <p>
078: * For CDC implementations with only AWT support:
079: * <pre>
080: * <code>
081: * try {
082: * Player p = Manager.createPlayer("http://abc.mpg");
083: * p.realize();
084: * GUIControl gc;
085: * if ((gc = (GUIControl)p.getControl("GUIControl")) != null)
086: * add((Component)gc.initDisplayMode(GUIControl.USE_GUI_PRIMITIVE, null));
087: * p.start();
088: * } catch (MediaException pe) {
089: * } catch (IOException ioe) {
090: * }
091: * </code>
092: * </pre>
093: * <p>
094: * For MIDP implementations with only LCDUI support:
095: * <pre>
096: * <code>
097: * try {
098: * Player p = Manager.createPlayer("http://abc.mpg");
099: * p.realize();
100: * GUIControl gc;
101: * if ((gc = (GUIControl)p.getControl("GUIControl")) != null) {
102: * Form form = new Form("My GUI");
103: * form.append((Item)gc.initDisplayMode(GUIControl.USE_GUI_PRIMITIVE, null));
104: * Display.getDisplay().setCurrent(form);
105: * }
106: * p.start();
107: * } catch (MediaException pe) {
108: * } catch (IOException ioe) {
109: * }
110: * </code>
111: * </pre>
112: * <p>
113: * For implementations with both AWT and LCDUI support:
114: * <pre>
115: * <code>
116: * try {
117: * Player p = Manager.createPlayer("http://abc.mpg");
118: * p.realize();
119: * GUIControl gc;
120: * if ((gc = (GUIControl)p.getControl("GUIControl")) != null)
121: * add((Component)gc.initDisplayMode(GUIControl.USE_GUI_PRIMITIVE,
122: * "java.awt.Component");
123: * p.start();
124: * } catch (MediaException pe) {
125: * } catch (IOException ioe) {
126: * }
127: * </code>
128: * </pre>
129: * <p>
130: * Value 0 is assigned to <code>USE_GUI_PRIMITIVE</code>.
131: */
132: int USE_GUI_PRIMITIVE = 0;
133:
134: /**
135: * Initialize the mode on how the GUI is displayed.
136: *
137: * @param mode The mode that determines how the GUI is
138: * displayed. <code>GUIControl</code> defines only
139: * one mode:
140: * <a href="#USE_GUI_PRIMITIVE"><code>USE_GUI_PRIMITIVE</code></a>.
141: * Subclasses of this may introduce more modes.
142: *
143: * @param arg The exact semantics of this argument is
144: * specified in the respective mode definitions.
145: *
146: * @return The exact semantics and type of the object returned
147: * are specified in the respective mode definitions.
148: *
149: * @exception IllegalStateException Thrown if
150: * <code>initDisplayMode</code> is called again after it has
151: * previously been called successfully.
152: *
153: * @exception IllegalArgumentException Thrown if
154: * the <code>mode</code> or <code>arg</code>
155: * argument is invalid. <code>mode</code> must be
156: * defined by GUIControl or its subclasses; or a custom mode
157: * supported by this implementation.
158: * <code>arg</code> must conform to the
159: * constraints defined by the
160: * respective mode definitions.
161: * Refer to the mode definitions for the required type
162: * of <code>arg</code>.
163: */
164: Object initDisplayMode(int mode, Object arg);
165: }
|