001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package javax.microedition.lcdui;
028:
029: /**
030: * An item that can contain a string. A <code>StringItem</code> is
031: * display-only; the user
032: * cannot edit the contents. Both the label and the textual content of a
033: * <code>StringItem</code> may be modified by the application. The
034: * visual representation
035: * of the label may differ from that of the textual contents.
036: */
037: public class StringItem extends Item {
038:
039: /**
040: * Creates a new <code>StringItem</code> object. Calling this
041: * constructor is equivalent to calling
042: *
043: * <TABLE BORDER="2">
044: * <TR>
045: * <TD ROWSPAN="1" COLSPAN="1">
046: * <pre><code>
047: * StringItem(label, text, PLAIN); </code></pre>
048: * </TD>
049: * </TR>
050: * </TABLE>
051: * @param label the <code>Item</code> label
052: * @param text the text contents
053: * @see #StringItem(String, String, int)
054: */
055: public StringItem(String label, String text) {
056: this (label, text, Item.PLAIN);
057: }
058:
059: /**
060: * Creates a new <code>StringItem</code> object with the given label,
061: * textual content, and appearance mode.
062: * Either label or text may be present or <code>null</code>.
063: *
064: * <p>The <code>appearanceMode</code> parameter
065: * (see <a href="Item.html#appearance">Appearance Modes</a>)
066: * is a hint to the platform of the application's intended use
067: * for this <code>StringItem</code>. To provide hyperlink- or
068: * button-like behavior,
069: * the application should associate a default <code>Command</code> with this
070: * <code>StringItem</code> and add an
071: * <code>ItemCommandListener</code> to this
072: * <code>StringItem</code>.
073: *
074: * <p>Here is an example showing the use of a
075: * <code>StringItem</code> as a button: </p>
076: * <TABLE BORDER="2">
077: * <TR>
078: * <TD ROWSPAN="1" COLSPAN="1">
079: * <pre><code>
080: * StringItem strItem =
081: * new StringItem("Default: ", "Set",
082: * Item.BUTTON);
083: * strItem.setDefaultCommand(
084: * new Command("Set", Command.ITEM, 1);
085: * // icl is ItemCommandListener
086: * strItem.setItemCommandListener(icl); </code></pre>
087: * </TD>
088: * </TR>
089: * </TABLE>
090: * @param label the <code>StringItem's</code> label, or <code>null</code>
091: * if no label
092: * @param text the <code>StringItem's</code> text contents, or
093: * <code>null</code> if the contents are initially empty
094: * @param appearanceMode the appearance mode of the <code>StringItem</code>,
095: * one of {@link #PLAIN}, {@link #HYPERLINK}, or {@link #BUTTON}
096: * @throws IllegalArgumentException if <code>appearanceMode</code> invalid
097: *
098: */
099: public StringItem(java.lang.String label, java.lang.String text,
100: int appearanceMode) {
101: super (label);
102:
103: synchronized (Display.LCDUILock) {
104: switch (appearanceMode) {
105: case Item.PLAIN:
106: case Item.HYPERLINK:
107: case Item.BUTTON:
108: this .appearanceMode = appearanceMode;
109: break;
110: default:
111: throw new IllegalArgumentException();
112: }
113:
114: this .str = text;
115:
116: itemLF = stringItemLF = LFFactory.getFactory()
117: .getStringItemLF(this );
118:
119: this .font = stringItemLF.getDefaultFont();
120:
121: }
122: }
123:
124: /**
125: * Gets the text contents of the <code>StringItem</code>, or
126: * <code>null</code> if the <code>StringItem</code> is
127: * empty.
128: * @return a string with the content of the item
129: * @see #setText
130: */
131: public String getText() {
132: // SYNC NOTE: return of atomic value, no locking necessary
133: return str;
134: }
135:
136: /**
137: * Sets the text contents of the <code>StringItem</code>. If text
138: * is <code>null</code>,
139: * the <code>StringItem</code>
140: * is set to be empty.
141: * @param text the new content
142: * @see #getText
143: */
144: public void setText(String text) {
145: synchronized (Display.LCDUILock) {
146: this .str = text;
147: stringItemLF.lSetText(text);
148: }
149: }
150:
151: /**
152: * Returns the appearance mode of the <code>StringItem</code>.
153: * See <a href="Item.html#appearance">Appearance Modes</a>.
154: *
155: * @return the appearance mode value,
156: * one of {@link #PLAIN}, {@link #HYPERLINK}, or {@link #BUTTON}
157: *
158: */
159: public int getAppearanceMode() {
160: // SYNC NOTE: return of atomic value, no locking necessary
161: return appearanceMode;
162: }
163:
164: /**
165: * Sets the application's preferred font for
166: * rendering this <code>StringItem</code>.
167: * The font is a hint, and the implementation may disregard
168: * the application's preferred font.
169: *
170: * <p> The <code>font</code> parameter must be a valid <code>Font</code>
171: * object or <code>null</code>. If the <code>font</code> parameter is
172: * <code>null</code>, the implementation must use its default font
173: * to render the <code>StringItem</code>.</p>
174: *
175: * @param font the preferred font to use to render this
176: * <code>StringItem</code>
177: * @see #getFont
178: */
179: public void setFont(Font font) {
180: synchronized (Display.LCDUILock) {
181: if (this .font != font) {
182: if (font == null) {
183: this .font = stringItemLF.getDefaultFont();
184: } else {
185: this .font = font;
186: }
187: stringItemLF.lSetFont(this .font);
188: }
189: }
190: }
191:
192: /**
193: * Gets the application's preferred font for
194: * rendering this <code>StringItem</code>. The
195: * value returned is the font that had been set by the application,
196: * even if that value had been disregarded by the implementation.
197: * If no font had been set by the application, or if the application
198: * explicitly set the font to <code>null</code>, the value is the default
199: * font chosen by the implementation.
200: *
201: * @return the preferred font to use to render this
202: * <code>StringItem</code>
203: * @see #setFont
204: */
205: public Font getFont() {
206: // SYNC NOTE: return of atomic value, no locking necessary
207: return font;
208: }
209:
210: /**
211: * Sets the preferred width and height for this <code>Item</code>.
212: * Values for width and height less than <code>-1</code> are illegal.
213: * If the width is between zero and the minimum width, inclusive,
214: * the minimum width is used instead.
215: * If the height is between zero and the minimum height, inclusive,
216: * the minimum height is used instead.
217: *
218: * <p>Supplying a width or height value greater than the minimum width or
219: * height <em>locks</em> that dimension to the supplied
220: * value. The implementation may silently enforce a maximum dimension for
221: * an <code>Item</code> based on factors such as the screen size.
222: * Supplying a value of
223: * <code>-1</code> for the width or height unlocks that dimension.
224: * See <a href="#sizes">Item Sizes</a> for a complete discussion.</p>
225: *
226: * <p>It is illegal to call this method if this <code>Item</code>
227: * is contained within an <code>Alert</code>.</p>
228: *
229: * @param width the value to which the width should be locked, or
230: * <code>-1</code> to unlock
231: * @param height the value to which the height should be locked, or
232: * <code>-1</code> to unlock
233: * @throws IllegalArgumentException if width or height is less than
234: * <code>-1</code>
235: * @throws IllegalStateException if this <code>Item</code> is contained
236: * within an <code>Alert</code>
237: * @see #getPreferredHeight
238: * @see #getPreferredWidth
239: */
240: public void setPreferredSize(int width, int height) {
241: super .setPreferredSize(width, height);
242: }
243:
244: // package private methods
245:
246: // package private instance variables
247:
248: /**
249: * The look&feel associated with this StringItem.
250: * Set in the constructor. getLF() should return this instance.
251: */
252: StringItemLF stringItemLF; // = null
253:
254: /** The text of this StringItem */
255: String str;
256:
257: /** The Font to render this StringItem's text in */
258: Font font;
259:
260: /** The appearance hint */
261: int appearanceMode;
262:
263: }
|