customitem.java

j2me polish学习的经典代码

				return INTERACTION_MODES;
			}
		} else {
			// assume REPEAT events are supported:
			return INTERACTION_MODES | KEY_REPEAT;			
		}
	}

	/**
	 * Implemented by the subclass to return the minimum width of the content
	 * area, in pixels.  This method is called by the implementation as part
	 * of its layout algorithm.  The actual width granted is reported in the
	 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#sizeChanged(int, int)"><CODE>sizeChanged</CODE></A> and <A HREF="../../../de/enough/polish/ui/CustomItem.html#paint(javax.microedition.lcdui.Graphics, int, int)"><CODE>paint</CODE></A> methods.
	 * 
	 * @return the minimum content width in pixels
	 */
	protected abstract int getMinContentWidth();

	/**
	 * Implemented by the subclass to return the minimum height of the content
	 * area, in pixels.  This method is called by the implementation as part
	 * of its layout algorithm.  The actual height granted is reported in the
	 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#sizeChanged(int, int)"><CODE>sizeChanged</CODE></A> and <A HREF="../../../de/enough/polish/ui/CustomItem.html#paint(javax.microedition.lcdui.Graphics, int, int)"><CODE>paint</CODE></A> methods.
	 * 
	 * @return the minimum content height in pixels
	 */
	protected abstract int getMinContentHeight();

	/**
	 * Implemented by the subclass to return the preferred width of the content
	 * area, in pixels.  This method is called by the implementation as part
	 * of its layout algorithm.
	 * 
	 * <p>The <code>height</code> parameter is the tentative height assigned
	 * to the content area.  The subclass code may use this value in its
	 * computation of the preferred width.  The <code>height</code> parameter
	 * will be -1 if the implementation has not assigned a tentative value
	 * for the height.  Otherwise, <code>height</code> will have a specific
	 * value if the application has locked the height of the
	 * <code>CustomItem</code> or if the container's layout algorithm has
	 * already computed a tentative height at the time of this call.  The
	 * subclass must not assume that the tentative height passed or the
	 * preferred width returned will be granted.
	 * The actual size granted is reported in the
	 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#sizeChanged(int, int)"><CODE>sizeChanged</CODE></A> and <A HREF="../../../de/enough/polish/ui/CustomItem.html#paint(javax.microedition.lcdui.Graphics, int, int)"><CODE>paint</CODE></A> methods.
	 * </p>
	 * <p>The J2ME Polish implementation does not suggest a value. It
	 * will always provide -1 for the tentative height.</p>
	 * <p>The J2ME Polish implementation will always call getPrefContentWidth(-1) first
	 * and then the getPrefContentHeight()-method with the actual granted width.
	 * <br/>The sizeChanged()-method will only be called when the returned preferred-width
	 * had to be adjusted. 
	 * </p>
	 * 
	 * 
	 * @param height the tentative content height in pixels, or -1 if a tentative height has not been computed.
	 * 			J2ME Polish will always specify -1 as the height.
	 * @return the preferred content width in pixels
	 */
	protected abstract int getPrefContentWidth(int height);

	/**
	 * Implemented by the subclass to return the preferred height of the
	 * content area, in pixels.  This method is called by the implementation
	 * as part of its layout algorithm.
	 * 
	 * <p>The <code>width</code> parameter is the tentative width assigned
	 * to the content area.  The subclass code may use this value in its
	 * computation of the preferred height.  The <code>width</code> parameter
	 * will be -1 if the implementation has not assigned a tentative value
	 * for the width.  Otherwise, <code>width</code> will have a specific
	 * value if the application has locked the width of the
	 * <code>CustomItem</code> or if the container's layout algorithm has
	 * already computed a tentative width at the time of this call.  The
	 * subclass must not assume that the tentative width passed or the
	 * preferred height returned will be granted.
	 * The actual size granted is reported in the
	 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#sizeChanged(int, int)"><CODE>sizeChanged</CODE></A> and <A HREF="../../../de/enough/polish/ui/CustomItem.html#paint(javax.microedition.lcdui.Graphics, int, int)"><CODE>paint</CODE></A> methods.
	 * </p>
	 * <p>The J2ME Polish implementation will always call getPrefContentWidth(-1) first
	 * and then the getPrefContentHeight()-method with the actual granted width.
	 * <br/>The sizeChanged()-method will only be called when the returned preferred-width
	 * had to be adjusted. 
	 * </p>
	 * 
	 * @param width the tentative content width in pixels, or -1 if a tentative width has not been computed
	 * @return the preferred content height in pixels
	 */
	protected abstract int getPrefContentHeight(int width);

	/**
	 * Implemented by the subclass in order to handle size change events.
	 * This method is called by the system when the size of the content area
	 * of this <code>CustomItem</code> has changed.
	 * 
	 * <p>If the size of a <code>CustomItem</code> changes while it is
	 * visible on the display, it may trigger an automatic
	 * repaint request.  If this occurs, the call to
	 * <code>sizeChanged</code> will occur prior to the call to
	 * <code>paint</code>.  If the <code>CustomItem</code> has become
	 * smaller, the implementation may choose not to trigger a repaint
	 * request if the remaining contents of the <code>CustomItem</code>
	 * have been preserved.  Similarly, if the <code>CustomItem</code>
	 * has become larger, the implementation may choose to trigger a
	 * repaint only for the new region.  In both cases, the preserved
	 * contents must remain stationary with respect to the origin of the
	 * <code>CustomItem</code>.  If the size change is significant to
	 * the contents of the <code>CustomItem</code>, the application must
	 * explicitly issue a repaint request for the changed areas.  Note
	 * that the application's repaint request should not cause multiple
	 * repaints, since it can be coalesced with repaint requests that
	 * are already pending.</p>
	 * 
	 * <p>If the size of the item's content area
	 * changes while it is not visible, calls to this method may be deferred.
	 * If the size had changed while the item was not visible,
	 * <code>sizeChanged</code> will be called at least once before the item
	 * becomes visible once again.</p>
	 * 
	 * <p>The default implementation of this method does
	 * nothing.</p>
	 * 
	 * @param w the new width of the item's content area
	 * @param h the new height of the item's content area
	 */
	protected void sizeChanged(int w, int h)
	{
		//default implementation does nothing
	}

	/**
	 * Signals that the <code>CustomItem's</code> size and traversal
	 * location need to be updated.
	 * This method is intended to be called by <code>CustomItem</code>
	 * subclass code to inform the implementation that the size of
	 * the <code>CustomItem's</code> content area or the internal
	 * traversal location might need to change.
	 * This often occurs if the contents of the <code>CustomItem</code>
	 * are modified.  A call to this method will return immediately, and it
	 * will cause the container's layout algorithm to run at some point in the
	 * future, possibly resulting in calls to
	 * 
	 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#getMinContentHeight()"><CODE>getMinContentHeight</CODE></A>,
	 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#getMinContentWidth()"><CODE>getMinContentWidth</CODE></A>,
	 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#getPrefContentHeight(int)"><CODE>getPrefContentHeight</CODE></A>,
	 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#getPrefContentWidth(int)"><CODE>getPrefContentWidth</CODE></A>,
	 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#sizeChanged(int, int)"><CODE>sizeChanged</CODE></A>, or
	 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#traverse(int, int, int, int[])"><CODE>traverse</CODE></A>.
	 * 
	 * The <A HREF="../../../de/enough/polish/ui/CustomItem.html#paint(javax.microedition.lcdui.Graphics, int, int)"><CODE>paint</CODE></A> method may also be called if
	 * repainting is necessary as a result of the layout operation.
	 * If the content size is invalidated while the
	 * <code>CustomItem</code> is not visible, the
	 * layout operation may be deferred.  The <code>traverse</code> method
	 * will be called if the <code>CustomItem</code> contains the current
	 * traversal location at the time <code>invalidate</code> is called.</DL>
	 * 
	 */
	protected final void invalidate()
	{
		requestInit();
	}

	/**
	 * Implemented by the subclass to render the item within its container.
	 * At the time of the call, the <code>Graphics</code> context's
	 * destination is the content area of this <code>CustomItem</code>
	 * (or back buffer for it).  The
	 * Translation is set so that the upper left corner of the content area is
	 * at <code>(0,0)</code>, 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 equal to the
	 * values passed with the most recent call to <code>sizeChanged()</code>;
	 * they are passed here as well for convenience.
	 * 
	 * <p>Other values of the <code>Graphics</code> object are as follows:</p>
	 * <UL>
	 * <LI>the current color is black;</LI>
	 * <LI>the font is the same as the font returned by
	 * <A HREF="../../../javax/microedition/lcdui/Font.html#getDefaultFont()"><CODE>Font.getDefaultFont()</CODE></A>;</LI>
	 * <LI>the stroke style is <A HREF="../../../javax/microedition/lcdui/Graphics.html#SOLID"><CODE>SOLID</CODE></A>;</LI>
	 * </UL>
	 * 
	 * <p>The <code>paint()</code> method will be called only after
	 * <code>showNotify()</code> call on this item and before a subsequent
	 * <code>hideNotify()</code> call on this item, in other words, only when
	 * at least a portion of the item is actually visible on the display.
	 * In addition, the <code>paint()</code> method will be called only
	 * if the item's width and height are both greater than zero.</p>
	 * 
	 * @param g the Graphics object to be used for rendering the item
	 * @param w current width of the item in pixels
	 * @param h current height of the item in pixels
	 */
	protected abstract void paint( Graphics g, int w, int h);

	/**
	 * Called by subclass code to request that the specified rectangular area
	 * of the item be repainted.  If that area is visible on the display, this
	 * will result in call to <code>paint</code> with graphics set to
	 * include the specified rectangular area.
	 * The area is specified relative to the <code>CustomItem's</code>
	 * content area.
	 * The <code>CustomItem</code> should call this method when the item's
	 * internal state has been updated and only part of the visual
	 * representation needs to be updated.
	 * 
	 * @param x the x coordinate of the rectangular area to be updated
	 * @param y the y coordinate of the rectangular area to be updated
	 * @param w the width of the rectangular area to be updated
	 * @param h the height of the rectangular area to be updated
	 */
	protected final void repaint(int x, int y, int w, int h)
	{
		repaint();
	}

	/**
	 * Called by the system when traversal has entered the item or has occurred within the item.  
	 * The direction of traversal and the item's
	 * visible rectangle are passed into the method.  The method must do one
	 * of the following: it must either update its state information
	 * pertaining to its internal traversal location, set the return rectangle
	 * to indicate a region associated with this location, and return
	 * <code>true</code>; or, it must return <code>false</code> to indicate
	 * that this item does not support internal traversal, or that that
	 * internal traversal has reached the edge of the item and that traversal
	 * should proceed to the next item if possible.
	 * 
	 * <p>The implementation indicates support for internal traversal within a
	 * <code>CustomItem</code> by setting one or both of the
	 * <code>TRAVERSE_HORIZONTAL</code> or
	 * <code>TRAVERSE_VERTICAL</code> bits in the value returned by the
	 * <code>getInteractionModes</code>
	 * method.  The <code>dir</code> parameter indicates the direction of
	 * traversal by using <code>Canvas</code> game actions
	 * <code>Canvas.UP</code>, <code>Canvas.DOWN</code>,
	 * <code>Canvas.LEFT</code>, and <code>Canvas.RIGHT</code>, or the
	 * value <code>NONE</code>, which indicates that there is no specific
	 * direction associated with this traversal event.
	 * If the <code>TRAVERSE_HORIZONTAL</code> bit is set,
	 * this indicates that the <code>Canvas.LEFT</code> and
	 * <code>Canvas.RIGHT</code> values will be
	 * used to indicate the traversal direction.
	 * If the <code>TRAVERSE_VERTICAL</code> bit
	 * is set, this indicates that the <code>Canvas.UP</code> and
	 * <code>Canvas.DOWN</code> values will
	 * be used to indicate the traversal direction.  If both bits are set, all
	 * four direction values may be used for the traversal direction,
	 * indicating that the item should perform two-dimensional traversal.  The
	 * <code>dir</code> parameter may have the value <code>NONE</code> under
	 * any combination of the <code>TRAVERSE_VERTICAL</code> and
	 * <code>TRAVERSE_HORIZONTAL</code> bits.
	 * </p>
	 * 
	 * <p>Although <code>Canvas</code> game actions are used to indicate the
	 * traversal direction, this does not imply that the keys mapped to these
	 * game actions are being used for traversal, nor that that keys are being
	 * used for traversal at all.</p>
	 * 
	 * <p>The <code>viewportWidth</code> and <code>viewportHeight</code>
	 * parameters indicate the size of the viewable area the item's container
	 * has granted to its items.  This represents the largest area of the
	 * item that is likely to be visible at any given time.</p>
	 * 
	 * <p>The <code>visRect_inout</code> parameter is used both for passing
	 * information into this method and for returning information from this
	 * method.  It must be an <code>int[4]</code> array.  The information in
	 * this array is a rectangle of the form <code>[x,y,w,h]</code>
	 * where <code>(x,y)</code> is the
	 * location of the upper-left corner of the rectangle relative to the
	 * item's origin, and <code>(w,h)</code> are the width and
	 * height of the rectangle.
	 * The return values placed into this array are significant only when the
	 * <code>traverse()</code> method returns <code>true</code>.
	 * The values are ignored if
	 * the <code>traverse()</code> method returns <code>false</code>.</p>
	 * 
	 * <p>When this method is called, the <code>visRect_inout</code> array
	 * contains a rectangle representing the region of the item that is
	 * currently visible.  This region might have zero area if no part of the