customitem.java

用于移动设备上的java虚拟机源代码

     * 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
     * 
     * {@link #getMinContentHeight getMinContentHeight},
     * {@link #getMinContentWidth getMinContentWidth},
     * {@link #getPrefContentHeight getPrefContentHeight},
     * {@link #getPrefContentWidth getPrefContentWidth},
     * {@link #sizeChanged sizeChanged}, or
     * {@link #traverse traverse}.
     * 
     * The {@link #paint paint} 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.
     */
    protected final void invalidate() {
        super.invalidate();
    }

    /**
     * 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
     * {@link Font#getDefaultFont() Font.getDefaultFont()};</LI>
     * <LI>the stroke style is {@link Graphics#SOLID SOLID};</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 <code>Graphics</code> 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 item be repainted.  If this
     * item is visible on the display, this will result in a call to 
     * <code>paint()</code> the next time the <code>CustomItem</code> 
     * is to be displayed.  The <code>CustomItem</code>
     * subclass should call this method when the item's internal state has
     * been updated such that its visual representation needs to be updated.
     */
    protected final void repaint() {
        try {
            // We prune off the label area when doing a complete repaint
            super.repaint(0, labelHeight,
                          bounds[WIDTH], bounds[HEIGHT] - labelHeight);
        } catch (Exception e) {
            Display.handleThrowable(e);
        }
    }

    /**
     * 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) {
        try {
            // We only allow the CustomItem to repaint within its
            // content area
            if (x > bounds[WIDTH]) {
                return;
            }
            if (x < 0) {
                x = 0;
            }
            if (y < 0) {
                y = 0;
            }
            // We offset the Item's coordinate space by the label
            y += labelHeight;
            if (y > bounds[HEIGHT]) {
                return;
            }
            if (x + w > bounds[WIDTH]) {
                w = bounds[WIDTH] - x;
            }
            if (y + h > bounds[HEIGHT]) {
                h = bounds[HEIGHT] - y;
            }
            super.repaint(x, y, w, h);
        } catch (Exception e) {
            Display.handleThrowable(e);
        }
    }

    /**
     * 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
     * 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>