customitem.java

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

     *
     * <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
     * {@link Canvas#UP Canvas.UP}, {@link Canvas#DOWN Canvas.DOWN},
     * {@link Canvas#LEFT Canvas.LEFT}, {@link Canvas#RIGHT Canvas.RIGHT}, or
     * {@link #NONE NONE}.
     * @param viewportWidth the width of the container's viewport
     * @param viewportHeight the height of the container's viewport
     * @param visRect_inout passes the visible rectangle into the method, and
     * returns the updated traversal rectangle from the method
     * @return <code>true</code> if internal traversal had occurred, 
     * <code>false</code> 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 visRect_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
     * @see #TRAVERSE_HORIZONTAL
     * @see #TRAVERSE_VERTICAL
     */
    protected void traverseOut() { }

    /**
     * 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.
     *
     * @param keyCode the key code of the key that has been pressed
     * @see #getInteractionModes
     */
    protected void keyPressed(int keyCode) { }

    /**
     * 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.
     *
     * @param keyCode the key code of the key that has been released
     * @see #getInteractionModes
     */
    protected void keyReleased(int keyCode) { }

    /**
     * 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 
     * <code>getInteractionModes</code> method.
     *
     * @param keyCode the key code of the key that has been repeated
     * @see #getInteractionModes
     */
    protected void keyRepeated(int keyCode) { }

    /**
     * Called by the system when a pointer down action (for example, a pen
     * tap) has occurred within the item.  The <code>(x,y)</code> 
     * coordinates are relative
     * to the origin of the item, and they will always indicate a location
     * within the item.  The implementation indicates support for delivery of
     * pointer press events by setting the <code>POINTER_PRESS</code> 
     * bit in the value
     * returned by the <code>getInteractionModes</code> method.
     *
     * @param x the <code>x</code> coordinate of the pointer down
     * @param y the <code>y</code> coordinate of the pointer down
     *
     * @see #getInteractionModes
     */
    protected void pointerPressed(int x, int y) { }

    /**
     * Called by the system when a pointer up action (for example, a pen lift)
     * has occurred after a pointer down action had occurred within the item.
     * The <code>(x,y)</code> coordinates are relative to the origin
     * of the item.
     * Implementations should deliver a pointer release event to an item even
     * if the pointer has moved outside the item when the release occurs.  In
     * this case the <code>(x,y)</code> coordinates may indicate a
     * location outside the
     * bounds of the item.  The implementation indicates support for delivery
     * of pointer release events by setting the 
     * <code>POINTER_RELEASE</code> bit in the
     * value returned by the <code>getInteractionModes</code> method.
     *
     * @param x the x coordinate of the pointer up
     * @param y the x coordinate of the pointer up
     *
     * @see #getInteractionModes
     */
    protected void pointerReleased(int x, int y) { }

    /**
     * Called by the system when a pointer drag action (for example, pen
     * motion after a press but before a release) has occurred within the item.
     * The <code>(x,y)</code> coordinates are relative to the origin
     * of the item.
     * Implementations should deliver pointer drag events to an item even if
     * the pointer is being moved outside the item.  In this case 
     * the <code>(x,y)</code>
     * coordinates may indicate a location outside the bounds of the item.
     * The implementation indicates support for delivery of pointer release
     * events by setting the <code>POINTER_DRAG</code> bit in the
     * value returned by the
     * <code>getInteractionModes</code> method.
     *
     * @param x the <code>x</code> coordinate of the pointer drag
     * @param y the <code>x</code> coordinate of the pointer drag
     *
     * @see #getInteractionModes
     */
    protected void pointerDragged(int x, int y) { }

    /**
     * Called by the system to notify the item that it is now at least
     * partially visible, when it previously had been completely invisible.
     * The item may receive <code>paint()</code> calls after
     * <code>showNotify()</code> has been called.
     *
     * <p>The default implementation of this method does nothing.</p>
     */
    protected void showNotify() { }

    /**
     * Called by the system to notify the item that it is now completely
     * invisible, when it previously had been at least partially visible.  No
     * further <code>paint()</code> calls will be made on this item
     * until after a <code>showNotify()</code> has been called again.
     *
     * <p>The default implementation of this method does nothing.</p>
     */
    protected void hideNotify() { }

// **************************************************************************
//  Package Private - These are all methods which delegate calls to
//                    CustomItem application code, locking on the calloutLock
//                    before doing so
// **************************************************************************

    /**
     * Called to determine the effective layout directive.
     *
     * @return the CustomItem's layout directive
     */
    int callGetLayout() {
        int l = LAYOUT_TOP | LAYOUT_LEFT;
        try {
            // SYNC NOTE: We lock on calloutLock around any calls
            // into application code
            synchronized (Display.calloutLock) {
                l = this.getLayout();
            }
        } catch (Throwable thr) {
            Display.handleThrowable(thr);
        }
        return l;
    }

    /**
     * Get the preferred width of this Item, including the preferred
     * content width and room for the label. This is the callback
     * for Item's public getPreferredWidth() method.
     *
     * @param h the height to base the width size on
     * @return the preferred width
     */
    int callPreferredWidth(int h) {
        try {
            synchronized (Display.calloutLock) {
                return this.getPrefContentWidth(h);
            }
        } catch (Throwable thr) {
            Display.handleThrowable(thr);
        }
        return -1;
    }