component.java

关于J4ME J2ME实例

package org.j4me.ui.components;

import javax.microedition.lcdui.*;
import org.j4me.ui.*;

/**
 * Components are UI widgets that appear on forms.  Examples of components include
 * labels, text boxes, and check boxes.  The <code>Dialog</code> class calls methods on
 * this interface to layout, paint, and manage components.
 */
public abstract class Component
{
	/**
	 * Components that highlight entry boxes should use this value as a width for
	 * their borders.  For example an unselected text box appears as a rectangle
	 * but a selected text box has a border around it that is this thick and has
	 * rounded edges.
	 */
	protected static final int HIGHLIGHTED_BORDER_WIDTH = 2;
	
	/**
	 * The horizontal justification of the text in this label.  It must be one of
	 * <code>Graphics.LEFT</code>, <code>Graphics.HCENTER</code>, and <code>Graphics.RIGHT</code>.
	 */
	private int horizontalAlignment = Graphics.LEFT;
	
	/**
	 * Whether the component is currently visible on the screen or not.
	 */
	private boolean visible;
	
	/**
	 * The screen this component is placed on.
	 */
	private DeviceScreen screen;
	
	/**
	 * The left corner pixel of this component.  This value is specified by the
	 * last call to <code>paint</code>.
	 */
	private int x;
	
	/**
	 * The top corner pixel of this component.  This value is specified by the
	 * last call to <code>paint</code>.
	 */
	private int y;
	
	/**
	 * The width of this component in pixels.  This value is specified by the
	 * last call to <code>paint</code>.
	 */
	private int width;
	
	/**
	 * The height of this component in pixels.  This value is specified by the
	 * last call to <code>paint</code>.
	 */
	private int height;
	
	/**
	 * Constructs a component and attaches it to a screen.
	 */
	public Component ()
	{
	}

	/**
	 * Paints the component using <code>g</code>.  The top-left corner is at (0,0)
	 * and the component fills the rectangle bounded by <code>width</code> and
	 * <code>height</code>. 
	 * 
	 * @param g is the <code>Graphics</code> object to be used for rendering the item.
	 * @param theme is the application's theme.  Use it to get fonts and colors.
	 * @param screen is the screen object displaying this component.
	 * @param x is the left corner pixel of the component.
	 * @param y is the top corner pixel of the component.
	 * @param width is the width, in pixels, to paint the component.
	 * @param height is the height, in pixels, to paint the component.
	 * @param selected is <code>true</code> when this components is currently selected
	 *  and <code>false</code> when it is not.
	 */
	public final void paint (Graphics g, Theme theme, DeviceScreen screen,
			int x, int y, int width, int height,
			boolean selected)
	{
		if ( isShown() )
		{
			// Record the position of this component.
			this.screen = screen;
			this.x = x;
			this.y = y;
			this.width = width;
			this.height = height;
			
			// Set the graphics properties for painting the component.
			int originalClipX = g.getClipX();
			int originalClipY = g.getClipY();
			int originalClipWidth = g.getClipWidth();
			int originalClipHeight = g.getClipHeight();
	
			// Workaround a bug by doubling the clip height.
			//  The Sun WTK clips the bottom of graphics operations for
			//  rounded rectangle drawing and filling.  This can be
			//  avoided by doubling the clip height.
			g.setClip( originalClipX, originalClipY, originalClipWidth, originalClipHeight * 2 );
			
			g.translate( x, y );
	
			g.clipRect( 0, 0, width, height * 2 );  // *2 to workaround clipping bug
			
			int originalColor = g.getColor();
			g.setColor( theme.getFontColor() );
			
			Font originalFont = g.getFont();
			g.setFont( theme.getFont() );
			
			int originalStroke = g.getStrokeStyle();
			g.setStrokeStyle( Graphics.SOLID );
			
			// Actually paint the component.
			paintComponent( g, theme, width, height, selected );
			
			// Reset the graphics properties.
			g.translate( -x, -y );
			g.setClip( originalClipX, originalClipY, originalClipWidth, originalClipHeight );
			g.setColor( originalColor );
			g.setFont( originalFont );
			g.setStrokeStyle( originalStroke );
		}
	}
	
	/**
	 * Implemented by the subclass to render the item within its container.  At the
	 * time of the call, the <code>Graphic</code>s context's destination is the content area of
	 * this <code>Component</code> (or back buffer for it).  The translation is set so that
	 * the upper left corner of the content area is at (0,0), and the clip is set
	 * to the area to be painted.  The application must paint every pixel within
	 * the given clip area.  The item is allowed to modify the clip area, but the 
	 * system must not allow any modification to result in drawing outside the 
	 * bounds of the item's content area.  The <code>w</code> and <code>h</code> passed in are the width
	 * and height of the content area of the item.  These values will always be
	 * set to the clip width and height and are passed here for convenience.
	 * <p>
	 * Other values of the <code>Graphics</code> object are as follows:
	 * <ul>
	 *  <li>the current color is <code>Theme.getFontColor()</code>;
	 *  <li>the font is <code>Theme.getFont()</code>;
	 *  <li>the stroke style is <code>SOLID</code>;
	 * </ul>
	 * <p>
	 * The <code>paint()</code> method will be called only when at least a portion of the
	 * item is actually visible on the display.
	 * 
	 * @param g is the <code>Graphics</code> object to be used for rendering the item.
	 * @param theme is the application's theme.  Use it to get fonts and colors.
	 * @param width is the width, in pixels, to paint the component.
	 * @param height is the height, in pixels, to paint the component.
	 * @param selected is <code>true</code> when this components is currently selected
	 *  and <code>false</code> when it is not.
	 */
	protected abstract void paintComponent (Graphics g, Theme theme, int width, int height, boolean selected);
	
	/**
	 * Returns the desired width and height of this component in pixels.
	 * 
	 * @param theme is the application's <code>Theme</code>.
	 * @param viewportWidth is the width of the screen in pixels.
	 * @param viewportHeight is the height of the screen in pixels.
	 * @return A array with two elements where the first is the width of the
	 *  component in pixels and the second is the height.
	 */
	public final int[] getPreferredSize (Theme theme, int viewportWidth, int viewportHeight)
	{
		// Get the component's dimensions.
		int[] dimensions = getPreferredComponentSize( theme, viewportWidth, viewportHeight );
		
		if ( (dimensions == null) || (dimensions.length != 2) )
		{
			throw new RuntimeException(getClass().getName() + ".getPreferredComponentSize must return an array of length 2");
		}
		
		return dimensions;
	}
	
	/**
	 * Returns the desired width and height of this component in pixels.
	 * It cannot be wider than the screen or it will be cropped.  However, it can
	 * be taller than the screen, in which case a scroll bar will be added to
	 * the form this component resides on.
	 * 
	 * @param theme is the application's <code>Theme</code>.
	 * @param viewportWidth is the width of the viewable area, in pixels,
	 *  the component can use.
	 * @param viewportHeight is the height of the viewable area, in pixels,
	 *  the component can use.
	 * @return A array with two elements where the first is the width of the
	 *  component in pixels and the second is the height.
	 */
	protected abstract int[] getPreferredComponentSize (Theme theme, int viewportWidth, int viewportHeight);
	
	/**
	 * Tells if this component accepts user input or not.  If it does then
	 * it can be scrolled to by the user.  If it does not, it will be displayed,
	 * but can be skipped over by scrolling.
	 * <p>
	 * The default implementation returns <code>false</code>.  Override this method
	 * to return <code>true</code> if the component accepts input.
	 * 
	 * @return <code>true</code> if the component accepts user input; <code>false</code> if
	 *  it does not.
	 */
	public boolean acceptsInput ()
	{
		return false;
	}
	
	/**
	 * @return The screen displaying this component.
	 */
	public DeviceScreen getScreen ()
	{
		return screen;
	}
	
	/**
	 * @return The pixel for the left side of this component.
	 */
	public int getX ()
	{
		return x;
	}
	
	/**
	 * @return The pixel for the top of this component.
	 */
	public int getY ()
	{
		return y;
	}
	
	/**
	 * @return The width, in pixels, for this component.
	 */
	public int getWidth ()
	{
		return width;
	}