0001: /*
0002: *
0003: *
0004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
0005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
0006: *
0007: * This program is free software; you can redistribute it and/or
0008: * modify it under the terms of the GNU General Public License version
0009: * 2 only, as published by the Free Software Foundation.
0010: *
0011: * This program is distributed in the hope that it will be useful, but
0012: * WITHOUT ANY WARRANTY; without even the implied warranty of
0013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
0014: * General Public License version 2 for more details (a copy is
0015: * included at /legal/license.txt).
0016: *
0017: * You should have received a copy of the GNU General Public License
0018: * version 2 along with this work; if not, write to the Free Software
0019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
0020: * 02110-1301 USA
0021: *
0022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
0023: * Clara, CA 95054 or visit www.sun.com if you need additional
0024: * information or have any questions.
0025: */
0026:
0027: package javax.microedition.lcdui;
0028:
0029: /* import javax.microedition.lcdui.KeyConverter; */
0030:
0031: /**
0032: * A CustomItem is customizable by subclassing to introduce new visual and
0033: * interactive elements into <code>Forms</code>.
0034: * Subclasses are responsible for their visual
0035: * appearance including sizing and rendering and choice of colors, fonts and
0036: * graphics. Subclasses are responsible for the user interaction mode by
0037: * responding to events generated by keys, pointer actions, and traversal
0038: * actions. Finally, subclasses are responsible for calling {@link
0039: * Item#notifyStateChanged} to trigger notification of listeners that the
0040: * <code>CustomItem's</code> value has changed.
0041: *
0042: * <p>Like other <code>Items</code>, <code>CustomItems</code>
0043: * have the concept of <em>minimum</em> and
0044: * <em>preferred</em> sizes. These pertain to the total area
0045: * of the <code>Item</code>,
0046: * which includes space for the content, label, borders, etc. See <a
0047: * href="Item.html#sizes">Item Sizes</a> for a full discussion of the
0048: * areas and sizes of <code>Items</code>.</p>
0049: *
0050: * <p><code>CustomItem</code> subclasses also have the concept
0051: * of the <em>content</em> size, which is the size of only the
0052: * content area of the <code>CustomItem</code>. The
0053: * content area is a rectangular area inside the total area occupied by the
0054: * <code>CustomItem</code>.
0055: * The content area is the area within which the <code>CustomItem</code>
0056: * subclass paints and receives input events. It does not include space
0057: * consumed by labels and borders. The implementation is responsible for
0058: * laying out, painting, and handling input events within the area
0059: * of the <code>Item</code> that is outside the content area.</p>
0060: *
0061: * <p>All coordinates passed between the implementation and
0062: * the <code>CustomItem</code>
0063: * subclass are relative to the item's content area, with the upper-left
0064: * corner of this area being located at <code>(0,0)</code>.
0065: * Size information passed
0066: * between the implementation and the <code>CustomItem</code> subclass with the
0067: *
0068: * {@link #getMinContentHeight getMinContentHeight},
0069: * {@link #getMinContentWidth getMinContentWidth},
0070: * {@link #getPrefContentHeight getPrefContentHeight},
0071: * {@link #getPrefContentWidth getPrefContentWidth}, and
0072: * {@link #sizeChanged sizeChanged}
0073: *
0074: * methods all refer to the size of the content area. The implementation is
0075: * responsible for computing and maintaining the difference between the size
0076: * of the content area and the size of the total area of the
0077: * <code>Item</code> as reported by the Item size methods
0078: *
0079: * {@link Item#getMinimumHeight Item.getMinimumHeight},
0080: * {@link Item#getMinimumWidth Item.getMinimumWidth},
0081: * {@link Item#getPreferredHeight Item.getPreferredHeight}, and
0082: * {@link Item#getPreferredWidth Item.getPreferredWidth}.</p>
0083: *
0084: * <p>The implementation may disregard sizing information returned from a
0085: * <code>CustomItem</code> if it exceeds limits imposed by the
0086: * implementation's user interface policy. In
0087: * this case, the implementation must always report the actual size granted to
0088: * the <code>CustomItem</code> via the {@link #sizeChanged sizeChanged}
0089: * and the {@link #paint paint} methods.
0090: * For example, this situation may occur if the implementation
0091: * prohibits an <code>Item</code> from becoming wider than the screen. If the
0092: * <code>CustomItem</code> subclass code returns a value from
0093: * <code>getMinContentWidth</code> that would result in the
0094: * <code>CustomItem</code> being wider than the screen, the implementation may
0095: * assign a width smaller than the minimum width returned by
0096: * <code>getMinContentWidth</code>.</p>
0097: *
0098: * <p>The implementation is allowed to call the <code>CustomItem's</code>
0099: * content size methods
0100: *
0101: * {@link #getMinContentHeight getMinContentHeight},
0102: * {@link #getMinContentWidth getMinContentWidth},
0103: * {@link #getPrefContentHeight getPrefContentHeight}, and
0104: * {@link #getPrefContentWidth getPrefContentWidth},
0105: *
0106: * in any order with respect to other <code>CustomItem</code> methods.
0107: * For all of these methods, the <code>CustomItem</code> subclass code must
0108: * return values that are consistent with the current contents of the
0109: * <code>CustomItem</code>. If the contents changes, it is not sufficient for
0110: * the <code>CustomItem</code> subclass code simply to begin returning
0111: * different values from the content size methods. Instead, the subclass code
0112: * must call the {@link #invalidate invalidate} method whenever its contents
0113: * changes. This indicates to the implementation that it may need to perform
0114: * its layout computation, which will call the content size methods to get new
0115: * values based on the <code>CustomItem's</code> new contents.</p>
0116: *
0117: * <a name="interaction"></a>
0118: * <h2>Interaction Modes</h2>
0119: * <p>The <code>CustomItem</code> class is intended to allow
0120: * edit-in-place on many items,
0121: * but it does not allow every conceivable interaction. Desire for
0122: * flexibility has been balanced against a requirement that these APIs be
0123: * simple enough to master easily, along with a need to allow for
0124: * platform-specific variations in look-and-feel, all without sacrificing
0125: * interoperability.</p>
0126: *
0127: * <p>The general idea is that there are multiple interaction
0128: * "modes" and that the <code>Form</code>
0129: * implementation can convey which
0130: * ones it supports. The <code>CustomItem</code> can then choose to
0131: * support one or more interaction modes. There is no requirement for a
0132: * <code>CustomItem</code> to implement all combinations of
0133: * all interaction modes.
0134: * Typically, a <code>CustomItem</code> will implement an
0135: * approach (such as the separate
0136: * editing screen technique discussed below) that works on all platforms,
0137: * in addition to a highly interactive approach that relies on a particular
0138: * interaction mode. At run time, the <code>CustomItem</code>
0139: * code can query the system
0140: * to determine whether this interaction mode is supported. If it is, the
0141: * <code>CustomItem</code> can use it; otherwise, it will fall
0142: * back to the approach that works on all platforms. </p>
0143: *
0144: * <p><code>CustomItem</code> can always use item commands to invoke
0145: * a separate editing screen,
0146: * although components with a small number of discrete
0147: * states could simply respond by changing the state and
0148: * then causing an <code>notifyStateChanged</code> notification.
0149: * A technique for using a
0150: * separate editing screen would be to load the value into another
0151: * <code>Displayable</code> object (such as a List) and then to call
0152: * {@link Display#setCurrent(Displayable)} on it.
0153: * When the user
0154: * issues a command (such as "OK") to indicate that
0155: * editing of this value is
0156: * complete, the listener can retrieve the value from that
0157: * <code>Displayable</code> object
0158: * and then call
0159: * {@link Display#setCurrentItem(Item)} to return to this item.</p>
0160: *
0161: * <a name="keypad"></a>
0162: * <h2>Keypad Input</h2>
0163: *
0164: * <p>The implementation may optionally support delivery of keypad events to
0165: * the <code>CustomItem</code>. The implementation indicates
0166: * the level of support by
0167: * setting the <code>KEY_PRESS</code>, <code>KEY_RELEASE</code>, and
0168: * <code>KEY_REPEAT</code> bits in the value
0169: * returned by <code>getInteractionModes</code>.
0170: * Events corresponding to these bits are
0171: * delivered through calls to the <code>keyPressed()</code>,
0172: * <code>keyReleased()</code>, and
0173: * <code>keyRepeated()</code> methods, respectively.
0174: * If an implementation supports
0175: * <code>KEY_RELEASE</code> events, it must also support
0176: * <code>KEY_PRESS</code> events. If an
0177: * implementation supports <code>KEY_REPEAT</code> events, it must also
0178: * support <code>KEY_PRESS</code>
0179: * and <code>KEY_RELEASE</code> events. If supported,
0180: * <code>KEY_RELEASE</code> events will generally
0181: * occur after a corresponding <code>KEY_PRESS</code> event is
0182: * received, and <code>KEY_REPEAT</code>
0183: * events will generally occur between <code>KEY_PRESS</code> and
0184: * <code>KEY_RELEASE</code> events.
0185: * However, it is possible for the <code>CustomItem</code> to receive
0186: * <code>KEY_RELEASE</code> or
0187: * <code>KEY_REPEAT</code> events without a corresponding
0188: * <code>KEY_PRESS</code> if a key is down when
0189: * the <code>CustomItem</code> becomes visible.</p>
0190: *
0191: * <p>Key event methods are passed the <code>keyCode</code>
0192: * indicating the key on which the
0193: * event occurred. Implementations must provide means for the user to
0194: * generate events with key codes <code>Canvas.KEY_NUM0</code>
0195: * through <code>Canvas.KEY_NUM9</code>,
0196: * <code>Canvas.KEY_STAR</code>, and <code>Canvas.KEY_POUND</code>.
0197: * Implementations may also deliver
0198: * key events for other keys, include device-specific keys.
0199: * The set of keys
0200: * available to a <code>CustomItem</code> may differ depending
0201: * upon whether commands have been added to it.</p>
0202: *
0203: * <p>The application may map key codes to game actions through use of the
0204: * <code>getGameAction</code> method.
0205: * If the implementation supports key events on
0206: * <code>CustomItems</code>, the implementation must provide a
0207: * sufficient set of key codes
0208: * and a mapping to game actions such that all game actions are available to
0209: * <code>CustomItems</code>.</p>
0210: *
0211: * <p>The set of keys and the key events available to a
0212: * <code>CustomItem</code> may differ
0213: * from what is available on a <code>Canvas</code>.
0214: * In particular, on a system that
0215: * supports traversal, the system might use directional keys for traversal and
0216: * elect not to deliver these keys to <code>CustomItems</code>.
0217: * The mapping between key
0218: * codes and game actions in a <code>CustomItem</code> may differ
0219: * from the mapping in a <code>Canvas</code>. See
0220: * <a href="Canvas.html#keyevents">Key Events</a>
0221: * and
0222: * <a href="Canvas.html#gameactions">Game Actions</a>
0223: * on class <code>Canvas</code> for further information about key codes and game
0224: * actions.</p>
0225: *
0226: * <a name="pointer"></a>
0227: * <h2>Pointer Input</h2>
0228: *
0229: * <p>The implementation may optionally support delivery of pointer events
0230: * (such as taps with a stylus) to the <code>CustomItem</code>.
0231: * The implementation
0232: * indicates the level of support by setting the <code>POINTER_PRESS</code>,
0233: * <code>POINTER_RELEASE</code>, and <code>POINTER_DRAG</code> bits
0234: * in the value returned by <code>getInteractionModes</code>.
0235: * Events corresponding to these bits are delivered
0236: * through calls to the <code>pointerPressed()</code>,
0237: * <code>pointerReleased()</code>, and
0238: * <code>pointerDragged()</code> methods, respectively.
0239: * If an implementation supports
0240: * <code>POINTER_RELEASE</code> events, it must also support
0241: * <code>POINTER_PRESS</code> events. If an
0242: * implementation supports <code>POINTER_DRAG</code> events,
0243: * it must also support
0244: * <code>POINTER_PRESS</code> and <code>POINTER_RELEASE</code> events.
0245: * If supported, <code>POINTER_RELEASE</code>
0246: * events will generally occur after a corresponding
0247: * <code>POINTER_PRESS</code> event is
0248: * received, and <code>POINTER_DRAG</code> events will generally occur between
0249: * <code>POINTER_PRESS</code> and <code>POINTER_RELEASE</code> events.
0250: * However, it is possible for the
0251: * <code>CustomItem</code> to receive <code>POINTER_RELEASE</code>
0252: * or <code>POINTER_DRAG</code> events without a
0253: * corresponding <code>POINTER_PRESS</code> if the pointer is
0254: * down when the <code>CustomItem</code> becomes visible.</p>
0255: *
0256: * <p>The <code>(x,y)</code> location of the pointer event is
0257: * reported with every pointer
0258: * event. This location is expressed in the coordinate system of the
0259: * <code>CustomItem</code>, where <code>(0,0)</code> is the upper-left
0260: * corner of the <code>CustomItem</code>. Under
0261: * certain circumstances, pointer events may occur outside the bounds of the
0262: * item. </p>
0263: *
0264: * <h2>Traversal</h2>
0265: *
0266: * <p>An implementation may support traversal <em>internal</em> to a
0267: * <code>CustomItem</code>, that is, the implementation
0268: * may temporarily delegate the
0269: * responsibility for traversal to the item itself. Even if there is only one
0270: * traversal location inside the <code>CustomItem</code>,
0271: * the item may want support the
0272: * internal traversal protocol so that it can perform specialized
0273: * highlighting, animation, etc. when the user has traversed into it.</p>
0274: *
0275: * <p>The implementation indicates its support for traversal internal to a
0276: * <code>CustomItem</code> by setting one or both of the
0277: * <code>TRAVERSE_HORIZONTAL</code> or
0278: * <code>TRAVERSE_VERTICAL</code> bits in the value returned by
0279: * <code>getInteractionModes()</code>. If
0280: * neither of these bits is set, the implementation is unwilling to let
0281: * <code>CustomItems</code> traverse internally, or the
0282: * implementation does not support
0283: * traversal at all. If the implementation does support traversal but has
0284: * declined to permit traversal internal to <code>CustomItems</code>,
0285: * the implementation
0286: * will supply its own highlighting outside the
0287: * <code>CustomItem's</code> content area.</p>
0288: *
0289: * <p>The <code>CustomItem</code> need not support internal
0290: * traversal at all. It can do
0291: * this by returning <code>false</code> to the initial call to the
0292: * <code>traverse</code> method. (This is the default behavior if this method
0293: * hasn't been overridden by the <code>CustomItem</code>.)
0294: * If this occurs, the system must
0295: * arrange for the user to be able to traverse onto and past this item. The
0296: * system must also arrange for proper scrolling to take place, particularly
0297: * if the item exceeds the height of the screen, regardless of whether
0298: * internal traversal is occurring.</p>
0299: *
0300: * <p>An implementation may provide support for delivering keypad or pointer
0301: * events to <code>CustomItems</code> even if it has declined
0302: * to support delivering traverse events to <code>CustomItems</code>.
0303: * If an implementation provides support for
0304: * delivering keypad or pointer events to <code>CustomItems</code>,
0305: * it must provide a means
0306: * to do so for every <code>CustomItem</code>, even for those
0307: * that have refused internal
0308: * traversal by returning <code>false</code> to the initial
0309: * <code>traverse()</code> call.
0310: * This implies that such implementations must still support some notion
0311: * of focus for an item, even if that item is not supporting internal
0312: * traversal.</p>
0313: *
0314: * <p>See the documentation for the
0315: * {@link #traverse traverse} method for a full
0316: * specification of the behavior and responsibilities required for the item to
0317: * perform internal traversal.</p>
0318: *
0319: * <h2>Item Appearance</h2>
0320: *
0321: * <p>The visual appearance of each item consists of a
0322: * label (handled by the implementation)
0323: * and its contents (handled by the subclass).</p>
0324: *
0325: * <p>Labels are the responsibility of the implementation, not the item. The
0326: * screen area that is allocated to the <code>CustomItem</code>
0327: * for its contents is
0328: * separate from the area that the implementation uses to display the
0329: * <code>CustomItem's</code> label.
0330: * The implementation controls the rendering of the label
0331: * and its layout with respect to the content area.</p>
0332: *
0333: * <p>The <code>CustomItem</code> is responsible for
0334: * painting its contents whenever
0335: * the <code>paint</code> method is called.</p>
0336: *
0337: * <p>The colors for foreground, background, highlighted foreground,
0338: * highlighted background, border, and highlighted border should be
0339: * retrieved from {@link Display#getColor}.
0340: * This will allow <code>CustomItems</code> to
0341: * match the color scheme of other items provided with the device.
0342: * The <code>CustomItem</code> is responsible for keeping
0343: * track of its own highlighted and
0344: * unhighlighted state.</p>
0345: *
0346: * <p>The fonts used should be retrieved from {@link Font#getFont}.
0347: * This will allow them to match the fonts used by other items
0348: * on the device for a consistent visual appearance. </p>
0349: *
0350: */
0351: abstract public class CustomItem extends Item {
0352:
0353: /**
0354: * Interaction mode bit indicating support of horizontal traversal
0355: * internal to the <code>CustomItem</code>.
0356: *
0357: * <p><code>TRAVERSE_HORIZONTAL</code> has the value <code>1</code>.</p>
0358: *
0359: * @see #getInteractionModes
0360: * @see #traverse
0361: */
0362: protected static final int TRAVERSE_HORIZONTAL = 1;
0363:
0364: /**
0365: * Interaction mode bit indicating support for vertical traversal
0366: * internal to the <code>CustomItem</code>.
0367: *
0368: * <p><code>TRAVERSE_VERTICAL</code> has the value <code>2</code>.</p>
0369: *
0370: * @see #getInteractionModes
0371: * @see #traverse
0372: */
0373: protected static final int TRAVERSE_VERTICAL = 2;
0374:
0375: /**
0376: * Interaction mode bit indicating support for key pressed events.
0377: *
0378: * <p><code>KEY_PRESS</code> has the value <code>4</code>.</p>
0379: *
0380: * @see #getInteractionModes
0381: * @see #keyPressed
0382: */
0383: protected static final int KEY_PRESS = 4;
0384:
0385: /**
0386: * Interaction mode bit indicating support for key released events.
0387: *
0388: * <p><code>KEY_RELEASE</code> has the value <code>8</code>.</p>
0389: *
0390: * @see #getInteractionModes
0391: * @see #keyReleased
0392: */
0393: protected static final int KEY_RELEASE = 8;
0394:
0395: /**
0396: * Interaction mode bit indicating support for key repeated events.
0397: *
0398: * <p><code>KEY_REPEAT</code> has the value <code>0x10</code>.</p>
0399: *
0400: * @see #getInteractionModes
0401: * @see #keyRepeated
0402: */
0403: protected static final int KEY_REPEAT = 0x10;
0404:
0405: /**
0406: * Interaction mode bit indicating support for point pressed events.
0407: *
0408: * <p><code>POINTER_PRESS</code> has the value <code>0x20</code>.</p>
0409: *
0410: * @see #getInteractionModes
0411: * @see #pointerPressed
0412: */
0413: protected static final int POINTER_PRESS = 0x20;
0414:
0415: /**
0416: * Interaction mode bit indicating support for point released events.
0417: *
0418: * <p><code>POINTER_RELEASE</code> has the value<code> 0x40</code>.</p>
0419: *
0420: * @see #getInteractionModes
0421: * @see #pointerReleased
0422: */
0423: protected static final int POINTER_RELEASE = 0x40;
0424:
0425: /**
0426: * Interaction mode bit indicating support for point dragged events.
0427: *
0428: * <p><code>POINTER_DRAG</code> has the value <code>0x80</code>.</p>
0429: *
0430: * @see #getInteractionModes
0431: * @see #pointerDragged
0432: */
0433: protected static final int POINTER_DRAG = 0x80;
0434:
0435: /**
0436: * A value for traversal direction that indicates that traversal has
0437: * entered or has changed location within this item, but that no specific
0438: * direction is associated with this traversal event.
0439: *
0440: * <p><code>NONE</code> has the value <code>0</code>.</p>
0441: *
0442: * @see #traverse
0443: */
0444: protected static final int NONE = 0;
0445:
0446: /**
0447: * Superclass constructor, provided so that the
0448: * <code>CustomItem</code> subclass can specify its label.
0449: *
0450: * @param label the <code>CustomItem's</code> label
0451: */
0452: protected CustomItem(String label) {
0453: super (label);
0454:
0455: synchronized (Display.LCDUILock) {
0456: itemLF = customItemLF = LFFactory.getFactory()
0457: .getCustomItemLF(this );
0458: }
0459: }
0460:
0461: /**
0462: * Gets the game action associated with the given key code of the
0463: * device. Returns zero if no game action is associated with this key
0464: * code. See the
0465: * <a href="Canvas.html#gameactions">Game Actions</a>
0466: * section of class <code>Canvas</code> for further discussion
0467: * of game actions.
0468: *
0469: * <p>The mapping of key codes to game actions may differ between
0470: * <code>CustomItem</code> and <code>Canvas</code>.</p>
0471: *
0472: * @param keyCode the key code
0473: * @return the game action corresponding to this key, or <code>0</code>
0474: * if none
0475: * @throws IllegalArgumentException if <code>keyCode</code> is not
0476: * a valid key code
0477: */
0478: public int getGameAction(int keyCode) {
0479: int n = KeyConverter.getGameAction(keyCode);
0480:
0481: if (n == -1) {
0482: throw new IllegalArgumentException();
0483: }
0484:
0485: return n;
0486: }
0487:
0488: // JAVADOC COMMENT ELIDED
0489: protected final int getInteractionModes() {
0490: synchronized (Display.LCDUILock) {
0491: return customItemLF.lGetInteractionModes();
0492: }
0493: }
0494:
0495: /**
0496: * Implemented by the subclass to return the minimum width of the content
0497: * area, in pixels. This method is called by the implementation as part
0498: * of its layout algorithm. The actual width granted is reported in the
0499: * {@link #sizeChanged sizeChanged} and {@link #paint paint} methods.
0500: *
0501: * @return the minimum content width in pixels
0502: */
0503: protected abstract int getMinContentWidth();
0504:
0505: /**
0506: * Implemented by the subclass to return the minimum height of the content
0507: * area, in pixels. This method is called by the implementation as part
0508: * of its layout algorithm. The actual height granted is reported in the
0509: * {@link #sizeChanged sizeChanged} and {@link #paint paint} methods.
0510: *
0511: * @return the minimum content height in pixels
0512: */
0513: protected abstract int getMinContentHeight();
0514:
0515: /**
0516: * Implemented by the subclass to return the preferred width of the content
0517: * area, in pixels. This method is called by the implementation as part
0518: * of its layout algorithm.
0519: *
0520: * <p>The <code>height</code> parameter is the tentative height assigned
0521: * to the content area. The subclass code may use this value in its
0522: * computation of the preferred width. The <code>height</code> parameter
0523: * will be -1 if the implementation has not assigned a tentative value
0524: * for the height. Otherwise, <code>height</code> will have a specific
0525: * value if the application has locked the height of the
0526: * <code>CustomItem</code> or if the container's layout algorithm has
0527: * already computed a tentative height at the time of this call. The
0528: * subclass must not assume that the tentative height passed or the
0529: * preferred width returned will be granted.
0530: * The actual size granted is reported in the
0531: * {@link #sizeChanged sizeChanged} and {@link #paint paint} methods.
0532: * </p>
0533: *
0534: * @param height the tentative content height in pixels, or -1 if a
0535: * tentative height has not been computed
0536: * @return the preferred content width in pixels
0537: */
0538: protected abstract int getPrefContentWidth(int height);
0539:
0540: /**
0541: * Implemented by the subclass to return the preferred height of the
0542: * content area, in pixels. This method is called by the implementation
0543: * as part of its layout algorithm.
0544: *
0545: * <p>The <code>width</code> parameter is the tentative width assigned
0546: * to the content area. The subclass code may use this value in its
0547: * computation of the preferred height. The <code>width</code> parameter
0548: * will be -1 if the implementation has not assigned a tentative value
0549: * for the width. Otherwise, <code>width</code> will have a specific
0550: * value if the application has locked the width of the
0551: * <code>CustomItem</code> or if the container's layout algorithm has
0552: * already computed a tentative width at the time of this call. The
0553: * subclass must not assume that the tentative width passed or the
0554: * preferred height returned will be granted.
0555: * The actual size granted is reported in the
0556: * {@link #sizeChanged sizeChanged} and {@link #paint paint} methods.
0557: * </p>
0558: *
0559: * @param width the tentative content width in pixels, or -1 if a
0560: * tentative width has not been computed
0561: * @return the preferred content height in pixels
0562: */
0563: protected abstract int getPrefContentHeight(int width);
0564:
0565: /**
0566: * Implemented by the subclass in order to handle size change events.
0567: * This method is called by the system when the size of the content area
0568: * of this <code>CustomItem</code> has changed.
0569: *
0570: * <p>If the size of a <code>CustomItem</code> changes while it is
0571: * visible on the display, it may trigger an automatic
0572: * repaint request. If this occurs, the call to
0573: * <code>sizeChanged</code> will occur prior to the call to
0574: * <code>paint</code>. If the <code>CustomItem</code> has become
0575: * smaller, the implementation may choose not to trigger a repaint
0576: * request if the remaining contents of the <code>CustomItem</code>
0577: * have been preserved. Similarly, if the <code>CustomItem</code>
0578: * has become larger, the implementation may choose to trigger a
0579: * repaint only for the new region. In both cases, the preserved
0580: * contents must remain stationary with respect to the origin of the
0581: * <code>CustomItem</code>. If the size change is significant to
0582: * the contents of the <code>CustomItem</code>, the application must
0583: * explicitly issue a repaint request for the changed areas. Note
0584: * that the application's repaint request should not cause multiple
0585: * repaints, since it can be coalesced with repaint requests that
0586: * are already pending.</p>
0587: *
0588: * <p>If the size of the item's content area
0589: * changes while it is not visible, calls to this method may be deferred.
0590: * If the size had changed while the item was not visible,
0591: * <code>sizeChanged</code> will be called at least once before the item
0592: * becomes visible once again.</p>
0593: *
0594: * <p>The default implementation of this method does
0595: * nothing.</p>
0596: *
0597: * @param w the new width of the item's content area
0598: * @param h the new height of the item's content area
0599: */
0600: protected void sizeChanged(int w, int h) {
0601: }
0602:
0603: /**
0604: * Signals that the <code>CustomItem's</code> size and traversal
0605: * location need to be updated.
0606: * This method is intended to be called by <code>CustomItem</code>
0607: * subclass code to inform the implementation that the size of
0608: * the <code>CustomItem's</code> content area or the internal
0609: * traversal location might need to change.
0610: * This often occurs if the contents of the <code>CustomItem</code>
0611: * are modified. A call to this method will return immediately, and it
0612: * will cause the container's layout algorithm to run at some point in the
0613: * future, possibly resulting in calls to
0614: *
0615: * {@link #getMinContentHeight getMinContentHeight},
0616: * {@link #getMinContentWidth getMinContentWidth},
0617: * {@link #getPrefContentHeight getPrefContentHeight},
0618: * {@link #getPrefContentWidth getPrefContentWidth},
0619: * {@link #sizeChanged sizeChanged}, or
0620: * {@link #traverse traverse}.
0621: *
0622: * The {@link #paint paint} method may also be called if
0623: * repainting is necessary as a result of the layout operation.
0624: * If the content size is invalidated while the
0625: * <code>CustomItem</code> is not visible, the
0626: * layout operation may be deferred. The <code>traverse</code> method
0627: * will be called if the <code>CustomItem</code> contains the current
0628: * traversal location at the time <code>invalidate</code> is called.
0629: */
0630: protected final void invalidate() {
0631: synchronized (Display.LCDUILock) {
0632: customItemLF.lInvalidate();
0633: }
0634: }
0635:
0636: /**
0637: * Implemented by the subclass to render the item within its container.
0638: * At the time of the call, the <code>Graphics</code> context's
0639: * destination is the content area of this <code>CustomItem</code>
0640: * (or back buffer for it). The
0641: * Translation is set so that the upper left corner of the content area is
0642: * at <code>(0,0)</code>, and the clip is set to the area to be painted.
0643: * The application must paint every pixel within the given clip area. The
0644: * item is allowed to modify the clip area, but the system must not allow
0645: * any modification to result in drawing outside the bounds of the item's
0646: * content area. The <code>w</code> and <code>h</code> passed
0647: * in are the width and height of the
0648: * content area of the item. These values will always be equal to the
0649: * values passed with the most recent call to <code>sizeChanged()</code>;
0650: * they are passed here as well for convenience.
0651: *
0652: * <p>Other values of the <code>Graphics</code> object are as follows:</p>
0653: * <UL>
0654: * <LI>the current color is black;</LI>
0655: * <LI>the font is the same as the font returned by
0656: * {@link Font#getDefaultFont() Font.getDefaultFont()};</LI>
0657: * <LI>the stroke style is {@link Graphics#SOLID SOLID};</LI>
0658: * </UL>
0659: *
0660: * <p>The <code>paint()</code> method will be called only after
0661: * <code>showNotify()</code> call on this item and before a subsequent
0662: * <code>hideNotify()</code> call on this item, in other words, only when
0663: * at least a portion of the item is actually visible on the display.
0664: * In addition, the <code>paint()</code> method will be called only
0665: * if the item's width and height are both greater than zero.</p>
0666: *
0667: * @param g the <code>Graphics</code> object to be used for
0668: * rendering the item
0669: * @param w current width of the item in pixels
0670: * @param h current height of the item in pixels
0671: */
0672: protected abstract void paint(Graphics g, int w, int h);
0673:
0674: /**
0675: * Called by subclass code to request that the item be repainted. If this
0676: * item is visible on the display, this will result in a call to
0677: * <code>paint()</code> the next time the <code>CustomItem</code>
0678: * is to be displayed. The <code>CustomItem</code>
0679: * subclass should call this method when the item's internal state has
0680: * been updated such that its visual representation needs to be updated.
0681: */
0682: protected final void repaint() {
0683: synchronized (Display.LCDUILock) {
0684: customItemLF.lRepaint();
0685: }
0686: }
0687:
0688: /**
0689: * Called by subclass code to request that the specified rectangular area
0690: * of the item be repainted. If that area is visible on the display, this
0691: * will result in call to <code>paint</code> with graphics set to
0692: * include the specified rectangular area.
0693: * The area is specified relative to the <code>CustomItem's</code>
0694: * content area.
0695: * The <code>CustomItem</code> should call this method when the item's
0696: * internal state has been updated and only part of the visual
0697: * representation needs to be updated.
0698: *
0699: * @param x the x coordinate of the rectangular area to be updated
0700: * @param y the y coordinate of the rectangular area to be updated
0701: * @param w the width of the rectangular area to be updated
0702: * @param h the height of the rectangular area to be updated
0703: */
0704: protected final void repaint(int x, int y, int w, int h) {
0705: synchronized (Display.LCDUILock) {
0706: customItemLF.lRepaint(x, y, w, h);
0707: }
0708: }
0709:
0710: /**
0711: * Called by the system when traversal has entered the item or has
0712: * occurred within the item. The direction of traversal and the item's
0713: * visible rectangle are passed into the method. The method must do one
0714: * of the following: it must either update its state information
0715: * pertaining to its internal traversal location, set the return rectangle
0716: * to indicate a region associated with this location, and return
0717: * <code>true</code>; or, it must return <code>false</code> to indicate
0718: * that this item does not support internal traversal, or that that
0719: * internal traversal has reached the edge of the item and that traversal
0720: * should proceed to the next item if possible.
0721: *
0722: * <p>The implementation indicates support for internal traversal within a
0723: * <code>CustomItem</code> by setting one or both of the
0724: * <code>TRAVERSE_HORIZONTAL</code> or
0725: * <code>TRAVERSE_VERTICAL</code> bits in the value returned by the
0726: * <code>getInteractionModes</code>
0727: * method. The <code>dir</code> parameter indicates the direction of
0728: * traversal by using <code>Canvas</code> game actions
0729: * <code>Canvas.UP</code>, <code>Canvas.DOWN</code>,
0730: * <code>Canvas.LEFT</code>, and <code>Canvas.RIGHT</code>, or the
0731: * value <code>NONE</code>, which indicates that there is no specific
0732: * direction associated with this traversal event.
0733: * If the <code>TRAVERSE_HORIZONTAL</code> bit is set,
0734: * this indicates that the <code>Canvas.LEFT</code> and
0735: * <code>Canvas.RIGHT</code> values will be
0736: * used to indicate the traversal direction.
0737: * If the <code>TRAVERSE_VERTICAL</code> bit
0738: * is set, this indicates that the <code>Canvas.UP</code> and
0739: * <code>Canvas.DOWN</code> values will
0740: * be used to indicate the traversal direction. If both bits are set, all
0741: * four direction values may be used for the traversal direction,
0742: * indicating that the item should perform two-dimensional traversal. The
0743: * <code>dir</code> parameter may have the value <code>NONE</code> under
0744: * any combination of the <code>TRAVERSE_VERTICAL</code> and
0745: * <code>TRAVERSE_HORIZONTAL</code> bits.
0746: * </p>
0747: *
0748: * <p>Although <code>Canvas</code> game actions are used to indicate the
0749: * traversal direction, this does not imply that the keys mapped to these
0750: * game actions are being used for traversal, nor that that keys are being
0751: * used for traversal at all.</p>
0752: *
0753: * <p>The <code>viewportWidth</code> and <code>viewportHeight</code>
0754: * parameters indicate the size of the viewable area the item's container
0755: * has granted to its items. This represents the largest area of the
0756: * item that is likely to be visible at any given time.</p>
0757: *
0758: * <p>The <code>visRect_inout</code> parameter is used both for passing
0759: * information into this method and for returning information from this
0760: * method. It must be an <code>int[4]</code> array. The information in
0761: * this array is a rectangle of the form <code>[x,y,w,h]</code>
0762: * where <code>(x,y)</code> is the
0763: * location of the upper-left corner of the rectangle relative to the
0764: * item's origin, and <code>(w,h)</code> are the width and
0765: * height of the rectangle.
0766: * The return values placed into this array are significant only when the
0767: * <code>traverse()</code> method returns <code>true</code>.
0768: * The values are ignored if
0769: * the <code>traverse()</code> method returns <code>false</code>.</p>
0770: *
0771: * <p>When this method is called, the <code>visRect_inout</code> array
0772: * contains a rectangle representing the region of the item that is
0773: * currently visible. This region might have zero area if no part of the
0774: * item is visible, for example, if it is scrolled offscreen. The
0775: * semantics of the rectangle returned are discussed below.</p>
0776: *
0777: * <p>The <code>CustomItem</code> must maintain state that tracks
0778: * whether traversal is
0779: * within this item, and if it is, it must also record the current
0780: * internal location. Initially, traversal is outside the item. The
0781: * first call to the <code>traverse()</code> method indicates
0782: * that traversal has
0783: * entered the item. Subsequent calls to this method indicate that
0784: * traversal is occurring within this item. Traversal remains within the
0785: * item until the <code>traverseOut</code> method is called.
0786: * The <code>CustomItem</code> must keep
0787: * track of its traversal state so that it can distinguish traversal
0788: * <em>entering</em> the item from traversal <em>within</em> the item.
0789: * </p>
0790: *
0791: * <p>When traversal enters the item, the traversal code
0792: * should initialize its internal traversal
0793: * location to the "first" location appropriate
0794: * for the item's structure and the traversal direction.
0795: * As an example of the latter policy, if
0796: * the traversal direction is <code>DOWN</code>, the initial
0797: * location should be the
0798: * topmost internal element of the item. Similarly, if the traversal
0799: * direction is <code>UP</code>, the initial location should be the
0800: * bottommost element of the item.
0801: * The <code>CustomItem</code>
0802: * should still choose the "first" location appropriately
0803: * even if its primary axis is orthogonal to the
0804: * axis of traversal. For example, suppose the traversal
0805: * mode supported is <code>TRAVERSE_VERTICAL</code> but the
0806: * <code>CustomItem</code> is structured as a horizontal row
0807: * of elements. If the initial traversal direction is
0808: * <code>DOWN</code>, the initial location might be the leftmost
0809: * element, and if the initial traversal direction is
0810: * <code>UP</code>, the initial location might be the rightmost
0811: * element.</p>
0812: *
0813: * <p>Traversal may enter the item without any specific direction, in
0814: * which case the traversal direction will be <code>NONE</code>. This may
0815: * occur if the user selects the item directly (e.g., with a pointing
0816: * device), or if the item gains the focus because its containing
0817: * <code>Form</code> has become current. The <code>CustomItem</code>
0818: * should choose a default traversal location. If the
0819: * <code>CustomItem</code> had been traversed to previously, and if it is
0820: * appropriate for the user interface of the <code>CustomItem</code>, the
0821: * previous traversal location should be restored.</p>
0822: *
0823: * <p>When traversal occurs within
0824: * the item, the internal traversal location must be moved to the next
0825: * appropriate region in the direction of traversal. The item must report
0826: * its updated internal traversal location in the
0827: * <code>visRect_inout</code> return parameter as described below and
0828: * return <code>true</code>. The item will typically provide a highlight
0829: * to display the internal traversal location to the user. Thus, the item
0830: * will typically also request repaints of the old and new traversal
0831: * locations after each traversal event. There is no requirement that the
0832: * area the item requests to be repainted is the same as the area returned
0833: * in the <code>visRect_inout</code> rectangle. The system will combine
0834: * any repaint requests with any additional repainting that may occur as a
0835: * result of scrolling.</p>
0836: *
0837: * <p>The <code>traverse()</code> method may be called with a direction of
0838: * <code>NONE</code> when the traversal is already within the
0839: * <code>CustomItem</code>. This will occur in response to the
0840: * <code>CustomItem</code> subclass code having called the
0841: * <code>invalidate()</code> method. In this case, the
0842: * <code>CustomItem</code> should simply return its current notion of the
0843: * traversal location. This mechanism is useful if the
0844: * <code>CustomItem</code> needs to update the traversal location
0845: * spontaneously (that is, not in response to a traversal event), for
0846: * example, because of a change in its contents.</p>
0847: *
0848: * <p>If the internal traversal location is such that the traversal event
0849: * would logically cause traversal to proceed out of the item, the
0850: * item should return <code>false</code> from the
0851: * <code>traverse()</code> method. For
0852: * example, if the current traversal location is the bottommost internal
0853: * element of the item, and the traversal direction is
0854: * <code>DOWN</code>, the
0855: * <code>traverse()</code> method should simply return
0856: * <code>false</code>. In this
0857: * case the method need not update the values in the
0858: * <code>visRect_inout</code> array. The item must leave its internal
0859: * traversal location unchanged, and it should not request a repaint to
0860: * update its highlighting. It should defer these actions until the
0861: * <code>traverseOut()</code> method is called.
0862: * The system will call the <code>traverseOut()</code>
0863: * method when traversal actually leaves the item. The system might not
0864: * call the <code>traverseOut()</code> method, even if
0865: * <code>traverse()</code> has returned
0866: * <code>false</code>, if this item is at the edge of the
0867: * <code>Form</code> or there is
0868: * no other item beyond to accept the traversal.
0869: * Even if the <code>traverse()</code>
0870: * method returns <code>false</code>, the traversal location is still
0871: * within this item.
0872: * It remains within this item until <code>traverseOut()</code> is
0873: * called.</p>
0874: *
0875: * <p>Note the subtle distinction here between the initial
0876: * <code>traverse()</code> call
0877: * signifying <em>entry</em> into the item and subsequent calls signifying
0878: * traversal <em>within</em> the item. A return value of
0879: * <code>false</code> to the initial call indicates that this item
0880: * performs no internal traversal at all, whereas a return of
0881: * <code>false</code> to subsequent calls indicates that traversal is
0882: * within this item and may now exit. </p>
0883: *
0884: * <p>The width and height of the rectangle returned in the
0885: * <code>visRect_inout</code> array are used by the
0886: * <code>Form</code> for scrolling
0887: * and painting purposes. The <code>Form</code> must always
0888: * position the item so that
0889: * the upper left corner of this rectangle, as specified by
0890: * the <code>(x,y)</code>
0891: * position, is visible. In addition, the item may also specify a width
0892: * and height, in which case the <code>Form</code> will
0893: * attempt to position the item so
0894: * that as much of this rectangle as possible is visible. If the width
0895: * and height are larger than the size of the viewport, the bottom and
0896: * right portions of this rectangle will most likely not be visible to the
0897: * user. The rectangle thus returned will typically denote the size and
0898: * location of one of the item's internal elements, and it will also
0899: * typically (though not necessarily) correspond to where the element's
0900: * highlight will be painted. Width and height values of zero are legal
0901: * and are not treated specially. Negative values of width and height are
0902: * treated as if they were zero.</p>
0903: *
0904: * <p>There is no requirement on the location of the rectangle returned in
0905: * the <code>visRect_inout</code> array with respect to the traversal
0906: * direction. For example, if the <code>CustomItem</code> implements
0907: * internal scrolling, a traversal direction of <code>DOWN</code> may
0908: * cause the item's contents to scroll upwards far enough so that the
0909: * rectangle returned may be above its old location.
0910: * <code>CustomItem</code> subclasses must ensure that continued traversal
0911: * in one direction will eventually reach the edge of the item and then
0912: * traverse out by returning <code>false</code> from this method.
0913: * <code>CustomItems</code> must not implement "wraparound"
0914: * behavior (for example, traversing downwards from the bottommost element
0915: * moves the traversal location to the topmost element) because this will
0916: * trap the traversal within the item.</p>
0917: *
0918: * <p>If the <code>CustomItem</code> consists of internal
0919: * elements that are smaller
0920: * than the container's viewport, the rectangle returned
0921: * should be the
0922: * same size as one of these elements. However, the
0923: * <code>CustomItem</code> might have
0924: * contents whose elements are larger than the viewport, or it might have
0925: * contents having no internal structure. In either of these cases, the
0926: * item should return a rectangle that best represents its idea of the
0927: * content area that is important for the user to see. When traversal
0928: * occurs, the item should move its traversal location by an amount based
0929: * on the viewport size. For example, if the viewport is
0930: * <code>80</code> pixels high,
0931: * and traversal occurs downwards, the item might move its traversal
0932: * location down by <code>70</code> pixels in order to display
0933: * the next screenful of
0934: * content, with <code>10</code> pixels overlap for context.</p>
0935: *
0936: * <p>All internal traversal locations must be reachable regardless of
0937: * which traversal modes are provided by the implementation. This
0938: * implies that,
0939: * if the implementation provides one-dimensional traversal, the
0940: * <code>CustomItem</code> must linearize its internal locations.
0941: * For example, suppose the traversal mode is
0942: * <code>TRAVERSE_VERTICAL</code> and the <code>CustomItem</code> consists
0943: * of a horizontal row of elements. If the traversal direction is
0944: * <code>DOWN</code> the internal traversal location should move to the
0945: * right, and if the traversal direction is <code>UP</code> the internal
0946: * traversal location should move to the left. (The foregoing convention
0947: * is appropriate for languages that use left-to-right text. The opposite
0948: * convention should be used for languages that use right-to-left text.)
0949: * Consider a similar example where the traversal mode is
0950: * <code>TRAVERSE_VERTICAL</code> and the <code>CustomItem</code> consists
0951: * of a grid of elements. A traversal direction of <code>DOWN</code>
0952: * might proceed leftwards across each row, moving to the next row
0953: * downwards when the location reaches the rightmost element in a row.
0954: * </p>
0955: *
0956: * <p>If the implementation provides two-dimensional traversal but the
0957: * <code>CustomItem</code> is one-dimensional, a traversal direction
0958: * along the item's
0959: * axis should traverse within the item, and a traversal direction
0960: * orthogonal to the item's axis should cause immediate traversal out of
0961: * the item by returning <code>false</code> from this method. For
0962: * example, suppose a <code>CustomItem</code> is implementing
0963: * a vertical stack of
0964: * elements and traversal is already inside the item. If a traverse event
0965: * is received with direction <code>UP</code> or <code>DOWN</code>,
0966: * the <code>traverse()</code> method should
0967: * move to the next element and return <code>true</code>. On the other
0968: * hand, if a traverse event is received with direction
0969: * <code>RIGHT</code> or <code>LEFT</code>, the
0970: * <code>traverse()</code> method should always return
0971: * <code>false</code> so that
0972: * traversal exits the item immediately. An item that implements internal
0973: * traversal should always accept entry - that is, the initial call to
0974: * <code>traverse()</code> should return <code>true</code> -
0975: * regardless of the axis of the traversal direction.</p>
0976: *
0977: * <p>If the <code>traverse()</code> method returns
0978: * <code>false</code> when traversal
0979: * is entering the item, this indicates to the system that the item does
0980: * not support internal traversal. In this case, the item should not
0981: * perform any of its own highlighting, and the system will perform
0982: * highlighting appropriate for the platform, external to the item.</p>
0983: *
0984: * <p>The default implementation of the <code>traverse()</code>
0985: * method always returns <code>false</code>.</p>
0986: *
0987: * @param dir the direction of traversal, one of
0988: * {@link Canvas#UP Canvas.UP}, {@link Canvas#DOWN Canvas.DOWN},
0989: * {@link Canvas#LEFT Canvas.LEFT}, {@link Canvas#RIGHT Canvas.RIGHT}, or
0990: * {@link #NONE NONE}.
0991: * @param viewportWidth the width of the container's viewport
0992: * @param viewportHeight the height of the container's viewport
0993: * @param visRect_inout passes the visible rectangle into the method, and
0994: * returns the updated traversal rectangle from the method
0995: * @return <code>true</code> if internal traversal had occurred,
0996: * <code>false</code> if traversal should proceed out
0997: *
0998: * @see #getInteractionModes
0999: * @see #traverseOut
1000: * @see #TRAVERSE_HORIZONTAL
1001: * @see #TRAVERSE_VERTICAL
1002: */
1003: protected boolean traverse(int dir, int viewportWidth,
1004: int viewportHeight, int visRect_inout[]) {
1005: return false;
1006: }
1007:
1008: /**
1009: * Called by the system when traversal has occurred out of the item. This
1010: * may occur in response to the <code>CustomItem</code> having returned
1011: * <code>false</code> to a previous call to <code>traverse()</code>, if
1012: * the user has begun interacting with another item, or if
1013: * <code>Form</code> containing
1014: * this item is no longer current. If the <code>CustomItem</code>
1015: * is using highlighting to indicate internal traversal,
1016: * the <code>CustomItem</code>
1017: * should set its state to be unhighlighted and request a repaint. (Note
1018: * that painting will not occur if the item is no longer visible.)
1019: *
1020: * @see #getInteractionModes
1021: * @see #traverse
1022: * @see #TRAVERSE_HORIZONTAL
1023: * @see #TRAVERSE_VERTICAL
1024: */
1025: protected void traverseOut() {
1026: }
1027:
1028: /**
1029: * Called by the system when a key is pressed. The implementation
1030: * indicates support for delivery of key press events by setting the
1031: * <code>KEY_PRESS</code> bit in the value returned by the
1032: * <code>getInteractionModes</code> method.
1033: *
1034: * @param keyCode the key code of the key that has been pressed
1035: * @see #getInteractionModes
1036: */
1037: protected void keyPressed(int keyCode) {
1038: }
1039:
1040: /**
1041: * Called by the system when a key is released. The implementation
1042: * indicates support for delivery of key release events by setting the
1043: * <code>KEY_RELEASE</code> bit in the value returned by the
1044: * <code>getInteractionModes</code> method.
1045: *
1046: * @param keyCode the key code of the key that has been released
1047: * @see #getInteractionModes
1048: */
1049: protected void keyReleased(int keyCode) {
1050: }
1051:
1052: /**
1053: * Called by the system when a key is repeated. The implementation
1054: * indicates support for delivery of key repeat events by setting the
1055: * <code>KEY_REPEAT</code> bit in the value returned by the
1056: * <code>getInteractionModes</code> method.
1057: *
1058: * @param keyCode the key code of the key that has been repeated
1059: * @see #getInteractionModes
1060: */
1061: protected void keyRepeated(int keyCode) {
1062: }
1063:
1064: /**
1065: * Called by the system when a pointer down action (for example, a pen
1066: * tap) has occurred within the item. The <code>(x,y)</code>
1067: * coordinates are relative
1068: * to the origin of the item, and they will always indicate a location
1069: * within the item. The implementation indicates support for delivery of
1070: * pointer press events by setting the <code>POINTER_PRESS</code>
1071: * bit in the value
1072: * returned by the <code>getInteractionModes</code> method.
1073: *
1074: * @param x the <code>x</code> coordinate of the pointer down
1075: * @param y the <code>y</code> coordinate of the pointer down
1076: *
1077: * @see #getInteractionModes
1078: */
1079: protected void pointerPressed(int x, int y) {
1080: }
1081:
1082: /**
1083: * Called by the system when a pointer up action (for example, a pen lift)
1084: * has occurred after a pointer down action had occurred within the item.
1085: * The <code>(x,y)</code> coordinates are relative to the origin
1086: * of the item.
1087: * Implementations should deliver a pointer release event to an item even
1088: * if the pointer has moved outside the item when the release occurs. In
1089: * this case the <code>(x,y)</code> coordinates may indicate a
1090: * location outside the
1091: * bounds of the item. The implementation indicates support for delivery
1092: * of pointer release events by setting the
1093: * <code>POINTER_RELEASE</code> bit in the
1094: * value returned by the <code>getInteractionModes</code> method.
1095: *
1096: * @param x the x coordinate of the pointer up
1097: * @param y the x coordinate of the pointer up
1098: *
1099: * @see #getInteractionModes
1100: */
1101: protected void pointerReleased(int x, int y) {
1102: }
1103:
1104: /**
1105: * Called by the system when a pointer drag action (for example, pen
1106: * motion after a press but before a release) has occurred within the item.
1107: * The <code>(x,y)</code> coordinates are relative to the origin
1108: * of the item.
1109: * Implementations should deliver pointer drag events to an item even if
1110: * the pointer is being moved outside the item. In this case
1111: * the <code>(x,y)</code>
1112: * coordinates may indicate a location outside the bounds of the item.
1113: * The implementation indicates support for delivery of pointer release
1114: * events by setting the <code>POINTER_DRAG</code> bit in the
1115: * value returned by the
1116: * <code>getInteractionModes</code> method.
1117: *
1118: * @param x the <code>x</code> coordinate of the pointer drag
1119: * @param y the <code>x</code> coordinate of the pointer drag
1120: *
1121: * @see #getInteractionModes
1122: */
1123: protected void pointerDragged(int x, int y) {
1124: }
1125:
1126: /**
1127: * Called by the system to notify the item that it is now at least
1128: * partially visible, when it previously had been completely invisible.
1129: * The item may receive <code>paint()</code> calls after
1130: * <code>showNotify()</code> has been called.
1131: *
1132: * <p>The default implementation of this method does nothing.</p>
1133: */
1134: protected void showNotify() {
1135: }
1136:
1137: /**
1138: * Called by the system to notify the item that it is now completely
1139: * invisible, when it previously had been at least partially visible. No
1140: * further <code>paint()</code> calls will be made on this item
1141: * until after a <code>showNotify()</code> has been called again.
1142: *
1143: * <p>The default implementation of this method does nothing.</p>
1144: */
1145: protected void hideNotify() {
1146: }
1147:
1148: // ******************************************
1149: // Package private methods
1150: // ******************************************
1151:
1152: /** Size type of minimum width */
1153: final static int SIZE_MIN_WIDTH = 0;
1154:
1155: /** Size type of minimum height */
1156: final static int SIZE_MIN_HEIGHT = 1;
1157:
1158: /** Size type of preferred width */
1159: final static int SIZE_PREF_WIDTH = 2;
1160:
1161: /** Size type of preferred height */
1162: final static int SIZE_PREF_HEIGHT = 3;
1163:
1164: /**
1165: * Internal function to query for preferred content size.
1166: * This function will never return negative value.
1167: * SYNC NOTE: This function will internally acquire calloutLock.
1168: * So caller must not hold LCDUILock around this call.
1169: *
1170: * @param type the type of size that is queried.
1171: * @param lockedSize the tentative content size in pixels, or -1 if a
1172: * tentative size has not been computed
1173: * @return the preferred content size in pixels
1174: */
1175: int uGetContentSize(int type, int lockedSize) {
1176: int result = 0; // default value
1177:
1178: try {
1179: synchronized (Display.calloutLock) {
1180: switch (type) {
1181:
1182: case SIZE_MIN_WIDTH:
1183: result = getMinContentWidth();
1184: break;
1185:
1186: case SIZE_MIN_HEIGHT:
1187: result = getMinContentHeight();
1188: break;
1189:
1190: case SIZE_PREF_WIDTH:
1191: result = getPrefContentWidth(lockedSize);
1192: break;
1193:
1194: case SIZE_PREF_HEIGHT:
1195: result = getPrefContentHeight(lockedSize);
1196: break;
1197: }
1198: }
1199: } catch (Throwable thr) {
1200: Display.handleThrowable(thr);
1201: }
1202:
1203: // If subclass returns negative size, treat it as 0
1204: return (result > 0) ? result : 0;
1205: }
1206:
1207: /**
1208: * Return whether the Item takes user input focus.
1209: *
1210: * @return always return <code>true</code>
1211: */
1212: boolean acceptFocus() {
1213: return true;
1214: }
1215:
1216: /**
1217: * The look&feel associated with this CustomItem.
1218: * Set in the constructor.
1219: */
1220: CustomItemLF customItemLF; // = null
1221: }
|