item.java

j2me polish学习的经典代码

	 * only when the item is active, for example, highlighted.
	 * <p>
	 * If the added command is already in the item (tested by comparing the
	 * object references), the method has no effect. If the item is
	 * actually visible on the display, and this call affects the set of
	 * visible commands, the implementation should update the display as soon
	 * as it is feasible to do so.
	 * 
	 * <p>It is illegal to call this method if this <code>Item</code>
	 * is contained within an <code>Alert</code>.</p>
	 * 
	 * @param cmd the command to be added
	 * @throws IllegalStateException if this Item is contained within an Alert
	 * @throws NullPointerException if cmd is null
	 * @since  MIDP 2.0
	 */
	public void addCommand( Command cmd)
	{
		if (this.commands == null) {
			this.commands = new ArrayList();
		}
		if (!this.commands.contains( cmd )) {
			this.commands.add(cmd);
			if (this.appearanceMode == PLAIN) {
				this.appearanceMode = HYPERLINK;
			}
			if (this.isFocused) {
				Screen scr = getScreen();
				if (scr != null) {
					scr.addCommand( cmd );
				}
			}
			if (this.isInitialised) {
				repaint();
			}
		}
	}

	/**
	 * Repaints the screen to which this item belongs to.
	 * Subclasses can call this method whenever their contents
	 * have changed and they need an immediate refresh. 
	 */
	protected void repaint() {
		//System.out.println("repaint called by class " + getClass().getName() );
		if (this.parent instanceof Container) {
			((Container) this.parent).isInitialised = false;
		}
		Screen scr = getScreen();
		if (scr != null && scr == StyleSheet.currentScreen) {
			scr.repaint();
		}
	}
	
	/**
	 * Requests that this item and all its parents are to be re-initialised at the next repainting.
	 * All parents of this item are notified, too.
	 * This method should be called when an item changes its size more than
	 * usual.
	 * When the item already has been initialised, a repaint() is requested, too.
	 */
	protected void requestInit() {
		//System.out.println("requestInit called by class " + getClass().getName() + " - screen.class=" + getScreen().getClass().getName()  );
		Item p = this.parent;
		while ( p != null) {
			p.isInitialised = false;
			p = p.parent;
		}
		if (this.isInitialised) {
			this.isInitialised = false;
			repaint();
		}
	}
	
	/**
	 * Retrieves the screen to which this item belongs to.
	 * 
	 * @return either the corresponding screen or null when no screen could be found 
	 */
	public Screen getScreen() {
		if (this.screen != null) {
			return this.screen;
		} else if (this.parent != null) {
			Item p = this.parent;
			while (p.parent != null) {
				p = p.parent;
			}
			return p.screen;
		} else {
			return null;
		}
	}

	/**
	 * Removes the context sensitive command from item. If the command is not
	 * in the <code>Item</code> (tested by comparing the object references),
	 * the method has
	 * no effect. If the <code>Item</code> is actually visible on the display,
	 * and this  call
	 * affects the set of visible commands, the implementation should update
	 * the display as soon as it is feasible to do so.
	 * 
	 * 
	 * If the command to be removed happens to be the default command,
	 * the command is removed and the default command on this Item is
	 * set to <code>null</code>.
	 * 
	 * The following code:
	 * <CODE> <pre>
	 * // Command c is the default command on Item item
	 * item.removeCommand(c);
	 * </pre> </CODE>
	 * is equivalent to the following code:
	 * <CODE> <pre>
	 * // Command c is the default command on Item item
	 * item.setDefaultCommand(null);
	 * item.removeCommand(c);
	 * </pre> </CODE>
	 * 
	 * @param cmd - the command to be removed
	 * @since  MIDP 2.0
	 */
	public void removeCommand( Command cmd ) {
		if (this.commands != null) {
			if (cmd == this.defaultCommand) {
				this.defaultCommand = null;
			}
			if (this.commands.remove(cmd)) {
				if (this.isFocused) {
					Screen scr = getScreen();
					if (scr != null) {
						scr.removeCommand( cmd );
					}
				}
				if (this.isInitialised) {
					repaint();
				}
			}
		}
	}

	/**
	 * Sets a listener for <code>Commands</code> to this <code>Item</code>,
	 * replacing any previous
	 * <code>ItemCommandListener</code>. A <code>null</code> reference
	 * is allowed and has the effect of removing any existing listener.
	 * 
	 * When no listener is registered, J2ME Polish notofies the 
	 * command-listener of the current screen, when an item command 
	 * has been selected.
	 * 
	 * <p>It is illegal to call this method if this <code>Item</code>
	 * is contained within an <code>Alert</code>.</p>
	 * 
	 * @param l the new listener, or null.
	 * @throws IllegalStateException if this Item is contained within an Alert
	 * @since  MIDP 2.0
	 */
	public void setItemCommandListener( ItemCommandListener l)
	{
		this.itemCommandListener = l;
	}

	/**
	 * Gets the preferred width of this <code>Item</code>.
	 * If the application has locked
	 * the width to a specific value, this method returns that value.
	 * Otherwise, the return value is computed based on the
	 * <code>Item's</code> contents,
	 * possibly with respect to the <code>Item's</code> preferred height
	 * if it is locked.
	 * See <a href="#sizes">Item Sizes</a> for a complete discussion.
	 * 
	 * @return the preferred width of the Item
	 * @see #getPreferredHeight()
	 * @see #setPreferredSize(int, int)
	 * @since  MIDP 2.0
	 */
	public int getPreferredWidth()
	{
		return this.preferredWidth;
	}

	/**
	 * Gets the preferred height of this <code>Item</code>.
	 * If the application has locked
	 * the height to a specific value, this method returns that value.
	 * Otherwise, the return value is computed based on the
	 * <code>Item's</code> contents,
	 * possibly with respect to the <code>Item's</code> preferred
	 * width if it is locked.
	 * See <a href="#sizes">Item Sizes</a> for a complete discussion.
	 * 
	 * @return the preferred height of the Item
	 * @see #getPreferredWidth()
	 * @see #setPreferredSize(int, int)
	 * @since  MIDP 2.0
	 */
	public int getPreferredHeight()
	{
		return this.preferredHeight;
	}

	/**
	 * Sets the preferred width and height for this <code>Item</code>.
	 * Values for width and height less than <code>-1</code> are illegal.
	 * If the width is between zero and the minimum width, inclusive,
	 * the minimum width is used instead.
	 * If the height is between zero and the minimum height, inclusive,
	 * the minimum height is used instead.
	 * 
	 * <p>Supplying a width or height value greater than the minimum width or
	 * height <em>locks</em> that dimension to the supplied
	 * value.  The implementation may silently enforce a maximum dimension for
	 * an <code>Item</code> based on factors such as the screen size.
	 * Supplying a value of
	 * <code>-1</code> for the width or height unlocks that dimension.
	 * See <a href="#sizes">Item Sizes</a> for a complete discussion.</p>
	 * 
	 * <p>It is illegal to call this method if this <code>Item</code>
	 * is contained within  an <code>Alert</code>.</p>
	 * 
	 * @param width - the value to which the width should be locked, or -1 to unlock
	 * @param height - the value to which the height should be locked, or -1 to unlock
	 * @throws IllegalArgumentException - if width or height is less than -1
	 * @throws IllegalStateException - if this Item is contained within an Alert
	 * @see #getPreferredHeight()
	 * @see #getPreferredWidth()
	 * @since  MIDP 2.0
	 */
	public void setPreferredSize(int width, int height)
	{
		this.preferredHeight = height;
		this.preferredWidth = width;
	}

	/**
	 * Gets the minimum width for this <code>Item</code>.  This is a width
	 * at which the item can function and display its contents,
	 * though perhaps not optimally.
	 * See <a href="#sizes">Item Sizes</a> for a complete discussion.
	 * 
	 * @return the minimum width of the item
	 * @since  MIDP 2.0
	 */
	public int getMinimumWidth()
	{
		return this.minimumWidth;
	}

	/**
	 * Gets the minimum height for this <code>Item</code>.  This is a height
	 * at which the item can function and display its contents,
	 * though perhaps not optimally.
	 * See <a href="#sizes">Item Sizes</a> for a complete discussion.
	 * 
	 * @return the minimum height of the item
	 * @since  MIDP 2.0
	 */
	public int getMinimumHeight()
	{
		return this.minimumHeight;
	}

	/**
	 * Sets default <code>Command</code> for this <code>Item</code>.
	 * If the <code>Item</code> previously had a
	 * default <code>Command</code>, that <code>Command</code>
	 * is no longer the default, but it
	 * remains present on the <code>Item</code>.
	 * 
	 * <p>If not <code>null</code>, the <code>Command</code> object
	 * passed becomes the default <code>Command</code>
	 * for this <code>Item</code>.  If the <code>Command</code> object
	 * passed is not currently present
	 * on this <code>Item</code>, it is added as if <A HREF="../../../javax/microedition/lcdui/Item.html#addCommand(javax.microedition.lcdui.Command)"><CODE>addCommand(javax.microedition.lcdui.Command)</CODE></A>
	 * had been called
	 * before it is made the default <code>Command</code>, unless the &quot;polish.Item.suppressDefaultCommand&quot; preprocessing variable is set to &quot;true&quot;.</p>
	 * 
	 * <p>If <code>null</code> is passed, the <code>Item</code> is set to
	 * have no default <code>Command</code>.
	 * The previous default <code>Command</code>, if any, remains present
	 * on the <code>Item</code>.
	 * </p>
	 * 
	 * <p>It is illegal to call this method if this <code>Item</code>
	 * is contained within  an <code>Alert</code>.</p>
	 * 
	 * @param cmd the command to be used as this Item's default Command, or null if there is to be no default command
	 * @throws IllegalStateException - if this Item is contained within an Alert
	 * @since  MIDP 2.0
	 */
	public void setDefaultCommand( Command cmd)
	{
		//#if !polish.Item.suppressDefaultCommand
		if (this.defaultCommand != null && cmd != this.defaultCommand) {
			addCommand(this.defaultCommand);
		}
		//#endif		
		this.defaultCommand = cmd;
		//#if !polish.Item.suppressDefaultCommand
		if (cmd != null) {
			addCommand(cmd);
		}
		//#endif
	}

	/**
	 * Causes this <code>Item's</code> containing <code>Form</code> to notify
	 * the <code>Item's</code> <CODE>ItemStateListener</CODE>.
	 * The application calls this method to inform the
	 * listener on the <code>Item</code> that the <code>Item's</code>
	 * state has been changed in
	 * response to an action.  Even though this method simply causes a call
	 * to another part of the application, this mechanism is useful for
	 * decoupling the implementation of an <code>Item</code> (in particular, the
	 * implementation of a <code>CustomItem</code>, though this also applies to
	 * subclasses of other items) from the consumer of the item.
	 * 
	 * <p>If an edit was performed by invoking a separate screen, and the
	 * editor now wishes to &quot;return&quot; to the form which contained the
	 * selected <code>Item</code>, the preferred method is
	 * <code>Display.setCurrent(Item)</code>
	 * instead of <code>Display.setCurrent(Displayable)</code>,
	 * because it allows the
	 * <code>Form</code> to restore focus to the <code>Item</code>
	 * that initially invoked the editor.</p>
	 * 
	 * <p>In order to make sure that the documented behavior of
	 * <code>ItemStateListener</code> is maintained, it is up to the caller
	 * (application) to guarantee that this function is
	 * not called unless:</p>
	 * 
	 * <ul>
	 * <li>the <code>Item's</code> value has actually been changed, and</li>
	 * <li>the change was the result of a user action (an &quot;edit&quot;)
	 * and NOT as a result of state change via calls to
	 * <code>Item's</code> APIs </li>
	 * </ul>
	 * 
	 * <p>The call to <code>ItemStateListener.itemStateChanged</code>
	 * may be delayed in order to be serialized with the event stream.
	 * The <code>notifyStateChanged</code> method does not block awaiting
	 * the completion of the <code>itemStateChanged</code> method.</p>
	 * 
	 * @throws IllegalStateException if the Item is not owned by a Form
	 * @since  MIDP 2.0
	 */
	public void notifyStateChanged()
	{
		
		Screen scr = StyleSheet.currentScreen;
		if (scr == null) {