canvas.java

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

/*
 * @(#)Canvas.java	1.49 02/09/10 @(#)
 *
 * Copyright (c) 1999-2002 Sun Microsystems, Inc.  All rights reserved.
 * PROPRIETARY/CONFIDENTIAL
 * Use is subject to license terms.
 */

package javax.microedition.lcdui;

/**
 * The <code>Canvas</code> class is a base class for writing
 * applications that need to
 * handle low-level events and to issue graphics calls for drawing to the
 * display. Game applications will likely make heavy use of the
 * <code>Canvas</code> class.
 * From an application development perspective, the <code>Canvas</code> class is
 * interchangeable with standard <code>Screen</code> classes, so an
 * application may mix and
 * match <code>Canvas</code> with high-level screens as needed. For
 * example, a List screen
 * may be used to select the track for a racing game, and a
 * <code>Canvas</code> subclass
 * would implement the actual game.
 *
 * <P>The <code>Canvas</code> provides the developer with methods to
 * handle game actions,
 * key events, and
 * pointer events (if supported by the device).  Methods are
 * also provided to identify the device's capabilities and mapping of
 * keys to game actions.
 * The key events are reported with respect to <em>key codes</em>, which
 * are directly bound to concrete keys on the device, use of which may hinder
 * portability.  Portable applications should use game actions instead of key 
 * codes.</p>
 * 
 * <p> Like other subclasses of <code>Displayable</code>, the
 * <code>Canvas</code> class allows the
 * application to register a listener for commands.  Unlike other
 * <code>Displayables</code>,
 * however, the <code>Canvas</code> class requires applications to
 * subclass it in order to
 * use it. The <code>paint()</code> method is declared
 * <code>abstract</code>, and so the
 * application <em>must</em> provide an implementation in its subclass. Other
 * event-reporting methods are not declared <code>abstract,</code> and their
 * default implementations are empty (that is, they do nothing). This allows
 * the application to override only the methods that report events in which the
 * application has interest.  </p>
 *
 * <p> This is in contrast to the {@link Screen Screen} classes, which allow
 * the application to define listeners and to register them with instances of
 * the <code>Screen</code> classes. This style is not used for the
 * <code>Canvas</code> class, because
 * several new listener interfaces would need to be created, one for each kind
 * of event that might be delivered. An alternative would be to have fewer
 * listener interfaces, but this would require listeners to filter out events
 * in which they had no interest. </p>
 *
 * <a name="keyevents"></a>
 * <h3>Key Events</h3>
 *
 * <p> Applications receive keystroke events in which the individual keys are
 * named within a space of <em>key codes</em>. Every key for which events are
 * reported to MIDP applications is assigned a key code.
 * The key code values are unique for each hardware key unless two keys are
 * obvious synonyms for each other.
 * MIDP defines the following key codes:
 * {@link #KEY_NUM0 KEY_NUM0},
 * {@link #KEY_NUM1 KEY_NUM1},
 * {@link #KEY_NUM2 KEY_NUM2},
 * {@link #KEY_NUM3 KEY_NUM3},
 * {@link #KEY_NUM4 KEY_NUM4},
 * {@link #KEY_NUM5 KEY_NUM5},
 * {@link #KEY_NUM6 KEY_NUM6},
 * {@link #KEY_NUM7 KEY_NUM7},
 * {@link #KEY_NUM8 KEY_NUM8},
 * {@link #KEY_NUM9 KEY_NUM9},
 * {@link #KEY_STAR KEY_STAR}, and
 * {@link #KEY_POUND KEY_POUND}.
 * 
 * (These key codes correspond to keys on a ITU-T standard telephone keypad.)
 * Other keys may be present on the keyboard, and they will generally have key
 * codes distinct from those list above.  In order to guarantee portability,
 * applications should use only the standard key codes. </p>
 * 
 * <p>The standard key codes' values are equal to the Unicode encoding for the
 * character that represents the key.  If the device includes any other keys
 * that have an obvious correspondence to a Unicode character, their key code
 * values should equal the Unicode encoding for that character.  For keys that
 * have no corresponding Unicode character, the implementation must use
 * negative values.  Zero is defined to be an invalid key code.  It is thus
 * possible for an application to convert a keyCode into a Unicode character
 * using the following code: </p>
 * 
 * <TABLE BORDER="2">
 * <TR>
 * <TD ROWSPAN="1" COLSPAN="1">
 *    <pre><code>
 *    if (keyCode &gt; 0) {
 *        char ch = (char)keyCode;    
 *        // ...
 *    }    </code></pre>
 * </TD>
 * </TR>
 * </TABLE>
 * <p>This technique is useful only in certain limited cases.  In particular,
 * it is not sufficient for full textual input, because it does not handle
 * upper and lower case, keyboard shift states, and characters that require
 * more than one keystroke to enter.  For textual input, applications should
 * always use {@link TextBox TextBox} or {@link TextField TextField}
 * objects.</p>
 *
 * <p> It is sometimes useful to find the <em>name</em> of a key in order to
 * display a message about this key. In this case the application may use the
 * {@link #getKeyName(int) getKeyName()} method to find a key's name. </p>
 *
 * <a name="gameactions"></a>
 * <h3>Game Actions</h3>
 * <p>
 * Portable applications that need arrow key events and gaming-related events 
 * should use <em>game actions</em> in preference to key codes and key names.  
 * MIDP defines the following game actions:
 * {@link #UP UP},
 * {@link #DOWN DOWN},
 * {@link #LEFT LEFT},
 * {@link #RIGHT RIGHT},
 * {@link #FIRE FIRE},
 * {@link #GAME_A GAME_A},
 * {@link #GAME_B GAME_B},
 * {@link #GAME_C GAME_C}, and
 * {@link #GAME_D GAME_D}.
 * </P>
 * 
 * <P> Each key code may be mapped to at most one game action.  However, a game
 * action may be associated with more than one key code.  The application can
 * translate a key code into a game action using the {@link #getGameAction(int)
 * getGameAction(int keyCode)} method, and it can translate a game action into
 * a key code using the {@link #getKeyCode(int) getKeyCode(int gameAction)}
 * method.  There may be multiple keycodes associated with a particular game 
 * action, but <code>getKeyCode</code> returns only one of them.  Supposing
 * that <code>g</code> is a valid game action and <code>k</code>
 * is a valid key code for a key associated with a game action, consider
 * the following expressions:</p>
 *
 * <TABLE BORDER="2">
 * <TR>
 * <TD ROWSPAN="1" COLSPAN="1">
 *    <pre><code>
 *    g == getGameAction(getKeyCode(g))     // (1)
 *    k == getKeyCode(getGameAction(k))     // (2)    </code></pre>
 * </TD>
 * </TR>
 * </TABLE>
 * <p>Expression (1) is <em>always</em> true.  However, expression (2) 
 * might be true but is <em>not necessarily</em> true.</p>
 *
 * <P>The implementation is not allowed to change the mapping of game
 * actions and key codes during execution of the application.</P>
 *
 * <p> Portable applications that are interested in using game actions should
 * translate every key event into a game action by calling the {@link
 * #getGameAction getGameAction()} method and then testing the result.  For
 * example, on some devices the game actions <code>UP</code>,
 * <code>DOWN</code>, <code>LEFT</code> and <code>RIGHT</code> may be
 * mapped to 4-way navigation arrow keys. In this case,<code>
 * getKeyCode(UP)</code> would
 * return a device-dependent code for the up-arrow key.  On other devices, a
 * possible mapping would be on the number keys <code>2</code>,
 * <code>4</code>, <code>6</code> and <code>8</code>. In this case,
 * <code>getKeyCode(UP)</code> would return <code>KEY_NUM2</code>.  In
 * both cases, the <code>getGameAction()</code>
 * method would return the <code>LEFT</code> game action when the user
 * presses the key that
 * is a &quot;natural left&quot; on her device.  </P>
 *
 * <a name="commands"></a>
 * <h3>Commands</h3>
 * 
 * <p> It is also possible for the user to issue {@link Command commands} when
 * a canvas is current. <code>Commands</code> are mapped to keys and menus in a
 * device-specific fashion. For some devices the keys used for commands may
 * overlap with the keys that will deliver key code events to the canvas. If
 * this is the case, the device will provide a means transparent to the
 * application that enables the user to select a mode that determines whether
 * these keys will deliver commands or key code events to the application.
 * When the <code>Canvas</code> is in normal mode (see <a
 * href="#fullscreen">below</a>),
 * the set of key code events available to a canvas will not change depending
 * upon the number of commands present or the presence of a command listener.
 * When the <code>Canvas</code> is in full-screen mode, if there is no
 * command listener
 * present, the device may choose to deliver key code events for keys that
 * would otherwise be reserved for delivery of commands.  Game developers
 * should be aware that access to commands will vary greatly across devices,
 * and that requiring the user to issue commands during game play may have a
 * great impact on the ease with which the game can be played. </p>
 *
 * <a name="eventdelivery"></a>
 * <h3>Event Delivery</h3>
 *
 * <P> The <code>Canvas</code> object defines several methods that are
 * called by the
 * implementation. These methods are primarily for the purpose of delivering
 * events to the application, and so they are referred to as
 * <em>event delivery</em> methods. The set of methods is: </p>
 *
 * <ul>
 * <li> <code>showNotify()</code> </li>
 * <li> <code>hideNotify()</code> </li>
 * <li> <code>keyPressed()</code> </li>
 * <li> <code>keyRepeated()</code> </li>
 * <li> <code>keyReleased()</code> </li>
 * <li> <code>pointerPressed()</code> </li>
 * <li> <code>pointerDragged()</code> </li>
 * <li> <code>pointerReleased()</code> </li>
 * <li> <code>paint()</code> </li>
 * </ul>
 *
 * <p> These methods are all called serially. That is, the implementation will
 * never call an event delivery method before a prior call to <em>any</em> of
 * the event delivery methods has returned.  The
 * <code>serviceRepaints()</code> method is an exception to this rule, as it
 * blocks until <code>paint()</code> is called and returns. This will occur
 * even if the application is in the midst of one of the event delivery
 * methods when it calls <code>serviceRepaints()</code>.  </p>
 *
 * <p>The {@link Display#callSerially Display.callSerially()} method can be
 * used to serialize some application-defined work with the event stream.
 * For further information, see the
 * <a href="./package-summary.html#events">Event Handling</a> and
 * <a href="./package-summary.html#concurrency">Concurrency</a>
 * sections of the package summary. </p>
 *
 * <p> The key-related, pointer-related, and <code>paint()</code> methods
 * will only be called while the <code>Canvas</code> is actually
 * visible on the output
 * device. These methods will therefore only be called on this
 * <code>Canvas</code> object
 * only after a call to <code>showNotify()</code> and before a call to
 * <code>hideNotify()</code>. After
 * <code>hideNotify()</code> has been called, none of the key,
 * pointer, and <code>paint</code>
 * methods will be called until after a
 * subsequent call to
 * <code>showNotify()</code> has returned.  A call to a
 * <code>run()</code> method resulting from
 * <code>callSerially()</code> may occur irrespective of calls to
 * <code>showNotify()</code> and
 * <code>hideNotify()</code>.  </p>
 *
 * <p> The {@link #showNotify() showNotify()} method is called prior to the
 * <code>Canvas</code> actually being made visible on the display, and
 * the {@link
 * #hideNotify() hideNotify()} method is called after the
 * <code>Canvas</code> has been
 * removed from the display.  The visibility state of a
 * <code>Canvas</code> (or any other
 * <code>Displayable</code> object) may be queried through the use of the {@link
 * Displayable#isShown() Displayable.isShown()} method.  The change in
 * visibility state of a <code>Canvas</code> may be caused by the
 * application management
 * software moving <code>MIDlets</code> between foreground and
 * background states, or by the
 * system obscuring the <code>Canvas</code> with system screens.
 * Thus, the calls to
 * <code>showNotify()</code> and <code>hideNotify()</code> are not
 * under the control of the <code>MIDlet</code> and
 * may occur fairly frequently.  Application developers are encouraged to
 * perform expensive setup and teardown tasks outside the
 * <code>showNotify()</code> and
 * <code>hideNotify()</code> methods in order to make them as
 * lightweight as possible. </p>
 *
 * <a name="fullscreen"></a>
 * <P>A <code>Canvas</code> can be in normal mode or in full-screen
 * mode.  In normal mode,
 * space on the display may be occupied by command labels, a title, and a
 * ticker.  By setting a <code>Canvas</code> into full-screen mode,
 * the application is
 * requesting that the <code>Canvas</code> occupy as much of the
 * display space as is
 * possible.  In full-screen mode, the title and ticker are not displayed even
 * if they are present on the <code>Canvas</code>, and
 * <code>Commands</code> may be presented using some
 * alternative means (such as through a pop-up menu).  Note that the
 * implementation may still consume a portion of the display for things like
 * status indicators, even if the displayed <code>Canvas</code> is in
 * full-screen mode.  In
 * full-screen mode, although the title is not displayed, its text may still 
 * be used for other purposes, such as for the title of a pop-up menu of 
 * <code>Commands</code>.</P>
 *
 * <P><code>Canvas</code> objects are in normal mode by default.  The normal vs.
 * full-screen mode setting is controlled through the use of the {@link
 * #setFullScreenMode} method.</P>
 * 
 * <P>Calling {@link #setFullScreenMode} may result in 
 * {@link #sizeChanged(int, int) sizeChanged()} being called.
 * The default implementation of this method does nothing.
 * The application can override this method to handle changes 
 * in size of available drawing area.
 * </p>
 *
 * <P><strong>Note:</strong> As mentioned in the &quot;Specification
 * Requirements&quot; section
 * of the overview, implementations must provide the user with an indication