component.java

Micro Window Toolkit(MWT)是一个用于开发J2ME用户界面(UI)的工具包。它具有友好

/*
 * MWT - Micro Window Toolkit
 * Copyright (C) 2007 Lucas Domanico - [e-mail]
 * 
 * Licensed under the terms of the GNU Lesser General Public License:
 * 		http://www.opensource.org/licenses/lgpl-license.php
 * 
 * For further information visit:
 * 		http://j2me-mwt.sourceforge.net/
 */

package mwt;

import java.util.Vector;

import javax.microedition.lcdui.Graphics;
import javax.microedition.lcdui.Image;



/**
 * <p>A component is an object having a graphical representation that can be displayed on
 * the screen (canvas) and can interact with the user.</p>
 * 
 * <h3><a name="containers"></a>Containers</h3>
 * <p>In MWT components can be containers, this means, that you could append child components.<br>
 * This behavior is determined when the component is created. It cannot be changed later.<br> 
 * Examples of no-container components are buttons, checkboxes and labels. Examples of
 * container components are the panels and frames/forms.</p>
 * 
 * <p>Components added are tracked in a list. The order of the list will define the components'
 * front-to-back stacking order within the container component.<br>
 * If no index is specified when adding a component to a container, it will be added to the
 * end of the list (and hence to the bottom of the stacking order).</p>
 * 
 * <p>Trying to append childs to a no-container component will throw an exception.</p>
 * 
 * 
 * <h3>Position and Size</h3>
 * <p>A component position (x and y coordinates) is relative to its parent container.<br>
 * The size is defined by its width and height.</p>
 * 
 * <p>When a component is being painted, the {@link javax.microedition.lcdui.Graphics} object is
 * translated and clipped in order to make it relative to component's position, and disable painting
 * outside its bounds.<br>
 * Note: you can change the graphics clip if you want, using {@link javax.microedition.lcdui.Graphics#setClip(int, int, int, int)})
 * howewer, this trick is not MWT related.</p>
 * 
 * 
 * <h3>Focus</h3>
 * <p>A component accepts focus when is visible, enabled, focusable and is not a container.<br>
 * Components are visible and enabled by default.<br>
 * A component may be hidden (not visible) or disabled even if {@link #isVisible()} and/or
 * {@link #isEnabled()()} returns true. This is because the component's parent hierarchy
 * affects this properties. In other words, if a container is hidden or disabled, all
 * its child hierarchy is hidden and disabled too.<br>
 * Use {@link #isHierarchyVisible()} and {@link #isHierarchyEnabled()} to know if a component and all
 * its hierarchy is visible and/or enabled.</p>
 * 
 * <p>The focusable property determines if a component should not accept focus regardless of its
 * visible and enabled properties.</p>
 * 
 * <p>Note that if you switch any of these properties to false whenever a component or one of its childs
 * has focus, you may want change its container window's focus "manually", otherwise it will remains
 * focus until the next window key event.</p>
 * 
 * <h3>Events</h3>
 * <p>Component's events can be handled overriding methods.</p>
 *
 * <table width="60%" border="1" cellspacing="0" cellpadding="0">
 * 	<tr><td>Appearance</td>
 * 		<td>{@link #paint(Graphics, Window)}</td></tr>
 * 
 *  <tr><td rowspan="2">Behavior</td>
 * 		<td>{@link #add(Component, int)}</td> </tr>
 * 	<tr><td>{@link #remove(int)}</td> </tr>
 * 
 *  <tr><td rowspan="2">Focus</td>
 * 		<td>{@link #focusGained()}</td> </tr>
 * 	<tr><td>{@link #focusLost()}</td> </tr>
 * 
 * 	<tr><td>Key</td>
 * 		<td>{@link #keyEvent(long, Window)}</td> </tr>
 * 
 *  <tr><td rowspan="8">Property Changed</td>
 * 		<td>{@link #setX(int)}</td> </tr>
 * 	<tr><td>{@link #setY(int)}</td> </tr>
 * 	<tr><td>{@link #setWidth(int)}</td> </tr>
 * 	<tr><td>{@link #setHeight(int)}</td> </tr>
 * 	<tr><td>{@link #setVisible(boolean)}</td> </tr>
 * 	<tr><td>{@link #setEnabled(boolean)}</td> </tr>
 * 	<tr><td>{@link #setFocusable(boolean)}</td> </tr>
 * 	<tr><td>{@link #setDoubleBuffered(boolean)}</td> </tr>
 * 
 * <tr><td rowspan="4">Getters</td>
 * 		<td>{@link #getX()}</td> </tr>
 * 	<tr><td>{@link #getY()}</td> </tr>
 * 	<tr><td>{@link #getWidth()}</td> </tr>
 * 	<tr><td>{@link #getHeight()}</td> </tr>
 * </table>
 * 
 * <p>Normally the appearance and key methods are overriden. This way, you can handle the
 * component's input and output.</p>
 * 
 * <p>The focus methods can be used in different ways. For example, you can validate a
 * component when it loses focus, if the validation fails you can set the focus back.</p>
 * 
 * <p>Avoid overriding setters (property changed methods) and getters unless is absolutely necessary.<br>
 * Otherwise the java virtual machine will call this methods indirectly via a virtual table,
 * instead of calling them directly (which -may- impact performance significally).</p>
 * 
 * <h3><a name="align"></a>Align Constants</h3>
 * This class contains aligns constant that can be used in different ways.
 * For example, text alignment.
 * 
<table width="334" border="0" cellspacing="4" cellpadding="0" style="border: 1px black solid">
  <tr>
    <td width="232" bgcolor="#CEDBFF">{@link #ALIGN_TOP_LEFT}</td>
    <td width="90" bgcolor="#CEDBFF"><img src="{@docRoot}/resources/font_sys_anchor_top_left.png" width="90" height="30" /></td>
  </tr>
  <tr>
    <td bgcolor="#CEDBFF">{@link #ALIGN_TOP_CENTER}</td>
    <td bgcolor="#CEDBFF"><img src="{@docRoot}/resources/font_sys_anchor_top_center.png" width="90" height="30" /></td>
  </tr>
  <tr>
    <td bgcolor="#CEDBFF">{@link #ALIGN_TOP_RIGHT}</td>
    <td bgcolor="#CEDBFF"><img src="{@docRoot}/resources/font_sys_anchor_top_right.png" width="90" height="30" /></td>
  </tr>
  <tr>
    <td bgcolor="#CEDBFF">{@link #ALIGN_MIDDLE_LEFT}</td>
    <td bgcolor="#CEDBFF"><img src="{@docRoot}/resources/font_sys_anchor_middle_left.png" width="90" height="30" /></td>
  </tr>
  <tr>
    <td bgcolor="#CEDBFF">{@link #ALIGN_MIDDLE_CENTER}</td>
    <td bgcolor="#CEDBFF"><img src="{@docRoot}/resources/font_sys_anchor_middle_center.png" width="90" height="30" /></td>
  </tr>
  <tr>
    <td bgcolor="#CEDBFF">{@link #ALIGN_MIDDLE_RIGHT}</td>
    <td bgcolor="#CEDBFF"><img src="{@docRoot}/resources/font_sys_anchor_middle_right.png" width="90" height="30" /></td>
  </tr>
  <tr>
    <td bgcolor="#CEDBFF">{@link #ALIGN_BOTTOM_LEFT}</td>
    <td bgcolor="#CEDBFF"><img src="{@docRoot}/resources/font_sys_anchor_bottom_left.png" width="90" height="30" /></td>
  </tr>
  <tr>
    <td bgcolor="#CEDBFF">{@link #ALIGN_BOTTOM_CENTER}</td>
    <td bgcolor="#CEDBFF"><img src="{@docRoot}/resources/font_sys_anchor_bottom_center.png" width="90" height="30" /></td>
  </tr>
  <tr>
    <td bgcolor="#CEDBFF">{@link #ALIGN_BOTTOM_RIGHT}</td>
    <td bgcolor="#CEDBFF"><img src="{@docRoot}/resources/font_sys_anchor_bottom_right.png" width="90" height="30" /></td>
  </tr>
</table>
 * 
 */
public class Component {
    /** Constant for component/text alignment. */ 
    static final public int ALIGN_TOP_LEFT = 0;
    /** Constant for component/text alignment. */
	static final public int ALIGN_TOP_CENTER = Graphics.TOP|Graphics.HCENTER;
	/** Constant for component/text alignment. */
	static final public int ALIGN_TOP_RIGHT = Graphics.TOP|Graphics.RIGHT;
	/** Constant for component/text alignment. */
	static final public int ALIGN_MIDDLE_LEFT = Graphics.VCENTER|Graphics.LEFT;
	/** Constant for component/text alignment. */
	static final public int ALIGN_MIDDLE_CENTER = Graphics.VCENTER|Graphics.HCENTER;
	/** Constant for component/text alignment. */
	static final public int ALIGN_MIDDLE_RIGHT = Graphics.VCENTER|Graphics.RIGHT;
	/** Constant for component/text alignment. */
	static final public int ALIGN_BOTTOM_LEFT = Graphics.BOTTOM|Graphics.LEFT;
	/** Constant for component/text alignment. */
	static final public int ALIGN_BOTTOM_CENTER = Graphics.BOTTOM|Graphics.HCENTER;
	/** Constant for component/text alignment. */
	static final public int ALIGN_BOTTOM_RIGHT = Graphics.BOTTOM|Graphics.RIGHT;
	
	private Component parent;
	final Vector childs = new Vector(); // <Component>, package friendly since it's used by Window
	
	private boolean enabled = true;
	private boolean visible = true;
	private int x;
	private int y;
	private int width;
	private int height;
	private boolean focusable;
	private boolean doubleBuffered;
	final private boolean isContainer;
	
	
	// used by Skin: if doubleBuffered is true, the skin class will try to cache a image.
	// The width and height are saved since if the component is resized, the cache is cleared
	int skinWidth;
	int skinHeight;
	Image skinImage;
	int skinCount;

	
	private String id = ""; // since 1.2
	
	/**
	 * Creates a new component with the given position and size.<br>
	 * If the component should be a container, childs can be appended but it will cannot accept focus.
	 * @see <a href="#containers">Containers</a>
	 */
	public Component(int x, int y, int width, int height, boolean isContainer) {
		this.setX(x);
		this.setY(y);
		this.setWidth(width);
		this.setHeight(height);
		this.focusable = !isContainer;
		this.isContainer = isContainer;
	}
	
	
	/** Gets the id.
	 * 	@since 1.2 */
	final public String getId() { return id; }
	/** Sets the id.
	 * 	@since 1.2 */
	final public void setId(String id) { this.id = id; }
	
	/** Gets the x coordinate of this component within the parent.*/
	public int getX()	{ return x;	}
	/** Sets the x coordinate of this component within the parent. */
	public void setX(int x) { this.x = x; }
	
	/** Gets the y coordinate of this component within the parent. */
	public int getY() { return y; }
	/** Sets the y coordinate of this component within the parent. */
	public void setY(int y) { this.y = y; }
	
	/** Gets the width of this component, in pixels. */
	//public int getWidth() { return (width >= 0)? width : (-width*parent.getWidth())/100; }
	public int getWidth() { return width; }
	/** Sets the width of this component, in pixels. */
	public void setWidth(int width) { this.width = width; }
	
	/** Gets the height of this component, in pixels. */
	//public int getHeight() { return (height >= 0)? height : (-height*parent.getHeight())/100; }
	public int getHeight() { return height; }
	/** Sets the height of this component, in pixels. */
	public void setHeight(int height) { this.height = height; }

	/** Checks if this component should be visible when its parent hierarchy is visible.
	 *	@see #isHierarchyVisible() */ 
	final public boolean isVisible() { return visible; }
	/** Shows or hides this component. By default components are visible. */ 
	public void setVisible(boolean visible) { this.visible = visible; }
	
	/** Checks if this component should be enabled when its parent hierarchy is enabled.
	 *	@see #isHierarchyEnabled() */
	final public boolean isEnabled() { return enabled; }
	/** Enables or disables this component. By default components are enabled. */
	public void setEnabled(boolean enabled) { this.enabled = enabled; }
	
	/** Checks if this component is focusable.
	 *	@see #acceptsFocus() */
	final public boolean isFocusable() { return focusable; }
	/** Enables or disables focusable.
	 *	@see #acceptsFocus() */
	public void setFocusable(boolean focusStop) { this.focusable = focusStop; }
	
	/** Checks if this component should be double buffered. */
	final public boolean isDoubleBuffered() { return doubleBuffered; }
	/** Enables or disables the double buffer. By default components are not double buffered. */
	public void setDoubleBuffered(boolean doubleBuffered) {
		this.doubleBuffered = doubleBuffered;
		if(!doubleBuffered) this.skinImage = null;
		else skinCount = skinCount = 1;
	}
	
	/** Checks if this component and its parent hierarchy is visible.
	 *	@see #isVisible() */