customitem.java

j2me polish学习的经典代码

	 * item is visible, for example, if it is scrolled offscreen.  The
	 * semantics of the rectangle returned are discussed below.</p>
	 * 
	 * <p>The <code>CustomItem</code> must maintain state that tracks
	 * whether traversal is
	 * within this item, and if it is, it must also record the current
	 * internal location.  Initially, traversal is outside the item.  The
	 * first call to the <code>traverse()</code> method indicates
	 * that traversal has
	 * entered the item.  Subsequent calls to this method indicate that
	 * traversal is occurring within this item.  Traversal remains within the
	 * item until the <code>traverseOut</code> method is called.
	 * The <code>CustomItem</code> must keep
	 * track of its traversal state so that it can distinguish traversal
	 * <em>entering</em> the item from traversal <em>within</em> the item.
	 * </p>
	 * 
	 * <p>When traversal enters the item, the traversal code
	 * should initialize its internal traversal
	 * location to the &quot;first&quot; location appropriate
	 * for the item's structure and the traversal direction.
	 * As an example of the latter policy, if
	 * the traversal direction is <code>DOWN</code>, the initial
	 * location should be the
	 * topmost internal element of the item.  Similarly, if the traversal
	 * direction is <code>UP</code>, the initial location should be the
	 * bottommost element of the item.
	 * The <code>CustomItem</code>
	 * should still choose the &quot;first&quot; location appropriately
	 * even if its primary axis is orthogonal to the
	 * axis of traversal.  For example, suppose the traversal
	 * mode supported is <code>TRAVERSE_VERTICAL</code> but the
	 * <code>CustomItem</code> is structured as a horizontal row
	 * of elements.  If the initial traversal direction is
	 * <code>DOWN</code>, the initial location might be the leftmost
	 * element, and if the initial traversal direction is
	 * <code>UP</code>, the initial location might be the rightmost
	 * element.</p>
	 * 
	 * <p>Traversal may enter the item without any specific direction, in
	 * which case the traversal direction will be <code>NONE</code>.  This may
	 * occur if the user selects the item directly (e.g., with a pointing
	 * device), or if the item gains the focus because its containing
	 * <code>Form</code> has become current. The <code>CustomItem</code>
	 * should choose a default traversal location.  If the
	 * <code>CustomItem</code> had been traversed to previously, and if it is
	 * appropriate for the user interface of the <code>CustomItem</code>, the
	 * previous traversal location should be restored.</p>
	 * 
	 * <p>When traversal occurs within
	 * the item, the internal traversal location must be moved to the next
	 * appropriate region in the direction of traversal.  The item must report
	 * its updated internal traversal location in the
	 * <code>visRect_inout</code> return parameter as described below and
	 * return <code>true</code>.  The item will typically provide a highlight
	 * to display the internal traversal location to the user.  Thus, the item
	 * will typically also request repaints of the old and new traversal
	 * locations after each traversal event.  There is no requirement that the
	 * area the item requests to be repainted is the same as the area returned
	 * in the <code>visRect_inout</code> rectangle.  The system will combine
	 * any repaint requests with any additional repainting that may occur as a
	 * result of scrolling.</p>
	 * 
	 * <p>The <code>traverse()</code> method may be called with a direction of
	 * <code>NONE</code> when the traversal is already within the
	 * <code>CustomItem</code>.  This will occur in response to the
	 * <code>CustomItem</code> subclass code having called the
	 * <code>invalidate()</code> method.  In this case, the
	 * <code>CustomItem</code> should simply return its current notion of the
	 * traversal location.  This mechanism is useful if the
	 * <code>CustomItem</code> needs to update the traversal location
	 * spontaneously (that is, not in response to a traversal event), for
	 * example, because of a change in its contents.</p>
	 * 
	 * <p>If the internal traversal location is such that the traversal event
	 * would logically cause traversal to proceed out of the item, the
	 * item should return <code>false</code> from the
	 * <code>traverse()</code> method.  For
	 * example, if the current traversal location is the bottommost internal
	 * element of the item, and the traversal direction is
	 * <code>DOWN</code>, the
	 * <code>traverse()</code> method should simply return
	 * <code>false</code>.  In this
	 * case the method need not update the values in the
	 * <code>visRect_inout</code> array.  The item must leave its internal
	 * traversal location unchanged, and it should not request a repaint to
	 * update its highlighting.  It should defer these actions until the
	 * <code>traverseOut()</code> method is called.
	 * The system will call the <code>traverseOut()</code>
	 * method when traversal actually leaves the item.  The system might not
	 * call the <code>traverseOut()</code> method, even if
	 * <code>traverse()</code> has returned
	 * <code>false</code>, if this item is at the edge of the
	 * <code>Form</code> or there is
	 * no other item beyond to accept the traversal.
	 * Even if the <code>traverse()</code>
	 * method returns <code>false</code>, the traversal location is still
	 * within this item.
	 * It remains within this item until <code>traverseOut()</code> is
	 * called.</p>
	 * 
	 * <p>Note the subtle distinction here between the initial
	 * <code>traverse()</code> call
	 * signifying <em>entry</em> into the item and subsequent calls signifying
	 * traversal <em>within</em> the item.  A return value of
	 * <code>false</code> to the initial call indicates that this item
	 * performs no internal traversal at all, whereas a return of
	 * <code>false</code> to subsequent calls indicates that traversal is
	 * within this item and may now exit.  </p>
	 * 
	 * <p>The width and height of the rectangle returned in the
	 * <code>visRect_inout</code> array are used by the
	 * <code>Form</code> for scrolling
	 * and painting purposes.  The <code>Form</code> must always
	 * position the item so that
	 * the upper left corner of this rectangle, as specified by
	 * the <code>(x,y)</code>
	 * position, is visible.  In addition, the item may also specify a width
	 * and height, in which case the <code>Form</code> will
	 * attempt to position the item so
	 * that as much of this rectangle as possible is visible.  If the width
	 * and height are larger than the size of the viewport, the bottom and
	 * right portions of this rectangle will most likely not be visible to the
	 * user.  The rectangle thus returned will typically denote the size and
	 * location of one of the item's internal elements, and it will also
	 * typically (though not necessarily) correspond to where the element's
	 * highlight will be painted.  Width and height values of zero are legal
	 * and are not treated specially.  Negative values of width and height are
	 * treated as if they were zero.</p>
	 * 
	 * <p>There is no requirement on the location of the rectangle returned in
	 * the <code>visRect_inout</code> array with respect to the traversal
	 * direction.  For example, if the <code>CustomItem</code> implements
	 * internal scrolling, a traversal direction of <code>DOWN</code> may
	 * cause the item's contents to scroll upwards far enough so that the
	 * rectangle returned may be above its old location.
	 * <code>CustomItem</code> subclasses must ensure that continued traversal
	 * in one direction will eventually reach the edge of the item and then
	 * traverse out by returning <code>false</code> from this method.
	 * <code>CustomItems</code> must not implement &quot;wraparound&quot;
	 * behavior (for example, traversing downwards from the bottommost element
	 * moves the traversal location to the topmost element) because this will
	 * trap the traversal within the item.</p>
	 * 
	 * <p>If the <code>CustomItem</code> consists of internal
	 * elements that are smaller
	 * than the container's viewport, the rectangle returned
	 * should be the
	 * same size as one of these elements.  However, the
	 * <code>CustomItem</code> might have
	 * contents whose elements are larger than the viewport, or it might have
	 * contents having no internal structure.  In either of these cases, the
	 * item should return a rectangle that best represents its idea of the
	 * content area that is important for the user to see.  When traversal
	 * occurs, the item should move its traversal location by an amount based
	 * on the viewport size.  For example, if the viewport is
	 * <code>80</code> pixels high,
	 * and traversal occurs downwards, the item might move its traversal
	 * location down by <code>70</code> pixels in order to display
	 * the next screenful of
	 * content, with <code>10</code> pixels overlap for context.</p>
	 * 
	 * <p>All internal traversal locations must be reachable regardless of
	 * which traversal modes are provided by the implementation.  This
	 * implies that,
	 * if the implementation provides one-dimensional traversal, the
	 * <code>CustomItem</code> must linearize its internal locations.
	 * For example, suppose the traversal mode is
	 * <code>TRAVERSE_VERTICAL</code> and the <code>CustomItem</code> consists
	 * of a horizontal row of elements.  If the traversal direction is
	 * <code>DOWN</code> the internal traversal location should move to the
	 * right, and if the traversal direction is <code>UP</code> the internal
	 * traversal location should move to the left.  (The foregoing convention
	 * is appropriate for languages that use left-to-right text.  The opposite
	 * convention should be used for languages that use right-to-left text.)
	 * Consider a similar example where the traversal mode is
	 * <code>TRAVERSE_VERTICAL</code> and the <code>CustomItem</code> consists
	 * of a grid of elements.  A traversal direction of <code>DOWN</code>
	 * might proceed leftwards across each row, moving to the next row
	 * downwards when the location reaches the rightmost element in a row.
	 * </p>
	 * 
	 * <p>If the implementation provides two-dimensional traversal but the
	 * <code>CustomItem</code> is one-dimensional, a traversal direction
	 * along the item's
	 * axis should traverse within the item, and a traversal direction
	 * orthogonal to the item's axis should cause immediate traversal out of
	 * the item by returning <code>false</code> from this method.  For
	 * example, suppose a <code>CustomItem</code> is implementing
	 * a vertical stack of
	 * elements and traversal is already inside the item.  If a traverse event
	 * is received with direction <code>UP</code> or <code>DOWN</code>,
	 * the <code>traverse()</code> method should
	 * move to the next element and return <code>true</code>.  On the other
	 * hand, if a traverse event is received with direction
	 * <code>RIGHT</code> or <code>LEFT</code>, the
	 * <code>traverse()</code> method should always return
	 * <code>false</code> so that
	 * traversal exits the item immediately.  An item that implements internal
	 * traversal should always accept entry - that is, the initial call to
	 * <code>traverse()</code> should return <code>true</code> -
	 * regardless of the axis of the traversal direction.</p>
	 * 
	 * <p>If the <code>traverse()</code> method returns
	 * <code>false</code> when traversal
	 * is entering the item, this indicates to the system that the item does
	 * not support internal traversal.  In this case, the item should not
	 * perform any of its own highlighting, and the system will perform
	 * highlighting appropriate for the platform, external to the item.</p>
	 * 
	 * <p>The default implementation of the <code>traverse()</code>
	 * method always returns <code>false</code>.</p>
	 * 
	 * @param dir the direction of traversal, one of Canvas.UP, Canvas.DOWN, Canvas.LEFT, Canvas.RIGHT, or NONE.
	 * @param viewportWidth the width of the container's viewport
	 * @param viewportHeight the height of the container's viewport
	 * @param myVisRect_inout passes the visible rectangle into the method, and returns the updated traversal rectangle from the method
	 * @return true if internal traversal had occurred, false if traversal should proceed out
	 * @see #getInteractionModes()
	 * @see #traverseOut()
	 * @see #TRAVERSE_HORIZONTAL
	 * @see #TRAVERSE_VERTICAL
	 */
	protected boolean traverse(int dir, int viewportWidth, int viewportHeight, int[] myVisRect_inout)
	{
		return false;
	}

	/**
	 * Called by the system when traversal has occurred out of the item.  This
	 * may occur in response to the <code>CustomItem</code> having returned
	 * <code>false</code> to a previous call to <code>traverse()</code>, if
	 * the user has begun interacting with another item, or if
	 * <code>Form</code> containing
	 * this item is no longer current.  If the <code>CustomItem</code>
	 * is using highlighting to indicate internal traversal,
	 * the <code>CustomItem</code>
	 * should set its state to be unhighlighted and request a repaint.  (Note
	 * that painting will not occur if the item is no longer visible.)
	 * 
	 * @see #getInteractionModes()
	 * @see #traverse(int, int, int, int[])
	 * @see #TRAVERSE_HORIZONTAL
	 * @see #TRAVERSE_VERTICAL
	 */
	protected void traverseOut()
	{
		// the default implentation does nothing
	}

	/**
	 * Called by the system when a key is pressed.  The implementation
	 * indicates support for delivery of key press events by setting the
	 * <code>KEY_PRESS</code> bit in the value returned by the
	 * <code>getInteractionModes</code> method.
	 * <p>J2ME Polish supports the KEY_PRESS interaction mode.</p>
	 * 
	 * @param keyCode the key code of the key that has been pressed
	 * @see #getInteractionModes()
	 */
	protected void keyPressed(int keyCode)
	{
		// this method is called by J2ME Polish whenever a key has been pressed
	}

	/**
	 * Called by the system when a key is released.  The implementation
	 * indicates support for delivery of key release events by setting the
	 * <code>KEY_RELEASE</code> bit in the value returned by the
	 * <code>getInteractionModes</code> method.
	 * 
	 * <p>keyReleased() is suported by the J2ME Polish implementation when the native system forwards keyReleased events to Canvas classes.</p>
	 * 
	 * @param keyCode - the key code of the key that has been released
	 * @see #getInteractionModes()
	 */
	protected void keyReleased(int keyCode)
	{
		//do nothing
	}

	/**
	 * Called by the system when a key is repeated.  The implementation
	 * indicates support for delivery of key repeat events by setting the
	 * <code>KEY_REPEAT</code> bit in the value returned by the