package-summary.html

是MIDP 的API 查詢文件, 大家可以看一下裡面的index.html, 再用Package 或 Class 名字來查.

      The purpose of a command.  The implementation will use the
      command type for placing the command appropriately within the
      device's user interface. <code>Commands</code> with similar
      types may, for example, be found near each other in certain
      dedicated place in the user interface.  Often, devices will have
      policy for placement and presentation of certain operations.
      For example, a &quot;backward navigation&quot; command might be
      always placed on the right soft key on a particular device, but
      it might be placed on the left soft key on a different device.
      The <CODE>Command</CODE> class provides fixed set of command
      types that provide <code>MIDlet</code> the capability to tell
      the device implementation the intent of a <code>Command</code>.
      The application can use the <CODE>BACK</CODE> command type for
      commands that perform backward navigation.  On the devices
      mentioned above, this type information would be used to assign
      the command to the appropriate soft key.</LI>
    <LI>Priority:
      Defines the relative importance between <CODE>Commands</CODE> of
      the same type. A command with a lower priority value is more
      important than a command of the same type but with a higher
      priority value. If possible, a more important command is
      presented before, or is more easily accessible, than a less
      important one.</LI>
  </UL>

  <H4>
    Device-Provided Operations</H4>
  <P>

    In many high-level UI classes there are also some additional
    operations available in the user interface. The additional
    operations are not visible to applications, only to the end-user.
    The set of operations available depends totally on the user
    interface design of the specific device. For example, an operation
    that allows the user to change the mode for text input between
    alphabetic and numeric is needed in devices that have only an
    ITU-T keypad.  More complex input systems will require additional
    operations. Some of operations available are presented in the user
    interface in the same way the application-defined commands are.
    End-users need not understand which operations are provided by the
    application and which provided by the system. Not all operations
    are available in every implementation.  For example, a system that
    has a word-lookup-based text input scheme will generally provide
    additional operations within the <CODE>TextBox</CODE> class.  A
    system that lacks such an input scheme will also lack the
    corresponding operations.</P>

  <P>
    Some operations are available on all devices, but the way the
    operation is implemented may differ greatly from device to device.
    Examples of this kind of operation are: the mechanism used to
    navigate between <code>List</code> elements and <code>Form</code>
    items, the selection of <code>List</code> elements, moving an
    insertion position within a text editor, and so forth.  Some
    devices do not allow the direct editing of the value of an
    <CODE>Item</CODE>, but instead require the user to switch to an
    off-screen editor.  In such devices, there must be a dedicated
    selection operation that can be used to invoke the off-screen
    editor.  The selection of a <CODE>List</CODE> elements could be,
    for example, implemented with a dedicated &quot;Go&quot; or
    &quot;Select&quot; or some other similar key.  Some devices have
    no dedicated selection key and must select elements using some
    other means.</P>
  <P>
    On devices where the selection operation is performed using a
    dedicated select key, this key will often not have a label
    displayed for it.  It is appropriate for the implementation to use
    this key in situations where its meaning is obvious.  For example,
    if the user is presented with a set of mutually exclusive options,
    the selection key will obviously select one of those options.
    However, in a device that doesn't have a dedicated select key, it
    is likely that the selection operation will be performed using a
    soft key that requires a label.  The ability to set the
    select-command for a <CODE>List</CODE> of type
    <CODE>IMPLICIT</CODE> and the ability to set the default command
    for an <CODE>Item</CODE> are provided so that the application can
    set the label for this operation and so it can receive
    notification when this operation occurs. </P>
  
  <H4>
    High-Level API for Events</H4>
  <P>
    The handling of events in the high-level API is based on a
    listener model. <CODE>Screens</CODE> and <CODE>Canvases</CODE> may
    have listeners for commands.  An object willing to be a listener
    should implement an interface <CODE>CommandListener</CODE> that
    has one method:</P>
  <P>
  <TABLE BORDER="2">
    <TR>
      <TD ROWSPAN="1" COLSPAN="1">
        <pre><code>
    void commandAction(Command c, Displayable d);    </code></pre>
      </TD>
    </TR>
  </TABLE>
  </P>
  <P>
    The application gets these events if the <CODE>Screen</CODE> or
    <CODE>Canvas</CODE> has attached <CODE>Commands</CODE> and if
    there is a registered listener. A unicast-version of the listener
    model is adopted, so the <CODE>Screen</CODE> or
    <CODE>Canvas</CODE> can have one listener at a time.</P>
  <P>
    There is also a listener interface for state changes of the
    <CODE>Items</CODE> in a <CODE>Form</CODE> . The method</P>
  <P>
  <TABLE BORDER="2">
    <TR>
      <TD ROWSPAN="1" COLSPAN="1">
        <pre><code>
    void itemStateChanged(Item item);    </code></pre>
      </TD>
    </TR>
  </TABLE>
  </P>
  <P>
    defined in interface <CODE>ItemStateListener</CODE> is called when
    the value of an interactive <CODE>Gauge</CODE> ,
    <CODE>ChoiceGroup</CODE> , or <CODE>TextField</CODE> changes. It
    is not expected that the listener will be called after every
    change. However, if the value of an Item has been changed, the
    listener will be called for the change sometime before it is
    called for another item or before a command is delivered to the
    <code>Form's</code> <code>CommandListener</code>. It is suggested
    that the change listener is called at least after focus (or
    equivalent) is lost from field. The listener should only be called
    if the field's value has actually changed.</P>
  
  
  <H4>
    Low-Level API for Events</H4>
  <P>
    Low-level graphics and events have the following methods to handle
    low-level key events: </P>
  <P>
  <TABLE BORDER="2">
    <TR>
      <TD ROWSPAN="1" COLSPAN="1">
        <pre><code>
    public void keyPressed(int keyCode);    
    public void keyReleased(int keyCode);    
    public void keyRepeated(int keyCode);</code> </pre>
      </TD>
    </TR>
  </TABLE>
  </P>
  <P>
    The last call, <CODE>keyRepeated</CODE> , is not necessarily
    available in all devices. The applications can check the
    availability of repeat actions by calling the following method of
    the <CODE>Canvas</CODE> :</P>
  <P>
  <TABLE BORDER="2">
    <TR>
      <TD ROWSPAN="1" COLSPAN="1">
        <pre><code>
    public static boolean hasRepeatEvents();    </code> </pre>
      </TD>
    </TR>
  </TABLE>
  </P>
  <P>
    The API requires that there be standard key codes for the ITU-T keypad
    (0-9, *, #), but no keypad layout is required by the API. Although an
    implementation may provide additional keys, applications relying on
    these keys are not portable.</P>
  <P>
    In addition, the class <CODE>Canvas</CODE> has methods for
    handling abstract game events. An implementation maps all these
    key events to suitable keys on the device. For example, a device
    with four-way navigation and a select key in the middle could use
    those keys, but a simpler device may use certain keys on the
    numeric keypad (e.g., <code>2</code>, <code>4</code>,
    <code>5</code>, <code>6</code>, <code>8</code>). These game events
    allow development of portable applications that use the low-level
    events.  The API defines a set of abstract key-events:
    <code>UP</code>, <code>DOWN</code>, <code>LEFT</code>,
    <code>RIGHT</code>, <code>FIRE</code>, <code>GAME_A</code>,
    <code>GAME_B</code>, <code>GAME_C</code>, and
    <code>GAME_D</code>.</P>
  <P>
    An application can get the mapping of the key events to abstract
    key events by calling: </P>
  <P>
  <TABLE BORDER="2">
    <TR>
      <TD ROWSPAN="1" COLSPAN="1">
        <pre><code>
    public static int getGameAction(int keyCode);    </code></pre>
      </TD>
    </TR>
  </TABLE>
  </P>
  <P>
    If the logic of the application is based on the values returned by
    this method, the application is portable and run regardless of the
    keypad design.</P>
  <P>
    It is also possible to map an abstract event to a key with:</P>
  <P>
  <TABLE BORDER="2">
    <TR>
      <TD ROWSPAN="1" COLSPAN="1">
        <pre><code>
    public static int getKeyCode(int gameAction);    </code></pre>
      </TD>
    </TR>
  </TABLE>
  </P>
  <P> where <CODE>gameAction</CODE> is
    <code>UP</code>,<code>DOWN</code>, <code>LEFT</code>,
    <code>RIGHT</code>, <code>FIRE</code>, etc.  On some devices, more
    than one key is mapped to the same game action, in which case the
    <CODE>getKeyCode</CODE> method will return just one of them.
    Properly-written applications should map the key code to an
    abstract key event and make decisions based on the result.</P>

  <P> The mapping between keys and abstract events does not change
    during the execution of the game.</P> <P> The following is an
    example of how an application can use game actions to interpret
    keystrokes.</P>
  <P>
  <TABLE BORDER="2"> <TR> <TD ROWSPAN="1"
    COLSPAN="1">
          <PRE> <CODE>
    class MovingBlocksCanvas extends Canvas {
        public void keyPressed(int keyCode) {
            int action = getGameAction(keyCode);    
            switch (action) {
            case LEFT:
                moveBlockLeft();
                break;
            case RIGHT:
                ...
            }
        }
    }     </CODE> </PRE>
      </TD>
    </TR>
  </TABLE>
  </P>
  <P>
    The low-level API also has support for pointer events, but since
    the following input mechanisms may not be present in all devices,
    the following callback methods may never be called in some
    devices: </P>
  <P>
  <TABLE BORDER="2">
    <TR>
      <TD ROWSPAN="1" COLSPAN="1">
        <pre><CODE>
    public void pointerPressed(int x, int y);
    public void pointerReleased(int x, int y);
    public void pointerDragged(int x, int y);    </CODE></pre>
      </TD>
    </TR>
  </TABLE>
</P>
  <P>
    The application may check whether the pointer is available by calling
    the following methods of class <CODE>Canvas</CODE>
    : </P>
  <P>
  <TABLE BORDER="2">
    <TR>
      <TD ROWSPAN="1" COLSPAN="1">
        <pre><CODE>
    public static boolean hasPointerEvents();
    public static boolean hasPointerMotionEvents();    </CODE></pre>
      </TD>
    </TR>
  </TABLE>
  </P>
  
  <H4>
    Interplay of High-Level Commands and the Low-Level API</H4>

  <P>
    The class <CODE>Canvas</CODE> , which is used for low-level events
    and drawing, is a subclass of <CODE>Displayable</CODE> , and
    applications can attach <CODE>Commands</CODE> to it. This is
    useful for jumping to an options setup <CODE>Screen</CODE> in the
    middle of a game. Another example could be a map-based navigation
    application where keys are used for moving in the map but commands
    are used for higher-level actions.</P>
  <P>
    Some devices may not have the means to invoke commands when
    <CODE>Canvas</CODE> and the low-level event mechanism are in use.
    In that case, the implementation may provide a means to switch to
    a command mode and back.  This command mode might pop up a menu
    over the contents of the <CODE>Canvas</CODE>.  In this case, the
    <CODE>Canvas</CODE> methods <CODE>hideNotify()</CODE> and
    <CODE>showNotify()</CODE> will be called to indicate when the
    <CODE>Canvas</CODE> has been obscured and unobscured,
    respectively.</P>
  <P>
    The <CODE>Canvas</CODE> may have a title and a <CODE>Ticker</CODE>
    like the <CODE>Screen</CODE> objects.  However,
    <CODE>Canvas</CODE> also has a full-screen mode where the title
    and the <CODE>Ticker</CODE> are not displayed.  Setting this mode
    indicates that the application wishes for the <CODE>Canvas</CODE>
    to occupy as much of the physical display as is possible.  In this
    mode, the title may be reused by the implementation as the title
    for pop-up menus.  In normal (not full-screen) mode, the
    appearance of the <CODE>Canvas</CODE> should be similar to that of
    <CODE>Screen</CODE> classes, so that visual continuity is retained
    when the application switches between low-level
    <CODE>Canvas</CODE> objects and high-level <CODE>Screen</CODE>
    objects.</P>

  <H3>Graphics and Text in Low-Level API</H3>
  
  <H4>
    The Redrawing Scheme</H4>
  <P>
    Repainting is done automatically for all <CODE>Screens</CODE> ,
    but not for <CODE>Canvas</CODE>
    ; therefore, developers utilizing the low-level API must
    ; understand its
    repainting scheme. </P>