imageitem.java

有关j2me的很好的例子可以研究一下

/*
 * @(#)ImageItem.java	1.45 01/08/16
 * Copyright (c) 1999-2001 Sun Microsystems, Inc. All Rights Reserved.
 *
 * This software is the confidential and proprietary information of Sun
 * Microsystems, Inc. ("Confidential Information").  You shall not
 * disclose such Confidential Information and shall use it only in
 * accordance with the terms of the license agreement you entered into
 * with Sun.
 *
 * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
 * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
 * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
 * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
 * THIS SOFTWARE OR ITS DERIVATIVES.
 */
package javax.microedition.lcdui;

/**
 * <P>A class that provides layout control when Image objects are added
 * to a {@link Form Form} or to an {@link Alert Alert}. </p>
 *
 * <P>Each ImageItem object contains a reference to an Image object. This image
 * must be immutable. (If the image object were not required to be immutable,
 * the application could paint into it at any time, potentially requiring
 * the containing Form or Alert to be updated on every graphics call.) See
 * the definition of the {@link Image Image} object for further details on
 * image mutability how to create immutable images. </p>
 *
 * <P>The value null may be specified for the image contents of an ImageItem. If
 * this occurs (and if the label is also null) the ImageItem will occupy no
 * space on the screen. </p>
 *
 * <P>Each ImageItem object contains a layout field that is combined from the
 * following values:
 * LAYOUT_LEFT, LAYOUT_RIGHT, LAYOUT_CENTER,
 * LAYOUT_NEWLINE_BEFORE, and LAYOUT_NEWLINE_AFTER.
 * LAYOUT_LEFT + LAYOUT_RIGHT is equal to
 * LAYOUT_CENTER. LAYOUT_DEFAULT may be specified, which indicates that the
 * system should use its default layout policy for this ImageItem.
 * The value of the layout field is merely a hint. Because of device
 * constraints, such as limited screen size, the implementation may choose to
 * ignore layout directions. </p>
 *
 * <P>There are some implicit rules on how the layout directives can
 *  be combined:
 * <UL>
 * <LI>LAYOUT_DEFAULT cannot not be combined with any other directive.
 *  In fact, any
 * other value will override LAYOUT_DEFAULT since its value is 0.
 * <LI>LAYOUT_LEFT, LAYOUT_RIGHT and LAYOUT_CENTER are meant to be mutually
 * exclusive.
 * <LI>It usually makes sense to combine LAYOUT_LEFT, LAYOUT_RIGHT
 * and LAYOUT_CENTER with
 * LAYOUT_NEWLINE_BEFORE and LAYOUT_NEWLINE_AFTER.
 * </UL>
 *
 * <P>The altText parameter specifies a string to be displayed in place of the
 * image if the image exceeds the capacity of the display. The altText
 * parameter may be null.</P>
 */
public class ImageItem extends Item {

    /**
     * <P>Use the default formatting of the "container" of the image.</P>
     *
     * <P>Value 0 is assigned to LAYOUT_DEFAULT.</P>
     */
    public final static int LAYOUT_DEFAULT = 0;

    /**
     * <P>Image should be close to left-edge of the drawing area.</P>
     *
     * <P>Value 1 is assigned to LAYOUT_LEFT.</P>
     */
    public final static int LAYOUT_LEFT = 1;
    
    /**
     * <P>Image should be close to right-edge of the drawing area.</P>
     *
     * <P>Value 2 is assigned to LAYOUT_RIGHT.</P>
     */
    public final static int LAYOUT_RIGHT = 2;

    /**
     * <P>Image should be horizontally centered.</P>
     *
     * <P>Value 3 is assigned to LAYOUT_CENTER.</P>
     */
    public final static int LAYOUT_CENTER = 3;
    
    /**
     * <P>A new line should be started before the image is drawn.</P>
     *
     * <P>Value 0x100 is assigned to LAYOUT_NEWLINE_BEFORE.</P>
     */
    public final static int LAYOUT_NEWLINE_BEFORE = 0x100;
    
    /**
     * <P>A new line should be started after the image is drawn.</P>
     *
     * <P>Value 0x200 is assigned to LAYOUT_DEFAULT.</P>
     */
    public final static int LAYOUT_NEWLINE_AFTER = 0x200;

    /**
     * The Image of this ImageItem
     */
    private Image img;
    /**
     * The alternate text of this ImageItem
     */
    private String altText;
    /**
     * The layout type of this ImageItem
     */
    private int layout;

    /**
     * Creates a new ImageItem with the given label, image, layout
     * directive, and alternate text string.
     * @param label the label string
     * @param img the image, must be immutable
     * @param layout a combination of layout directives
     * @param altText the text that may be used in place of the image
     * @throws IllegalArgumentException if the image is mutable
     * @throws IllegalArgumentException if the layout value is not
     * a legal combination of directives
     */
    public ImageItem(String label, Image img, int layout, String altText) {
        super(label);

        synchronized (Display.LCDUILock) {
            layouts = new Layout[1];

            setImageImpl(img);
            setLayoutImpl(layout);
            setAltTextImpl(altText);
        }
    }

    /**
     * Gets the image contained within the ImageItem, or null if there is no
     * contained image.
     * @return image used by the ImageItem
     *
     * @see #setImage
     */
    public Image getImage() {
        // SYNC NOTE: return of atomic value, no locking necessary
        return img;
    }

    /**
     * Sets the image object contained within the ImageItem.  The image must 
     * be immutable.
     * If img is null, the
     * ImageItem is set to be empty.
     *
     * @param img the new image
     *
     * @throws IllegalArgumentException if the image is mutable
     *
     * @see #getImage
     */
    public void setImage(Image img) {
        synchronized (Display.LCDUILock) {
            setImageImpl(img);
            handleContentChanged();
        }
    }

    /**
     * Gets the text string to be used if the image exceeds the device's
     * capacity to display it.
     *
     * @return the alternate text value, or null if none
     *
     * @see #setAltText
     */
    public String getAltText() { 
        // SYNC NOTE: return of atomic value, no locking necessary
        return altText;
    }

    /**
     * Sets the alternate text of the ImageItem, or null if no alternate text is
     * provided.
     * @param text the new alternate text
     *
     * @see #getAltText
     */
    public void setAltText(String text) {
        synchronized (Display.LCDUILock) {
            setAltTextImpl(text);
            handleContentChanged();
        }
    }

    /**
     * Gets the layout directives used for placing the image.
     * @return a combination of layout directive values
     *
     * @see #setLayout
     */
    public int getLayout() {
        // SYNC NOTE: return of atomic value, no locking necessary
        return layout;
    }

    /**
     * Sets the layout directives.
     * @param layout a combination of layout directive values
     * @throws IllegalArgumentException if the value of layout is not a valid
     * combination of layout directives
     *
     * @see #getLayout
     */
    public void setLayout(int layout) {
        synchronized (Display.LCDUILock) {
            setLayoutImpl(layout);
            handleContentChanged();
        }
    }

    /**
     * Sets the label of the Item. If label is null, specifies that this
     * item has no label.
     * @param label the label string
     */
    public void setLabel(String label) {
        synchronized (Display.LCDUILock) {
            super.setLabel(label);
            handleContentChanged();
        }
    }

    // package private

    /**
     * StringItems and ImageItems are grouped together.
     *
     * @param item  to be checked against
     * @return true if this Item and passed in item are part of the 
     *         same group, otherwise false is returned
     */
    boolean isGrouped(Item item) {
        if (item != null && item.isGroupable()) {
            return item.layouts[0] == layouts[0];
        }

        return false;
    }

    /**
     * Determines if that item can be grouped with other items in a
     * common layout.
     * @return true if this item can be grouped with others; 
     *         false - otherwise
     */
    boolean isGroupable() {
        return true;
    }

    /**
     * Determine if this ImageItem can take focus
     *
     * @return boolean Always returns false
     */
    boolean takesFocus() {
        return false;
    }

    /**
     * Get the pixel height of this ImageItem
     *
     * @return int The pixel height of this ImageItem
     */
    int getHeight() {
        if (layouts[0] == null) {
            return 0;
        }

        return layouts[0].getHeight();
    }

    /**
     * Set the allowable width for this ImageItem
     *
     * @param width The maximum allowable width for this ImageItem
     * @return int The height required to display this ImageItem
     *              given the maximum allowable width
     */
    int setWidth(int width) {
        if (layouts[0] == null) {
            return 0;
        }

        return layouts[0].setWidth(width);
    }

    /**
     * Paint this ImageItem
     *
     * @param g The Graphics context to paint to
     */
    void paint(Graphics g) {
        if (layouts[0] != null) {
            layouts[0].paint(g, true, false);
        }
    }

    // private

    /**
     * Set the Image for this ImageItem
     *
     * @param img The image to use for this ImageItem
     */
    private void setImageImpl(Image img) {
        if (img != null && img.isMutable()) {
            throw new IllegalArgumentException();
        }

        this.img = img;
    }

    /**
     * Set the layout type of this ImageItem
     *
     * @param layout The layout type: left, right, center,
     *              newline before, or newline after
     */
    private void setLayoutImpl(int layout) {
        int allowedLayout = ImageItem.LAYOUT_DEFAULT |
            ImageItem.LAYOUT_LEFT |
            ImageItem.LAYOUT_RIGHT |
            ImageItem.LAYOUT_CENTER |
            ImageItem.LAYOUT_NEWLINE_BEFORE |
            ImageItem.LAYOUT_NEWLINE_AFTER;

        if ((layout & ~allowedLayout) != 0) {
            throw new IllegalArgumentException();
        }

        this.layout = layout;
    }

    /**
     * Set the alternate text for this ImageItem
     *
     * @param text The alternate text for this ImageItem
     */
    private void setAltTextImpl(String text) {
        this.altText = text;
    }

    /**
     * Re-layout this ImageItem if necessary when its contents
     * change
     */
    private void handleContentChanged() {
        if (!initLayoutDone() || layouts[0] == null) {
            return;
        }

        contentChanged(0, 0,
            ((TaGLayout)layouts[0]).itemContentChanged(this));

    }
}