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: import com.sun.midp.configurator.Constants;
0032:
0033: /**
0034: * The <code>Canvas</code> class is a base class for writing
0035: * only.
0036: * applications that need to
0037: * handle low-level events and to issue graphics calls for drawing to the
0038: * display. Game applications will likely make heavy use of the
0039: * <code>Canvas</code> class.
0040: * From an application development perspective, the <code>Canvas</code> class is
0041: * interchangeable with standard <code>Screen</code> classes, so an
0042: * application may mix and
0043: * match <code>Canvas</code> with high-level screens as needed. For
0044: * example, a List screen
0045: * may be used to select the track for a racing game, and a
0046: * <code>Canvas</code> subclass
0047: * would implement the actual game.
0048: *
0049: * <P>The <code>Canvas</code> provides the developer with methods to
0050: * handle game actions,
0051: * key events, and
0052: * pointer events (if supported by the device). Methods are
0053: * also provided to identify the device's capabilities and mapping of
0054: * keys to game actions.
0055: * The key events are reported with respect to <em>key codes</em>, which
0056: * are directly bound to concrete keys on the device, use of which may hinder
0057: * portability. Portable applications should use game actions instead of key
0058: * codes.</p>
0059: *
0060: * <p> Like other subclasses of <code>Displayable</code>, the
0061: * <code>Canvas</code> class allows the
0062: * application to register a listener for commands. Unlike other
0063: * <code>Displayables</code>,
0064: * however, the <code>Canvas</code> class requires applications to
0065: * subclass it in order to
0066: * use it. The <code>paint()</code> method is declared
0067: * <code>abstract</code>, and so the
0068: * application <em>must</em> provide an implementation in its subclass. Other
0069: * event-reporting methods are not declared <code>abstract,</code> and their
0070: * default implementations are empty (that is, they do nothing). This allows
0071: * the application to override only the methods that report events in which the
0072: * application has interest. </p>
0073: *
0074: * <p> This is in contrast to the {@link Screen Screen} classes, which allow
0075: * the application to define listeners and to register them with instances of
0076: * the <code>Screen</code> classes. This style is not used for the
0077: * <code>Canvas</code> class, because
0078: * several new listener interfaces would need to be created, one for each kind
0079: * of event that might be delivered. An alternative would be to have fewer
0080: * listener interfaces, but this would require listeners to filter out events
0081: * in which they had no interest. </p>
0082: *
0083: * <a name="keyevents"></a>
0084: * <h3>Key Events</h3>
0085: *
0086: * <p> Applications receive keystroke events in which the individual keys are
0087: * named within a space of <em>key codes</em>. Every key for which events are
0088: * reported to MIDP applications is assigned a key code.
0089: * The key code values are unique for each hardware key unless two keys are
0090: * obvious synonyms for each other.
0091: * MIDP defines the following key codes:
0092: * {@link #KEY_NUM0 KEY_NUM0},
0093: * {@link #KEY_NUM1 KEY_NUM1},
0094: * {@link #KEY_NUM2 KEY_NUM2},
0095: * {@link #KEY_NUM3 KEY_NUM3},
0096: * {@link #KEY_NUM4 KEY_NUM4},
0097: * {@link #KEY_NUM5 KEY_NUM5},
0098: * {@link #KEY_NUM6 KEY_NUM6},
0099: * {@link #KEY_NUM7 KEY_NUM7},
0100: * {@link #KEY_NUM8 KEY_NUM8},
0101: * {@link #KEY_NUM9 KEY_NUM9},
0102: * {@link #KEY_STAR KEY_STAR}, and
0103: * {@link #KEY_POUND KEY_POUND}.
0104: *
0105: * (These key codes correspond to keys on a ITU-T standard telephone keypad.)
0106: * Other keys may be present on the keyboard, and they will generally have key
0107: * codes distinct from those list above. In order to guarantee portability,
0108: * applications should use only the standard key codes. </p>
0109: *
0110: * <p>The standard key codes' values are equal to the Unicode encoding for the
0111: * character that represents the key. If the device includes any other keys
0112: * that have an obvious correspondence to a Unicode character, their key code
0113: * values should equal the Unicode encoding for that character. For keys that
0114: * have no corresponding Unicode character, the implementation must use
0115: * negative values. Zero is defined to be an invalid key code. It is thus
0116: * possible for an application to convert a keyCode into a Unicode character
0117: * using the following code: </p>
0118: *
0119: * <TABLE BORDER="2">
0120: * <TR>
0121: * <TD ROWSPAN="1" COLSPAN="1">
0122: * <pre><code>
0123: * if (keyCode > 0) {
0124: * char ch = (char)keyCode;
0125: * // ...
0126: * } </code></pre>
0127: * </TD>
0128: * </TR>
0129: * </TABLE>
0130: * <p>This technique is useful only in certain limited cases. In particular,
0131: * it is not sufficient for full textual input, because it does not handle
0132: * upper and lower case, keyboard shift states, and characters that require
0133: * more than one keystroke to enter. For textual input, applications should
0134: * always use {@link TextBox TextBox} or {@link TextField TextField}
0135: * objects.</p>
0136: *
0137: * <p> It is sometimes useful to find the <em>name</em> of a key in order to
0138: * display a message about this key. In this case the application may use the
0139: * {@link #getKeyName(int) getKeyName()} method to find a key's name. </p>
0140: *
0141: * <a name="gameactions"></a>
0142: * <h3>Game Actions</h3>
0143: * <p>
0144: * Portable applications that need arrow key events and gaming-related events
0145: * should use <em>game actions</em> in preference to key codes and key names.
0146: * MIDP defines the following game actions:
0147: * {@link #UP UP},
0148: * {@link #DOWN DOWN},
0149: * {@link #LEFT LEFT},
0150: * {@link #RIGHT RIGHT},
0151: * {@link #FIRE FIRE},
0152: * {@link #GAME_A GAME_A},
0153: * {@link #GAME_B GAME_B},
0154: * {@link #GAME_C GAME_C}, and
0155: * {@link #GAME_D GAME_D}.
0156: * </P>
0157: *
0158: * <P> Each key code may be mapped to at most one game action. However, a game
0159: * action may be associated with more than one key code. The application can
0160: * translate a key code into a game action using the {@link #getGameAction(int)
0161: * getGameAction(int keyCode)} method, and it can translate a game action into
0162: * a key code using the {@link #getKeyCode(int) getKeyCode(int gameAction)}
0163: * method. There may be multiple keycodes associated with a particular game
0164: * action, but <code>getKeyCode</code> returns only one of them. Supposing
0165: * that <code>g</code> is a valid game action and <code>k</code>
0166: * is a valid key code for a key associated with a game action, consider
0167: * the following expressions:</p>
0168: *
0169: * <TABLE BORDER="2">
0170: * <TR>
0171: * <TD ROWSPAN="1" COLSPAN="1">
0172: * <pre><code>
0173: * g == getGameAction(getKeyCode(g)) // (1)
0174: * k == getKeyCode(getGameAction(k)) // (2) </code></pre>
0175: * </TD>
0176: * </TR>
0177: * </TABLE>
0178: * <p>Expression (1) is <em>always</em> true. However, expression (2)
0179: * might be true but is <em>not necessarily</em> true.</p>
0180: *
0181: * <P>The implementation is not allowed to change the mapping of game
0182: * actions and key codes during execution of the application.</P>
0183: *
0184: * <p> Portable applications that are interested in using game actions should
0185: * translate every key event into a game action by calling the {@link
0186: * #getGameAction getGameAction()} method and then testing the result. For
0187: * example, on some devices the game actions <code>UP</code>,
0188: * <code>DOWN</code>, <code>LEFT</code> and <code>RIGHT</code> may be
0189: * mapped to 4-way navigation arrow keys. In this case,<code>
0190: * getKeyCode(UP)</code> would
0191: * return a device-dependent code for the up-arrow key. On other devices, a
0192: * possible mapping would be on the number keys <code>2</code>,
0193: * <code>4</code>, <code>6</code> and <code>8</code>. In this case,
0194: * <code>getKeyCode(UP)</code> would return <code>KEY_NUM2</code>. In
0195: * both cases, the <code>getGameAction()</code>
0196: * method would return the <code>LEFT</code> game action when the user
0197: * presses the key that
0198: * is a "natural left" on her device. </P>
0199: *
0200: * <a name="commands"></a>
0201: * <h3>Commands</h3>
0202: *
0203: * <p> It is also possible for the user to issue {@link Command commands} when
0204: * a canvas is current. <code>Commands</code> are mapped to keys and menus in a
0205: * device-specific fashion. For some devices the keys used for commands may
0206: * overlap with the keys that will deliver key code events to the canvas. If
0207: * this is the case, the device will provide a means transparent to the
0208: * application that enables the user to select a mode that determines whether
0209: * these keys will deliver commands or key code events to the application.
0210: * When the <code>Canvas</code> is in normal mode (see <a
0211: * href="#fullscreen">below</a>),
0212: * the set of key code events available to a canvas will not change depending
0213: * upon the number of commands present or the presence of a command listener.
0214: * When the <code>Canvas</code> is in full-screen mode, if there is no
0215: * command listener
0216: * present, the device may choose to deliver key code events for keys that
0217: * would otherwise be reserved for delivery of commands. Game developers
0218: * should be aware that access to commands will vary greatly across devices,
0219: * and that requiring the user to issue commands during game play may have a
0220: * great impact on the ease with which the game can be played. </p>
0221: *
0222: * <a name="eventdelivery"></a>
0223: * <h3>Event Delivery</h3>
0224: *
0225: * <P> The <code>Canvas</code> object defines several methods that are
0226: * called by the
0227: * implementation. These methods are primarily for the purpose of delivering
0228: * events to the application, and so they are referred to as
0229: * <em>event delivery</em> methods. The set of methods is: </p>
0230: *
0231: * <ul>
0232: * <li> <code>showNotify()</code> </li>
0233: * <li> <code>hideNotify()</code> </li>
0234: * <li> <code>keyPressed()</code> </li>
0235: * <li> <code>keyRepeated()</code> </li>
0236: * <li> <code>keyReleased()</code> </li>
0237: * <li> <code>pointerPressed()</code> </li>
0238: * <li> <code>pointerDragged()</code> </li>
0239: * <li> <code>pointerReleased()</code> </li>
0240: * <li> <code>paint()</code> </li>
0241: * </ul>
0242: *
0243: * <p> These methods are all called serially. That is, the implementation will
0244: * never call an event delivery method before a prior call to <em>any</em> of
0245: * the event delivery methods has returned. The
0246: * <code>serviceRepaints()</code> method is an exception to this rule, as it
0247: * blocks until <code>paint()</code> is called and returns. This will occur
0248: * even if the application is in the midst of one of the event delivery
0249: * methods when it calls <code>serviceRepaints()</code>. </p>
0250: *
0251: * <p>The {@link Display#callSerially Display.callSerially()} method can be
0252: * used to serialize some application-defined work with the event stream.
0253: * For further information, see the
0254: * <a href="./package-summary.html#events">Event Handling</a> and
0255: * <a href="./package-summary.html#concurrency">Concurrency</a>
0256: * sections of the package summary. </p>
0257: *
0258: * <p> The key-related, pointer-related, and <code>paint()</code> methods
0259: * will only be called while the <code>Canvas</code> is actually
0260: * visible on the output
0261: * device. These methods will therefore only be called on this
0262: * <code>Canvas</code> object
0263: * only after a call to <code>showNotify()</code> and before a call to
0264: * <code>hideNotify()</code>. After
0265: * <code>hideNotify()</code> has been called, none of the key,
0266: * pointer, and <code>paint</code>
0267: * methods will be called until after a
0268: * subsequent call to
0269: * <code>showNotify()</code> has returned. A call to a
0270: * <code>run()</code> method resulting from
0271: * <code>callSerially()</code> may occur irrespective of calls to
0272: * <code>showNotify()</code> and
0273: * <code>hideNotify()</code>. </p>
0274: *
0275: * <p> The {@link #showNotify() showNotify()} method is called prior to the
0276: * <code>Canvas</code> actually being made visible on the display, and
0277: * the {@link
0278: * #hideNotify() hideNotify()} method is called after the
0279: * <code>Canvas</code> has been
0280: * removed from the display. The visibility state of a
0281: * <code>Canvas</code> (or any other
0282: * <code>Displayable</code> object) may be queried through the use of the {@link
0283: * Displayable#isShown() Displayable.isShown()} method. The change in
0284: * visibility state of a <code>Canvas</code> may be caused by the
0285: * application management
0286: * software moving <code>MIDlets</code> between foreground and
0287: * background states, or by the
0288: * system obscuring the <code>Canvas</code> with system screens.
0289: * Thus, the calls to
0290: * <code>showNotify()</code> and <code>hideNotify()</code> are not
0291: * under the control of the <code>MIDlet</code> and
0292: * may occur fairly frequently. Application developers are encouraged to
0293: * perform expensive setup and teardown tasks outside the
0294: * <code>showNotify()</code> and
0295: * <code>hideNotify()</code> methods in order to make them as
0296: * lightweight as possible. </p>
0297: *
0298: * <a name="fullscreen"></a>
0299: * <P>A <code>Canvas</code> can be in normal mode or in full-screen
0300: * mode. In normal mode,
0301: * space on the display may be occupied by command labels, a title, and a
0302: * ticker. By setting a <code>Canvas</code> into full-screen mode,
0303: * the application is
0304: * requesting that the <code>Canvas</code> occupy as much of the
0305: * display space as is
0306: * possible. In full-screen mode, the title and ticker are not displayed even
0307: * if they are present on the <code>Canvas</code>, and
0308: * <code>Commands</code> may be presented using some
0309: * alternative means (such as through a pop-up menu). Note that the
0310: * implementation may still consume a portion of the display for things like
0311: * status indicators, even if the displayed <code>Canvas</code> is in
0312: * full-screen mode. In
0313: * full-screen mode, although the title is not displayed, its text may still
0314: * be used for other purposes, such as for the title of a pop-up menu of
0315: * <code>Commands</code>.</P>
0316: *
0317: * <P><code>Canvas</code> objects are in normal mode by default. The normal vs.
0318: * full-screen mode setting is controlled through the use of the {@link
0319: * #setFullScreenMode} method.</P>
0320: *
0321: * <P>Calling {@link #setFullScreenMode} may result in
0322: * {@link #sizeChanged(int, int) sizeChanged()} being called.
0323: * The default implementation of this method does nothing.
0324: * The application can override this method to handle changes
0325: * in size of available drawing area.
0326: * </p>
0327: *
0328: * <P><strong>Note:</strong> As mentioned in the "Specification
0329: * Requirements" section
0330: * of the overview, implementations must provide the user with an indication
0331: * of network usage. If the indicator is rendered on screen,
0332: * it must be visible when network activity occurs, even when
0333: * the <code>Canvas</code> is in full-screen mode.</P>
0334: *
0335: * @since MIDP 1.0
0336: */
0337:
0338: public abstract class Canvas extends Displayable {
0339:
0340: /**
0341: * Constant for the <code>UP</code> game action.
0342: *
0343: * <P>Constant value <code>1</code> is set to <code>UP</code>.</P>
0344: */
0345: public static final int UP = 1;
0346:
0347: /**
0348: * Constant for the <code>DOWN</code> game action.
0349: *
0350: * <P>Constant value <code>6</code> is set to <code>DOWN</code>.</P>
0351: */
0352: public static final int DOWN = 6;
0353:
0354: /**
0355: * Constant for the <code>LEFT</code> game action.
0356: *
0357: * <P>Constant value <code>2</code> is set to <code>LEFT</code>.</P>
0358: */
0359: public static final int LEFT = 2;
0360:
0361: /**
0362: * Constant for the <code>RIGHT</code> game action.
0363: *
0364: * <P>Constant value <code>5</code> is set to <code>RIGHT</code>.</P>
0365: */
0366: public static final int RIGHT = 5;
0367:
0368: /**
0369: * Constant for the <code>FIRE</code> game action.
0370: *
0371: * <P>Constant value <code>8</code> is set to <code>FIRE</code>.</P>
0372: */
0373: public static final int FIRE = 8;
0374:
0375: /**
0376: * Constant for the general purpose "<code>A</code>" game action.
0377: *
0378: * <P>Constant value <code>9</code> is set to <code>GAME_A</code>.</P>
0379: */
0380: public static final int GAME_A = 9;
0381:
0382: /**
0383: * Constant for the general purpose "<code>B</code>" game action.
0384: *
0385: * <P>Constant value <code>10</code> is set to <code>GAME_B</code>.</P>
0386: */
0387: public static final int GAME_B = 10;
0388:
0389: /**
0390: * Constant for the general purpose "<code>C</code>" game action.
0391: *
0392: * <P>Constant value <code>11</code> is set to <code>GAME_C</code>.</P>
0393: */
0394: public static final int GAME_C = 11;
0395:
0396: /**
0397: * Constant for the general purpose "<code>D</code>" game action.
0398: *
0399: * <P>Constant value <code>12</code> is set to <code>GAME_D</code>.</P>
0400: */
0401: public static final int GAME_D = 12;
0402:
0403: /**
0404: * keyCode for ITU-T key <code>0</code>.
0405: *
0406: * <P>Constant value <code>48</code> is set to <code>KEY_NUM0</code>.</P>
0407: */
0408: public static final int KEY_NUM0 = 48;
0409:
0410: /**
0411: * keyCode for ITU-T key <code>1</code>.
0412: *
0413: * <P>Constant value <code>49</code> is set to <code>KEY_NUM1</code>.</P>
0414: */
0415: public static final int KEY_NUM1 = 49;
0416:
0417: /**
0418: * keyCode for ITU-T key <code>2</code>.
0419: *
0420: * <P>Constant value <code>50</code> is set to <code>KEY_NUM2</code>.</P>
0421: */
0422: public static final int KEY_NUM2 = 50;
0423:
0424: /**
0425: * keyCode for ITU-T key <code>3</code>.
0426: *
0427: * <P>Constant value <code>51</code> is set to <code>KEY_NUM3</code>.</P>
0428: */
0429: public static final int KEY_NUM3 = 51;
0430:
0431: /**
0432: * keyCode for ITU-T key <code>4</code>.
0433: *
0434: * <P>Constant value <code>52</code> is set to <code>KEY_NUM4</code>.</P>
0435: */
0436: public static final int KEY_NUM4 = 52;
0437:
0438: /**
0439: * keyCode for ITU-T key <code>5</code>.
0440: *
0441: * <P>Constant value <code>53</code> is set to <code>KEY_NUM5</code>.</P>
0442: */
0443: public static final int KEY_NUM5 = 53;
0444:
0445: /**
0446: * keyCode for ITU-T key <code>6</code>.
0447: *
0448: * <P>Constant value <code>54</code> is set to <code>KEY_NUM6</code>.</P>
0449: */
0450: public static final int KEY_NUM6 = 54;
0451:
0452: /**
0453: * keyCode for ITU-T key <code>7</code>.
0454: *
0455: * <P>Constant value <code>55</code> is set to <code>KEY_NUM7</code>.</P>
0456: */
0457: public static final int KEY_NUM7 = 55;
0458:
0459: /**
0460: * keyCode for ITU-T key <code>8</code>.
0461: *
0462: * <P>Constant value <code>56</code> is set to <code>KEY_NUM8</code>.</P>
0463: */
0464: public static final int KEY_NUM8 = 56;
0465:
0466: /**
0467: * keyCode for ITU-T key <code>9</code>.
0468: *
0469: * <P>Constant value <code>57</code> is set to <code>KEY_NUM09</code>.</P>
0470: */
0471: public static final int KEY_NUM9 = 57;
0472:
0473: /**
0474: * keyCode for ITU-T key "star" (<code>*</code>).
0475: *
0476: * <P>Constant value <code>42</code> is set to <code>KEY_STAR</code>.</P>
0477: */
0478: public static final int KEY_STAR = 42;
0479:
0480: /**
0481: * keyCode for ITU-T key "pound" (<code>#</code>).
0482: *
0483: * <P>Constant value <code>35</code> is set to <code>KEY_POUND</code>.</P>
0484: */
0485: public static final int KEY_POUND = 35;
0486:
0487: /**
0488: * Constructs a new <code>Canvas</code> object.
0489: */
0490: protected Canvas() {
0491: synchronized (Display.LCDUILock) {
0492: displayableLF = canvasLF = LFFactory.getFactory()
0493: .getCanvasLF(this );
0494: }
0495: }
0496:
0497: /**
0498: * Checks if the <code>Canvas</code> is double buffered by the
0499: * implementation.
0500: * @return <code>true</code> if double buffered,
0501: * <code>false</code> otherwise
0502: */
0503: public boolean isDoubleBuffered() {
0504: // SYNC NOTE: return of atomic value, no locking necessary
0505: return Constants.IS_DOUBLE_BUFFERED;
0506: }
0507:
0508: /**
0509: * Checks if the platform supports pointer press and release events.
0510: * @return <code>true</code> if the device supports pointer events
0511: */
0512: public boolean hasPointerEvents() {
0513: // SYNC NOTE: return of atomic value, no locking necessary
0514: return Constants.POINTER_SUPPORTED;
0515: }
0516:
0517: /**
0518: * Checks if the platform supports pointer motion events (pointer dragged).
0519: * Applications may use this method to determine if the platform is capable
0520: * of supporting motion events.
0521: * @return <code>true</code> if the device supports pointer motion events
0522: */
0523: public boolean hasPointerMotionEvents() {
0524: // SYNC NOTE: return of atomic value, no locking necessary
0525: return Constants.MOTION_SUPPORTED;
0526: }
0527:
0528: /**
0529: * Checks if the platform can generate repeat events when key
0530: * is kept down.
0531: * @return <code>true</code> if the device supports repeat events
0532: */
0533: public boolean hasRepeatEvents() {
0534: // SYNC NOTE: return of atomic value, no locking necessary
0535: return Constants.REPEAT_SUPPORTED;
0536: }
0537:
0538: /**
0539: * Gets a key code that corresponds to the specified game action on the
0540: * device. The implementation is required to provide a mapping for every
0541: * game action, so this method will always return a valid key code for
0542: * every game action. See <a href="#gameactions">above</a> for further
0543: * discussion of game actions. There may be multiple keys associated
0544: * with the same game action; however, this method will return only one of
0545: * them. Applications should translate the key code of every key event
0546: * into a game action using {@link #getGameAction} and then interpret the
0547: * resulting game action, instead of generating a table of key codes at
0548: * using this method during initialization.
0549: *
0550: * <P>The mapping between key codes and game actions
0551: * will not change during the execution of the application.</P>
0552: *
0553: * @param gameAction the game action
0554: * @return a key code corresponding to this game action
0555: * @throws IllegalArgumentException if <code>gameAction</code>
0556: * is not a valid game action
0557: */
0558: public int getKeyCode(int gameAction) {
0559: // SYNC NOTE: no locking necessary as we are doing a static
0560: // table lookup and getKeyCode() is implemented natively
0561: int n = KeyConverter.getKeyCode(gameAction);
0562:
0563: if (n == 0) {
0564: throw new IllegalArgumentException();
0565: }
0566:
0567: return n;
0568: }
0569:
0570: /**
0571: * Gets an informative key string for a key. The string returned will
0572: * resemble the text physically printed on the key. This string is
0573: * suitable for displaying to the user. For example, on a device
0574: * with function keys <code>F1</code> through <code>F4</code>,
0575: * calling this method on the <code>keyCode</code> for
0576: * the <code>F1</code> key will return the string
0577: * "<code>F1</code>". A typical use for this string
0578: * will be to compose help text such as "Press
0579: * <code>F1</code> to proceed."
0580: *
0581: * <p> This method will return a non-empty string for every valid key code.
0582: * </p>
0583: *
0584: * <p> There is no direct mapping from game actions to key names. To get
0585: * the string name for a game action <code>GAME_A</code>, the
0586: * application must call </p>
0587: *
0588: * <TABLE BORDER="2">
0589: * <TR>
0590: * <TD ROWSPAN="1" COLSPAN="1">
0591: * <pre><code>
0592: * getKeyName(getKeyCode(GAME_A)); </code></pre>
0593: * </TD>
0594: * </TR>
0595: * </TABLE>
0596: * @param keyCode the key code being requested
0597: * @return a string name for the key
0598: * @throws IllegalArgumentException if <code>keyCode</code>
0599: * is not a valid key code
0600: */
0601: public String getKeyName(int keyCode) {
0602: // SYNC NOTE: no locking necessary as we are doing a static
0603: // table lookup and getKeyName() is implemented natively
0604: String s = KeyConverter.getKeyName(keyCode);
0605:
0606: if (s == null) {
0607: throw new IllegalArgumentException();
0608: }
0609:
0610: return s;
0611: }
0612:
0613: /**
0614: * Gets the game action associated with the given key code of the
0615: * device. Returns zero if no game action is associated with this key
0616: * code. See <a href="#gameactions">above</a> for further discussion of
0617: * game actions.
0618: *
0619: * <P>The mapping between key codes and game actions
0620: * will not change during the execution of the application.</P>
0621: *
0622: * @param keyCode the key code
0623: * @return the game action corresponding to this key, or
0624: * <code>0</code> if none
0625: * @throws IllegalArgumentException if <code>keyCode</code>
0626: * is not a valid key code
0627: */
0628: public int getGameAction(int keyCode) {
0629: // SYNC NOTE: no locking necessary as we are doing a static
0630: // table lookup and getGameAction() is implemented natively
0631: int n = KeyConverter.getGameAction(keyCode);
0632:
0633: if (n == -1) {
0634: throw new IllegalArgumentException();
0635: }
0636:
0637: return n;
0638: }
0639:
0640: /**
0641: * Controls whether the <code>Canvas</code> is in full-screen mode
0642: * or in normal mode.
0643: *
0644: * @param mode <code>true</code> if the <code>Canvas</code>
0645: * is to be in full screen mode, <code>false</code> otherwise
0646: *
0647: */
0648: public void setFullScreenMode(boolean mode) {
0649:
0650: // Do not do everything if already in the mode given
0651: if (mode == isInFullScreenMode) {
0652: return;
0653: }
0654:
0655: // Ask the Displayable to set fullscrn natively
0656: // To handle it better (and optimize correctly),
0657: // it should sent an event to the event queue.
0658: synchronized (Display.LCDUILock) {
0659: isInFullScreenMode = mode;
0660: }
0661: canvasLF.uSetFullScreenMode(mode);
0662: }
0663:
0664: /**
0665: * Called when a key is pressed.
0666: *
0667: * <P>The <code>getGameAction()</code> method can be called to
0668: * determine what game action, if any, is mapped to the key.
0669: * Class <code>Canvas</code> has an empty implementation of this method, and
0670: * the subclass has to redefine it if it wants to listen this method.
0671: * @param keyCode the key code of the key that was pressed
0672: */
0673: protected void keyPressed(int keyCode) {
0674: }
0675:
0676: /**
0677: * Called when a key is repeated (held down).
0678: *
0679: * <P>The <code>getGameAction()</code> method can
0680: * be called to determine what game action,
0681: * if any, is mapped to the key.
0682: * Class <code>Canvas</code> has an empty implementation of this method, and
0683: * the subclass has to redefine it if it wants to listen this method.
0684: * </P>
0685: * @param keyCode the key code of the key that was repeated
0686: * @see #hasRepeatEvents()
0687: */
0688: protected void keyRepeated(int keyCode) {
0689: }
0690:
0691: /**
0692: * Called when a key is released.
0693: * <P>
0694: * The <code>getGameAction()</code> method can be called to
0695: * determine what game action, if any, is mapped to the key.
0696: * Class <code>Canvas</code> has an empty implementation of this method, and
0697: * the subclass has to redefine it if it wants to listen this method.
0698: * </P>
0699: * @param keyCode the key code of the key that was released
0700: */
0701: protected void keyReleased(int keyCode) {
0702: }
0703:
0704: /**
0705: * Called when the pointer is pressed.
0706: *
0707: * <P>
0708: * The {@link #hasPointerEvents() hasPointerEvents()}
0709: * method may be called to determine if the device supports pointer events.
0710: * Class <code>Canvas</code> has an empty implementation of this method, and
0711: * the subclass has to redefine it if it wants to listen this method.
0712: * </P>
0713: * @param x the horizontal location where the pointer was pressed (relative
0714: * to the <code>Canvas</code>)
0715: * @param y the vertical location where the pointer was pressed
0716: * (relative to the <code>Canvas</code>)
0717: */
0718: protected void pointerPressed(int x, int y) {
0719: }
0720:
0721: /**
0722: * Called when the pointer is released.
0723: *
0724: * <P>
0725: * The {@link #hasPointerEvents() hasPointerEvents()}
0726: * method may be called to determine if the device supports pointer events.
0727: * Class <code>Canvas</code> has an empty implementation of this method, and
0728: * the subclass has to redefine it if it wants to listen this method.
0729: * </P>
0730: * @param x the horizontal location where the pointer was released
0731: * (relative to the <code>Canvas</code>)
0732: * @param y the vertical location where the pointer was released
0733: * (relative to the <code>Canvas</code>)
0734: */
0735: protected void pointerReleased(int x, int y) {
0736: }
0737:
0738: /**
0739: * Called when the pointer is dragged.
0740: *
0741: * <P>
0742: * The {@link #hasPointerMotionEvents() hasPointerMotionEvents()}
0743: * method may be called to determine if the device supports pointer events.
0744: * Class <code>Canvas</code> has an empty implementation of this method, and
0745: * the subclass has to redefine it if it wants to listen this method.
0746: * </P>
0747: * @param x the horizontal location where the pointer was dragged
0748: * (relative to the <code>Canvas</code>)
0749: * @param y the vertical location where the pointer was dragged
0750: * (relative to the <code>Canvas</code>)
0751: */
0752: protected void pointerDragged(int x, int y) {
0753: }
0754:
0755: /**
0756: * Requests a repaint for the specified region of the
0757: * <code>Canvas</code>. Calling
0758: * this method may result in subsequent call to
0759: * <code>paint()</code>, where the passed
0760: * <code>Graphics</code> object's clip region will include at
0761: * least the specified
0762: * region.
0763: *
0764: * <p> If the canvas is not visible, or if width and height are zero or
0765: * less, or if the rectangle does not specify a visible region of
0766: * the display, this call has no effect. </p>
0767: *
0768: * <p> The call to <code>paint()</code> occurs asynchronously of
0769: * the call to <code>repaint()</code>.
0770: * That is, <code>repaint()</code> will not block waiting for
0771: * <code>paint()</code> to finish. The
0772: * <code>paint()</code> method will either be called after the
0773: * caller of <code>repaint(</code>)
0774: * returns
0775: * to the implementation (if the caller is a callback) or on another thread
0776: * entirely. </p>
0777: *
0778: * <p> To synchronize with its <code>paint()</code> routine,
0779: * applications can use either
0780: * {@link Display#callSerially(Runnable) Display.callSerially()} or
0781: * {@link #serviceRepaints() serviceRepaints()}, or they can code explicit
0782: * synchronization into their <code>paint()</code> routine. </p>
0783: *
0784: * <p> The origin of the coordinate system is above and to the left of the
0785: * pixel in the upper left corner of the displayable area of the
0786: * <code>Canvas</code>.
0787: * The X-coordinate is positive right and the Y-coordinate is
0788: * positive downwards.
0789: * </p>
0790: *
0791: * @param x the x coordinate of the rectangle to be repainted
0792: * @param y the y coordinate of the rectangle to be repainted
0793: * @param width the width of the rectangle to be repainted
0794: * @param height the height of the rectangle to be repainted
0795: *
0796: * @see Display#callSerially(Runnable)
0797: * @see #serviceRepaints()
0798: */
0799: public final void repaint(int x, int y, int width, int height) {
0800: synchronized (Display.LCDUILock) {
0801: if (width > 0 && height > 0) {
0802: canvasLF.lRepaint(x, y, width, height, null);
0803: }
0804: }
0805: }
0806:
0807: /**
0808: * Requests a repaint for the entire <code>Canvas</code>. The
0809: * effect is identical to
0810: * <p> <code> repaint(0, 0, getWidth(), getHeight()); </code>
0811: */
0812: public final void repaint() {
0813: synchronized (Display.LCDUILock) {
0814: canvasLF.lRepaint();
0815: }
0816: }
0817:
0818: /**
0819: * Forces any pending repaint requests to be serviced immediately. This
0820: * method blocks until the pending requests have been serviced. If
0821: * there are
0822: * no pending repaints, or if this canvas is not visible on the display,
0823: * this call does nothing and returns immediately.
0824: *
0825: * <p><strong>Warning:</strong> This method blocks until the call to the
0826: * application's <code>paint()</code> method returns. The
0827: * application has no
0828: * control over
0829: * which thread calls <code>paint()</code>; it may vary from
0830: * implementation to
0831: * implementation. If the caller of <code>serviceRepaints()</code>
0832: * holds a lock that the
0833: * <code>paint()</code> method acquires, this may result in
0834: * deadlock. Therefore, callers
0835: * of <code>serviceRepaints()</code> <em>must not</em> hold any
0836: * locks that might be
0837: * acquired within the <code>paint()</code> method. The
0838: * {@link Display#callSerially(Runnable) Display.callSerially()}
0839: * method provides a facility where an application can be called back after
0840: * painting has completed, avoiding the danger of deadlock.
0841: * </p>
0842: *
0843: * @see Display#callSerially(Runnable)
0844: */
0845: public final void serviceRepaints() {
0846: // SYNC NOTE: unlike most public API methods, no locking is done
0847: // here. This is necessary because Display.serviceRepaints()
0848: // needs to handle its own locking.
0849: canvasLF.uServiceRepaints();
0850: }
0851:
0852: /**
0853: * The implementation calls <code>showNotify()</code>
0854: * immediately prior to this <code>Canvas</code> being made
0855: * visible on the display.
0856: * Canvas subclasses may override
0857: * this method to perform tasks before being shown, such
0858: * as setting up animations, starting timers, etc.
0859: * The default implementation of this method in class
0860: * <code>Canvas</code> is empty.
0861: */
0862: protected void showNotify() {
0863: }
0864:
0865: /**
0866: * The implementation calls <code>hideNotify()</code> shortly
0867: * after the <code>Canvas</code> has been
0868: * removed from the display.
0869: * <code>Canvas</code> subclasses may override this method in
0870: * order to pause
0871: * animations,
0872: * revoke timers, etc. The default implementation of this
0873: * method in class <code>Canvas</code> is empty.
0874: */
0875: protected void hideNotify() {
0876: }
0877:
0878: /**
0879: * Renders the <code>Canvas</code>. The application must implement
0880: * this method in
0881: * order to paint any graphics.
0882: *
0883: * <p>The <code>Graphics</code> object's clip region defines the
0884: * area of the screen
0885: * that is considered to be invalid. A correctly-written
0886: * <code>paint()</code> routine
0887: * must paint <em>every</em> pixel within this region. This is necessary
0888: * because the implementation is not required to clear the region prior to
0889: * calling <code>paint()</code> on it. Thus, failing to paint
0890: * every pixel may result
0891: * in a portion of the previous screen image remaining visible. </p>
0892: *
0893: * <p>Applications <em>must not</em> assume that
0894: * they know the underlying source of the <code>paint()</code>
0895: * call and use this
0896: * assumption
0897: * to paint only a subset of the pixels within the clip region. The
0898: * reason is
0899: * that this particular <code>paint()</code> call may have
0900: * resulted from multiple
0901: * <code>repaint()</code>
0902: * requests, some of which may have been generated from outside the
0903: * application. An application that paints only what it thinks is
0904: * necessary to
0905: * be painted may display incorrectly if the screen contents had been
0906: * invalidated by, for example, an incoming telephone call. </p>
0907: *
0908: * <p>Operations on this graphics object after the <code>paint()
0909: * </code>call returns are
0910: * undefined. Thus, the application <em>must not</em> cache this
0911: * <code>Graphics</code>
0912: * object for later use or use by another thread. It must only be
0913: * used within
0914: * the scope of this method. </p>
0915: *
0916: * <p>The implementation may postpone visible effects of
0917: * graphics operations until the end of the paint method.</p>
0918: *
0919: * <p> The contents of the <code>Canvas</code> are never saved if
0920: * it is hidden and then
0921: * is made visible again. Thus, shortly after
0922: * <code>showNotify()</code> is called,
0923: * <code>paint()</code> will always be called with a
0924: * <code>Graphics</code> object whose clip region
0925: * specifies the entire displayable area of the
0926: * <code>Canvas</code>. Applications
0927: * <em>must not</em> rely on any contents being preserved from a previous
0928: * occasion when the <code>Canvas</code> was current. This call to
0929: * <code>paint()</code> will not
0930: * necessarily occur before any other key or pointer
0931: * methods are called on the <code>Canvas</code>. Applications
0932: * whose repaint
0933: * recomputation is expensive may create an offscreen
0934: * <code>Image</code>, paint into it,
0935: * and then draw this image on the <code>Canvas</code> when
0936: * <code>paint()</code> is called. </p>
0937: *
0938: * <P>The application code must never call <code>paint()</code>;
0939: * it is called only by
0940: * the implementation.</P>
0941: *
0942: * <P>The <code>Graphics</code> object passed to the
0943: * <code>paint()</code> method has the following
0944: * properties:</P>
0945: * <UL>
0946: * <LI>the destination is the actual display, or if double buffering is in
0947: * effect, a back buffer for the display;</LI>
0948: * <LI>the clip region includes at least one pixel
0949: * within this <code>Canvas</code>;</LI>
0950: * <LI>the current color is black;</LI>
0951: * <LI>the font is the same as the font returned by
0952: * {@link Font#getDefaultFont() Font.getDefaultFont()};</LI>
0953: * <LI>the stroke style is {@link Graphics#SOLID SOLID};</LI>
0954: * <LI>the origin of the coordinate system is located at the upper-left
0955: * corner of the <code>Canvas</code>; and</LI>
0956: * <LI>the <code>Canvas</code> is visible, that is, a call to
0957: * <code>isShown()</code> will return
0958: * <code>true</code>.</LI>
0959: * </UL>
0960: *
0961: * @param g the <code>Graphics</code> object to be used for
0962: * rendering the <code>Canvas</code>
0963: */
0964: protected abstract void paint(Graphics g);
0965:
0966: /**
0967: * Called when the drawable area of the <code>Canvas</code> has
0968: * been changed. This
0969: * method has augmented semantics compared to {@link
0970: * Displayable#sizeChanged(int, int) Displayable.sizeChanged}.
0971: *
0972: * <p>In addition to the causes listed in
0973: * <code>Displayable.sizeChanged</code>, a size change can occur on a
0974: * <code>Canvas</code> because of a change between normal and
0975: * full-screen modes.</p>
0976: *
0977: * <p>If the size of a <code>Canvas</code> changes while it is
0978: * actually visible on the
0979: * display, it may trigger an automatic repaint request. If this occurs,
0980: * the call to <code>sizeChanged</code> will occur prior to the call to
0981: * <code>paint</code>. If the <code>Canvas</code> has become smaller, the
0982: * implementation may choose not to trigger a repaint request if the
0983: * remaining contents of the <code>Canvas</code> have been
0984: * preserved. Similarly, if
0985: * the <code>Canvas</code> has become larger, the implementation
0986: * may choose to trigger
0987: * a repaint only for the new region. In both cases, the preserved
0988: * contents must remain stationary with respect to the origin of the
0989: * <code>Canvas</code>. If the size change is significant to the
0990: * contents of the
0991: * <code>Canvas</code>, the application must explicitly issue a
0992: * repaint request for the
0993: * changed areas. Note that the application's repaint request should not
0994: * cause multiple repaints, since it can be coalesced with repaint
0995: * requests that are already pending.</p>
0996: *
0997: * <p>If the size of a <code>Canvas</code> changes while it is not
0998: * visible, the
0999: * implementation may choose to delay calls to <code>sizeChanged</code>
1000: * until immediately prior to the call to <code>showNotify</code>. In
1001: * that case, there will be only one call to <code>sizeChanged</code>,
1002: * regardless of the number of size changes.</p>
1003: *
1004: * <p>An application that is sensitive to size changes can update instance
1005: * variables in its implementation of <code>sizeChanged</code>. These
1006: * updated values will be available to the code in the
1007: * <code>showNotify</code>, <code>hideNotify</code>, and
1008: * <code>paint</code> methods.</p>
1009: *
1010: * @param w the new width in pixels of the drawable area of the
1011: * <code>Canvas</code>
1012: * @param h the new height in pixels of the drawable area of
1013: * the <code>Canvas</code>
1014: */
1015: protected void sizeChanged(int w, int h) {
1016: // this method is intended to be overridden by the application
1017: }
1018:
1019: /**
1020: * Used by GameCanvas to suppress Game action key events
1021: */
1022: boolean suppressKeyEvents; // = false
1023:
1024: /** The Canvas look&feel object associated with this Canvas */
1025: CanvasLF canvasLF;
1026: }
|