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 an image.
031: *
032: * <P> Each <code>ImageItem</code> object contains a reference to an
033: * {@link Image} object.
034: * This <code>Image</code> may be mutable or immutable. If the
035: * <code>Image</code> is mutable, the
036: * effect is as if snapshot of its contents is taken at the time the
037: * <code>ImageItem</code>
038: * is constructed with this <code>Image</code> and when
039: * <code>setImage</code> is called with an <code>Image</code>.
040: * The snapshot is used whenever the contents of the
041: * <code>ImageItem</code> are to be
042: * displayed. Even if the application subsequently draws into the
043: * <code>Image</code>, the
044: * snapshot is not modified until the next call to
045: * <code>setImage</code>. The snapshot is
046: * <em>not</em> updated when the container of the
047: * <code>ImageItem</code> becomes current or
048: * becomes visible on the display. (This is because the application does not
049: * have control over exactly when <code>Displayables</code> and Items
050: * appear and disappear
051: * from the display.)</P>
052: *
053: * <P>The value <code>null</code> may be specified for the image
054: * contents of an <code>ImageItem</code>.
055: * If
056: * this occurs (and if the label is also <code>null</code>) the
057: * <code>ImageItem</code> will occupy no
058: * space on the screen. </p>
059: *
060: * <p><code>ImageItem</code> contains layout directives that were
061: * originally defined in
062: * MIDP 1.0. These layout directives have been moved to the
063: * {@link Item} class and now apply to all items. The declarations are left
064: * in <code>ImageItem</code> for source compatibility purposes.</p>
065: *
066: * <P>The <code>altText</code> parameter specifies a string to be
067: * displayed in place of the
068: * image if the image exceeds the capacity of the display. The
069: * <code>altText</code>
070: * parameter may be <code>null</code>.</P>
071: *
072: * @since MIDP 1.0
073: */
074:
075: public class ImageItem extends Item {
076:
077: /**
078: * Creates a new <code>ImageItem</code> with the given label, image, layout
079: * directive, and alternate text string. Calling this constructor is
080: * equivalent to calling
081: *
082: * <TABLE BORDER="2">
083: * <TR>
084: * <TD ROWSPAN="1" COLSPAN="1">
085: * <pre><code>
086: * ImageItem(label, image, layout, altText, PLAIN); </code></pre>
087: * </TD>
088: * </TR>
089: * </TABLE>
090: * @param label the label string
091: * @param img the image, can be mutable or immutable
092: * @param layout a combination of layout directives
093: * @param altText the text that may be used in place of the image
094: * @throws IllegalArgumentException if the <code>layout</code> value is not
095: * a legal combination of directives
096: * @see #ImageItem(String, Image, int, String, int)
097: */
098: public ImageItem(String label, Image img, int layout, String altText) {
099: this (label, img, layout, altText, PLAIN);
100: }
101:
102: /**
103: * Creates a new <code>ImageItem</code> object with the given label, image,
104: * layout directive, alternate text string, and appearance mode.
105: * Either label or alternative text may be present or <code>null</code>.
106: *
107: * <p>The <code>appearanceMode</code> parameter
108: * (see <a href="Item.html#appearance">Appearance Modes</a>)
109: * is a hint to the platform of the application's intended use
110: * for this <code>ImageItem</code>. To provide hyperlink- or
111: * button-like behavior,
112: * the application should associate a default <code>Command</code> with this
113: * <code>ImageItem</code> and add an
114: * <code>ItemCommandListener</code> to this
115: * <code>ImageItem</code>.
116: *
117: * <p>Here is an example showing the use of an
118: * <code>ImageItem</code> as a button: <p>
119: * <TABLE BORDER="2">
120: * <TR>
121: * <TD ROWSPAN="1" COLSPAN="1">
122: * <pre><code>
123: * ImageItem imgItem =
124: * new ImageItem("Default: ", img,
125: * Item.LAYOUT_CENTER, null,
126: * Item.BUTTON);
127: * imgItem.setDefaultCommand(
128: * new Command("Set", Command.ITEM, 1);
129: * // icl is ItemCommandListener
130: * imgItem.setItemCommandListener(icl); </code></pre>
131: * </TD>
132: * </TR>
133: * </TABLE>
134: *
135: * @param label the label string
136: * @param image the image, can be mutable or immutable
137: * @param layout a combination of layout directives
138: * @param altText the text that may be used in place of the image
139: * @throws IllegalArgumentException if the <code>layout</code> value is not
140: * a legal combination of directives
141: * @param appearanceMode the appearance mode of the <code>ImageItem</code>,
142: * one of {@link #PLAIN}, {@link #HYPERLINK}, or {@link #BUTTON}
143: * @throws IllegalArgumentException if <code>appearanceMode</code> invalid
144: *
145: */
146: public ImageItem(String label, Image image, int layout,
147: String altText, int appearanceMode) {
148: super (label);
149:
150: synchronized (Display.LCDUILock) {
151:
152: setImageImpl(image);
153: setLayoutImpl(layout);
154: this .altText = altText;
155:
156: switch (appearanceMode) {
157: case Item.PLAIN:
158: case Item.HYPERLINK:
159: case Item.BUTTON:
160: this .appearanceMode = appearanceMode;
161: break;
162: default:
163: throw new IllegalArgumentException();
164: }
165:
166: itemLF = imageItemLF = LFFactory.getFactory()
167: .getImageItemLF(this );
168: } // synchronized
169: }
170:
171: /**
172: * Gets the image contained within the <code>ImageItem</code>, or
173: * <code>null</code> if there is no
174: * contained image.
175: * @return image used by the <code>ImageItem</code>
176: * @see #setImage
177: */
178: public Image getImage() {
179: synchronized (Display.LCDUILock) {
180: return mutableImg == null ? immutableImg : mutableImg;
181: }
182: }
183:
184: /**
185: * Sets the <code>Image</code> object contained within the
186: * <code>ImageItem</code>. The image may be
187: * mutable or immutable. If <code>img</code> is
188: * <code>null</code>, the <code>ImageItem</code> is set to be
189: * empty. If <code>img</code> is mutable, the effect is as if a
190: * snapshot is taken of
191: * <code>img's</code> contents immediately prior to the call to
192: * <code>setImage</code>. This
193: * snapshot is used whenever the contents of the
194: * <code>ImageItem</code> are to be
195: * displayed. If <code>img</code> is already the
196: * <code>Image</code> of this <code>ImageItem</code>, the effect
197: * is as if a new snapshot of img's contents is taken. Thus, after
198: * painting into a mutable image contained by an
199: * <code>ImageItem</code>, the
200: * application can call
201: *
202: * <TABLE BORDER="2">
203: * <TR>
204: * <TD ROWSPAN="1" COLSPAN="1">
205: * <pre><code>
206: * imageItem.setImage(imageItem.getImage()); </code></pre>
207: * </TD>
208: * </TR>
209: * </TABLE>
210: *
211: * <p>to refresh the <code>ImageItem's</code> snapshot of its Image.</p>
212: *
213: * <p>If the <code>ImageItem</code> is visible on the display when
214: * the snapshot is
215: * updated through a call to <code>setImage</code>, the display is
216: * updated with the new
217: * snapshot as soon as it is feasible for the implementation to so do.</p>
218: *
219: * @param img the <code>Image</code> for this
220: * <code>ImageItem</code>, or <code>null</code> if none
221: * @see #getImage
222: */
223: public void setImage(Image img) {
224: synchronized (Display.LCDUILock) {
225: setImageImpl(img);
226: imageItemLF.lSetImage(this .immutableImg);
227: }
228: }
229:
230: /**
231: * Gets the text string to be used if the image exceeds the device's
232: * capacity to display it.
233: *
234: * @return the alternate text value, or <code>null</code> if none
235: * @see #setAltText
236: */
237: public String getAltText() {
238: // SYNC NOTE: return of atomic value, no locking necessary
239: return altText;
240: }
241:
242: /**
243: * Sets the alternate text of the <code>ImageItem</code>, or
244: * <code>null</code> if no alternate text is provided.
245: * @param text the new alternate text
246: * @see #getAltText
247: */
248: public void setAltText(String text) {
249: synchronized (Display.LCDUILock) {
250: this .altText = text;
251: imageItemLF.lSetAltText(text);
252: }
253: }
254:
255: /**
256: * Gets the layout directives used for placing the image.
257: * @return a combination of layout directive values
258: * @see #setLayout
259: */
260: public int getLayout() {
261: // NOTE: looks odd, but this method is required for 1.0 compatibility
262: return super .getLayout();
263: }
264:
265: /**
266: * Sets the layout directives.
267: * @param layout a combination of layout directive values
268: * @throws IllegalArgumentException if the value of <code>layout</code>
269: * is not a valid
270: * combination of layout directives
271: * @see #getLayout
272: */
273: public void setLayout(int layout) {
274: // NOTE: looks odd, but this method is required for 1.0 compatibility
275: super .setLayout(layout);
276: }
277:
278: /**
279: * Returns the appearance mode of the <code>ImageItem</code>.
280: * See <a href="Item.html#appearance">Appearance Modes</a>.
281: *
282: * @return the appearance mode value,
283: * one of {@link #PLAIN}, {@link #HYPERLINK}, or {@link #BUTTON}
284: *
285: */
286: public int getAppearanceMode() {
287: return appearanceMode;
288: }
289:
290: // package private implementation
291:
292: // private
293:
294: /**
295: * Set the Image for this ImageItem
296: *
297: * @param img The image to use for this ImageItem
298: */
299: private void setImageImpl(Image img) {
300: if (img != null && img.isMutable()) {
301: this .mutableImg = img;
302: // make an immutable copy of img
303: this .immutableImg = Image.createImage(img);
304: } else {
305: this .mutableImg = null;
306: this .immutableImg = img;
307: }
308: }
309:
310: /**
311: * The look&feel associated with this ImageItem.
312: * Set in the constructor. getLF() should return this instance.
313: */
314: ImageItemLF imageItemLF; // = null
315:
316: /**
317: * The snapshot of the Image of this ImageItem;
318: * If the Image of this ImageItem was set to a mutable Image
319: * this variable is updated with a new snapshot each time setImage() is
320: * called.
321: */
322: Image immutableImg;
323:
324: /**
325: * If the ImageItem was created with a mutable image or its Image
326: * was set to a mutable image, that mutable image is stored in
327: * the mutImg variable so that ImageItem.getImage() could return it.
328: */
329: Image mutableImg;
330:
331: /**
332: * The alternate text of this ImageItem
333: */
334: String altText;
335:
336: /**
337: * The appearance hint
338: */
339: int appearanceMode;
340: }
|